@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/orchestration/cli.js

@@ -0,0 +1,475 @@
+#!/usr/bin/env node
+/**
+ * orchestrate — the execution-loop entrypoint.
+ *
+ *   orchestrate run [--repo <path>] [--config <path>]
+ *       drive the spec DAG in a real checkout — CliHarness + CliRouteSource +
+ *       ShellGit + LocalForge/GithubForge + ClaudeRunner, per orchestration.json.
+ *   orchestrate demo
+ *       the M1 dry loop against a fake DAG — prints RunState.
+ *
+ * `orchestrate report` (end-of-run HTML from the final RunState — D2) is M5.
+ */
+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 { join, resolve } from "node:path";
+import { DEFAULT_CONFIG, FakeGit, resumeAfterDoor, runLoop, startupSweep, } from "./loop/index.js";
+import { renderRunReport } from "./report/index.js";
+import { assembleRun } from "./run/index.js";
+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";
+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]
+                         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;
+                         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
+  orchestrate doctor [--repo <path>] --routes <path> [--spool <path>] [--json]
+                         read-only preflight; --allow-dirty makes dirt a warning
+  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>]
+                         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)
+  orchestrate demo [--report <path>]
+                         the M1 dry loop against a fake DAG, prints RunState
+  orchestrate analyze [--run <id> | --last | --log <path>] [--repo <path>]
+                      [--out <path>] [--json] [--no-ledger]
+                         synthesize a captured activity.jsonl into findings (P1);
+                         --run/--last resolve under <repo>/.harness/runs/, or pass --log directly;
+                         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)
+  orchestrate --help     this text
+
+Env: HARNESS_MACHINE_ID, ORCHESTRATE_STUB_RUNNER, ORCHESTRATE_STUB_CONFIG.
+  Development-only escape hatch (not for installed packages): HARNESS_BIN, AGENT_HARNESS_BIN.
+`;
+function exitCodeForRunState(state) {
+    if (state.outcome === "completed")
+        return 0;
+    if (state.needsYou.some((entry) => entry.kind === "one-way-door"))
+        return 2;
+    return 1;
+}
+function exitCodeForSweepHalts(halts) {
+    return halts.length === 0 ? 0 : 1;
+}
+function readStubEnvConfig() {
+    if (process.env.ORCHESTRATE_STUB_RUNNER !== "1")
+        return null;
+    const path = process.env.ORCHESTRATE_STUB_CONFIG;
+    if (!path)
+        return {};
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function buildStubRunner(repo, config, stubConfig) {
+    const afterImplement = (unitId) => {
+        const action = stubConfig.afterImplement?.[unitId];
+        if (action === "ledger-unwritable") {
+            const ledgerDir = join(repo, ".harness", "ledger");
+            renameSync(ledgerDir, `${ledgerDir}-saved`);
+            writeFileSync(ledgerDir, "fault injection");
+        }
+    };
+    const stub = new StubRunner({
+        cwd: repo,
+        baseBranch: config.baseBranch,
+        ...(Object.keys(stubConfig.afterImplement ?? {}).length ? { afterImplement } : {}),
+    });
+    for (const [unitId, mode] of Object.entries(stubConfig.scripts ?? {})) {
+        if (mode === "out-of-scope")
+            stub.scriptOutOfScope(unitId);
+        else if (mode === "fail")
+            stub.scriptFail(unitId);
+        else if (mode === "escalate")
+            stub.scriptEscalate(unitId);
+    }
+    return stub;
+}
+/** E2E-only: swap real runners for StubRunner after assembleRun. */
+function applyStubRunners(deps, repo) {
+    const stubConfig = readStubEnvConfig();
+    if (stubConfig === null)
+        return;
+    const stub = buildStubRunner(repo, deps.config, stubConfig);
+    for (const name of deps.config.runnersEnabled)
+        deps.runners.set(name, stub);
+    if (stubConfig.retryBudget !== undefined)
+        deps.config.retryBudget = stubConfig.retryBudget;
+}
+function flag(name) {
+    const i = process.argv.indexOf(`--${name}`);
+    return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : undefined;
+}
+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} ` +
+        `parked=${state.counts.parked} escalated=${state.counts.escalated} ` +
+        `needsYou=${state.counts.needsYou}\n`);
+    for (const n of state.needsYou) {
+        process.stdout.write(`  needs-you [${n.kind}] ${n.unitId ?? ""}: ${n.unblock}\n`);
+    }
+    const reportPath = flag("report");
+    if (reportPath) {
+        writeFileSync(reportPath, renderRunReport(state, analysis ?? undefined));
+        process.stdout.write(`\nreport → ${reportPath}\n`);
+    }
+}
+/** the `run.analyzed` body — metrics and rule ids only, no free text (P5.3: nothing for redaction to strip). */
+function runAnalyzedBody(summary) {
+    return {
+        run_id: summary.runId,
+        units: summary.units.map((u) => ({
+            unit_id: u.unitId,
+            turns_total: u.turnsTotal,
+            tool_failures: u.toolFailures,
+            attempts: u.attempts,
+            wall_ms: u.wallMs,
+            agent_ms: u.agentMs,
+            ...(u.costUsd !== undefined ? { cost_usd: u.costUsd } : {}),
+            runner: u.runner,
+            model: u.model,
+        })),
+        findings: summary.findings.map((f) => ({
+            rule: f.id,
+            unit_id: f.unitId,
+            severity: f.severity,
+            count: f.evidence.length,
+        })),
+        log_ref: summary.logRef,
+    };
+}
+async function appendRunAnalyzed(harness, runId, summary) {
+    // run-scoped event — CliHarness.ledgerAppend always folds `unitId` into
+    // `body.unit_id`; there is no single natural unit for a whole run, so `runId`
+    // 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) });
+}
+/**
+ * P2 — runs automatically at the end of `orchestrate run`/`resume`. A no-op
+ * when capture was disabled (`--no-activity-log`) so a missing summary.json
+ * 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) {
+    if (!deps.activityLog) {
+        process.stderr.write("orchestrate: activity capture was disabled — skipping analysis\n");
+        return null;
+    }
+    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 summaryPath = join(repo, ".harness", "runs", runId, "summary.json");
+    writeFileSync(summaryPath, JSON.stringify(summary, null, 2));
+    if (!hasFlag("no-ledger")) {
+        try {
+            await appendRunAnalyzed(deps.harness, runId, summary);
+        }
+        catch (e) {
+            process.stderr.write(`orchestrate: run.analyzed ledger append failed: ${e.message}\n`);
+        }
+    }
+    return summary;
+}
+function report() {
+    const statePath = flag("state");
+    if (!statePath) {
+        process.stderr.write("orchestrate report --state <run-state.json> [--out <path>]\n");
+        return 2;
+    }
+    let state;
+    try {
+        state = JSON.parse(readFileSync(statePath, "utf8"));
+    }
+    catch (e) {
+        process.stderr.write(`orchestrate report: cannot read ${statePath}: ${e.message}\n`);
+        return 2;
+    }
+    const out = flag("out") ?? "run-report.html";
+    writeFileSync(out, renderRunReport(state));
+    process.stdout.write(`report → ${out}\n`);
+    return 0;
+}
+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: "spike", mode: "explore", scope: ["src/spike/**"] },
+    ]);
+    const runners = new Map([["claude", new FakeRunner({ name: "claude" })]]);
+    const deps = {
+        harness,
+        routes: new FakeRouteSource(),
+        runners,
+        git: new FakeGit(),
+        config: { ...DEFAULT_CONFIG, runnersEnabled: ["claude"] },
+        log: new RunLog(),
+        runId: "demo-run",
+        machineId: "local",
+    };
+    const state = await runLoop(deps, {
+        specRef: "specs/demo.yaml",
+        systemId: "demo",
+        dagSize: 3,
+    });
+    summarise(state);
+    return state.outcome === "completed" ? 0 : 1;
+}
+function hasFlag(name) {
+    return process.argv.includes(`--${name}`);
+}
+async function realRun() {
+    const configPath = flag("config");
+    const routesPath = flag("routes");
+    const spoolDir = flag("spool");
+    const onlyPrefix = flag("only");
+    const watch = hasFlag("watch");
+    const activityLogDir = flag("activity-log");
+    const noActivityLog = hasFlag("no-activity-log");
+    let assembled;
+    try {
+        assembled = assembleRun({
+            repo: flag("repo") ?? process.cwd(),
+            ...(configPath ? { configPath } : {}),
+            ...(routesPath ? { routesPath } : {}),
+            ...(onlyPrefix ? { onlyPrefix } : {}),
+            ...(spoolDir ? { spoolDir } : {}),
+            ...(watch ? { watch } : {}),
+            ...(activityLogDir ? { activityLogDir } : {}),
+            ...(noActivityLog ? { activityLog: false } : {}),
+        });
+    }
+    catch (e) {
+        process.stderr.write(`orchestrate run: ${e.message}\n`);
+        return 2;
+    }
+    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 state = await runLoop(deps, { specRef, systemId, dagSize });
+    const analysis = await runAutoAnalyze(deps, repo, runId, state);
+    summarise(state, analysis);
+    return exitCodeForRunState(state);
+}
+async function resume() {
+    const unitId = flag("unit");
+    if (!unitId) {
+        process.stderr.write("orchestrate resume --unit <id> [--repo <path>] [--routes <path>]\n");
+        return 2;
+    }
+    const configPath = flag("config");
+    const routesPath = flag("routes");
+    const spoolDir = flag("spool");
+    const onlyPrefix = flag("only");
+    const watch = hasFlag("watch");
+    const activityLogDir = flag("activity-log");
+    const noActivityLog = hasFlag("no-activity-log");
+    const resumesRunId = flag("resumes");
+    let assembled;
+    try {
+        assembled = assembleRun({
+            repo: flag("repo") ?? process.cwd(),
+            ...(configPath ? { configPath } : {}),
+            ...(routesPath ? { routesPath } : {}),
+            ...(onlyPrefix ? { onlyPrefix } : {}),
+            ...(spoolDir ? { spoolDir } : {}),
+            ...(watch ? { watch } : {}),
+            ...(activityLogDir ? { activityLogDir } : {}),
+            ...(noActivityLog ? { activityLog: false } : {}),
+            ...(resumesRunId ? { resumesRunId } : {}),
+        });
+    }
+    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);
+    if (result.outcome !== "merged") {
+        process.stderr.write(result.outcome === "halted"
+            ? `${result.halt.message}\n  ${result.halt.unblock}\n`
+            : `${unitId} was not resumed (${result.outcome})\n`);
+        return 1;
+    }
+    const state = await runLoop(assembled.deps, {
+        specRef: assembled.specRef,
+        systemId: assembled.systemId,
+        dagSize,
+    });
+    const analysis = await runAutoAnalyze(assembled.deps, repo, assembled.runId, state);
+    summarise(state, analysis);
+    return exitCodeForRunState(state);
+}
+async function sweep() {
+    const configPath = flag("config");
+    const routesPath = flag("routes");
+    const onlyPrefix = flag("only");
+    let assembled;
+    try {
+        assembled = assembleRun({
+            repo: flag("repo") ?? process.cwd(),
+            ...(configPath ? { configPath } : {}),
+            ...(routesPath ? { routesPath } : {}),
+            ...(onlyPrefix ? { onlyPrefix } : {}),
+        });
+    }
+    catch (error) {
+        process.stderr.write(`orchestrate sweep: ${error.message}\n`);
+        return 2;
+    }
+    applyStubRunners(assembled.deps, resolve(flag("repo") ?? process.cwd()));
+    const halts = await startupSweep(assembled.deps);
+    if (process.argv.includes("--json")) {
+        process.stdout.write(JSON.stringify(halts, null, 2) + "\n");
+    }
+    else {
+        for (const halt of halts) {
+            process.stderr.write(`  ⛔ ${halt.kind} ${halt.unitId ?? ""}: ${halt.message}\n`);
+        }
+    }
+    return exitCodeForSweepHalts(halts);
+}
+/** run ids are `run-${Date.now().toString(36)}` — sorts chronologically as a string. */
+function findLastRunId(runsRoot) {
+    let entries;
+    try {
+        entries = readdirSync(runsRoot);
+    }
+    catch {
+        return undefined;
+    }
+    return entries.filter((e) => e.startsWith("run-")).sort().at(-1);
+}
+async function analyze() {
+    const repo = resolve(flag("repo") ?? process.cwd());
+    const runsRoot = join(repo, ".harness", "runs");
+    let logPath = flag("log");
+    let runId = flag("run");
+    if (!logPath) {
+        if (hasFlag("last"))
+            runId = findLastRunId(runsRoot);
+        if (!runId) {
+            process.stderr.write("orchestrate analyze: pass --run <id>, --last, or --log <path>\n");
+            return 2;
+        }
+        logPath = join(runsRoot, runId, "activity.jsonl");
+    }
+    let events;
+    try {
+        events = parseActivityLog(readFileSync(logPath, "utf8"));
+    }
+    catch (e) {
+        process.stderr.write(`orchestrate analyze: cannot read ${logPath}: ${e.message}\n`);
+        return 2;
+    }
+    const logRef = runId ? `runs/${runId}/activity.jsonl` : logPath;
+    const summary = analyzeRun(events, { logRef });
+    const outPath = flag("out") ?? (runId ? join(runsRoot, runId, "summary.json") : undefined);
+    if (outPath)
+        writeFileSync(outPath, JSON.stringify(summary, null, 2));
+    if (hasFlag("json")) {
+        process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(`run ${summary.runId || "(unknown)"} — ${summary.units.length} unit(s), ${summary.findings.length} finding(s)\n`);
+        for (const f of summary.findings) {
+            process.stdout.write(`  [${f.severity}] ${f.id} ${f.unitId}: ${f.message} (${f.evidence.length} evidence line(s))\n`);
+        }
+        if (outPath)
+            process.stdout.write(`\nsummary → ${outPath}\n`);
+    }
+    if (!hasFlag("no-ledger") && runId) {
+        try {
+            const assembled = assembleRun({ repo, activityLog: false });
+            await appendRunAnalyzed(assembled.deps.harness, runId, summary);
+        }
+        catch (e) {
+            process.stderr.write(`orchestrate analyze: run.analyzed ledger append failed: ${e.message}\n`);
+        }
+    }
+    return 0;
+}
+async function doctor() {
+    const repo = flag("repo") ?? process.cwd();
+    const routesPath = flag("routes") ?? `${repo}/routes.toml`;
+    try {
+        const report = await runDoctor({
+            repo,
+            ...(flag("config") ? { configPath: flag("config") } : {}),
+            routesPath,
+            ...(flag("spool") ? { spoolDir: flag("spool") } : {}),
+            allowDirty: process.argv.includes("--allow-dirty"),
+            harness: resolveCommandSpec(process.env.HARNESS_BIN ?? "harness", repo),
+            agentHarness: resolveCommandSpec(process.env.AGENT_HARNESS_BIN ?? "agent-harness", repo),
+        });
+        if (process.argv.includes("--json")) {
+            process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        }
+        else {
+            for (const check of report.checks) {
+                const mark = check.status === "pass" ? "✓" : check.status === "warn" ? "⚠" : "✗";
+                process.stdout.write(`  ${mark} ${check.id}: ${check.detail}\n`);
+                if (check.fix)
+                    process.stdout.write(`      fix: ${check.fix}\n`);
+            }
+            process.stdout.write(`\ndoctor: ${report.status}\n`);
+        }
+        return report.status === "ready" ? 0 : 1;
+    }
+    catch (error) {
+        process.stderr.write(`orchestrate doctor: ${error.message}\n`);
+        return 2;
+    }
+}
+const cmd = process.argv[2];
+if (cmd === "--help" || cmd === "-h" || cmd === undefined) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+}
+else if (cmd === "demo") {
+    demo().then((c) => process.exit(c));
+}
+else if (cmd === "run") {
+    realRun().then((c) => process.exit(c));
+}
+else if (cmd === "doctor") {
+    doctor().then((c) => process.exit(c));
+}
+else if (cmd === "resume") {
+    resume().then((c) => process.exit(c));
+}
+else if (cmd === "sweep") {
+    sweep().then((c) => process.exit(c));
+}
+else if (cmd === "analyze") {
+    analyze().then((c) => process.exit(c));
+}
+else if (cmd === "report") {
+    process.exit(report());
+}
+else {
+    process.stderr.write(`unknown command "${cmd}"\n\n${USAGE}`);
+    process.exit(2);
+}
+//# sourceMappingURL=cli.js.map

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

