pikasTech-HWLAB/docs/m4-agent-loop.md

M4 Agent Automation Loop Local Contract Smoke

Run the local M4 smoke from the repository root:

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:

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.