@mikenguyen69/harness 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/cli.js

@@ -8,19 +8,45 @@
  * hook-install policy lives here.
  */
 import { buildDispatchRequest, dispatch } from "./dispatch.js";
-import { USAGE } from "./help.js";
+import { COMMAND_HELP, SESSION_HELP, SESSION_PHASES, USAGE, wantsHelp, } from "./help.js";
 import { resolveInternalClis } from "./paths.js";
 import { buildInternalArgv, resolveRoute } from "./routes.js";
 import { formatVersion } from "./version.js";
 export async function main(argv) {
-    if (argv.includes("--help") || argv.includes("-h")) {
-        process.stdout.write(USAGE);
-        return 0;
-    }
     if (argv.includes("--version") || argv.includes("-V")) {
         process.stdout.write(formatVersion());
         return 0;
     }
+    const first = argv[0];
+    const helpRequested = wantsHelp(argv);
+    // Bare `harness`, `harness --help`, `harness -h` — the operator-journey text.
+    // A help flag that is not the leading token belongs to a specific command.
+    if (first === undefined || first === "--help" || first === "-h") {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    // `harness session [<phase>]` — enumerate the phases, and classify an
+    // unrecognised one as an unknown *phase*, not an unknown command. Runs before
+    // the generic `<noun> --help` path so a bare `harness session` prints them too.
+    if (first === "session") {
+        const phase = argv[1];
+        if (phase === undefined || phase === "--help" || phase === "-h") {
+            process.stdout.write(SESSION_HELP + "\n");
+            return 0;
+        }
+        if (!SESSION_PHASES.includes(phase)) {
+            process.stderr.write(`harness session ${phase}: unknown phase — expected one of ${SESSION_PHASES.join(", ")}\n`);
+            return 2;
+        }
+    }
+    // `harness <noun> --help` / `harness <noun> -h` — that command's own usage.
+    if (helpRequested && (argv[1] === "--help" || argv[1] === "-h")) {
+        const synopsis = COMMAND_HELP[first];
+        if (synopsis !== undefined) {
+            process.stdout.write(synopsis + "\n");
+            return 0;
+        }
+    }
     const route = resolveRoute(argv);
     if (route === null) {
         process.stderr.write(argv.length === 0
@@ -28,10 +54,6 @@ export async function main(argv) {
             : `harness ${argv.join(" ")}: unknown command\nRun harness --help\n`);
         return argv.length === 0 ? 0 : 2;
     }
-    if (route === "status-skeleton") {
-        process.stderr.write("harness status: not implemented (skeleton)\n");
-        return 1;
-    }
     const clis = resolveInternalClis();
     const internalArgv = buildInternalArgv(route, argv);
     const request = buildDispatchRequest(route.product, internalArgv, {

package/dist/help.js

@@ -5,7 +5,7 @@ Operator journey:
   harness doctor               read-only preflight before a run
   harness run                  drive the spec DAG with an agent fleet
   harness resume               continue after a signed door approval
-  harness status               project run and lane status from RunState
+  harness status               read-only unit lanes from the ledger (+ run overlay)
   harness report run           render the end-of-run HTML report
   harness report calibration   aggregate verification envelopes (calibration input)
 
@@ -16,6 +16,7 @@ Advanced — verification and gates:
 Advanced — specs and units:
   harness spec check           lint specs, dep DAG, consumes/produces
   harness spec materialize     write idempotent unit.planned facts
+  harness spec project         emit unit YAML from OpenSpec + projection
   harness next                 list units ready to claim
   harness claim                atomically take a ready unit
   harness heartbeat            keep a claim alive
@@ -41,7 +42,87 @@ Integration (machine-facing, same binary):
 
 Usage:
   harness --help               this text
+  harness <command> --help     usage for one command
   harness --version            facade version and internal build identity
   harness <command> [args…]    dispatch to the owning internal CLI
 `;
+/**
+ * The phases `harness session <phase>` accepts. The facade routes each to
+ * `agent session <phase>`; anything else is an unknown phase, not an unknown
+ * command.
+ */
+export const SESSION_PHASES = [
+    "started",
+    "heartbeat",
+    "gate_fired",
+    "escalated",
+    "ended",
+];
+export const SESSION_HELP = `harness session <phase>  append session.<phase> evidence (event JSON on stdin)
+
+  phases: ${SESSION_PHASES.join(", ")}
+
+  e.g. harness session started  < event.json`;
+/**
+ * One synopsis per facade command noun, shown for `harness <noun> --help` /
+ * `harness <noun> -h` so subcommand help never falls through to the
+ * operator-journey text above. Keyed by the leading facade token.
+ */
+export const COMMAND_HELP = {
+    init: `harness init  scaffold component.toml, hooks, CI workflow, generated adapters
+  --audit             read-only brownfield inventory (writes nothing)
+  --mode ratchet      brownfield adoption against a frozen debt baseline`,
+    doctor: `harness doctor  read-only preflight before a run
+  --repo <dir> --routes <routes.toml> [--spool <dir>] [--json]`,
+    run: `harness run  drive the spec DAG with an agent fleet
+  --repo <dir> --config <orchestration.json> --routes <routes.toml> [--only <id-prefix>] [--spool <dir>] [--report <html>]
+  --only <id-prefix>  limits which units the run may claim (same as harness next --only)`,
+    resume: `harness resume  continue a run after a signed door approval
+  --unit <id> [--repo <dir>] [--routes <routes.toml>]`,
+    status: `harness status  read-only unit lanes from the ledger, with a run-status spool overlay
+  [--ledger <dir>] [--spool <dir>] [--json]`,
+    report: `harness report <run|calibration>
+  report run --state <state.json>   end-of-run HTML report (orchestration)
+  report calibration                aggregate verification envelopes (system)`,
+    verify: `harness verify  run all bound gates (cheap first, fail fast) and emit the signed envelope`,
+    gate: `harness gate --pre --file <path>  ring-0 cheap gates before tool use`,
+    spec: `harness spec <check|materialize|project>
+  check        lint specs, dep DAG, consumes/produces   [--specs <dir>] [--system <system.toml>]
+  materialize  write idempotent unit.planned facts       --specs <dir> --system <system.toml> [--ledger <dir>] [--json]
+  project      emit unit YAML from OpenSpec + projection  --change <dir> [--openspec <dir>] [--out <dir>] [--json]`,
+    next: `harness next  list units ready to claim (deps merged, unclaimed or stale)
+  [--only <id-prefix>] [--all | --in-review | --merged | --escalated] [--json]`,
+    claim: `harness claim <unit-id> --session <id>  atomically take a ready unit
+  [--specs <dir>] [--system <path>] [--ledger <dir>] [--json] [--resume | --resume-after-door]`,
+    heartbeat: `harness heartbeat <unit-id> --session <id>  keep a claim alive  [--ledger <dir>]`,
+    merge: `harness merge <unit-id> <--check | --landed <sha>>  authorize or record a landed merge
+  [--system <system.toml>] [facts…]`,
+    door: `harness door <list|show|approve|reject>  open-decision surface
+  list [--sweep]
+  show <id>
+  approve <id> --reason "<who>: <why>" [--who <w>]
+  reject <id> --reason <why>`,
+    ledger: `harness ledger <append|read|verify-chain>  the hash-chained record plane  [--dir <path>]
+  append        full event JSON document on stdin
+  read          print the chain
+  verify-chain  check hash linkage`,
+    board: `harness board <build|serve>  local live dashboard
+  build [--ledger <dir>] [--spool <dir>] [--out board.html]
+  serve [--root <dir>]… [--port 4317] [--refresh 2000]`,
+    attest: `harness attest  write/verify provenance attestations for a merge
+  write  --unit <id> --landed <sha> [--ledger <dir>] [--out <dir>]
+  verify --unit <id> [--ledger <dir>] [--dir <dir>]`,
+    calibrate: `harness calibrate  calibration jobs`,
+    digest: `harness digest  digest surfaces`,
+    route: `harness route  print the resolved route as JSON`,
+    escalate: `harness escalate  raise session.escalated for the current unit`,
+    hook: `harness hook pre-tool-use  agent PreToolUse handler (payload on stdin)`,
+    session: SESSION_HELP,
+};
+/** True when a `-h`/`--help` token appears before any bare `--` separator. */
+export function wantsHelp(argv) {
+    const sep = argv.indexOf("--");
+    const scan = sep === -1 ? argv : argv.slice(0, sep);
+    return scan.includes("--help") || scan.includes("-h");
+}
 //# sourceMappingURL=help.js.map

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

@@ -1,4 +1,5 @@
 const DEFAULT_HIGH_TURN_COUNT = 50;
+const DEFAULT_EXPLORE_BEFORE_EDIT = 15;
 const IMPLEMENT_STEPS = new Set(["implement"]);
 const REVIEW_STEPS = new Set(["review"]);
 export function parseActivityLog(text) {
@@ -157,17 +158,16 @@ export function findRetryWithoutDelta(unitEvents) {
     }
     return findings;
 }
-export function findExploreBeforeEdit(unitEvents) {
+export function findExploreBeforeEdit(unitEvents, threshold = DEFAULT_EXPLORE_BEFORE_EDIT) {
     const findings = [];
     let sinceEditCount = 0;
     const seen = [];
-    const EXPLORE_THRESHOLD = 15;
     for (const e of unitEvents) {
         if (e.kind !== "tool")
             continue;
         const isEdit = e.tool === "write" || e.tool === "edit";
         if (isEdit) {
-            if (sinceEditCount > EXPLORE_THRESHOLD) {
+            if (sinceEditCount > threshold) {
                 findings.push({
                     id: "explore-before-edit",
                     severity: "info",
@@ -186,7 +186,10 @@ export function findExploreBeforeEdit(unitEvents) {
 export function findVerifyHeavierThanImplement(unitEvents) {
     const implementTurns = unitEvents.filter((e) => IMPLEMENT_STEPS.has(e.step) && (e.kind === "tool" || e.kind === "text")).length;
     const reviewTurns = unitEvents.filter((e) => REVIEW_STEPS.has(e.step) && (e.kind === "tool" || e.kind === "text")).length;
-    if (reviewTurns <= implementTurns || reviewTurns === 0)
+    // implementTurns === 0 is structural (a resume starting mid-pipeline, no
+    // implement step at all) — there is nothing to compare review against, not
+    // an imbalance. Symmetric with the reviewTurns === 0 guard below.
+    if (reviewTurns <= implementTurns || reviewTurns === 0 || implementTurns === 0)
         return [];
     return [
         {
@@ -203,6 +206,7 @@ export function analyzeRun(events, opts) {
     const runId = events.find((e) => e.t === "run.started")
         ?.run_id ?? "";
     const highTurnCount = opts.thresholds?.highTurnCount ?? DEFAULT_HIGH_TURN_COUNT;
+    const exploreBeforeEdit = opts.thresholds?.exploreBeforeEdit ?? DEFAULT_EXPLORE_BEFORE_EDIT;
     const stepsByUnit = new Map();
     const activityByUnit = new Map();
     for (const e of events) {
@@ -224,7 +228,7 @@ export function analyzeRun(events, opts) {
         const steps = stepsByUnit.get(unitId) ?? [];
         const activity = activityByUnit.get(unitId) ?? [];
         units.push(unitMetrics(unitId, steps, activity, opts.costByUnit));
-        findings.push(...findRepeatedRead(activity), ...findToolFailureCluster(activity), ...findHighTurnCount(activity, highTurnCount), ...findRetryWithoutDelta(activity), ...findExploreBeforeEdit(activity), ...findVerifyHeavierThanImplement(activity));
+        findings.push(...findRepeatedRead(activity), ...findToolFailureCluster(activity), ...findHighTurnCount(activity, highTurnCount), ...findRetryWithoutDelta(activity), ...findExploreBeforeEdit(activity, exploreBeforeEdit), ...findVerifyHeavierThanImplement(activity));
     }
     return {
         runId,

package/dist/internal/orchestration/cli.js

@@ -14,7 +14,7 @@ import { FakeHarness } from "./harness/index.js";
 import { FakeRouteSource } from "./routes/index.js";
 import { FakeRunner } from "./runner/index.js";
 import { RunLog } from "./runstate/index.js";
-import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { DEFAULT_CONFIG, FakeGit, resumeAfterDoor, runLoop, startupSweep, } from "./loop/index.js";
 import { renderRunReport } from "./report/index.js";
@@ -23,16 +23,23 @@ import { runDoctor } from "./doctor/index.js";
 import { resolveCommandSpec } from "./harness/cli.js";
 import { StubRunner } from "./runners/stub/index.js";
 import { readdirSync } from "node:fs";
-import { analyzeRun, parseActivityLog } from "./analyze/index.js";
+import { analyzeRun, parseActivityLog, } from "./analyze/index.js";
+import { resolveResumeWorktreeRoot } from "./worktree/index.js";
+import { loadOrchestrationConfig } from "./config/index.js";
+import { matchesOnly, loadUnitStories } from "./only/index.js";
 const USAGE = `orchestrate — drive a spec DAG to merged with an agent fleet
 
 Usage:
   orchestrate run [--repo <path>] [--config <path>] [--routes <path>]
                   [--only <id-prefix>] [--spool <hub-dir>] [--report <path>]
                   [--watch] [--activity-log <dir>] [--no-activity-log] [--no-ledger]
+                  [--worktree-root <dir>] [--threshold <rule>=<n>]
                          real run against a checkout (default --repo: cwd);
                          --only limits claims (harness next --only); --spool feeds the board (D1);
                          --watch mirrors Cursor lane activity to stderr as well as the spool;
+                         --worktree-root overrides the default per-run worktree root
+                         (<repo>/.harness/worktrees/<run-id>);
+                         --threshold <rule>=<n> overrides analysis thresholds (repeatable);
                          activity capture is ON by default (<repo>/.harness/runs/<run-id>/activity.jsonl);
                          analysis runs automatically at the end and appends one run.analyzed ledger
                          event unless --no-ledger; --no-activity-log disables capture entirely
@@ -41,16 +48,21 @@ Usage:
   orchestrate resume --unit <id> [--repo <path>] [--routes <path>]
                      [--spool <hub-dir>] [--report <path>] [--watch]
                      [--activity-log <dir>] [--no-activity-log] [--no-ledger] [--resumes <run-id>]
+                     [--worktree-root <dir>] [--threshold <rule>=<n>]
                          after a signed door approval, reverify/review/land the unit;
-                         --resumes links the new run's activity log back to the run it continues
-  orchestrate sweep [--repo <path>] [--routes <path>] [--json]
-                         startup crash-window check (stranded in-review, ledger-ahead-of-git)
+                         --resumes links the new run's activity log back to the run it continues;
+                         --worktree-root overrides the resolved prior-run worktree root;
+                         --threshold <rule>=<n> overrides analysis thresholds (repeatable)
+  orchestrate sweep [--repo <path>] [--routes <path>] [--json] [--no-ledger]
+                         startup crash-window check (interrupted runs, stranded in-review, ledger-ahead-of-git)
   orchestrate demo [--report <path>]
                          the M1 dry loop against a fake DAG, prints RunState
   orchestrate analyze [--run <id> | --last | --log <path>] [--repo <path>]
+                      [--config <path>] [--threshold <rule>=<n>]
                       [--out <path>] [--json] [--no-ledger]
                          synthesize a captured activity.jsonl into findings (P1);
                          --run/--last resolve under <repo>/.harness/runs/, or pass --log directly;
+                         --threshold <rule>=<n> overrides analysis thresholds (repeatable);
                          writes summary.json next to the log unless --out is given
   orchestrate report --state <run-state.json> [--out <path>]
                          render the end-of-run HTML from a saved RunState (D2)
@@ -89,7 +101,9 @@ function buildStubRunner(repo, config, stubConfig) {
     const stub = new StubRunner({
         cwd: repo,
         baseBranch: config.baseBranch,
-        ...(Object.keys(stubConfig.afterImplement ?? {}).length ? { afterImplement } : {}),
+        ...(Object.keys(stubConfig.afterImplement ?? {}).length
+            ? { afterImplement }
+            : {}),
     });
     for (const [unitId, mode] of Object.entries(stubConfig.scripts ?? {})) {
         if (mode === "out-of-scope")
@@ -116,6 +130,55 @@ function flag(name) {
     const i = process.argv.indexOf(`--${name}`);
     return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : undefined;
 }
+function repeatFlags(name) {
+    const out = [];
+    for (let i = 0; i < process.argv.length; i++) {
+        if (process.argv[i] === `--${name}` && process.argv[i + 1]) {
+            out.push(process.argv[i + 1]);
+            i++;
+        }
+        else if (process.argv[i]?.startsWith(`--${name}=`)) {
+            out.push(process.argv[i].slice(`--${name}=`.length));
+        }
+    }
+    return out;
+}
+function parseCliThresholds() {
+    const raw = repeatFlags("threshold");
+    if (raw.length === 0)
+        return null;
+    const thresholds = {};
+    for (const item of raw) {
+        const eqIdx = item.indexOf("=");
+        if (eqIdx === -1) {
+            throw new Error(`invalid --threshold format "${item}", expected <rule>=<n>`);
+        }
+        const rule = item.slice(0, eqIdx).trim();
+        const valStr = item.slice(eqIdx + 1).trim();
+        const val = Number(valStr);
+        if (!Number.isFinite(val) || val < 0) {
+            throw new Error(`invalid threshold value "${valStr}" for rule "${rule}", expected a non-negative number`);
+        }
+        if (rule === "high-turn-count" || rule === "highTurnCount") {
+            thresholds.highTurnCount = val;
+        }
+        else if (rule === "explore-before-edit" || rule === "exploreBeforeEdit") {
+            thresholds.exploreBeforeEdit = val;
+        }
+        else {
+            throw new Error(`unknown threshold rule "${rule}" — expected "high-turn-count" or "explore-before-edit"`);
+        }
+    }
+    return thresholds;
+}
+function resolveThresholds(configThresholds, cliThresholds) {
+    if (!configThresholds && !cliThresholds)
+        return undefined;
+    return {
+        ...configThresholds,
+        ...cliThresholds,
+    };
+}
 function summarise(state, analysis) {
     process.stdout.write(JSON.stringify(state, null, 2) + "\n");
     process.stdout.write(`\noutcome=${state.outcome} merged=${state.counts.merged}/${state.dagSize} ` +
@@ -131,9 +194,9 @@ function summarise(state, analysis) {
     }
 }
 /** the `run.analyzed` body — metrics and rule ids only, no free text (P5.3: nothing for redaction to strip). */
-function runAnalyzedBody(summary) {
+function runAnalyzedBody(summary, fallbackRunId) {
     return {
-        run_id: summary.runId,
+        run_id: summary.runId || fallbackRunId || "unknown-run",
         units: summary.units.map((u) => ({
             unit_id: u.unitId,
             turns_total: u.turnsTotal,
@@ -160,7 +223,11 @@ async function appendRunAnalyzed(harness, runId, summary) {
     // doubles for both (and, since `session` is unset, for `actor.id` too —
     // assembleRun already sets actorId to runId). Redundant with body.run_id,
     // but harmless — not a copy-paste bug.
-    await harness.ledgerAppend({ type: "run.analyzed", unitId: runId, body: runAnalyzedBody(summary) });
+    await harness.ledgerAppend({
+        type: "run.analyzed",
+        unitId: runId,
+        body: runAnalyzedBody(summary, runId),
+    });
 }
 /**
  * P2 — runs automatically at the end of `orchestrate run`/`resume`. A no-op
@@ -168,7 +235,7 @@ async function appendRunAnalyzed(harness, runId, summary) {
  * isn't a silent surprise — we tell the operator why. Appends one bounded
  * `run.analyzed` ledger event unless `--no-ledger` is passed.
  */
-async function runAutoAnalyze(deps, repo, runId, state) {
+async function runAutoAnalyze(deps, repo, runId, state, cliThresholds) {
     if (!deps.activityLog) {
         process.stderr.write("orchestrate: activity capture was disabled — skipping analysis\n");
         return null;
@@ -176,7 +243,12 @@ async function runAutoAnalyze(deps, repo, runId, state) {
     const events = deps.activityLog.events(); // in-process — no re-read of the file needed
     const costByUnit = new Map(state.lanes.map((l) => [l.unitId, l.cost]));
     const logRef = `runs/${runId}/activity.jsonl`;
-    const summary = analyzeRun(events, { logRef, costByUnit });
+    const thresholds = resolveThresholds(deps.config.analyze?.thresholds, cliThresholds);
+    const summary = analyzeRun(events, {
+        logRef,
+        costByUnit,
+        ...(thresholds ? { thresholds } : {}),
+    });
     const summaryPath = join(repo, ".harness", "runs", runId, "summary.json");
     writeFileSync(summaryPath, JSON.stringify(summary, null, 2));
     if (!hasFlag("no-ledger")) {
@@ -211,10 +283,17 @@ function report() {
 async function demo() {
     const harness = new FakeHarness([
         { id: "a", scope: ["src/a/**"], mergeFacts: { door: "two-way" } },
-        { id: "b", deps: ["a"], scope: ["src/b/**"], mergeFacts: { door: "two-way" } },
+        {
+            id: "b",
+            deps: ["a"],
+            scope: ["src/b/**"],
+            mergeFacts: { door: "two-way" },
+        },
         { id: "spike", mode: "explore", scope: ["src/spike/**"] },
     ]);
-    const runners = new Map([["claude", new FakeRunner({ name: "claude" })]]);
+    const runners = new Map([
+        ["claude", new FakeRunner({ name: "claude" })],
+    ]);
     const deps = {
         harness,
         routes: new FakeRouteSource(),
@@ -237,6 +316,14 @@ function hasFlag(name) {
     return process.argv.includes(`--${name}`);
 }
 async function realRun() {
+    let cliThresholds;
+    try {
+        cliThresholds = parseCliThresholds();
+    }
+    catch (e) {
+        process.stderr.write(`orchestrate run: ${e.message}\n`);
+        return 2;
+    }
     const configPath = flag("config");
     const routesPath = flag("routes");
     const spoolDir = flag("spool");
@@ -244,6 +331,7 @@ async function realRun() {
     const watch = hasFlag("watch");
     const activityLogDir = flag("activity-log");
     const noActivityLog = hasFlag("no-activity-log");
+    const worktreeRoot = flag("worktree-root");
     let assembled;
     try {
         assembled = assembleRun({
@@ -255,6 +343,7 @@ async function realRun() {
             ...(watch ? { watch } : {}),
             ...(activityLogDir ? { activityLogDir } : {}),
             ...(noActivityLog ? { activityLog: false } : {}),
+            ...(worktreeRoot ? { worktreeRoot } : {}),
         });
     }
     catch (e) {
@@ -264,18 +353,37 @@ async function realRun() {
     const repo = resolve(flag("repo") ?? process.cwd());
     applyStubRunners(assembled.deps, repo);
     const { deps, runId, systemId, specRef } = assembled;
-    const dagSize = (await deps.harness.units()).length;
+    const allUnits = await deps.harness.units();
+    const stories = loadUnitStories({ repo });
+    if (onlyPrefix &&
+        !allUnits.some((u) => matchesOnly({
+            id: u.id,
+            story: u.story ?? stories.get(u.id),
+        }, onlyPrefix))) {
+        process.stderr.write(`orchestrate run: no units match --only prefix "${onlyPrefix}"\n`);
+        return 1;
+    }
+    const dagSize = allUnits.length;
     const state = await runLoop(deps, { specRef, systemId, dagSize });
-    const analysis = await runAutoAnalyze(deps, repo, runId, state);
+    const analysis = await runAutoAnalyze(deps, repo, runId, state, cliThresholds);
     summarise(state, analysis);
     return exitCodeForRunState(state);
 }
 async function resume() {
+    let cliThresholds;
+    try {
+        cliThresholds = parseCliThresholds();
+    }
+    catch (e) {
+        process.stderr.write(`orchestrate resume: ${e.message}\n`);
+        return 2;
+    }
     const unitId = flag("unit");
     if (!unitId) {
         process.stderr.write("orchestrate resume --unit <id> [--repo <path>] [--routes <path>]\n");
         return 2;
     }
+    const repo = resolve(flag("repo") ?? process.cwd());
     const configPath = flag("config");
     const routesPath = flag("routes");
     const spoolDir = flag("spool");
@@ -284,10 +392,19 @@ async function resume() {
     const activityLogDir = flag("activity-log");
     const noActivityLog = hasFlag("no-activity-log");
     const resumesRunId = flag("resumes");
+    const explicitWorktreeRoot = flag("worktree-root");
+    let worktreeRoot = explicitWorktreeRoot;
+    if (!worktreeRoot) {
+        worktreeRoot = await resolveResumeWorktreeRoot({
+            repo,
+            unitId,
+            resumesRunId,
+        });
+    }
     let assembled;
     try {
         assembled = assembleRun({
-            repo: flag("repo") ?? process.cwd(),
+            repo,
             ...(configPath ? { configPath } : {}),
             ...(routesPath ? { routesPath } : {}),
             ...(onlyPrefix ? { onlyPrefix } : {}),
@@ -296,13 +413,13 @@ async function resume() {
             ...(activityLogDir ? { activityLogDir } : {}),
             ...(noActivityLog ? { activityLog: false } : {}),
             ...(resumesRunId ? { resumesRunId } : {}),
+            ...(worktreeRoot ? { worktreeRoot } : {}),
         });
     }
     catch (error) {
         process.stderr.write(`orchestrate resume: ${error.message}\n`);
         return 2;
     }
-    const repo = resolve(flag("repo") ?? process.cwd());
     applyStubRunners(assembled.deps, repo);
     const dagSize = (await assembled.deps.harness.units()).length;
     const result = await resumeAfterDoor(unitId, assembled.deps);
@@ -317,33 +434,95 @@ async function resume() {
         systemId: assembled.systemId,
         dagSize,
     });
-    const analysis = await runAutoAnalyze(assembled.deps, repo, assembled.runId, state);
+    const analysis = await runAutoAnalyze(assembled.deps, repo, assembled.runId, state, cliThresholds);
     summarise(state, analysis);
     return exitCodeForRunState(state);
 }
+async function catchUpInterruptedRuns(repo, harness, configThresholds) {
+    const runsRoot = join(repo, ".harness", "runs");
+    let entries;
+    try {
+        entries = readdirSync(runsRoot, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const analyzed = [];
+    for (const runId of entries) {
+        const runDir = join(runsRoot, runId);
+        const activityPath = join(runDir, "activity.jsonl");
+        const summaryPath = join(runDir, "summary.json");
+        if (existsSync(summaryPath))
+            continue;
+        if (!existsSync(activityPath))
+            continue;
+        let content;
+        try {
+            content = readFileSync(activityPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let events;
+        try {
+            events = parseActivityLog(content);
+        }
+        catch {
+            continue;
+        }
+        const logRef = `runs/${runId}/activity.jsonl`;
+        const summary = analyzeRun(events, {
+            logRef,
+            ...(configThresholds ? { thresholds: configThresholds } : {}),
+        });
+        writeFileSync(summaryPath, JSON.stringify(summary, null, 2));
+        if (!hasFlag("no-ledger")) {
+            try {
+                await appendRunAnalyzed(harness, runId, summary);
+            }
+            catch (e) {
+                process.stderr.write(`orchestrate sweep: run.analyzed ledger append failed for ${runId}: ${e.message}\n`);
+            }
+        }
+        analyzed.push(runId);
+    }
+    return analyzed;
+}
 async function sweep() {
+    const repo = resolve(flag("repo") ?? process.cwd());
     const configPath = flag("config");
     const routesPath = flag("routes");
     const onlyPrefix = flag("only");
+    const worktreeRoot = flag("worktree-root");
     let assembled;
     try {
         assembled = assembleRun({
-            repo: flag("repo") ?? process.cwd(),
+            repo,
             ...(configPath ? { configPath } : {}),
             ...(routesPath ? { routesPath } : {}),
             ...(onlyPrefix ? { onlyPrefix } : {}),
+            ...(worktreeRoot ? { worktreeRoot } : {}),
+            activityLog: false,
         });
     }
     catch (error) {
         process.stderr.write(`orchestrate sweep: ${error.message}\n`);
         return 2;
     }
-    applyStubRunners(assembled.deps, resolve(flag("repo") ?? process.cwd()));
+    applyStubRunners(assembled.deps, repo);
+    const analyzed = await catchUpInterruptedRuns(repo, assembled.deps.harness, assembled.deps.config.analyze?.thresholds);
     const halts = await startupSweep(assembled.deps);
     if (process.argv.includes("--json")) {
-        process.stdout.write(JSON.stringify(halts, null, 2) + "\n");
+        const payload = halts.length > 0 && analyzed.length === 0 ? halts : { halts, analyzed };
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
     }
     else {
+        for (const runId of analyzed) {
+            process.stdout.write(`  ✓ caught up interrupted run ${runId}\n`);
+        }
         for (const halt of halts) {
             process.stderr.write(`  ⛔ ${halt.kind} ${halt.unitId ?? ""}: ${halt.message}\n`);
         }
@@ -359,7 +538,10 @@ function findLastRunId(runsRoot) {
     catch {
         return undefined;
     }
-    return entries.filter((e) => e.startsWith("run-")).sort().at(-1);
+    return entries
+        .filter((e) => e.startsWith("run-"))
+        .sort()
+        .at(-1);
 }
 async function analyze() {
     const repo = resolve(flag("repo") ?? process.cwd());
@@ -383,8 +565,40 @@ async function analyze() {
         process.stderr.write(`orchestrate analyze: cannot read ${logPath}: ${e.message}\n`);
         return 2;
     }
+    const configPath = flag("config") ?? join(repo, "orchestration.json");
+    let fileConfig;
+    if (flag("config")) {
+        try {
+            fileConfig = loadOrchestrationConfig(configPath);
+        }
+        catch (e) {
+            process.stderr.write(`orchestrate analyze: ${e.message}\n`);
+            return 2;
+        }
+    }
+    else if (existsSync(configPath)) {
+        try {
+            fileConfig = loadOrchestrationConfig(configPath);
+        }
+        catch (e) {
+            process.stderr.write(`orchestrate analyze: ${e.message}\n`);
+            return 2;
+        }
+    }
+    let cliThresholds;
+    try {
+        cliThresholds = parseCliThresholds();
+    }
+    catch (e) {
+        process.stderr.write(`orchestrate analyze: ${e.message}\n`);
+        return 2;
+    }
+    const thresholds = resolveThresholds(fileConfig?.analyze?.thresholds, cliThresholds);
     const logRef = runId ? `runs/${runId}/activity.jsonl` : logPath;
-    const summary = analyzeRun(events, { logRef });
+    const summary = analyzeRun(events, {
+        logRef,
+        ...(thresholds ? { thresholds } : {}),
+    });
     const outPath = flag("out") ?? (runId ? join(runsRoot, runId, "summary.json") : undefined);
     if (outPath)
         writeFileSync(outPath, JSON.stringify(summary, null, 2));