@@ -0,0 +1,66 @@
+/**
+ * config — `orchestration.json`, the run policy file (successor to the
+ * prototype's `drive.json`). It holds ONLY what is genuinely orchestration:
+ * concurrency, retries, run budgets, forge, and which runner implementations
+ * this installation has. Model/runner *selection* is agent-harness's
+ * `resolveRoute` — `drive`'s `models.rules` matcher is deliberately not ported.
+ *
+ *   { forge, baseBranch, maxParallel, retryBudget,
+ *     maxRunCost?, maxRunDuration?, runners: { enabled: [...] } }
+ */
+import { readFileSync } from "node:fs";
+import { DEFAULT_CONFIG } from "../loop/index.js";
+export class ConfigError extends Error {
+    name = "ConfigError";
+}
+export function parseOrchestrationConfig(raw, source = "orchestration.json") {
+    if (raw === null || typeof raw !== "object") {
+        throw new ConfigError(`${source}: expected a JSON object`);
+    }
+    const f = raw;
+    if (f.forge !== undefined && f.forge !== "local" && f.forge !== "github") {
+        throw new ConfigError(`${source}: forge must be "local" or "github"`);
+    }
+    for (const k of ["maxParallel", "retryBudget", "maxRunCost", "maxRunDuration"]) {
+        if (f[k] !== undefined && (typeof f[k] !== "number" || f[k] < 0)) {
+            throw new ConfigError(`${source}: ${k} must be a non-negative number`);
+        }
+    }
+    const enabled = f.runners?.enabled;
+    if (enabled !== undefined && (!Array.isArray(enabled) || enabled.some((e) => typeof e !== "string"))) {
+        throw new ConfigError(`${source}: runners.enabled must be an array of strings`);
+    }
+    const cfg = {
+        forge: f.forge ?? DEFAULT_CONFIG.forge,
+        baseBranch: f.baseBranch ?? DEFAULT_CONFIG.baseBranch,
+        maxParallel: f.maxParallel ?? DEFAULT_CONFIG.maxParallel,
+        retryBudget: f.retryBudget ?? DEFAULT_CONFIG.retryBudget,
+        systemToml: f.systemToml ?? DEFAULT_CONFIG.systemToml,
+        runnersEnabled: enabled ?? DEFAULT_CONFIG.runnersEnabled,
+    };
+    // optional run-level circuit breakers — absent means uncapped (an explicit
+    // operator choice, never a silent default).
+    if (f.maxRunCost !== undefined)
+        cfg.maxRunCost = f.maxRunCost;
+    if (f.maxRunDuration !== undefined)
+        cfg.maxRunDuration = f.maxRunDuration;
+    return cfg;
+}
+export function loadOrchestrationConfig(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        throw new ConfigError(`orchestration.json not found at ${path}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new ConfigError(`${path}: invalid JSON — ${e.message}`);
+    }
+    return parseOrchestrationConfig(raw, path);
+}
+//# sourceMappingURL=index.js.map