harnery 0.14.0 → 0.15.0

package/README.md

@@ -23,6 +23,7 @@
 - **Cross-machine presence:** sessions on every machine that shares a repo see each other, labeled by machine. Zero-config over the repo's own git remote (presence refs), with an optional live-socket upgrade via an end-to-end-encrypted relay — the public `relay.harnery.com`, or self-host with `harn relay serve` / the bundled Cloudflare Worker (`relay/worker/`). The relay sees only ciphertext in opaquely-named rooms.
 - **Coordination-aware workflows:** `harn workflow run <script>` executes bounded, schema-gated multi-subagent workflow scripts — plain JS stages fanning out to headless harness-CLI subagents that are born coordination-registered (heartbeats, events, claim guards), with deterministic code deciding the routing between stages. An optional host-owned policy gates dispatch and declared external mutations with `ALLOW`, `ASK`, and `DENY`; CLI `ASK` requests park durably for an explicit approve/deny and same-run resume, while library callers remain fail-closed by default.
 - **Durable work above attempts:** `harn work` preserves an objective across bounded workflow attempts, dependencies, approval parks, failures, and review. Its one-shot reconciler derives state from append-only local evidence and reports the next explicit action without silently spawning, retrying, or accepting work.
+- **Bounded goal supervision:** `harn supervisor` freezes a specialist team and safety limits around a root durable-work graph, then runs foreground scheduling cycles until success, human attention, no progress, or budget exhaustion. Specialist roles survive as configuration while every child remains a bounded process.
 - **Standalone web UI:** `harn web up` boots a local Next.js dashboard for the coord layer, councils, per-project state, and a local coding-agent status view (Claude Code / Codex / Cursor usage, backed by `harn devtools`). Ships with the git clone, not the npm package (see [Install](#install)).
 - **Backup + sync:** `harn backup` snapshots `.harnery/` via [restic](https://restic.net/); `harn sync` keeps a curated subset live across machines via [rclone](https://rclone.org/) (Google Drive or any rclone remote).
 

package/dist/commander.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"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"}

package/dist/commander.js

@@ -47,6 +47,7 @@ import { registerReadCommand } from "./commands/read.js";
 import { registerRelayCommand } from "./commands/relay.js";
 import { registerScratchCommand } from "./commands/scratch.js";
 import { registerSessionCommand } from "./commands/session.js";
+import { registerSupervisorCommand } from "./commands/supervisor.js";
 import { registerSyncCommand } from "./commands/sync.js";
 import { registerSectionCommand, registerTocCommand } from "./commands/toc.js";
 import { registerTokensCommand } from "./commands/tokens.js";
@@ -134,6 +135,7 @@ export function createHarneryProgram(opts = {}) {
     registerSyncCommand(program, emit);
     registerWorkflowCommand(program, emit);
     registerWorkCommand(program, emit);
+    registerSupervisorCommand(program, emit);
     if (include("web"))
         registerWebCommand(program, emit);
     return program;

package/dist/commands/supervisor.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerSupervisorCommand(program: Command, emit: EmitContext): void;
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/commands/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/commands/supervisor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA4CnD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA0FnF"}

package/dist/commands/supervisor.js

@@ -0,0 +1,238 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { workflowSubscriptionOnly } from "../core/config.js";
+import { createBuiltinHarnessRegistry } from "../core/harnesses/index.js";
+import { findCoordRoot } from "../core/hooks/resolve/coord-root.js";
+import { loadPolicyFile } from "../core/policy/index.js";
+import { createSupervisor, listSupervisors, readSupervisor, runSupervisor, } from "../core/supervisor/index.js";
+export function registerSupervisorCommand(program, emit) {
+    const registry = createBuiltinHarnessRegistry();
+    const supervisor = program
+        .command("supervisor")
+        .description("Run a bounded specialist team over a durable-work dependency graph.");
+    supervisor
+        .command("create <root-work-id>")
+        .description("Freeze a goal, specialist team, automation policy, and execution limits.")
+        .requiredOption("--team <file>", "JSON object mapping specialist ids to profiles")
+        .option("--id <goal-id>", "Stable goal id (generated by default)")
+        .option("--title <text>", "Goal title (defaults to root work title)")
+        .option("--max-cycles <n>", "Foreground cycle ceiling (default 50)")
+        .option("--max-runtime-ms <n>", "Foreground wall-time ceiling (default 14400000)")
+        .option("--max-parallel-work <n>", "Concurrent work-item ceiling (default 1)")
+        .option("--max-total-attempts <n>", "Graph-wide attempt ceiling (default 100)")
+        .option("--max-agents-per-work <n>", "Child-agent ceiling per work item (default 20)")
+        .option("--agent-concurrency <n>", "Child concurrency per work item (default 4)")
+        .option("--accept-passing-proof", "Allow the supervisor to explicitly accept passing proof")
+        .option("--no-resume-approved", "Stop after an approval instead of resuming its parked run")
+        .option("--retry-blocked", "Allow bounded retry of blocked work")
+        .option("--json", "Emit the complete supervisor record as JSON")
+        .action((rootWorkId, opts) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+            const specialists = readTeamFile(opts.team);
+            for (const [id, profile] of Object.entries(specialists)) {
+                if (profile.harness && !registry.get(profile.harness)) {
+                    throw new Error(`specialist ${id} names unknown harness ${JSON.stringify(profile.harness)}`);
+                }
+            }
+            emitSupervisor(createSupervisor({
+                coordRoot,
+                rootWorkId,
+                specialists,
+                id: opts.id,
+                title: opts.title,
+                limits: {
+                    max_cycles: integer(opts.maxCycles),
+                    max_runtime_ms: integer(opts.maxRuntimeMs),
+                    max_parallel_work: integer(opts.maxParallelWork),
+                    max_total_attempts: integer(opts.maxTotalAttempts),
+                    max_agents_per_work: integer(opts.maxAgentsPerWork),
+                    agent_concurrency: integer(opts.agentConcurrency),
+                },
+                automation: {
+                    accept_passing_proof: opts.acceptPassingProof,
+                    resume_approved: opts.resumeApproved,
+                    retry_blocked: opts.retryBlocked,
+                },
+            }), opts.json, emit, true);
+        });
+    });
+    supervisor
+        .command("list")
+        .description("List durable goals and their derived next action.")
+        .option("--json", "Emit complete supervisor records as JSON")
+        .action((opts) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+            const records = listSupervisors(coordRoot);
+            if (opts.json) {
+                emit.config({ format: "json" });
+                emit.data(records);
+            }
+            else if (records.length === 0) {
+                emit.text("no durable supervisors\n");
+            }
+            else {
+                emit.text(`${records.map(renderSupervisorRow).join("\n")}\n`);
+            }
+        });
+    });
+    supervisor
+        .command("show <goal-id>")
+        .description("Show one goal, frozen team, bounds, graph state, and next action.")
+        .option("--json", "Emit the complete supervisor record as JSON")
+        .action((goalId, opts) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+            emitSupervisor(readSupervisor(coordRoot, goalId), opts.json, emit, true);
+        });
+    });
+    registerRunCommand(supervisor, "tick", registry, emit);
+    registerRunCommand(supervisor, "run", registry, emit);
+}
+function registerRunCommand(supervisor, mode, registry, emit) {
+    supervisor
+        .command(`${mode} <goal-id>`)
+        .description(mode === "tick"
+        ? "Perform at most one bounded scheduling cycle."
+        : "Run bounded cycles until success, attention, no progress, or budget exhaustion.")
+        .option("--harness <name>", "Fallback harness for agent calls without a specialist")
+        .option("--cwd <dir>", "Working directory for child agents")
+        .option("--subscription-only", "Require stored harness-login billing")
+        .option("--allow-api-billing", "Permit API-key override billing")
+        .option("--policy <file>", "Host policy JSON/JSONC")
+        .option("--isolation <mode>", "shared | worktree | sandbox | remote")
+        .option("--approval-to <address>", "Address durable ASK requests")
+        .option("--actor <name>", "Actor recorded on supervisor work decisions")
+        .option("--json", "Emit the complete run report as JSON")
+        .action(async (goalId, opts) => {
+        await withSupervisorRootAsync(emit, async (coordRoot) => {
+            if (opts.harness && !registry.get(opts.harness)) {
+                throw new Error(`unknown harness ${JSON.stringify(opts.harness)}`);
+            }
+            const report = await runSupervisor({
+                coordRoot,
+                goalId,
+                mode,
+                actor: opts.actor,
+                onLog: opts.json ? undefined : (line) => emit.text(`${line}\n`),
+                engine: {
+                    spawners: registry.spawners(),
+                    defaultHarness: opts.harness,
+                    cwd: opts.cwd,
+                    subscriptionOnly: opts.subscriptionOnly === true ? true : workflowSubscriptionOnly(coordRoot),
+                    allowApiBilling: opts.allowApiBilling,
+                    harnessEvidence: Object.fromEntries(registry
+                        .list()
+                        .map((adapter) => [
+                        adapter.profile.id,
+                        { toolEvidence: adapter.profile.capabilities.toolEvidence },
+                    ])),
+                    policy: opts.policy ? loadPolicyFile(opts.policy) : undefined,
+                    approvalMode: "park",
+                    approvalAddressee: opts.approvalTo,
+                    isolation: opts.isolation,
+                    networkAccess: "enabled",
+                },
+            });
+            emitSupervisorReport(report, opts.json, emit);
+        });
+    });
+}
+function readTeamFile(path) {
+    const absolute = resolve(path);
+    let value;
+    try {
+        value = JSON.parse(readFileSync(absolute, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`cannot read supervisor team at ${absolute}: ${error.message}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("supervisor team must be a JSON object keyed by specialist id");
+    }
+    return value;
+}
+function emitSupervisor(record, json, emit, detail = false) {
+    if (json) {
+        emit.config({ format: "json" });
+        emit.data(record);
+        return;
+    }
+    if (!detail) {
+        emit.text(`${renderSupervisorRow(record)}\n`);
+        return;
+    }
+    const projection = record.projection;
+    const lines = [
+        `${record.intent.id}: ${record.intent.title}`,
+        `state: ${projection.state}`,
+        `root: ${record.intent.root_work_id}`,
+        `reason: ${projection.reason}`,
+        `next: ${projection.next_action}`,
+        `work: ${projection.work_ids.length}`,
+        `attempts: ${projection.attempts_used}/${record.intent.limits.max_total_attempts}`,
+        `specialists: ${projection.specialists.join(", ") || "none"}`,
+        `automation: accept=${record.intent.automation.accept_passing_proof}, ` +
+            `resume=${record.intent.automation.resume_approved}, retry=${record.intent.automation.retry_blocked}`,
+    ];
+    if (projection.attention_work.length) {
+        lines.push(`attention: ${projection.attention_work.join(", ")}`);
+    }
+    emit.text(`${lines.join("\n")}\n`);
+}
+function emitSupervisorReport(report, json, emit) {
+    if (json) {
+        emit.config({ format: "json" });
+        emit.data(report);
+        return;
+    }
+    emit.text(`supervisor ${report.goal_id}: ${report.stop_reason}\n` +
+        `reason: ${report.reason}\n` +
+        `cycles: ${report.cycles}; dispatches: ${report.dispatches}; acceptances: ${report.acceptances}\n` +
+        `state: ${report.projection.state}; next: ${report.projection.next_action}\n`);
+}
+function renderSupervisorRow(record) {
+    const projection = record.projection;
+    return `${record.intent.id}  ${projection.state.padEnd(20)}  ${projection.attempts_used}/${record.intent.limits.max_total_attempts}  ${projection.next_action.padEnd(18)}  ${record.intent.title}`;
+}
+function integer(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value))
+        throw new Error(`expected a positive integer, got ${JSON.stringify(value)}`);
+    return Number.parseInt(value, 10);
+}
+function withSupervisorRoot(emit, fn) {
+    const coordRoot = findCoordRoot();
+    if (!coordRoot) {
+        emit.error({
+            code: "no_coord_root",
+            message: "no .harnery/ coordination root found; run `init` first",
+        });
+        emit.setExitCode(1);
+        return;
+    }
+    try {
+        fn(coordRoot);
+    }
+    catch (error) {
+        emit.error({ code: "supervisor_failed", message: error.message });
+        emit.setExitCode(1);
+    }
+}
+async function withSupervisorRootAsync(emit, fn) {
+    const coordRoot = findCoordRoot();
+    if (!coordRoot) {
+        emit.error({
+            code: "no_coord_root",
+            message: "no .harnery/ coordination root found; run `init` first",
+        });
+        emit.setExitCode(1);
+        return;
+    }
+    try {
+        await fn(coordRoot);
+    }
+    catch (error) {
+        emit.error({ code: "supervisor_failed", message: error.message });
+        emit.setExitCode(1);
+    }
+}

package/dist/core/supervisor/index.d.ts

@@ -0,0 +1,3 @@
+export { type RunSupervisorInput, runSupervisor, type SupervisorDispatchOutcome, type SupervisorRunReport, type SupervisorStopReason, } from "./runner.js";
+export { assertSupervisorId, type CreateSupervisorInput, collectSupervisorWork, createSupervisor, listSupervisors, newSupervisorId, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, type SupervisorAutomationPolicy, type SupervisorIntent, type SupervisorLimits, type SupervisorNextAction, type SupervisorProjection, type SupervisorRecord, type SupervisorState, } from "./state.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/supervisor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,EACd,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC"}

package/dist/core/supervisor/index.js

@@ -0,0 +1,2 @@
+export { runSupervisor, } from "./runner.js";
+export { assertSupervisorId, collectSupervisorWork, createSupervisor, listSupervisors, newSupervisorId, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, } from "./state.js";

package/dist/core/supervisor/read.d.ts

@@ -0,0 +1,2 @@
+export { assertSupervisorId, collectSupervisorWork, listSupervisors, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, type SupervisorAutomationPolicy, type SupervisorIntent, type SupervisorLimits, type SupervisorNextAction, type SupervisorProjection, type SupervisorRecord, type SupervisorState, } from "./state.js";
+//# sourceMappingURL=read.d.ts.map

package/dist/core/supervisor/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/read.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC"}

package/dist/core/supervisor/read.js

@@ -0,0 +1 @@
+export { assertSupervisorId, collectSupervisorWork, listSupervisors, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, } from "./state.js";

package/dist/core/supervisor/runner.d.ts

@@ -0,0 +1,34 @@
+import { type RunWorkItemInput } from "../work/index.js";
+import { type SupervisorProjection } from "./state.js";
+export type SupervisorStopReason = "succeeded" | "awaiting_attention" | "blocked" | "budget_exhausted" | "no_progress" | "tick_complete";
+export interface SupervisorDispatchOutcome {
+    work_id: string;
+    action: "run" | "resume" | "retry";
+    status: "completed" | "parked" | "failed";
+    run_id?: string;
+    error?: string;
+}
+export interface SupervisorRunReport {
+    goal_id: string;
+    mode: "tick" | "run";
+    stop_reason: SupervisorStopReason;
+    reason: string;
+    started_at: string;
+    ended_at: string;
+    duration_ms: number;
+    cycles: number;
+    dispatches: number;
+    acceptances: number;
+    outcomes: SupervisorDispatchOutcome[];
+    projection: SupervisorProjection;
+}
+export interface RunSupervisorInput {
+    coordRoot: string;
+    goalId: string;
+    mode?: "tick" | "run";
+    actor?: string;
+    engine: Omit<RunWorkItemInput["engine"], "maxAgents" | "concurrency" | "specialists">;
+    onLog?: (line: string) => void;
+}
+export declare function runSupervisor(input: RunSupervisorInput): Promise<SupervisorRunReport>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/core/supervisor/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/runner.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EAItB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,oBAAoB,GACpB,SAAS,GACT,kBAAkB,GAClB,aAAa,GACb,eAAe,CAAC;AAEpB,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IACnC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,WAAW,EAAE,oBAAoB,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC,UAAU,EAAE,oBAAoB,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,aAAa,GAAG,aAAa,CAAC,CAAC;IACtF,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAQD,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuJ3F"}

package/dist/core/supervisor/runner.js

@@ -0,0 +1,198 @@
+import { resolve } from "node:path";
+import { acceptWorkItem, reconcileWorkItem, runWorkItem, } from "../work/index.js";
+import { acquireSupervisorLease, readSupervisorIgnoringLease, } from "./state.js";
+export async function runSupervisor(input) {
+    const coordRoot = resolve(input.coordRoot);
+    const mode = input.mode ?? "run";
+    const actor = input.actor?.trim() || `supervisor:${input.goalId}`;
+    const log = input.onLog ?? (() => undefined);
+    const startedAt = new Date().toISOString();
+    const startedMs = Date.now();
+    const release = acquireSupervisorLease(coordRoot, input.goalId);
+    let cycles = 0;
+    let dispatches = 0;
+    let acceptances = 0;
+    const outcomes = [];
+    try {
+        const initial = readSupervisorIgnoringLease(coordRoot, input.goalId);
+        const cycleLimit = mode === "tick" ? 1 : initial.intent.limits.max_cycles;
+        const deadline = startedMs + initial.intent.limits.max_runtime_ms;
+        while (cycles < cycleLimit) {
+            cycles++;
+            let record = refreshGraph(coordRoot, input.goalId, actor);
+            log(`[${record.intent.title}] cycle ${cycles}: ${record.projection.state}; ` +
+                `${record.projection.ready_work.length} ready, ${record.projection.attention_work.length} attention`);
+            if (record.projection.state === "succeeded") {
+                return report("succeeded", record.projection.reason, record);
+            }
+            if (Date.now() >= deadline) {
+                return report("budget_exhausted", "supervisor wall-time limit reached", record);
+            }
+            const before = graphFingerprint(record);
+            let changed = false;
+            if (record.intent.automation.accept_passing_proof) {
+                for (const work of record.work) {
+                    if (work.projection.state !== "in_review")
+                        continue;
+                    acceptWorkItem(coordRoot, work.intent.id, {
+                        actor,
+                        reason: "passing proof accepted by frozen supervisor policy",
+                    });
+                    acceptances++;
+                    changed = true;
+                    log(`[${record.intent.title}] accepted ${work.intent.id} from passing proof`);
+                }
+                if (changed)
+                    record = refreshGraph(coordRoot, input.goalId, actor);
+                if (record.projection.state === "succeeded") {
+                    return report("succeeded", record.projection.reason, record);
+                }
+            }
+            const candidates = selectCandidates(record);
+            const selected = selectWithinAttemptBudget(record, candidates).slice(0, record.intent.limits.max_parallel_work);
+            if (selected.length > 0 && Date.now() < deadline) {
+                const settled = await Promise.all(selected.map(async (candidate) => {
+                    dispatches++;
+                    log(`[${record.intent.title}] ${candidate.action} ${candidate.record.intent.id}`);
+                    try {
+                        const result = await runWorkItem({
+                            coordRoot,
+                            workId: candidate.record.intent.id,
+                            retry: candidate.action === "retry",
+                            actor,
+                            engine: {
+                                ...input.engine,
+                                specialists: record.intent.specialists,
+                                maxAgents: record.intent.limits.max_agents_per_work,
+                                concurrency: record.intent.limits.agent_concurrency,
+                            },
+                        });
+                        return {
+                            work_id: candidate.record.intent.id,
+                            action: candidate.action,
+                            status: "completed",
+                            run_id: result.runId,
+                        };
+                    }
+                    catch (error) {
+                        const latest = reconcileWorkItem(coordRoot, candidate.record.intent.id, actor);
+                        return {
+                            work_id: candidate.record.intent.id,
+                            action: candidate.action,
+                            status: latest.projection.state === "awaiting_approval" ? "parked" : "failed",
+                            run_id: latest.projection.latest_run_id,
+                            error: boundedError(error.message),
+                        };
+                    }
+                }));
+                outcomes.push(...settled);
+                changed = true;
+            }
+            record = refreshGraph(coordRoot, input.goalId, actor);
+            const after = graphFingerprint(record);
+            if (record.projection.state === "succeeded") {
+                return report("succeeded", record.projection.reason, record);
+            }
+            if (mode === "tick") {
+                return report(before === after ? "no_progress" : "tick_complete", before === after
+                    ? "the tick found no legal progress action"
+                    : "one bounded supervisor cycle completed", record);
+            }
+            if (Date.now() >= deadline) {
+                return report("budget_exhausted", "supervisor wall-time limit reached", record);
+            }
+            if (record.projection.state === "budget_exhausted") {
+                return report("budget_exhausted", record.projection.reason, record);
+            }
+            if (selected.length === 0 && !changed) {
+                return report(stopForProjection(record.projection), record.projection.reason, record);
+            }
+            if (selected.length === 0 && record.projection.state !== "ready") {
+                return report(stopForProjection(record.projection), record.projection.reason, record);
+            }
+            if (before === after) {
+                return report("no_progress", "a supervisor cycle produced no durable state change", record);
+            }
+        }
+        const final = refreshGraph(coordRoot, input.goalId, actor);
+        return report("budget_exhausted", `supervisor cycle limit reached (${cycleLimit})`, final);
+    }
+    finally {
+        release();
+    }
+    function report(stopReason, reason, record) {
+        const endedAt = new Date().toISOString();
+        return {
+            goal_id: input.goalId,
+            mode,
+            stop_reason: stopReason,
+            reason,
+            started_at: startedAt,
+            ended_at: endedAt,
+            duration_ms: Date.now() - startedMs,
+            cycles,
+            dispatches,
+            acceptances,
+            outcomes,
+            projection: record.projection,
+        };
+    }
+}
+function refreshGraph(coordRoot, goalId, actor) {
+    const before = readSupervisorIgnoringLease(coordRoot, goalId);
+    for (const work of before.work)
+        reconcileWorkItem(coordRoot, work.intent.id, actor);
+    return readSupervisorIgnoringLease(coordRoot, goalId);
+}
+function selectCandidates(record) {
+    const candidates = [];
+    for (const work of record.work) {
+        if (work.projection.state === "ready") {
+            candidates.push({ record: work, action: "run", consumesAttempt: true });
+            continue;
+        }
+        if (work.projection.state === "awaiting_approval" &&
+            work.projection.next_action === "resume" &&
+            record.intent.automation.resume_approved) {
+            candidates.push({ record: work, action: "resume", consumesAttempt: false });
+            continue;
+        }
+        if (work.projection.state === "blocked" &&
+            work.projection.next_action === "retry" &&
+            record.intent.automation.retry_blocked) {
+            candidates.push({ record: work, action: "retry", consumesAttempt: true });
+        }
+    }
+    return candidates;
+}
+function selectWithinAttemptBudget(record, candidates) {
+    let remaining = record.projection.attempts_remaining;
+    return candidates.filter((candidate) => {
+        if (!candidate.consumesAttempt)
+            return true;
+        if (remaining <= 0)
+            return false;
+        remaining--;
+        return true;
+    });
+}
+function graphFingerprint(record) {
+    return JSON.stringify(record.work.map((work) => [
+        work.intent.id,
+        work.projection.state,
+        work.projection.next_action,
+        work.projection.attempts_used,
+        work.events.length,
+    ]));
+}
+function stopForProjection(projection) {
+    if (projection.state === "budget_exhausted")
+        return "budget_exhausted";
+    if (projection.state === "blocked")
+        return "blocked";
+    return "awaiting_attention";
+}
+function boundedError(message) {
+    const normalized = message.replace(/\s+/g, " ").trim();
+    return normalized.length > 2_000 ? `${normalized.slice(0, 1_999)}…` : normalized;
+}

package/dist/core/supervisor/state.d.ts

@@ -0,0 +1,69 @@
+import { type WorkRecord } from "../work/read.js";
+import type { WorkflowSpecialistProfile } from "../workflow/types.js";
+export declare const SUPERVISOR_INTENT_SCHEMA_VERSION: 1;
+export interface SupervisorLimits {
+    max_cycles: number;
+    max_runtime_ms: number;
+    max_parallel_work: number;
+    max_total_attempts: number;
+    max_agents_per_work: number;
+    agent_concurrency: number;
+}
+export interface SupervisorAutomationPolicy {
+    accept_passing_proof: boolean;
+    resume_approved: boolean;
+    retry_blocked: boolean;
+}
+export interface SupervisorIntent {
+    schema_version: typeof SUPERVISOR_INTENT_SCHEMA_VERSION;
+    id: string;
+    title: string;
+    root_work_id: string;
+    specialists: Record<string, WorkflowSpecialistProfile>;
+    limits: SupervisorLimits;
+    automation: SupervisorAutomationPolicy;
+    created_at: string;
+}
+export type SupervisorState = "ready" | "running" | "awaiting_attention" | "blocked" | "budget_exhausted" | "succeeded";
+export type SupervisorNextAction = "run" | "wait_for_run" | "resolve_approval" | "review" | "retry" | "none";
+export interface SupervisorProjection {
+    id: string;
+    title: string;
+    root_work_id: string;
+    state: SupervisorState;
+    reason: string;
+    next_action: SupervisorNextAction;
+    work_ids: string[];
+    ready_work: string[];
+    resumable_work: string[];
+    retryable_work: string[];
+    attention_work: string[];
+    attempts_used: number;
+    attempts_remaining: number;
+    specialists: string[];
+}
+export interface SupervisorRecord {
+    intent: SupervisorIntent;
+    projection: SupervisorProjection;
+    work: WorkRecord[];
+}
+export interface CreateSupervisorInput {
+    coordRoot: string;
+    rootWorkId: string;
+    specialists: Readonly<Record<string, WorkflowSpecialistProfile>>;
+    title?: string;
+    id?: string;
+    limits?: Partial<SupervisorLimits>;
+    automation?: Partial<SupervisorAutomationPolicy>;
+}
+export declare function createSupervisor(input: CreateSupervisorInput): SupervisorRecord;
+export declare function readSupervisor(coordRoot: string, goalId: string): SupervisorRecord;
+/** @internal Runner seam; ignores the lease held by this supervisor process. */
+export declare function readSupervisorIgnoringLease(coordRoot: string, goalId: string): SupervisorRecord;
+export declare function listSupervisors(coordRoot: string): SupervisorRecord[];
+export declare function collectSupervisorWork(coordRoot: string, rootWorkId: string): WorkRecord[];
+export declare function assertSupervisorId(goalId: string): void;
+export declare function newSupervisorId(): string;
+/** @internal Runner seam; one exclusive crash-recoverable supervisor lease. */
+export declare function acquireSupervisorLease(coordRoot: string, goalId: string): () => void;
+//# sourceMappingURL=state.d.ts.map

package/dist/core/supervisor/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/state.ts"],"names":[],"mappings":"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"}