# M4 Agent Automation Loop Local Contract Smoke

Run the local M4 smoke from the repository root:

```sh
node scripts/m4-agent-loop-smoke.mjs
```

This check stays local. It uses the `internal/agent` runtime skeleton and a
repo fixture to verify:

- lifecycle coverage for `create`, `start`, `trace`, `finish`, and `cleanup`;
- manager `create/status/trace/evidence/cleanup` contract behavior through the
  local file-system runtime;
- worker `dry-run` task claim, trace write, evidence write, and temporary
  workspace cleanup;
- workspace isolation per agent session;
- explicit skills `commitId` and `version` wiring;
- evidence record fields, URI shape, and SHA-256 digest;
- the fixture evidence note that marks the run as local-only.

The local CLI contract is JSON-only and short-lived:

```sh
STATE_DIR="$(mktemp -d)"
node cmd/hwlab-agent-mgr/main.mjs create --state-dir "$STATE_DIR" \
  --agent-session-id agt_local_m4 --project-id prj_local_m4 \
  --goal "verify local agent loop" --prompt "dry-run" \
  --skill-commit-id 6509a35 --skill-version v1
node cmd/hwlab-agent-worker/main.mjs dry-run --state-dir "$STATE_DIR" \
  --agent-session-id agt_local_m4 \
  --skill-commit-id 6509a35 --skill-version v1
node cmd/hwlab-agent-mgr/main.mjs status --state-dir "$STATE_DIR" \
  --agent-session-id agt_local_m4
node cmd/hwlab-agent-mgr/main.mjs trace --state-dir "$STATE_DIR" \
  --agent-session-id agt_local_m4
node cmd/hwlab-agent-mgr/main.mjs evidence --state-dir "$STATE_DIR" \
  --agent-session-id agt_local_m4
node cmd/hwlab-agent-mgr/main.mjs cleanup --state-dir "$STATE_DIR" \
  --agent-session-id agt_local_m4
```

If either skills `commitId` or `version` is omitted, health and evidence are
reported as `degraded`; no fallback commit or external skill source is inferred.

## Real DEV Preconditions

A real DEV M4 run is separate from this smoke. It would need a live DEV
environment, a seeded `prj_*` project, the `hwlab-agent-mgr`,
`hwlab-agent-worker`, and `hwlab-agent-skills` services, and a stable
`hwlab-agent-skills` artifact with an explicit `commitId`.

That live path must not read tokens or secrets from the runner. Do not inspect
`GH_TOKEN`, `GITHUB_TOKEN`, kubeconfig material, tunnel credentials, or any
other secret-bearing source as part of this smoke. If a live M4 path cannot run
without those reads, the blocker is safety, not contract shape.

## Failure Classification

- `contract_blocker`: fixture, lifecycle, or field shape mismatch.
- `environment_blocker`: DEV-only boundary or endpoint assumptions are wrong.
- `agent_blocker`: workspace isolation, cleanup, or evidence wiring fails.
- `observability_blocker`: a live artifact cannot be tied to service or
  `commitId` identity.
- `safety_blocker`: any secret read, real deployment, or long-running agent
  task.

## What This Is Not

This does not deploy, does not call production, and does not run a real agent
job. It only checks the local runtime skeleton contract and its fixture-backed
evidence note.