@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/system/runstatus/index.js

@@ -0,0 +1,168 @@
+/**
+ * runstatus — the run-status overlay's write side (P7.1). An orchestration run
+ * publishes a latest-state-wins snapshot per `(machine_id, run_id)` into the hub
+ * spool; the hub ingests it beside portfolio truth (P7.2) and the board renders
+ * it (P7.3). This is NOT a ledger channel — the document is disposable and never
+ * an input to a merge, door, or calibration decision (dashboard-plan.md).
+ *
+ *   validateRunStatus(doc)          — schema check (run-status.schema.json)
+ *   publishRunStatus(doc, opts)     — stamp machine_id, validate, write to spool
+ *
+ * A publisher never writes spool files directly — it calls
+ * `harness runstatus publish`, exactly as it appends the ledger only through
+ * `harness ledger append`.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormatsDefault from "ajv-formats";
+import { packageSchemaDir } from "../assets.js";
+const addFormats = addFormatsDefault;
+export class RunStatusError extends Error {
+    name = "RunStatusError";
+}
+function schemaPath() {
+    return join(packageSchemaDir(), "run-status.schema.json");
+}
+let _validate;
+function validator() {
+    if (!_validate) {
+        const ajv = new Ajv2020({ allErrors: true, strict: false });
+        addFormats(ajv);
+        _validate = ajv.compile(JSON.parse(readFileSync(schemaPath(), "utf8")));
+    }
+    return _validate;
+}
+export function validateRunStatus(doc) {
+    const v = validator();
+    if (v(doc))
+        return { ok: true };
+    return {
+        ok: false,
+        errors: (v.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}`),
+    };
+}
+/** `<machine_id>__<run_id>` with anything outside [A-Za-z0-9._-] collapsed to `-`. */
+export function spoolKey(machineId, runId) {
+    const s = (x) => x.replace(/[^A-Za-z0-9._-]+/g, "-");
+    return `${s(machineId)}__${s(runId)}`;
+}
+/**
+ * Stamp `machine_id` (a value the publisher set itself is overridden — the hub
+ * trusts only what `publish` writes), validate, and write to the spool as
+ * `<spoolDir>/<key>.json`. Latest-per-key wins: the file is overwritten.
+ */
+export function publishRunStatus(doc, opts) {
+    const stamped = { ...doc, machine_id: opts.machineId };
+    const check = validateRunStatus(stamped);
+    if (!check.ok) {
+        throw new RunStatusError(`run-status document is invalid:\n  ${check.errors.join("\n  ")}`);
+    }
+    const runId = String(stamped.run_id ?? "");
+    if (!runId)
+        throw new RunStatusError("run-status document has no run_id");
+    const key = spoolKey(opts.machineId, runId);
+    mkdirSync(opts.spoolDir, { recursive: true });
+    const path = join(opts.spoolDir, `${key}.json`);
+    writeFileSync(path, JSON.stringify(stamped, null, 2) + "\n");
+    return { path, key };
+}
+// ---------------------------------------------------------------------------
+// Ingestion + staleness (P7.2) — the read side the board renders.
+// ---------------------------------------------------------------------------
+/** ms since `heartbeat_at` before a run renders as `stale`, never `live`. */
+export const DEFAULT_STALE_AFTER_MS = 90_000;
+/** ms since `heartbeat_at` (or a terminal `outcome`) after which a run is retired. */
+export const DEFAULT_EXPIRE_AFTER_MS = 24 * 60 * 60 * 1000;
+/**
+ * ms a run may go without opening its first lane before it retires early. A
+ * process that crashes before ever publishing a lane leaves a zero-lane
+ * document behind that would otherwise sit at "stale" for a full day,
+ * cluttering the board at the same visual weight as a real run.
+ */
+export const DEFAULT_ZOMBIE_AFTER_MS = 15 * 60 * 1000;
+/**
+ * Project the spool into the board overlay. The spool already holds
+ * latest-per-`(machine_id, run_id)` (publish overwrites `<key>.json`), so this
+ * is a pure classify + sort + optional redact. Re-projecting the same spool
+ * yields a byte-identical overlay bar `generated_at` (golden property).
+ */
+export function projectRuns(spoolDir, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const staleAfter = opts.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    const expireAfter = opts.expireAfterMs ?? DEFAULT_EXPIRE_AFTER_MS;
+    const zombieAfter = opts.zombieAfterMs ?? DEFAULT_ZOMBIE_AFTER_MS;
+    const entries = [];
+    if (existsSync(spoolDir)) {
+        for (const name of readdirSync(spoolDir).filter((n) => n.endsWith(".json"))) {
+            let doc;
+            try {
+                doc = JSON.parse(readFileSync(join(spoolDir, name), "utf8"));
+            }
+            catch {
+                continue; // a half-written spool file — skip, never crash the board
+            }
+            const check = validateRunStatus(doc);
+            if (!check.ok)
+                continue;
+            const hb = Date.parse(String(doc.heartbeat_at ?? ""));
+            const age = Number.isNaN(hb) ? Infinity : now - hb;
+            const terminal = typeof doc.outcome === "string";
+            const hasLanes = Array.isArray(doc.lanes) && doc.lanes.length > 0;
+            let liveness;
+            if (terminal || age > expireAfter)
+                liveness = "retired";
+            // never opened a lane and gone quiet well past staleness — the actuator
+            // most likely crashed before its first publish; don't let it sit at
+            // "stale" for a full day at the same weight as a real run.
+            else if (!hasLanes && age > zombieAfter)
+                liveness = "retired";
+            else if (age > staleAfter)
+                liveness = "stale";
+            else
+                liveness = "live";
+            if (liveness === "retired")
+                continue; // dropped from the overlay
+            entries.push({
+                machine_id: String(doc.machine_id),
+                run_id: String(doc.run_id),
+                liveness,
+                heartbeat_age_ms: Number.isFinite(age) ? age : -1,
+                document: opts.redact ? redactRunStatus(doc) : doc,
+            });
+        }
+    }
+    // Live before stale (the thing changing belongs above the things that
+    // aren't), freshest heartbeat first within each group, (machine_id, run_id)
+    // as the final tiebreak so a tie of identical ages is still deterministic.
+    const livenessRank = { live: 0, stale: 1, retired: 2 };
+    entries.sort((a, b) => livenessRank[a.liveness] - livenessRank[b.liveness] ||
+        a.heartbeat_age_ms - b.heartbeat_age_ms ||
+        a.machine_id.localeCompare(b.machine_id) ||
+        a.run_id.localeCompare(b.run_id));
+    return { generated_at: new Date(now).toISOString(), runs: entries };
+}
+/** Strip operator-facing reason text; keep the machine-actionable `kind` / `unblock`. */
+export function redactRunStatus(doc) {
+    const clone = JSON.parse(JSON.stringify(doc));
+    const needs = clone.needs_you;
+    if (Array.isArray(needs)) {
+        for (const n of needs) {
+            if (typeof n.message === "string")
+                n.message = "[redacted]";
+        }
+    }
+    return clone;
+}
+/** Copy run-status spool files (like `hub sync` for the ledger). Latest file wins. */
+export function syncSpool(fromDir, toDir) {
+    if (!existsSync(fromDir))
+        return [];
+    mkdirSync(toDir, { recursive: true });
+    const names = readdirSync(fromDir).filter((n) => n.endsWith(".json"));
+    for (const n of names) {
+        writeFileSync(join(toDir, n), readFileSync(join(fromDir, n), "utf8"));
+    }
+    return names;
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/sequencer/briefing.js

@@ -0,0 +1,75 @@
+/**
+ * briefing — assembles the `harness claim <id> --json` payload (P7.4).
+ *
+ * The orchestrator (orchestration-harness) claims a unit and needs everything
+ * to run an implementer/verifier session off it, WITHOUT re-reading the spec
+ * DAG or guessing merge policy from a diff:
+ *   - intent + acceptance_criteria + effective scope   → the session prompt
+ *   - resolved branch                                   → where the work lands
+ *   - component + profile                               → routing context
+ *   - declared merge facts (door + P7.5 merge_facts)    → passed to
+ *     `harness merge` verbatim; NEVER derived from the diff
+ *
+ * Pure over specs/*.yaml + system.toml — no ledger writes.
+ */
+import { existsSync } from "node:fs";
+import { loadSpecs } from "../spec/index.js";
+import { loadSystem } from "../system/index.js";
+export class BriefingError extends Error {
+    name = "BriefingError";
+}
+function bareId(ref) {
+    return ref.includes("#") ? ref.slice(ref.indexOf("#") + 1) : ref;
+}
+/** `unit/<id>` with the id sanitised for git ref-name rules. */
+export function branchFor(unitId) {
+    const slug = bareId(unitId)
+        .replaceAll(".", "-")
+        .replace(/[^A-Za-z0-9._/-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return `unit/${slug}`;
+}
+const NO_FACTS = {
+    adds_dependency: false,
+    schema_change: false,
+    security: false,
+    gate_external: false,
+    artifact_producer_change: false,
+};
+export function buildBriefing(unitId, opts = {}) {
+    const specsDir = opts.specsDir ?? "specs";
+    const systemToml = opts.systemToml ?? "system.toml";
+    const bare = bareId(unitId);
+    if (!existsSync(specsDir)) {
+        throw new BriefingError(`specs dir not found: ${specsDir}`);
+    }
+    const spec = loadSpecs(specsDir).find((s) => s.spec.id === bare)?.spec;
+    if (!spec) {
+        throw new BriefingError(`no spec for unit "${bare}" under ${specsDir}`);
+    }
+    let profile = null;
+    if (existsSync(systemToml)) {
+        const sys = loadSystem(systemToml);
+        profile = sys.component.find((c) => c.id === spec.component)?.profile ?? null;
+    }
+    const mf = spec.merge_facts ?? {};
+    return {
+        unit_id: bare,
+        component: spec.component,
+        profile,
+        branch: branchFor(bare),
+        intent: spec.intent,
+        acceptance_criteria: spec.acceptance_criteria,
+        scope: spec.scope,
+        door: spec.door ?? null,
+        merge_facts: {
+            ...NO_FACTS,
+            adds_dependency: mf.adds_dependency ?? false,
+            schema_change: mf.schema_change ?? false,
+            security: mf.security ?? false,
+            gate_external: mf.gate_external ?? false,
+            artifact_producer_change: mf.artifact_producer_change ?? false,
+        },
+    };
+}
+//# sourceMappingURL=briefing.js.map

package/dist/internal/system/sequencer/cli.js

@@ -0,0 +1,170 @@
+/**
+ * `harness next` / `harness claim` / `harness heartbeat` — the sequencer surface.
+ *
+ *   harness next      [--ledger <dir>] [--only <id-prefix>]
+ *                     [--escalated | --in-review | --merged | --all] [--json]
+ *   harness claim     <unit-id> --session <id> [--ledger <dir>] [--json]
+ *                     [--specs <dir>] [--system <system.toml>]
+ *                     [--resume | --resume-after-door] [--keys <dir>]
+ *   harness heartbeat <unit-id> --session <id> [--ledger <dir>]
+ *
+ * `next` exits 0 with ids on stdout, or 0 with nothing when idle. `--json`
+ * emits the ready set as `[{id, component, deps, mode}]` — text stays default.
+ * `--in-review` (P7.6) lists units stranded between `unit.done` and `merge`;
+ * its `--json` rows carry `done_at` / `done_seq`.
+ * `--merged` (G2.3) lists merged units; its `--json` rows carry `landed` (the
+ * sha from `unit.merged`'s body) — the actuator's ledger-ahead-of-git sweep.
+ * `claim` exits 0 if the unit was claimed, 1 otherwise. `--json` emits the full
+ * briefing on success (P7.4), or `{"error": "<reason>"}` on a lost claim.
+ * `--resume` (P7.6) reclaims a stale in-review unit instead of a ready one.
+ * `--resume-after-door` permits immediate reclaim only when a cryptographically
+ * valid approved door covers that in-review unit.
+ */
+import { targetOwnedPaths, targetPath } from "../assets.js";
+import { buildBriefing, BriefingError, } from "./briefing.js";
+import { allUnits, claim, escalatedUnits, heartbeat, inReviewUnits, mergedUnits, readyUnits, resumeClaim, } from "./index.js";
+import { read as ledgerRead } from "../ledger/index.js";
+import { bareUnitId, projectDoors } from "../doors/index.js";
+import { loadOperatorPublicKey } from "../verify/signing.js";
+import { resolve } from "node:path";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+function opts(args, cwd = process.cwd()) {
+    const raw = flag(args, "ledger");
+    return {
+        ledgerDir: raw
+            ? resolve(cwd, raw)
+            : targetOwnedPaths(cwd).ledgerDir,
+    };
+}
+export function nextCommand(args) {
+    const only = flag(args, "only");
+    const escalated = args.includes("--escalated");
+    const inReview = args.includes("--in-review");
+    const merged = args.includes("--merged");
+    const all = args.includes("--all");
+    const list = escalated
+        ? escalatedUnits(opts(args))
+        : inReview
+            ? inReviewUnits(opts(args))
+            : merged
+                ? mergedUnits(opts(args))
+                : all
+                    ? allUnits(opts(args))
+                    : readyUnits(opts(args));
+    const filtered = list.filter((u) => !only || u.id.startsWith(only));
+    if (args.includes("--json")) {
+        // the set as data. An empty set is `[]` on stdout (not an error), exit 0.
+        process.stdout.write(JSON.stringify(filtered.map((u) => ({
+            id: u.id,
+            component: u.component ?? null,
+            deps: u.deps,
+            mode: u.mode ?? "build",
+            ...(inReview
+                ? { done_at: u.doneAt ?? null, done_seq: u.doneSeq ?? null }
+                : {}),
+            ...(merged ? { landed: u.landedSha ?? null } : {}),
+            ...(all
+                ? {
+                    state: u.state,
+                    done_at: u.doneAt ?? null,
+                    landed: u.landedSha ?? null,
+                }
+                : {}),
+        }))) + "\n");
+        return 0;
+    }
+    for (const u of filtered)
+        process.stdout.write(`${u.component ? u.component + "#" : ""}${u.id}\n`);
+    if (filtered.length === 0) {
+        process.stderr.write(escalated
+            ? "no escalated units\n"
+            : inReview
+                ? "no in-review units\n"
+                : merged
+                    ? "no merged units\n"
+                    : "no ready units\n");
+    }
+    return 0;
+}
+export function claimCommand(args) {
+    const unitId = args[0];
+    const session = flag(args, "session");
+    const json = args.includes("--json");
+    if (!unitId || unitId.startsWith("--") || !session) {
+        process.stderr.write("harness claim <unit-id> --session <id> [--ledger <dir>] [--json] [--specs <dir>] [--system <path>]\n");
+        return 2;
+    }
+    const resumeAfterDoor = args.includes("--resume-after-door");
+    const resume = args.includes("--resume") || resumeAfterDoor;
+    if (resumeAfterDoor && !hasApprovedDoor(unitId, args)) {
+        if (json)
+            process.stdout.write(JSON.stringify({ error: "no-approved-door" }) + "\n");
+        else
+            process.stderr.write("not resumed: no cryptographically valid approved door covers this unit\n");
+        return 1;
+    }
+    const r = resume
+        ? resumeClaim(unitId, session, {
+            ...opts(args),
+            ...(resumeAfterDoor ? { heartbeatTimeoutMs: -1 } : {}),
+        })
+        : claim(unitId, session, opts(args));
+    if (!r.ok) {
+        // exit code unchanged (1); --json puts the reason on stdout as data so a
+        // caller can branch on claim-lost without scraping stderr.
+        if (json)
+            process.stdout.write(JSON.stringify({ error: r.reason }) + "\n");
+        else
+            process.stderr.write(`${resume ? "not resumed" : "not claimed"}: ${r.reason}\n`);
+        return 1;
+    }
+    if (!json) {
+        process.stdout.write(`claimed ${unitId} by ${session} (seq ${r.event.seq})\n`);
+        return 0;
+    }
+    const cwd = process.cwd();
+    const specsRaw = flag(args, "specs");
+    const systemRaw = flag(args, "system");
+    let briefing;
+    try {
+        briefing = buildBriefing(unitId, {
+            ...(specsRaw ? { specsDir: resolve(cwd, specsRaw) } : { specsDir: targetPath(cwd, "specs") }),
+            ...(systemRaw
+                ? { systemToml: resolve(cwd, systemRaw) }
+                : { systemToml: targetPath(cwd, "system.toml") }),
+        });
+    }
+    catch (e) {
+        // the claim already landed in the ledger; surface the assembly failure but
+        // keep exit non-zero so the caller does not proceed on a partial briefing.
+        const msg = e instanceof BriefingError ? e.message : e.message;
+        process.stdout.write(JSON.stringify({ error: `claimed but briefing unavailable: ${msg}`, seq: r.event.seq }) + "\n");
+        return 1;
+    }
+    process.stdout.write(JSON.stringify({ ...briefing, session, seq: r.event.seq }) + "\n");
+    return 0;
+}
+function hasApprovedDoor(unitId, args) {
+    const sequencer = opts(args);
+    const keyDir = flag(args, "keys")
+        ? resolve(process.cwd(), flag(args, "keys"))
+        : targetOwnedPaths(process.cwd()).harnessDir;
+    const publicKey = loadOperatorPublicKey(keyDir);
+    return [...projectDoors(ledgerRead(sequencer.ledgerDir), publicKey).values()].some((door) => door.state === "approved" &&
+        bareUnitId(door.unitId) === bareUnitId(unitId));
+}
+export function heartbeatCommand(args) {
+    const unitId = args[0];
+    const session = flag(args, "session");
+    if (!unitId || unitId.startsWith("--") || !session) {
+        process.stderr.write("harness heartbeat <unit-id> --session <id> [--ledger <dir>]\n");
+        return 2;
+    }
+    const e = heartbeat(unitId, session, opts(args));
+    process.stdout.write(`heartbeat ${unitId} (seq ${e.seq})\n`);
+    return 0;
+}
+//# sourceMappingURL=cli.js.map

package/dist/internal/system/sequencer/index.js

@@ -0,0 +1,156 @@
+/**
+ * sequencer — "what is ready to work" is a QUERY over the ledger, not a daemon
+ * (solution design §7.3). Claiming is an atomic, CAS-guarded ledger append:
+ * exactly one of N concurrent claimers wins. A unit whose holding session has
+ * stopped heart-beating becomes reclaimable.
+ */
+import { append, LedgerConflict, read as ledgerRead, ZERO_HASH, } from "../ledger/index.js";
+import { projectUnits } from "../units/index.js";
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 15 * 60 * 1000;
+const CLAIM_RETRIES = 5;
+function bareId(ref) {
+    return ref.includes("#") ? ref.slice(ref.indexOf("#") + 1) : ref;
+}
+function isStale(u, timeoutMs, now) {
+    if (u.state !== "executing")
+        return false;
+    const hb = u.heartbeatAt ? Date.parse(u.heartbeatAt) : 0;
+    return now - hb > timeoutMs;
+}
+/**
+ * Ready = not terminal ∧ not escalated ∧ every dep merged ∧
+ * (planned | ready | stale-executing). ring-2-clean is a Phase-4 predicate
+ * (Contract C) — assumed true here.
+ *
+ * An escalated unit is deliberately withheld even once its heartbeat goes
+ * stale: it is waiting on an operator decision (widen | split | abort), not on
+ * a reclaim.
+ */
+export function readyUnits(opts) {
+    const timeout = opts.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    const now = opts.now ?? Date.now();
+    const units = projectUnits(ledgerRead(opts.ledgerDir));
+    const merged = (id) => units.get(bareId(id))?.state === "merged";
+    return [...units.values()]
+        .filter((u) => {
+        if (u.escalated)
+            return false;
+        const claimable = u.state === "planned" ||
+            u.state === "ready" ||
+            isStale(u, timeout, now);
+        return claimable && u.deps.every(merged);
+    })
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Units whose holding session escalated and are waiting on the operator. */
+export function escalatedUnits(opts) {
+    return [...projectUnits(ledgerRead(opts.ledgerDir)).values()]
+        .filter((u) => u.escalated)
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Units stranded `in-review` — a lane died between `unit.done` and
+ * `harness merge` (P7.6). The list includes escalated ones (visible per P7.7);
+ * the resume claim below is what withholds them. Each carries `doneAt` / `doneSeq`.
+ */
+export function inReviewUnits(opts) {
+    return [...projectUnits(ledgerRead(opts.ledgerDir)).values()]
+        .filter((u) => u.state === "in-review")
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Merged units, with the `landed` sha from `unit.merged`'s body (G2.3). The
+ * actuator's startup sweep reads this to run the *ledger-ahead-of-git* check —
+ * every ledger-merged unit's landed sha must be an ancestor of the base branch.
+ */
+export function mergedUnits(opts) {
+    return [...projectUnits(ledgerRead(opts.ledgerDir)).values()]
+        .filter((u) => u.state === "merged")
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Every materialised unit, for truthful run sizing and recovery diagnostics. */
+export function allUnits(opts) {
+    return [...projectUnits(ledgerRead(opts.ledgerDir)).values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Resume a stranded in-review unit (P7.6). CAS-guarded append of `unit.claimed`,
+ * which the fold takes back to `executing`. Legal ONLY when the unit is
+ * `in-review`, not escalated (P7.7), and its `unit.done` is older than the
+ * heartbeat timeout — the same staleness bar the reclaim path uses for
+ * `executing`, so a live retry is never yanked out from under itself.
+ */
+export function resumeClaim(unitId, session, opts) {
+    const bare = bareId(unitId);
+    const timeout = opts.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    const now = opts.now ?? Date.now();
+    for (let attempt = 0; attempt <= CLAIM_RETRIES; attempt++) {
+        const events = ledgerRead(opts.ledgerDir);
+        const tailHash = events.at(-1)?.hash ?? ZERO_HASH;
+        const system = events[0]?.system ?? bare;
+        const u = projectUnits(events).get(bare);
+        if (!u || u.state !== "in-review")
+            return { ok: false, reason: "not-in-review" };
+        if (u.escalated)
+            return { ok: false, reason: "escalated" };
+        const doneMs = u.doneAt ? Date.parse(u.doneAt) : 0;
+        if (now - doneMs <= timeout)
+            return { ok: false, reason: "too-fresh" };
+        try {
+            const event = append(opts.ledgerDir, {
+                system,
+                actor: { kind: "agent", id: session },
+                type: "unit.claimed",
+                body: { unit_id: unitId, session, resumed: true },
+            }, { expectPrevHash: tailHash });
+            return { ok: true, event };
+        }
+        catch (e) {
+            if (e instanceof LedgerConflict)
+                continue; // ledger moved — re-evaluate
+            throw e;
+        }
+    }
+    return { ok: false, reason: "conflict" };
+}
+/** CAS-guarded append of `unit.claimed`. Exactly one concurrent claimer wins. */
+export function claim(unitId, session, opts) {
+    const bare = bareId(unitId);
+    for (let attempt = 0; attempt <= CLAIM_RETRIES; attempt++) {
+        const events = ledgerRead(opts.ledgerDir);
+        const tailHash = events.at(-1)?.hash ?? ZERO_HASH;
+        const system = events[0]?.system ?? bare;
+        if (!readyUnits(opts).some((u) => u.id === bare)) {
+            const u = projectUnits(events).get(bare);
+            return {
+                ok: false,
+                reason: u?.state === "executing" ? "already-claimed" : "not-ready",
+            };
+        }
+        try {
+            const event = append(opts.ledgerDir, {
+                system,
+                actor: { kind: "agent", id: session },
+                type: "unit.claimed",
+                body: { unit_id: unitId, session },
+            }, { expectPrevHash: tailHash });
+            return { ok: true, event };
+        }
+        catch (e) {
+            if (e instanceof LedgerConflict)
+                continue; // ledger moved — re-evaluate readiness
+            throw e;
+        }
+    }
+    return { ok: false, reason: "conflict" };
+}
+/** Append a `session.heartbeat` so the sequencer keeps the unit out of the reclaim pool. */
+export function heartbeat(unitId, session, opts) {
+    const events = ledgerRead(opts.ledgerDir);
+    return append(opts.ledgerDir, {
+        system: events[0]?.system ?? bareId(unitId),
+        actor: { kind: "agent", id: session },
+        type: "session.heartbeat",
+        body: { unit_id: unitId, session },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/spec/cli.js

@@ -0,0 +1,110 @@
+/**
+ * `harness spec check` — run the `spec` gate over a specs directory.
+ *
+ *   harness spec check [--specs <dir>] [--system <system.toml>]
+ *
+ * With --system, also checks each spec's `component` and `outputs` against
+ * Contract C. Exit 1 if any error-level finding.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { targetPath } from "../assets.js";
+import { checkSpecs } from "./index.js";
+import { materializeSpecs } from "./materialize.js";
+import { projectSpecs } from "./project.js";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+/** Resolve a CLI path flag against the target repository (cwd), never the install. */
+function targetFlag(args, name, cwd, ...defaultSegments) {
+    const raw = flag(args, name);
+    if (raw)
+        return resolve(cwd, raw);
+    return targetPath(cwd, ...defaultSegments);
+}
+function systemOpts(path) {
+    const raw = parseToml(readFileSync(path, "utf8"));
+    const systemComponents = (raw.component ?? [])
+        .map((c) => c.id ?? "")
+        .filter(Boolean);
+    const artifactProducers = {};
+    for (const a of raw.artifact ?? [])
+        if (a.name && a.producer)
+            artifactProducers[a.name] = a.producer;
+    return { systemComponents, artifactProducers };
+}
+export function specCommand(args) {
+    if (args[0] === "project") {
+        const changeDir = flag(args, "change");
+        const openspecRoot = flag(args, "openspec") ?? "openspec";
+        const outDir = flag(args, "out") ?? ".harness/projected/specs";
+        const json = args.includes("--json");
+        if (!changeDir) {
+            process.stderr.write("harness spec project --change <dir> [--openspec <dir>] [--out <dir>] [--json]\n");
+            return 2;
+        }
+        const result = projectSpecs({ openspecRoot, changeDir, outDir });
+        if (json)
+            process.stdout.write(JSON.stringify(result) + "\n");
+        else {
+            for (const finding of result.findings)
+                process.stdout.write(`  ${finding.level === "error" ? "✗" : "⚠"} ${finding.specPath}: ${finding.message}\n`);
+            for (const unit of result.units)
+                process.stdout.write(`  ✓ ${unit.id} → ${unit.path}\n`);
+        }
+        process.stdout.write(result.ok
+            ? `  ✓ spec project passed (${result.units.length} unit(s))\n`
+            : `\n  spec project FAILED\n`);
+        return result.ok ? 0 : 1;
+    }
+    if (args[0] === "materialize") {
+        const cwd = process.cwd();
+        const specsDir = targetFlag(args, "specs", cwd, "specs");
+        const systemPath = flag(args, "system")
+            ? resolve(cwd, flag(args, "system"))
+            : undefined;
+        const ledgerDir = targetFlag(args, "ledger", cwd, ".harness", "ledger");
+        const json = args.includes("--json");
+        if (!systemPath) {
+            process.stderr.write("harness spec materialize --specs <dir> --system <system.toml> [--ledger <dir>] [--json]\n");
+            return 2;
+        }
+        const result = materializeSpecs({ specsDir, systemToml: systemPath, ledgerDir });
+        if (json)
+            process.stdout.write(JSON.stringify(result) + "\n");
+        else {
+            for (const finding of result.findings)
+                process.stdout.write(`  ${finding.level === "error" ? "✗" : "⚠"} ${finding.specPath}: ${finding.message}\n`);
+            for (const conflict of result.conflicts)
+                process.stdout.write(`  ✗ ${conflict.message}\n`);
+            for (const unit of result.units)
+                process.stdout.write(`  ${unit.status === "materialized" ? "✓" : "="} ${unit.id}: ${unit.status}\n`);
+        }
+        return result.ok ? 0 : 1;
+    }
+    if (args[0] !== "check") {
+        process.stderr.write("harness spec check [--specs <dir>] [--system <system.toml>]\n" +
+            "harness spec materialize --specs <dir> --system <system.toml> [--ledger <dir>] [--json]\n" +
+            "harness spec project --change <dir> [--openspec <dir>] [--out <dir>] [--json]\n");
+        return 2;
+    }
+    const cwd = process.cwd();
+    const specsDir = targetFlag(args, "specs", cwd, "specs");
+    const systemRaw = flag(args, "system");
+    const systemPath = systemRaw ? resolve(cwd, systemRaw) : undefined;
+    const findings = checkSpecs(specsDir, systemPath ? systemOpts(systemPath) : {});
+    for (const f of findings) {
+        const where = f.criterionIndex !== undefined
+            ? `${f.specPath}[criterion ${f.criterionIndex}]`
+            : f.specPath;
+        process.stdout.write(`  ${f.level === "error" ? "✗" : "⚠"} ${where}: ${f.message}\n`);
+    }
+    const errors = findings.filter((f) => f.level === "error").length;
+    process.stdout.write(errors === 0
+        ? `  ✓ spec gate passed (${findings.length} warning(s))\n`
+        : `\n  spec gate FAILED — ${errors} error(s)\n`);
+    return errors === 0 ? 0 : 1;
+}
+//# sourceMappingURL=cli.js.map