Harness Control

Operate runs in this repo's harness. Everything is public-safe: mock executor by default, no network, no keys.

Orientation

• Runs live under <runsDir>; each run is <runsDir>/<runId>/run.json plus append-only evidence.jsonl.
• The completion gate runs the independent verifier — computeVerdict + verifyFingerprint. A run only reaches DONE on a verifier PASS, never on a model claim.
• Ledgers are append-only. Re-running verify-manifest.mjs must reproduce the recorded verdict and fingerprint; a mismatch means tampering or a bug (see regressions below).

Do

• Start a mock run (no network, no key):

node -e "
import('@m2atrid/pis-harness-service').then(async ({ HarnessService }) => {
  const s = new HarnessService({ runsDir: '.runs' });
  const r = await s.start({ slug: 'demo', manifestSha256: 'a'.repeat(64), sessionId: 'x', argv: ['node','-e','true'], cwd: '.', requirements: [{ requirementId: 'r1', evaluator: 'output-includes', needle: 'fake-executor' }] });
  const f = await s.runner.waitFor(r.runId);
  console.log(r.runId, f.status);
});
"

• Independently verify a finished run:

node scripts/verify-manifest.mjs .runs <runId>

Expect recordedStatus === recomputedStatus and fingerprintMatch: true.

Approval flow

Closed state machine: RUNNING -> WAITING_APPROVAL -> QUEUED (approve, exactly one grant) | FAILED (reject). approve parks the run in QUEUED (never silently resumes); the child was already terminated at the gate. resume is the only grant consumer and takes no caller argv/cwd/env (server-side registry decides):

await service.requestApproval({ runId, scope: "approve:tool", prompt: "allow tool?" });
await service.approve({ runId, decidedBy: "ops" });
await service.resume({ runId }); // consumes the one-time grant, RUNNING

A second approve while a grant is outstanding throws; a grant is consumed at most once. reject closes the run FAILED. Run-record mutations are serialized per run (per-run lock in lock.mjs), so concurrent ops never lose updates.

Debugging terminal states

If a run reads FAILED but the executor exit was 0, read the attempt verdict reason: the model claimed completion but the requirement evidence did not prove it. That's the gate working.

Regressions this repo has already caught

• Completion-gate evidence bug: the verifier computed a PASS verdict in memory but the evidence was never appended to the ledger; verify-manifest.mjs reported fingerprintMatch: false, recomputedStatus: FAIL. Fixed in 10.5 — evidence is persisted via appendEvidence before the record is saved. Keep the regression test in packages/harness-core/test/core.test.js ("completion gate persists evidence so the independent verifier agrees").

Don't

• Don't edit ledgers or run.json by hand — the verifier will (correctly) fail.
• Don't add a provider that holds a key in a fixture. maskedProfile only.
• Don't run public-release-check.mjs on a dirty tree as a pass — a root .runs/dist is a blocker.