@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/orchestration/loop/index.js

@@ -0,0 +1,1107 @@
+import { reconstructSessionEvents } from "../runners/telemetry.js";
+import { NULL_PUBLISHER } from "../runstate/publish.js";
+import picomatch from "picomatch";
+function isRemoteTrackingRef(ref) {
+    return ref.startsWith("refs/remotes/") || ref.startsWith("origin/");
+}
+/**
+ * In-memory `Git` for the dry loop and tests. Defaults: a clean rebase produces
+ * `<branch>@rebased`, the base ref never moves, FF always succeeds, every sha is
+ * an ancestor. Test hooks script the failure modes M3 must handle.
+ */
+export class FakeGit {
+    landed = [];
+    rebases = [];
+    /** branches passed to `fetchRemoteTracking` — the startup sweep's refresh. */
+    fetches = [];
+    detached = new Set();
+    remoteOnly = new Set();
+    localOnly = new Set();
+    fetchFailed = false;
+    fetchThrows = false;
+    changed = new Map();
+    dirtyWorktrees = new Map();
+    conflicts = new Map(); // branch -> queued conflict messages
+    ffFail = new Map();
+    heads = new Map();
+    baseMoves = 0;
+    /** mark `sha` as NOT an ancestor of anything (simulate ledger-ahead-of-git). */
+    detach(sha) {
+        this.detached.add(sha);
+        return this;
+    }
+    /** sha is an ancestor of the remote-tracking base, not the stale local ref. */
+    staleLocal(sha) {
+        this.remoteOnly.add(sha);
+        return this;
+    }
+    /** sha is on the local base; the remote-tracking ref is behind. */
+    remoteBehind(sha) {
+        this.localOnly.add(sha);
+        return this;
+    }
+    /** simulate no remote / offline host / fetch failure. */
+    failFetch() {
+        this.fetchFailed = true;
+        return this;
+    }
+    /** simulate a thrown fetch (must not become an infrastructure-failure halt). */
+    throwOnFetch() {
+        this.fetchThrows = true;
+        return this;
+    }
+    /** what `git diff --name-only` returns for a branch. */
+    setChangedFiles(branch, files) {
+        this.changed.set(branch, files);
+        return this;
+    }
+    /** uncommitted paths in a lane worktree before the orchestrator backstop commits. */
+    setWorktreeDirty(path, files) {
+        this.dirtyWorktrees.set(path, files);
+        return this;
+    }
+    /** queue a rebase conflict for a branch — one per `rebase()` call, in order. */
+    conflictOn(branch, message = "CONFLICT (content): merge conflict in src/x") {
+        this.conflicts.set(branch, [...(this.conflicts.get(branch) ?? []), message]);
+        return this;
+    }
+    /** fail the fast-forward of `ref` (push race / branch protection). */
+    failFastForward(ref, reason = "! [rejected] (fetch first)") {
+        this.ffFail.set(ref, reason);
+        return this;
+    }
+    /** make `headSha(ref)` return a different sha on its Nth call onward (base moved). */
+    moveBaseAfter(calls) {
+        this.baseMoves = calls;
+        return this;
+    }
+    headCalls = new Map();
+    async headSha(ref) {
+        const n = (this.headCalls.get(ref) ?? 0) + 1;
+        this.headCalls.set(ref, n);
+        if (this.baseMoves && n > this.baseMoves)
+            return `${ref}@moved`;
+        return this.heads.get(ref) ?? `${ref}@head`;
+    }
+    async isAncestor(sha, ref) {
+        if (this.remoteOnly.has(sha))
+            return isRemoteTrackingRef(ref);
+        if (this.localOnly.has(sha))
+            return !isRemoteTrackingRef(ref);
+        return !this.detached.has(sha);
+    }
+    async fetchRemoteTracking(branch) {
+        this.fetches.push(branch);
+        if (this.fetchThrows)
+            throw new Error("network unreachable");
+        if (this.fetchFailed)
+            return { ok: false };
+        return { ok: true, trackingRef: `origin/${branch.replace(/^refs\/heads\//, "")}` };
+    }
+    async rebase(branch, onto, _workspace) {
+        this.rebases.push({ branch, onto });
+        const queued = this.conflicts.get(branch);
+        if (queued && queued.length) {
+            return { ok: false, conflict: queued.shift() };
+        }
+        return { ok: true, tipSha: `${branch}@rebased` };
+    }
+    async fastForward(ref, sha) {
+        const reason = this.ffFail.get(ref);
+        if (reason)
+            return { ok: false, reason };
+        this.landed.push({ ref, sha });
+        return { ok: true };
+    }
+    async changedFiles(branch, _base, _workspace) {
+        return this.changed.get(branch) ?? [];
+    }
+    diffs = new Map();
+    setDiffText(branch, text) {
+        this.diffs.set(branch, text);
+        return this;
+    }
+    async diffText(branch, _base, _workspace) {
+        return this.diffs.get(branch) ?? "";
+    }
+    async workingTreeFiles(workspace) {
+        return this.dirtyWorktrees.get(workspace.path) ?? [];
+    }
+    async commitWorkspace(workspace, _message) {
+        const files = this.dirtyWorktrees.get(workspace.path) ?? [];
+        this.dirtyWorktrees.delete(workspace.path);
+        const branch = workspace.branch;
+        const existing = this.changed.get(branch) ?? [];
+        this.changed.set(branch, [...existing, ...files]);
+        return `${branch}@committed`;
+    }
+}
+export const DEFAULT_CONFIG = {
+    forge: "local",
+    baseBranch: "main",
+    maxParallel: 1,
+    retryBudget: 2,
+    systemToml: null,
+    runnersEnabled: ["claude"],
+    activityFeedIntervalMs: 5000,
+};
+const needsYouKindFor = {
+    "one-way-door": "one-way-door",
+    "retry-exhausted": "retry-exhausted",
+    escalation: "escalation",
+    "verify-halt": "escalation",
+    "stranded-in-review": "stranded-in-review",
+    "ledger-ahead-of-git": "ledger-ahead-of-git",
+    "infrastructure-failure": "infrastructure-failure",
+    "config-error": "budget",
+    budget: "budget",
+};
+function recordHalt(log, halt) {
+    log.append({
+        t: "needs.you",
+        kind: needsYouKindFor[halt.kind],
+        ...(halt.unitId ? { unitId: halt.unitId } : {}),
+        message: halt.message,
+        unblock: halt.unblock,
+    });
+}
+/** Best-effort publish — never awaited by the loop hot path. */
+function publishFeed(deps, runId) {
+    const publisher = deps.publisher ?? NULL_PUBLISHER;
+    publisher.publish(deps.log.snapshot()).catch((e) => {
+        deps.log.append({
+            t: "lane.note",
+            unitId: runId,
+            note: `run-status publish threw (${e?.message ?? e}) — feed degraded`,
+        });
+    });
+}
+function makeActivitySink(deps, unitId, runId, lane) {
+    const { log, config } = deps;
+    const now = deps.now ?? Date.now;
+    const interval = config.activityFeedIntervalMs ?? 5000;
+    let lastMidRunPublish = 0;
+    const onActivity = (u) => {
+        try {
+            log.recordLaneActivity(unitId, u);
+        }
+        catch (e) {
+            log.append({
+                t: "lane.note",
+                unitId,
+                note: `activity fold failed (${e.message}) — feed degraded`,
+            });
+            return;
+        }
+        // Independent try/catch: a durable-log write failure must never mask (or
+        // be masked by) the RunState fold above.
+        try {
+            deps.activityLog?.writeAgentActivity({
+                runId,
+                unitId,
+                step: lane.getStep(),
+                attempt: lane.getAttempt(),
+                session: lane.session,
+                runner: lane.runner,
+                model: lane.model,
+                at: now(),
+                line: u.line,
+                turn: u.turn,
+                tokens: u.tokens,
+                ...(u.kind ? { kind: u.kind } : {}),
+                ...(u.tool ? { tool: u.tool } : {}),
+                ...(u.target ? { target: u.target } : {}),
+            });
+        }
+        catch (e) {
+            log.append({
+                t: "lane.note",
+                unitId,
+                note: `activity log write failed (${e.message}) — durable log degraded`,
+            });
+        }
+        const t = now();
+        if (t - lastMidRunPublish >= interval) {
+            lastMidRunPublish = t;
+            publishFeed(deps, runId);
+        }
+    };
+    return { onActivity, publishOnStep: () => publishFeed(deps, runId) };
+}
+function mutationFailure(unitId, operation, error, log) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const halt = {
+        kind: "infrastructure-failure",
+        unitId,
+        message: `${unitId}: ${operation} failed — ${detail}`,
+        unblock: `repair the harness CLI/ledger failure, then rerun ${unitId}`,
+    };
+    recordHalt(log, halt);
+    return { outcome: "halted", halt };
+}
+/** literal prefix before the first wildcard — the M5 "deliberately dumb" scope check. */
+function scopePrefix(glob) {
+    const star = glob.search(/[*?[]/);
+    const head = star === -1 ? glob : glob.slice(0, star);
+    const slash = head.lastIndexOf("/");
+    return slash === -1 ? head : head.slice(0, slash + 1);
+}
+/** two scopes overlap unless cheap string comparison proves them disjoint. */
+export function scopesDisjoint(a, b) {
+    for (const ga of a) {
+        const pa = scopePrefix(ga);
+        for (const gb of b) {
+            const pb = scopePrefix(gb);
+            if (pa === pb || pa.startsWith(pb) || pb.startsWith(pa))
+                return false;
+        }
+    }
+    return true;
+}
+export async function plan(deps) {
+    const { harness, routes, config, log } = deps;
+    const parked = [];
+    const halts = [];
+    // escalations raised out-of-band reach the operator via needs-you (D0 acceptance).
+    for (const u of await harness.escalated()) {
+        log.append({
+            t: "unit.escalated",
+            unitId: u.id,
+            reason: "raised out-of-band (harness next --escalated)",
+            wants: "operator decision: widen | split | abort",
+        });
+        const halt = {
+            kind: "escalation",
+            unitId: u.id,
+            message: `${u.id} is escalated and waiting on an operator decision`,
+            unblock: `harness door approve ${u.id} --reason "<widen|split|abort rationale>" --who <operator>`,
+        };
+        recordHalt(log, halt);
+        halts.push(halt);
+    }
+    const ready = await harness.next(deps.onlyPrefix ? { only: deps.onlyPrefix } : undefined);
+    const buildable = [];
+    for (const u of ready) {
+        if (u.mode === "explore") {
+            // explore units have no edge to merged — parked, never claimed, never
+            // counted against maxParallel or the retry budget (M1).
+            parked.push({ unitId: u.id, reason: "explore — operator-driven" });
+            log.append({ t: "unit.parked", unitId: u.id, reason: "explore — operator-driven" });
+            continue;
+        }
+        buildable.push(u);
+    }
+    // resolve routing; a runner not in `enabled` is a config error at plan time.
+    const resolved = [];
+    for (const u of buildable) {
+        const policy = await routes.resolve(u.id, u.component);
+        if (!config.runnersEnabled.includes(policy.runner)) {
+            const halt = {
+                kind: "config-error",
+                unitId: u.id,
+                message: `route for ${u.id} resolves to runner "${policy.runner}" which is not in orchestration.json runners.enabled`,
+                unblock: `add "${policy.runner}" to runners.enabled in orchestration.json, or fix the route`,
+            };
+            recordHalt(log, halt);
+            halts.push(halt);
+            continue;
+        }
+        resolved.push({ unit: u, policy });
+    }
+    // order by deps then id; take up to maxParallel that are pairwise "probably
+    // disjoint" (M5). The real per-unit scope globs are only known post-claim, so
+    // this is the cheap conservative proxy: two units in the SAME component are
+    // treated as overlapping (serialise them); different components, or — absent a
+    // component — different literal id-prefixes, are treated as disjoint. A false
+    // overlap only costs one round of serialisation.
+    resolved.sort((a, b) => a.unit.deps.length - b.unit.deps.length || a.unit.id.localeCompare(b.unit.id));
+    const lanes = [];
+    for (const cand of resolved) {
+        if (lanes.length >= config.maxParallel)
+            break;
+        const overlaps = lanes.some((l) => !probablyDisjoint(l.unit, cand.unit));
+        if (!overlaps)
+            lanes.push(cand);
+    }
+    return { lanes, parked, halts };
+}
+/** the cheap pre-claim disjoint proxy — see the comment at the call site. */
+function probablyDisjoint(a, b) {
+    if (a.component && b.component)
+        return a.component !== b.component;
+    return scopesDisjoint([`src/${a.id}/`], [`src/${b.id}/`]);
+}
+export async function step(unit, policy, deps) {
+    const { harness, runners, git, config, log } = deps;
+    const mint = deps.mintSession ?? defaultSession;
+    const runner = runners.get(policy.runner);
+    if (!runner) {
+        const halt = {
+            kind: "config-error",
+            unitId: unit.id,
+            message: `no Runner implementation registered for "${policy.runner}"`,
+            unblock: `register a ${policy.runner} runner or re-route ${unit.id}`,
+        };
+        recordHalt(log, halt);
+        return { outcome: "halted", halt };
+    }
+    // one session id per lane — unique per dispatch, stable across the lane's steps.
+    const session = mint();
+    const runId = deps.runId ?? unit.id;
+    const now = deps.now ?? Date.now;
+    // Hoisted above makeActivitySink/setStep (and the retry loop that mutates
+    // `attempt` below) so the very first `setStep("claim")` call — before any
+    // retry has happened — has an initialized attempt/step pair to report to the
+    // durable activity log. `currentStep` exists only for that log; RunState's
+    // `lane.step` events are unaffected (unchanged shape/order).
+    let attempt = 0;
+    let currentStep = "claim";
+    const { onActivity, publishOnStep } = makeActivitySink(deps, unit.id, runId, {
+        session,
+        runner: runner.name,
+        model: policy.model,
+        getStep: () => currentStep,
+        getAttempt: () => attempt,
+    });
+    const setStep = (s) => {
+        currentStep = s;
+        log.append({ t: "lane.step", unitId: unit.id, step: s });
+        try {
+            deps.activityLog?.writeOrchestratorStep({
+                runId,
+                unitId: unit.id,
+                step: s,
+                attempt,
+                session,
+                at: now(),
+            });
+        }
+        catch (e) {
+            log.append({
+                t: "lane.note",
+                unitId: unit.id,
+                note: `activity log step write failed (${e.message})`,
+            });
+        }
+        publishOnStep();
+    };
+    // --- claim -------------------------------------------------------------
+    setStep("claim");
+    const briefing = await harness.claim(unit.id, session);
+    if (!briefing) {
+        // lost the race (a sibling lane took it, or it stopped being ready) — not a
+        // halt: the loop re-plans and moves on.
+        return { outcome: "yielded", unitId: unit.id };
+    }
+    let workspace;
+    try {
+        workspace = await deps.workspaces?.acquire({
+            unitId: unit.id,
+            branch: briefing.branch,
+            baseBranch: config.baseBranch,
+        });
+    }
+    catch (error) {
+        return mutationFailure(unit.id, "worktree acquisition", error, log);
+    }
+    log.append({
+        t: "lane.opened",
+        unitId: unit.id,
+        session,
+        runner: runner.name,
+        model: policy.model,
+        retryBudget: config.retryBudget,
+        emitter: runner.capabilities().sessionTelemetry ? "session" : "orchestrator",
+    });
+    // retry loop: a retry re-dispatches the implementer on the same branch with a
+    // `retry` block carrying verbatim failure evidence (M2). Escalation parks and
+    // breaks out immediately — it never consumes the budget (M1).
+    for (;;) {
+        attempt += 1;
+        log.append({ t: "lane.attempt", unitId: unit.id, attempt });
+        // --- implement -----------------------------------------------------
+        setStep("implement");
+        try {
+            await harness.heartbeat(unit.id, session);
+        }
+        catch (error) {
+            return mutationFailure(unit.id, "heartbeat mutation", error, log);
+        }
+        const impl = await runner.run(briefing, policy, "implementer", workspace, onActivity);
+        log.append({ t: "lane.cost", unitId: unit.id, delta: impl.cost });
+        if (impl.telemetryError)
+            return mutationFailure(unit.id, "implementer session telemetry", impl.telemetryError, log);
+        await emitReconstructedTelemetry(deps, { unitId: unit.id, session, runner: runner.name, model: policy.model, kind: "implementer" }, runner, impl);
+        if (impl.escalation) {
+            log.append({
+                t: "unit.escalated",
+                unitId: unit.id,
+                reason: impl.escalation.reason,
+                wants: impl.escalation.wants,
+            });
+            const halt = {
+                kind: "escalation",
+                unitId: unit.id,
+                message: `${unit.id}: implementer escalated — ${impl.escalation.reason} (wants: ${impl.escalation.wants})`,
+                unblock: `resolve the escalation, then: harness door approve ${unit.id} --reason "<why>" --who <operator>`,
+            };
+            recordHalt(log, halt);
+            return { outcome: "halted", halt };
+        }
+        if (!impl.ok) {
+            if (registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, "implementer gate/verify failure"))
+                continue;
+            return exhausted(unit.id, config.retryBudget, log);
+        }
+        if (workspace) {
+            const materialized = await materializeImplementerWorkspace(git, workspace, briefing, unit.id);
+            if (!materialized.ok) {
+                if (registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, materialized.evidence))
+                    continue;
+                return exhausted(unit.id, config.retryBudget, log, materialized.evidence);
+            }
+        }
+        // --- authoritative orchestration backstop (M2.5) ------------------
+        // A write-time hook gives fast feedback, but never replaces this branch
+        // diff check. Every runner is checked against git before verify/merge.
+        const gitFiles = await git.changedFiles(briefing.branch, config.baseBranch, workspace);
+        const touched = [...new Set([...impl.filesTouched, ...gitFiles])];
+        const violation = outOfScope(touched, briefing.scope);
+        if (violation.length) {
+            const evidence = `post-hoc scope violation: ${violation.join(", ")}`;
+            const retry = registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, evidence);
+            if (retry)
+                continue;
+            return exhausted(unit.id, config.retryBudget, log, evidence);
+        }
+        // --- rebase before verify (M3) — the verified tree must be the landed tree.
+        setStep("rebase");
+        const rb = await git.rebase(briefing.branch, config.baseBranch, workspace);
+        if (!rb.ok || !rb.tipSha) {
+            if (registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, `rebase onto ${config.baseBranch} conflicted:\n${rb.conflict ?? "(no detail)"}`))
+                continue;
+            return exhausted(unit.id, config.retryBudget, log);
+        }
+        let rebasedTip = rb.tipSha;
+        let baseAtRebase = await git.headSha(config.baseBranch);
+        // --- done (ledger append) — in-review, so the verifier reviews a unit the
+        // projection agrees is done. A retry after this point re-emits unit.done
+        // (in-review → in-review is an idempotent no-op in the fold — v0-plan M3).
+        setStep("done");
+        try {
+            await harness.ledgerAppend({ type: "unit.done", unitId: unit.id, session });
+        }
+        catch (error) {
+            return mutationFailure(unit.id, "unit.done ledger append", error, log);
+        }
+        // --- verify ring 1, then ring 2 — both against the REBASED tip.
+        setStep("verify");
+        const verifySession = impl.sessionId ?? session;
+        const v1 = await harness.verify(briefing, verifySession, baseAtRebase, workspace);
+        if (v1.status === "halt")
+            return verifyHalt(unit.id, v1.evidence, log);
+        if (v1.status === "fail") {
+            const retry = registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, v1.evidence);
+            if (retry)
+                continue;
+            return exhausted(unit.id, config.retryBudget, log);
+        }
+        if (v1.envelopeHash)
+            log.append({ t: "lane.envelope", unitId: unit.id, hash: v1.envelopeHash });
+        if (config.systemToml) {
+            setStep("verify-system");
+            const v2 = await harness.verifySystem(unit.id, config.systemToml, workspace);
+            if (v2.status === "halt")
+                return verifyHalt(unit.id, v2.evidence, log);
+            if (v2.status === "fail") {
+                const retry = registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, v2.evidence);
+                if (retry)
+                    continue;
+                return exhausted(unit.id, config.retryBudget, log);
+            }
+        }
+        else {
+            // brownfield allowance — recorded, never a halt (v0-plan M3).
+            log.append({
+                t: "lane.note",
+                unitId: unit.id,
+                note: "ring 2 skipped — the driven project declares no system.toml (brownfield one-blob allowance)",
+            });
+        }
+        // --- review (independent verifier session, read-only) -----------
+        setStep("review");
+        const review = await runner.run(briefing, policy, "verifier", workspace, onActivity);
+        log.append({ t: "lane.cost", unitId: unit.id, delta: review.cost });
+        if (review.telemetryError)
+            return mutationFailure(unit.id, "verifier session telemetry", review.telemetryError, log);
+        await emitReconstructedTelemetry(deps, { unitId: unit.id, session, runner: runner.name, model: policy.model, kind: "verifier" }, runner, review);
+        // a verifier that touches a file voids its verdict (M2 backstop). A
+        // ClaudeRunner verifier structurally cannot write (no write tools); this
+        // catches a runner that reports one anyway. Isolating a degraded-tier
+        // verifier's writes from the implementer's on the same branch needs a
+        // pre/post snapshot — deferred to M3's rebase machinery.
+        if (review.filesTouched.length > 0) {
+            const retry = registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, `verifier session wrote files (${review.filesTouched.join(", ")}) — verdict voided`);
+            if (retry)
+                continue;
+            return exhausted(unit.id, config.retryBudget, log);
+        }
+        if (review.verdict && !review.verdict.approved) {
+            const retry = registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, `verifier rejected: ${review.verdict.reasons.join("; ")}`);
+            if (retry)
+                continue;
+            return exhausted(unit.id, config.retryBudget, log);
+        }
+        // --- re-rebase if the base moved (a sibling lane landed first — routine
+        // under M5). A clean re-rebase keeps the verifier's verdict (same content,
+        // new parent); a conflicted one is a retry. Re-run ring 1 against the new
+        // tip so `harness merge` never sees a sha ring 1 has not (M3).
+        if ((await git.headSha(config.baseBranch)) !== baseAtRebase) {
+            log.append({
+                t: "lane.note",
+                unitId: unit.id,
+                note: `base ${config.baseBranch} moved after ring 1 — re-rebasing and re-running ring 1`,
+            });
+            setStep("rebase");
+            const rr = await git.rebase(briefing.branch, config.baseBranch, workspace);
+            if (!rr.ok || !rr.tipSha) {
+                if (registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, `re-rebase onto moved ${config.baseBranch} conflicted:\n${rr.conflict ?? "(no detail)"}`))
+                    continue;
+                return exhausted(unit.id, config.retryBudget, log);
+            }
+            rebasedTip = rr.tipSha;
+            baseAtRebase = await git.headSha(config.baseBranch);
+            setStep("verify");
+            const v1b = await harness.verify(briefing, verifySession, baseAtRebase, workspace);
+            if (v1b.status === "halt")
+                return verifyHalt(unit.id, v1b.evidence, log);
+            if (v1b.status === "fail") {
+                const retry = registerRetryOrExhaust(unit.id, attempt, config.retryBudget, log, v1b.evidence);
+                if (retry)
+                    continue;
+                return exhausted(unit.id, config.retryBudget, log);
+            }
+            if (v1b.envelopeHash)
+                log.append({ t: "lane.envelope", unitId: unit.id, hash: v1b.envelopeHash });
+        }
+        // --- authorize merge — classify facts and verify signed doors before Git
+        // changes, but do not claim `unit.merged` until the forge actually lands.
+        // Propose-only from the route means no auto-merge even on green.
+        if (policy.mode === "propose-only") {
+            setStep("merge");
+            log.append({
+                t: "lane.note",
+                unitId: unit.id,
+                note: `route mode is propose-only — verified at ${rebasedTip}, left for an operator merge`,
+            });
+            return { outcome: "propose-only", unitId: unit.id, sha: rebasedTip };
+        }
+        setStep("merge");
+        const authorization = await harness.authorizeMerge(unit.id, briefing.mergeFacts, workspace);
+        if (authorization.status === "door-open") {
+            log.append({ t: "lane.door", unitId: unit.id, doorId: authorization.doorId });
+            const halt = {
+                kind: "one-way-door",
+                unitId: unit.id,
+                message: `${unit.id}: merge opened door ${authorization.doorId} (one-way / propose-only class) — blocked pending approval`,
+                unblock: authorization.unblock,
+            };
+            recordHalt(log, halt);
+            return { outcome: "halted", halt };
+        }
+        // --- land, then record truth — authorization gates the Git mutation.
+        // `unit.merged` is appended only after the forge returns the actual landed
+        // object id (which may be a GitHub merge commit rather than the branch tip).
+        setStep("land");
+        const land = deps.forge
+            ? await deps.forge.land({
+                branch: briefing.branch,
+                base: config.baseBranch,
+                unitId: unit.id,
+                tipSha: rebasedTip,
+            })
+            : await localLand(git, config.baseBranch, rebasedTip);
+        if (!land.ok) {
+            const halt = {
+                kind: "infrastructure-failure",
+                unitId: unit.id,
+                message: `${unit.id}: git land failed before unit.merged was recorded (${land.reason})`,
+                unblock: `resolve the ${config.baseBranch} race or protection failure, then re-run orchestrate`,
+            };
+            recordHalt(log, halt);
+            return { outcome: "halted", halt };
+        }
+        const recorded = await harness.recordMerge(unit.id, land.landedSha, briefing.mergeFacts, workspace);
+        if (recorded.status === "door-open") {
+            const halt = {
+                kind: "stranded-in-review",
+                unitId: unit.id,
+                message: `${unit.id}: Git landed ${land.landedSha} but unit.merged was not recorded`,
+                unblock: recorded.unblock,
+            };
+            recordHalt(log, halt);
+            return { outcome: "halted", halt };
+        }
+        log.append({ t: "unit.merged", unitId: unit.id, landedSha: land.landedSha });
+        if (workspace && deps.workspaces) {
+            try {
+                await deps.workspaces.release(workspace);
+            }
+            catch (error) {
+                log.append({
+                    t: "lane.note",
+                    unitId: unit.id,
+                    note: `landed successfully; worktree cleanup retained ${workspace.path}: ${error.message}`,
+                });
+            }
+        }
+        return { outcome: "merged", unitId: unit.id, landedSha: land.landedSha };
+    }
+}
+/**
+ * Resume the already-implemented branch behind a signed, approved one-way door.
+ * The system CLI atomically reclaims only an in-review unit covered by that
+ * approval. We then rebase, re-run deterministic verification and an
+ * independent read-only review, record done again, merge, and land.
+ */
+export async function resumeAfterDoor(unitId, deps) {
+    const { harness, git, config, log } = deps;
+    const snapshot = (await harness.units()).find((unit) => unit.id === unitId && unit.state === "in-review");
+    if (!snapshot) {
+        const halt = {
+            kind: "stranded-in-review",
+            unitId,
+            message: `${unitId} is not an in-review unit available for door resume`,
+            unblock: `inspect with harness next --in-review --json before retrying`,
+        };
+        recordHalt(log, halt);
+        return { outcome: "halted", halt };
+    }
+    const policy = await deps.routes.resolve(unitId, snapshot.component);
+    const runner = deps.runners.get(policy.runner);
+    if (!runner || !config.runnersEnabled.includes(policy.runner)) {
+        const halt = {
+            kind: "config-error",
+            unitId,
+            message: `door resume route for ${unitId} has no enabled ${policy.runner} runner`,
+            unblock: `enable ${policy.runner} or repair the route, then retry resume`,
+        };
+        recordHalt(log, halt);
+        return { outcome: "halted", halt };
+    }
+    const session = (deps.mintSession ?? defaultSession)();
+    const briefing = await harness.resumeAfterDoor(unitId, session);
+    if (!briefing) {
+        const halt = {
+            kind: "one-way-door",
+            unitId,
+            message: `${unitId} has no valid signed door approval and was not resumed`,
+            unblock: `approve the exact open door, then rerun orchestrate resume --unit ${unitId}`,
+        };
+        recordHalt(log, halt);
+        return { outcome: "halted", halt };
+    }
+    let workspace;
+    try {
+        workspace = await deps.workspaces?.acquire({
+            unitId,
+            branch: briefing.branch,
+            baseBranch: config.baseBranch,
+        });
+    }
+    catch (error) {
+        return mutationFailure(unitId, "door-resume worktree acquisition", error, log);
+    }
+    const runId = deps.runId ?? unitId;
+    const now = deps.now ?? Date.now;
+    let currentStep = "rebase";
+    const { onActivity, publishOnStep } = makeActivitySink(deps, unitId, runId, {
+        session,
+        runner: runner.name,
+        model: policy.model,
+        getStep: () => currentStep,
+        getAttempt: () => 1, // door-resume never retries — a fixed attempt, same as the existing lane.attempt fact below.
+    });
+    const setStep = (stepName) => {
+        currentStep = stepName;
+        log.append({ t: "lane.step", unitId, step: stepName });
+        try {
+            deps.activityLog?.writeOrchestratorStep({
+                runId,
+                unitId,
+                step: stepName,
+                attempt: 1,
+                session,
+                at: now(),
+            });
+        }
+        catch (e) {
+            log.append({
+                t: "lane.note",
+                unitId,
+                note: `activity log step write failed (${e.message})`,
+            });
+        }
+        publishOnStep();
+    };
+    log.append({
+        t: "lane.opened",
+        unitId,
+        session,
+        runner: runner.name,
+        model: policy.model,
+        retryBudget: 0,
+        emitter: runner.capabilities().sessionTelemetry ? "session" : "orchestrator",
+    });
+    log.append({ t: "lane.attempt", unitId, attempt: 1 });
+    const violation = outOfScope(await git.changedFiles(briefing.branch, config.baseBranch, workspace), briefing.scope);
+    if (violation.length)
+        return exhausted(unitId, 0, log, `post-hoc scope violation: ${violation.join(", ")}`);
+    setStep("rebase");
+    const rebased = await git.rebase(briefing.branch, config.baseBranch, workspace);
+    if (!rebased.ok || !rebased.tipSha)
+        return exhausted(unitId, 0, log, rebased.conflict ?? "door-resume rebase failed");
+    const base = await git.headSha(config.baseBranch);
+    setStep("done");
+    try {
+        await harness.ledgerAppend({ type: "unit.done", unitId, session });
+    }
+    catch (error) {
+        return mutationFailure(unitId, "door-resume unit.done ledger append", error, log);
+    }
+    setStep("verify");
+    const ring1 = await harness.verify(briefing, session, base, workspace);
+    if (ring1.status === "halt")
+        return verifyHalt(unitId, ring1.evidence, log);
+    if (ring1.status === "fail")
+        return exhausted(unitId, 0, log, ring1.evidence);
+    if (ring1.envelopeHash)
+        log.append({ t: "lane.envelope", unitId, hash: ring1.envelopeHash });
+    if (config.systemToml) {
+        setStep("verify-system");
+        const ring2 = await harness.verifySystem(unitId, config.systemToml, workspace);
+        if (ring2.status === "halt")
+            return verifyHalt(unitId, ring2.evidence, log);
+        if (ring2.status === "fail")
+            return exhausted(unitId, 0, log, ring2.evidence);
+    }
+    setStep("review");
+    const review = await runner.run(briefing, policy, "verifier", workspace, onActivity);
+    log.append({ t: "lane.cost", unitId, delta: review.cost });
+    if (review.telemetryError)
+        return mutationFailure(unitId, "door-resume verifier telemetry", review.telemetryError, log);
+    await emitReconstructedTelemetry(deps, { unitId, session, runner: runner.name, model: policy.model, kind: "verifier" }, runner, review);
+    if (!review.ok || review.filesTouched.length || review.verdict?.approved === false) {
+        const evidence = review.filesTouched.length
+            ? `verifier wrote files: ${review.filesTouched.join(", ")}`
+            : review.verdict?.reasons.join("; ") || "verifier rejected door resume";
+        return exhausted(unitId, 0, log, evidence);
+    }
+    if ((await git.headSha(config.baseBranch)) !== base) {
+        return exhausted(unitId, 0, log, `base ${config.baseBranch} moved during door resume; rerun resume to rebase and reverify`);
+    }
+    setStep("merge");
+    const authorization = await harness.authorizeMerge(unitId, briefing.mergeFacts, workspace);
+    if (authorization.status === "door-open") {
+        log.append({ t: "lane.door", unitId, doorId: authorization.doorId });
+        const halt = {
+            kind: "one-way-door",
+            unitId,
+            message: `${unitId} remains blocked by door ${authorization.doorId}`,
+            unblock: authorization.unblock,
+        };
+        recordHalt(log, halt);
+        return { outcome: "halted", halt };
+    }
+    setStep("land");
+    const land = deps.forge
+        ? await deps.forge.land({
+            branch: briefing.branch,
+            base: config.baseBranch,
+            unitId,
+            tipSha: rebased.tipSha,
+        })
+        : await localLand(git, config.baseBranch, rebased.tipSha);
+    if (!land.ok) {
+        const halt = {
+            kind: "infrastructure-failure",
+            unitId,
+            message: `${unitId}: git land failed before unit.merged was recorded (${land.reason})`,
+            unblock: `resolve the ${config.baseBranch} race or protection failure, then rerun resume`,
+        };
+        recordHalt(log, halt);
+        return { outcome: "halted", halt };
+    }
+    const recorded = await harness.recordMerge(unitId, land.landedSha, briefing.mergeFacts, workspace);
+    if (recorded.status === "door-open") {
+        const halt = {
+            kind: "stranded-in-review",
+            unitId,
+            message: `${unitId}: Git landed ${land.landedSha} but unit.merged was not recorded`,
+            unblock: recorded.unblock,
+        };
+        recordHalt(log, halt);
+        return { outcome: "halted", halt };
+    }
+    log.append({ t: "unit.merged", unitId, landedSha: land.landedSha });
+    if (workspace && deps.workspaces) {
+        try {
+            await deps.workspaces.release(workspace);
+        }
+        catch (error) {
+            log.append({
+                t: "lane.note",
+                unitId,
+                note: `landed successfully; worktree cleanup retained ${workspace.path}: ${error.message}`,
+            });
+        }
+    }
+    return { outcome: "merged", unitId, landedSha: land.landedSha };
+}
+function defaultSession() {
+    return `orch-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+async function materializeImplementerWorkspace(git, workspace, briefing, unitId) {
+    const dirty = await git.workingTreeFiles(workspace);
+    if (dirty.length === 0)
+        return { ok: true };
+    const violation = outOfScope(dirty, briefing.scope);
+    if (violation.length) {
+        return { ok: false, evidence: `uncommitted out-of-scope paths: ${violation.join(", ")}` };
+    }
+    try {
+        await git.commitWorkspace(workspace, `Implement ${unitId}\n\nUnit: ${unitId}`);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            evidence: `failed to commit implementer changes: ${error.message}`,
+        };
+    }
+}
+function outOfScope(files, scope) {
+    if (scope.length === 0)
+        return files;
+    const norm = (path) => path.replaceAll("\\", "/").replace(/^\.\//, "");
+    const matches = picomatch(scope.map(norm), { dot: true });
+    return files.map(norm).filter((file) => !matches(file));
+}
+/** the `forge: "local"` land — a plain fast-forward of `base` to the rebased tip. */
+async function localLand(git, base, tipSha) {
+    const ff = await git.fastForward(base, tipSha);
+    return ff.ok
+        ? { ok: true, landedSha: tipSha }
+        : { ok: false, reason: ff.reason ?? "not a fast-forward" };
+}
+/**
+ * M2.5 — for a runner that cannot self-emit `session.*` (`sessionTelemetry:
+ * false`), reconstruct the events from the `RunResult` and append them via
+ * `harness ledger append`, marked `emitter: "orchestrator"`. A publish failure
+ * is logged, never fatal.
+ */
+async function emitReconstructedTelemetry(deps, meta, runner, result) {
+    if (runner.capabilities().sessionTelemetry)
+        return;
+    const events = reconstructSessionEvents({ ...meta, result });
+    for (const e of events) {
+        try {
+            await deps.harness.ledgerAppend(e);
+        }
+        catch {
+            deps.log.append({
+                t: "needs.you",
+                kind: "budget",
+                unitId: meta.unitId,
+                message: `reconstructed telemetry append failed for ${meta.unitId} (${e.type}) — telemetry is degraded for this run`,
+                unblock: "none — the run continues; check the ledger-append path",
+            });
+        }
+    }
+}
+/** returns true → retry (continue the loop); false → budget exhausted. */
+function registerRetryOrExhaust(unitId, attempt, budget, log, evidence) {
+    if (attempt > budget)
+        return false;
+    log.append({ t: "lane.retry", unitId, attempt: attempt + 1, evidence });
+    return true;
+}
+function exhausted(unitId, budget, log, evidence) {
+    const halt = {
+        kind: "retry-exhausted",
+        unitId,
+        message: `${unitId}: retry budget (${budget}) exhausted${evidence ? ` — ${evidence}` : ""}`,
+        unblock: `inspect the last transcript, then re-plan the unit (widen scope / split) and re-run`,
+    };
+    recordHalt(log, halt);
+    return { outcome: "halted", halt };
+}
+function verifyHalt(unitId, evidence, log) {
+    const halt = {
+        kind: "verify-halt",
+        unitId,
+        message: `${unitId}: harness verify returned halt — ${evidence}`,
+        unblock: `resolve the ring-2 condition (dag_cycle | stale_artifact | scope_cross), then re-run`,
+    };
+    recordHalt(log, halt);
+    return { outcome: "halted", halt };
+}
+// ---------------------------------------------------------------------------
+// startupSweep() — the two crash windows staleness does not cover (M1).
+// ---------------------------------------------------------------------------
+export async function startupSweep(deps) {
+    const { harness, git, config, log } = deps;
+    const halts = [];
+    const units = await harness.units();
+    // 1. stranded in-review — a lane died between `unit.done` and `harness merge`.
+    //    No CLI moves it except merge; until SH P7.6 the sweep halts, never reclaims.
+    for (const u of units.filter((x) => x.state === "in-review")) {
+        const halt = {
+            kind: "stranded-in-review",
+            unitId: u.id,
+            message: `${u.id} is stranded in-review (a prior lane died after unit.done, before merge)`,
+            unblock: `manually verify + merge ${u.id}, or wait for the SH P7.6 in-review recovery path`,
+        };
+        recordHalt(log, halt);
+        halts.push(halt);
+    }
+    // 2. ledger ahead of git — a merge exited 0 without the fast-forward. For
+    //    every ledger-merged unit, its `landed` sha MUST be an ancestor of
+    //    baseBranch (local or, after a tracking refresh, the remote), else
+    //    dependents branch from a base missing that code.
+    const merged = units.filter((x) => x.state === "merged" && x.landedSha);
+    let trackingRef;
+    if (merged.length > 0) {
+        try {
+            const fetched = await git.fetchRemoteTracking(config.baseBranch);
+            if (fetched.ok && fetched.trackingRef)
+                trackingRef = fetched.trackingRef;
+        }
+        catch {
+            // no remote / offline / fetch error — fall back to the local ref; never
+            // a run failure or infrastructure-failure halt.
+        }
+    }
+    for (const u of merged) {
+        const sha = u.landedSha;
+        const onLocal = await git.isAncestor(sha, config.baseBranch);
+        const onRemote = trackingRef ? await git.isAncestor(sha, trackingRef) : false;
+        if (onLocal || onRemote)
+            continue;
+        const halt = {
+            kind: "ledger-ahead-of-git",
+            unitId: u.id,
+            message: `ledger ahead of git for ${u.id}: landed sha ${sha} is not an ancestor of ${config.baseBranch}`,
+            unblock: `fast-forward ${config.baseBranch} to ${sha} (or investigate the push race), then re-run`,
+        };
+        recordHalt(log, halt);
+        halts.push(halt);
+    }
+    return halts;
+}
+export async function runLoop(deps, opts) {
+    const { log } = deps;
+    const now = deps.now ?? Date.now;
+    const runId = deps.runId ?? `run-${now().toString(36)}`;
+    const machineId = deps.machineId ?? "local";
+    const publisher = deps.publisher ?? NULL_PUBLISHER;
+    log.setClock(now);
+    // D1 — best-effort run-status publish. Structurally cannot stop the loop:
+    // any rejection is swallowed here (the CliRunPublisher also logs a warning).
+    const feed = () => publisher.publish(log.snapshot()).catch((e) => {
+        log.append({
+            t: "lane.note",
+            unitId: runId,
+            note: `run-status publish threw (${e?.message ?? e}) — feed degraded`,
+        });
+    });
+    const finish = async (outcome) => {
+        log.append({ t: "run.ended", outcome, at: now() });
+        try {
+            deps.activityLog?.writeRunEnded({ runId, outcome, at: now() });
+        }
+        catch (e) {
+            log.append({
+                t: "lane.note",
+                unitId: runId,
+                note: `activity log run.ended write failed (${e.message})`,
+            });
+        }
+        await feed(); // terminal publish carries `outcome` — retires the run from the overlay
+        return log.snapshot();
+    };
+    log.append({
+        t: "run.started",
+        runId,
+        machineId,
+        systemId: opts.systemId,
+        specRef: opts.specRef,
+        dagSize: opts.dagSize,
+        at: now(),
+    });
+    try {
+        deps.activityLog?.writeRunStarted({
+            runId,
+            dagSize: opts.dagSize,
+            maxParallel: deps.config.maxParallel,
+            at: now(),
+        });
+    }
+    catch (e) {
+        log.append({
+            t: "lane.note",
+            unitId: runId,
+            note: `activity log run.started write failed (${e.message})`,
+        });
+    }
+    await feed();
+    // startup sweep BEFORE any claim.
+    const sweepHalts = await startupSweep(deps);
+    if (sweepHalts.length > 0)
+        return finish("halted");
+    const startedAt = now();
+    for (;;) {
+        const p = await plan(deps);
+        if (p.halts.length > 0)
+            return finish("halted");
+        if (p.lanes.length === 0) {
+            // nothing ready and nothing in flight — the run is done.
+            return finish("completed");
+        }
+        // run the batch in parallel (M5). `harness claim` CAS makes concurrent
+        // claims safe; the plan() selection kept the lanes probably-disjoint. On a
+        // budget trip we stop claiming NEW units but let this batch's in-flight
+        // lanes finish their current step — so the check is after Promise.all.
+        const results = await Promise.all(p.lanes.map((lane) => step(lane.unit, lane.policy, deps)));
+        let halted = results.some((r) => r.outcome === "halted");
+        const progressed = results.some((r) => r.outcome === "merged" || r.outcome === "propose-only");
+        const runCost = log.snapshot().lanes.reduce((s, l) => s + l.cost, 0);
+        if (deps.config.maxRunCost !== undefined && runCost >= deps.config.maxRunCost) {
+            recordHalt(log, {
+                kind: "budget",
+                message: `maxRunCost (${deps.config.maxRunCost}) tripped at ${runCost}`,
+                unblock: "raise maxRunCost in orchestration.json or accept the partial run, then re-run",
+            });
+            halted = true;
+        }
+        if (deps.config.maxRunDuration !== undefined &&
+            now() - startedAt >= deps.config.maxRunDuration) {
+            recordHalt(log, {
+                kind: "budget",
+                message: `maxRunDuration (${deps.config.maxRunDuration}ms) tripped`,
+                unblock: "raise maxRunDuration in orchestration.json or accept the partial run, then re-run",
+            });
+            halted = true;
+        }
+        if (halted)
+            return finish("halted");
+        if (!progressed) {
+            // every planned lane yielded without merging — no forward progress is
+            // possible (propose-only holds, or claims are all racing). Stop cleanly.
+            return finish("completed");
+        }
+        log.append({ t: "heartbeat", at: now() });
+        await feed(); // publish on every loop transition (dashboard-plan D1)
+    }
+}
+//# sourceMappingURL=index.js.map