harnery 0.16.0 → 0.17.0

package/README.md

@@ -23,7 +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 scheduling cycles until success, human attention, no progress, or budget exhaustion. Use explicit foreground ticks or enroll goals in the optional heartbeat-backed background service; specialist roles survive as configuration while every child remains a bounded process.
+- **Bounded goal supervision:** `harn supervisor` freezes a specialist team and safety limits around a root durable-work graph, then runs scheduling cycles until success, human attention, no progress, or budget exhaustion. An optional planner can propose a schema-gated replacement graph from a frozen workflow-template catalog when the active graph has no legal move; proposals require review by default, old graphs remain immutable evidence, and their attempts still consume the goal budget. Use explicit foreground ticks or enroll goals in the optional heartbeat-backed background service.
 - **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/commands/supervisor.d.ts.map

@@ -1 +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;AA4DnD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA2FnF"}
+{"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;AAmEnD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA8FnF"}

package/dist/commands/supervisor.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, isAbsolute, 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 { configureSupervisorService, createSupervisor, listSupervisors, readSupervisor, readSupervisorServiceConfig, readSupervisorServiceStatus, requestSupervisorServiceStop, runSupervisor, runSupervisorServiceDaemon, spawnSupervisorService, supervisorServiceLogPath, } from "../core/supervisor/index.js";
+import { approveSupervisorPlan, configureSupervisorService, createSupervisor, listSupervisors, readSupervisor, readSupervisorPlan, readSupervisorServiceConfig, readSupervisorServiceStatus, rejectSupervisorPlan, requestSupervisorServiceStop, runSupervisor, runSupervisorServiceDaemon, spawnSupervisorService, supervisorServiceLogPath, } from "../core/supervisor/index.js";
 export function registerSupervisorCommand(program, emit) {
     const registry = createBuiltinHarnessRegistry();
     const supervisor = program
@@ -25,6 +25,7 @@ export function registerSupervisorCommand(program, emit) {
         .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("--replanning <file>", "Frozen planner policy and allowed workflow-template catalog")
         .option("--json", "Emit the complete supervisor record as JSON")
         .action((rootWorkId, opts) => {
         withSupervisorRoot(emit, (coordRoot) => {
@@ -53,6 +54,7 @@ export function registerSupervisorCommand(program, emit) {
                     resume_approved: opts.resumeApproved,
                     retry_blocked: opts.retryBlocked,
                 },
+                replanning: opts.replanning ? readReplanningFile(opts.replanning) : undefined,
             }), opts.json, emit, true);
         });
     });
@@ -84,10 +86,78 @@ export function registerSupervisorCommand(program, emit) {
             emitSupervisor(readSupervisor(coordRoot, goalId), opts.json, emit, true);
         });
     });
+    registerPlanCommand(supervisor, emit);
     registerServiceCommand(supervisor, registry, emit);
     registerRunCommand(supervisor, "tick", registry, emit);
     registerRunCommand(supervisor, "run", registry, emit);
 }
+function registerPlanCommand(supervisor, emit) {
+    const plan = supervisor
+        .command("plan")
+        .description("Inspect and resolve bounded planner proposals for a durable goal.");
+    plan
+        .command("list <goal-id>")
+        .description("List append-only replanning attempts for one goal.")
+        .option("--json", "Emit complete plan records as JSON")
+        .action((goalId, opts) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+            const plans = readSupervisor(coordRoot, goalId).plans;
+            if (opts.json) {
+                emit.config({ format: "json" });
+                emit.data(plans);
+            }
+            else if (plans.length === 0) {
+                emit.text(`supervisor ${goalId} has no replanning attempts\n`);
+            }
+            else {
+                emit.text(`${plans.map(renderPlanRow).join("\n")}\n`);
+            }
+        });
+    });
+    plan
+        .command("show <goal-id> <plan-id>")
+        .description("Show one planner request, schema-gated proposal, and audit events.")
+        .option("--json", "Emit the complete plan record as JSON")
+        .action((goalId, planId, opts) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+            emitPlan(readSupervisorPlan(coordRoot, goalId, planId), opts.json, emit);
+        });
+    });
+    plan
+        .command("approve <goal-id> <plan-id>")
+        .description("Materialize a reviewed proposal and advance the active immutable root.")
+        .option("--actor <name>", "Actor recorded on the plan decision")
+        .option("--reason <text>", "Reason for approval")
+        .option("--json", "Emit the plan outcome as JSON")
+        .action((goalId, planId, opts) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+            emitPlanOutcome(approveSupervisorPlan({
+                coordRoot,
+                goalId,
+                planId,
+                actor: opts.actor,
+                reason: opts.reason,
+            }), opts.json, emit);
+        });
+    });
+    plan
+        .command("reject <goal-id> <plan-id>")
+        .description("Reject a pending proposal without mutating durable work.")
+        .requiredOption("--reason <text>", "Reason the proposal is rejected")
+        .option("--actor <name>", "Actor recorded on the plan decision")
+        .option("--json", "Emit the plan outcome as JSON")
+        .action((goalId, planId, opts) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+            emitPlanOutcome(rejectSupervisorPlan({
+                coordRoot,
+                goalId,
+                planId,
+                actor: opts.actor,
+                reason: opts.reason,
+            }), opts.json, emit);
+        });
+    });
+}
 function registerServiceCommand(supervisor, registry, emit) {
     const service = supervisor
         .command("service")
@@ -355,6 +425,56 @@ function readTeamFile(path) {
     }
     return value;
 }
+function readReplanningFile(path) {
+    const absolute = resolve(path);
+    let value;
+    try {
+        value = JSON.parse(readFileSync(absolute, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`cannot read supervisor replanning policy at ${absolute}: ${error.message}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("supervisor replanning policy must be a JSON object");
+    }
+    const config = value;
+    if (typeof config.planner_specialist !== "string") {
+        throw new Error("supervisor replanning planner_specialist must be a string");
+    }
+    if (!config.templates ||
+        typeof config.templates !== "object" ||
+        Array.isArray(config.templates)) {
+        throw new Error("supervisor replanning templates must be an object");
+    }
+    const base = dirname(absolute);
+    const templates = Object.fromEntries(Object.entries(config.templates).map(([id, raw]) => {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new Error(`supervisor replanning template ${id} must be an object`);
+        }
+        const template = raw;
+        if (typeof template.workflow !== "string") {
+            throw new Error(`supervisor replanning template ${id} workflow must be a string`);
+        }
+        return [
+            id,
+            {
+                workflowPath: isAbsolute(template.workflow)
+                    ? template.workflow
+                    : resolve(base, template.workflow),
+                maxAttempts: jsonInteger(template.max_attempts, `template ${id} max_attempts`),
+                root: jsonBoolean(template.root, `template ${id} root`),
+            },
+        ];
+    }));
+    return {
+        plannerSpecialist: config.planner_specialist,
+        autoApply: jsonBoolean(config.auto_apply, "replanning auto_apply"),
+        maxReplans: jsonInteger(config.max_replans, "replanning max_replans"),
+        maxWorkItemsPerPlan: jsonInteger(config.max_work_items_per_plan, "replanning max_work_items_per_plan"),
+        maxTotalWorkItems: jsonInteger(config.max_total_work_items, "replanning max_total_work_items"),
+        templates,
+    };
+}
 function emitSupervisor(record, json, emit, detail = false) {
     if (json) {
         emit.config({ format: "json" });
@@ -369,7 +489,7 @@ function emitSupervisor(record, json, emit, detail = false) {
     const lines = [
         `${record.intent.id}: ${record.intent.title}`,
         `state: ${projection.state}`,
-        `root: ${record.intent.root_work_id}`,
+        `root: ${projection.root_work_id}`,
         `reason: ${projection.reason}`,
         `next: ${projection.next_action}`,
         `work: ${projection.work_ids.length}`,
@@ -378,6 +498,14 @@ function emitSupervisor(record, json, emit, detail = false) {
         `automation: accept=${record.intent.automation.accept_passing_proof}, ` +
             `resume=${record.intent.automation.resume_approved}, retry=${record.intent.automation.retry_blocked}`,
     ];
+    if (record.intent.replanning) {
+        lines.push(`replanning: generation=${projection.plan_generation}, used=${projection.replans_used}/${record.intent.replanning.max_replans}, auto_apply=${record.intent.replanning.auto_apply}`);
+        if (projection.root_work_id !== record.intent.root_work_id) {
+            lines.push(`original root: ${record.intent.root_work_id}`);
+        }
+        if (projection.pending_plan_id)
+            lines.push(`pending plan: ${projection.pending_plan_id}`);
+    }
     if (projection.attention_work.length) {
         lines.push(`attention: ${projection.attention_work.join(", ")}`);
     }
@@ -392,6 +520,7 @@ function emitSupervisorReport(report, json, emit) {
     emit.text(`supervisor ${report.goal_id}: ${report.stop_reason}\n` +
         `reason: ${report.reason}\n` +
         `cycles: ${report.cycles}; dispatches: ${report.dispatches}; acceptances: ${report.acceptances}\n` +
+        `replans: ${report.replans}\n` +
         `state: ${report.projection.state}; next: ${report.projection.next_action}\n`);
 }
 function renderSupervisorRow(record) {
@@ -405,6 +534,58 @@ function integer(value) {
         throw new Error(`expected a positive integer, got ${JSON.stringify(value)}`);
     return Number.parseInt(value, 10);
 }
+function jsonInteger(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${field} must be a positive integer`);
+    }
+    return value;
+}
+function jsonBoolean(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new Error(`${field} must be boolean`);
+    return value;
+}
+function emitPlan(plan, json, emit) {
+    if (json) {
+        emit.config({ format: "json" });
+        emit.data(plan);
+        return;
+    }
+    const lines = [
+        `${plan.request.id}: ${plan.status}`,
+        `goal: ${plan.request.goal_id}`,
+        `sequence: ${plan.request.sequence}`,
+        `prior root: ${plan.request.prior_root_work_id}`,
+        `planner run: ${plan.request.workflow_run_id}`,
+    ];
+    if (plan.proposal) {
+        lines.push(`decision: ${plan.proposal.decision}`);
+        lines.push(`rationale: ${plan.proposal.rationale}`);
+        lines.push(`proposed work: ${plan.proposal.work.length}`);
+    }
+    if (plan.root_work_id)
+        lines.push(`applied root: ${plan.root_work_id}`);
+    if (plan.approval_id)
+        lines.push(`approval: ${plan.approval_id}`);
+    emit.text(`${lines.join("\n")}\n`);
+}
+function emitPlanOutcome(outcome, json, emit) {
+    if (json) {
+        emit.config({ format: "json" });
+        emit.data(outcome);
+        return;
+    }
+    emit.text(`supervisor plan ${outcome.plan_id}: ${outcome.status}\n` +
+        `${outcome.reason ? `reason: ${outcome.reason}\n` : ""}` +
+        `${outcome.root_work_id ? `root: ${outcome.root_work_id}\n` : ""}`);
+}
+function renderPlanRow(plan) {
+    return `${plan.request.id}  ${plan.status.padEnd(18)}  ${plan.request.prior_root_work_id}`;
+}
 function delay(ms) {
     return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
 }

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

@@ -1,3 +1,6 @@
+export { approveSupervisorPlan, rejectSupervisorPlan } from "./plan-api.js";
+export { readSupervisorPlan, readSupervisorPlans } from "./plan-read.js";
+export { type CreateSupervisorPlanTemplateInput, type CreateSupervisorReplanningInput, SUPERVISOR_PLAN_SCHEMA_VERSION, type SupervisorPlanEvent, type SupervisorPlanEventType, type SupervisorPlanHistory, type SupervisorPlanOutcome, type SupervisorPlanProposal, type SupervisorPlanRecord, type SupervisorPlanRequest, type SupervisorPlanStatus, type SupervisorPlanTemplate, type SupervisorPlanWorkSpec, type SupervisorReplanningPolicy, } from "./plan-types.js";
 export { type RunSupervisorInput, runSupervisor, type SupervisorDispatchOutcome, type SupervisorRunReport, type SupervisorStopReason, } from "./runner.js";
 export { type ConfigureSupervisorServiceInput, configureSupervisorService, type RunSupervisorServiceDaemonInput, type RunSupervisorServiceSweepInput, readSupervisorServiceConfig, readSupervisorServiceRuntime, readSupervisorServiceStatus, requestSupervisorServiceStop, runSupervisorServiceDaemon, runSupervisorServiceSweep, SUPERVISOR_SERVICE_CONFIG_SCHEMA_VERSION, SUPERVISOR_SERVICE_RUNTIME_SCHEMA_VERSION, SUPERVISOR_SERVICE_STATUS_SCHEMA_VERSION, type SupervisorServiceConfig, type SupervisorServiceEngineConfig, type SupervisorServiceGoalRuntime, type SupervisorServiceGoalState, type SupervisorServiceProcessState, type SupervisorServiceRuntime, type SupervisorServiceStatus, type SupervisorServiceStatusRecord, type SupervisorServiceSweepOutcome, type SupervisorServiceSweepReport, spawnSupervisorService, supervisorServiceLogPath, } from "./service.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";

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

@@ -1 +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,KAAK,+BAA+B,EACpC,0BAA0B,EAC1B,KAAK,+BAA+B,EACpC,KAAK,8BAA8B,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,wCAAwC,EACxC,yCAAyC,EACzC,wCAAwC,EACxC,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EACL,KAAK,iCAAiC,EACtC,KAAK,+BAA+B,EACpC,8BAA8B,EAC9B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,+BAA+B,EACpC,0BAA0B,EAC1B,KAAK,+BAA+B,EACpC,KAAK,8BAA8B,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,wCAAwC,EACxC,yCAAyC,EACzC,wCAAwC,EACxC,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,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

@@ -1,3 +1,6 @@
+export { approveSupervisorPlan, rejectSupervisorPlan } from "./plan-api.js";
+export { readSupervisorPlan, readSupervisorPlans } from "./plan-read.js";
+export { SUPERVISOR_PLAN_SCHEMA_VERSION, } from "./plan-types.js";
 export { runSupervisor, } from "./runner.js";
 export { configureSupervisorService, readSupervisorServiceConfig, readSupervisorServiceRuntime, readSupervisorServiceStatus, requestSupervisorServiceStop, runSupervisorServiceDaemon, runSupervisorServiceSweep, SUPERVISOR_SERVICE_CONFIG_SCHEMA_VERSION, SUPERVISOR_SERVICE_RUNTIME_SCHEMA_VERSION, SUPERVISOR_SERVICE_STATUS_SCHEMA_VERSION, spawnSupervisorService, supervisorServiceLogPath, } from "./service.js";
 export { assertSupervisorId, collectSupervisorWork, createSupervisor, listSupervisors, newSupervisorId, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, } from "./state.js";

package/dist/core/supervisor/plan-api.d.ts

@@ -0,0 +1,16 @@
+import type { SupervisorPlanOutcome } from "./plan-types.js";
+export declare function approveSupervisorPlan(input: {
+    coordRoot: string;
+    goalId: string;
+    planId: string;
+    actor?: string;
+    reason?: string;
+}): SupervisorPlanOutcome;
+export declare function rejectSupervisorPlan(input: {
+    coordRoot: string;
+    goalId: string;
+    planId: string;
+    actor?: string;
+    reason: string;
+}): SupervisorPlanOutcome;
+//# sourceMappingURL=plan-api.d.ts.map

package/dist/core/supervisor/plan-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-api.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/plan-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAI7D,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,qBAAqB,CAcxB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,qBAAqB,CAcxB"}

package/dist/core/supervisor/plan-api.js

@@ -0,0 +1,34 @@
+import { applySupervisorPlanProposal, rejectSupervisorPlanProposal } from "./planning.js";
+import { acquireSupervisorLease, readSupervisorIgnoringLease } from "./state.js";
+export function approveSupervisorPlan(input) {
+    const actor = input.actor?.trim() || `supervisor:${input.goalId}`;
+    const release = acquireSupervisorLease(input.coordRoot, input.goalId);
+    try {
+        return applySupervisorPlanProposal({
+            coordRoot: input.coordRoot,
+            record: readSupervisorIgnoringLease(input.coordRoot, input.goalId),
+            planId: input.planId,
+            actor,
+            reason: input.reason,
+        });
+    }
+    finally {
+        release();
+    }
+}
+export function rejectSupervisorPlan(input) {
+    const actor = input.actor?.trim() || `supervisor:${input.goalId}`;
+    const release = acquireSupervisorLease(input.coordRoot, input.goalId);
+    try {
+        return rejectSupervisorPlanProposal({
+            coordRoot: input.coordRoot,
+            goalId: input.goalId,
+            planId: input.planId,
+            actor,
+            reason: input.reason,
+        });
+    }
+    finally {
+        release();
+    }
+}

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

@@ -0,0 +1,4 @@
+import { type SupervisorPlanHistory, type SupervisorPlanRecord } from "./plan-types.js";
+export declare function readSupervisorPlans(coordRootRaw: string, goalId: string, originalRootWorkId: string): SupervisorPlanHistory;
+export declare function readSupervisorPlan(coordRootRaw: string, goalId: string, planId: string): SupervisorPlanRecord;
+//# sourceMappingURL=plan-read.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-read.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/plan-read.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,qBAAqB,EAE1B,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAC;AAsBzB,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,MAAM,GACzB,qBAAqB,CAoDvB;AAED,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,oBAAoB,CAetB"}

package/dist/core/supervisor/plan-read.js

@@ -0,0 +1,269 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { SUPERVISOR_PLAN_SCHEMA_VERSION, } from "./plan-types.js";
+const PLAN_ID = /^plan-[0-9]{4}-[a-f0-9]{8}$/;
+const GOAL_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const WORK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const APPROVAL_ID = /^apr-[a-f0-9]{20}$/;
+const PLAN_KEY = /^[a-z][a-z0-9-]{0,31}$/;
+const TEMPLATE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MAX_PLANS = 100;
+const MAX_RECORD_BYTES = 256 * 1024;
+const MAX_EVENTS_BYTES = 512 * 1024;
+const MAX_EVENTS = 100;
+const EVENT_TYPES = new Set([
+    "plan.awaiting_approval",
+    "plan.resumed",
+    "plan.proposed",
+    "plan.applied",
+    "plan.rejected",
+    "plan.attention",
+    "plan.failed",
+]);
+export function readSupervisorPlans(coordRootRaw, goalId, originalRootWorkId) {
+    assertId(goalId, GOAL_ID, "supervisor id");
+    assertId(originalRootWorkId, WORK_ID, "work id");
+    const coordRoot = resolve(coordRootRaw);
+    const root = plansRoot(coordRoot, goalId);
+    if (!existsSync(root)) {
+        return {
+            plans: [],
+            active_root_work_id: originalRootWorkId,
+            generation: 0,
+            applied_work_ids: [],
+            materialized_work_ids: [],
+        };
+    }
+    const entries = readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && PLAN_ID.test(entry.name))
+        .map((entry) => entry.name);
+    if (entries.length > MAX_PLANS)
+        throw new Error(`supervisor plan history exceeds ${MAX_PLANS}`);
+    const plans = entries
+        .map((planId) => readSupervisorPlan(coordRootRaw, goalId, planId))
+        .sort((left, right) => left.request.sequence - right.request.sequence);
+    const sequences = new Set();
+    for (const plan of plans) {
+        if (sequences.has(plan.request.sequence)) {
+            throw new Error(`supervisor ${goalId} has duplicate plan sequence ${plan.request.sequence}`);
+        }
+        sequences.add(plan.request.sequence);
+    }
+    let activeRoot = originalRootWorkId;
+    let generation = 0;
+    const appliedWork = new Set();
+    const materializedWork = new Set();
+    for (const plan of plans) {
+        for (const spec of plan.proposal?.work ?? []) {
+            const workId = `${plan.request.id}-${spec.key}`;
+            if (existsSync(join(coordRoot, ".harnery", "work", workId, "intent.json"))) {
+                materializedWork.add(workId);
+            }
+        }
+        if (plan.status !== "applied" || !plan.root_work_id)
+            continue;
+        activeRoot = plan.root_work_id;
+        generation++;
+        for (const workId of plan.work_ids)
+            appliedWork.add(workId);
+    }
+    return {
+        plans,
+        active_root_work_id: activeRoot,
+        generation,
+        applied_work_ids: [...appliedWork],
+        materialized_work_ids: [...materializedWork],
+        latest: plans.at(-1),
+    };
+}
+export function readSupervisorPlan(coordRootRaw, goalId, planId) {
+    assertId(goalId, GOAL_ID, "supervisor id");
+    assertId(planId, PLAN_ID, "supervisor plan id");
+    const coordRoot = resolve(coordRootRaw);
+    const dir = planDir(coordRoot, goalId, planId);
+    const request = readJson(join(dir, "request.json"), "plan request");
+    validateRequest(request, goalId, planId);
+    const proposalPath = join(dir, "proposal.json");
+    const proposal = existsSync(proposalPath)
+        ? readJson(proposalPath, "plan proposal")
+        : undefined;
+    if (proposal)
+        validateProposalEnvelope(proposal, planId);
+    const events = readEvents(join(dir, "events.jsonl"), planId);
+    const derived = deriveStatus(coordRoot, events, proposal);
+    return { request, proposal, events, ...derived };
+}
+function deriveStatus(coordRoot, events, proposal) {
+    const latest = events.at(-1);
+    const applied = [...events].reverse().find((event) => event.event === "plan.applied");
+    if (applied) {
+        return {
+            status: "applied",
+            root_work_id: applied.root_work_id,
+            work_ids: applied.work_ids ?? [],
+            reason: applied.reason,
+        };
+    }
+    if (latest?.event === "plan.rejected") {
+        return { status: "rejected", work_ids: [], reason: latest.reason };
+    }
+    if (latest?.event === "plan.attention") {
+        return { status: "attention", work_ids: [], reason: latest.reason };
+    }
+    if (latest?.event === "plan.failed") {
+        return { status: "failed", work_ids: [], reason: latest.reason };
+    }
+    const parked = [...events].reverse().find((event) => event.event === "plan.awaiting_approval");
+    const resumedAfterPark = parked !== undefined &&
+        events.some((event) => event.event === "plan.resumed" && event.seq > parked.seq);
+    if (parked?.approval_id && !resumedAfterPark) {
+        return {
+            status: approvalIsResolved(coordRoot, parked.approval_id) ? "resumable" : "awaiting_approval",
+            approval_id: parked.approval_id,
+            work_ids: [],
+            reason: parked.reason,
+        };
+    }
+    if (proposal)
+        return { status: "proposed", work_ids: [], reason: proposal.rationale };
+    return { status: "interrupted", work_ids: [], reason: latest?.reason };
+}
+function readEvents(path, planId) {
+    if (!existsSync(path))
+        return [];
+    const size = statSync(path).size;
+    if (size > MAX_EVENTS_BYTES)
+        throw new Error("supervisor plan events exceed their byte limit");
+    const body = readFileSync(path, "utf8");
+    if (body && !body.endsWith("\n"))
+        throw new Error(`supervisor plan ${planId} has a partial event`);
+    const lines = body.split("\n").filter(Boolean);
+    if (lines.length > MAX_EVENTS)
+        throw new Error(`supervisor plan exceeds ${MAX_EVENTS} events`);
+    return lines.map((line, index) => {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`cannot parse supervisor plan ${planId} event ${index + 1}: ${error.message}`);
+        }
+        validateEvent(event, planId, index + 1);
+        return event;
+    });
+}
+function validateRequest(request, goalId, planId) {
+    if (request.schema_version !== SUPERVISOR_PLAN_SCHEMA_VERSION ||
+        request.id !== planId ||
+        request.goal_id !== goalId ||
+        !Number.isSafeInteger(request.sequence) ||
+        request.sequence < 1 ||
+        request.sequence > MAX_PLANS ||
+        typeof request.trigger_fingerprint !== "string" ||
+        request.trigger_fingerprint.length < 1 ||
+        request.trigger_fingerprint.length > 64_000 ||
+        !WORK_ID.test(request.prior_root_work_id) ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(request.workflow_run_id) ||
+        !validTimestamp(request.created_at)) {
+        throw new Error(`supervisor plan request ${planId} has an unsupported schema`);
+    }
+}
+function validateProposalEnvelope(proposal, planId) {
+    if (proposal.schema_version !== SUPERVISOR_PLAN_SCHEMA_VERSION ||
+        proposal.plan_id !== planId ||
+        !["apply", "attention"].includes(proposal.decision) ||
+        typeof proposal.rationale !== "string" ||
+        proposal.rationale.length < 1 ||
+        proposal.rationale.length > 2_000 ||
+        !Array.isArray(proposal.work) ||
+        proposal.work.length > 25 ||
+        typeof proposal.root !== "string" ||
+        proposal.root.length > 32 ||
+        !validTimestamp(proposal.proposed_at)) {
+        throw new Error(`supervisor plan proposal ${planId} has an unsupported schema`);
+    }
+    for (const [index, spec] of proposal.work.entries()) {
+        if (!spec ||
+            typeof spec !== "object" ||
+            !PLAN_KEY.test(spec.key) ||
+            typeof spec.title !== "string" ||
+            spec.title.length < 1 ||
+            spec.title.length > 200 ||
+            typeof spec.objective !== "string" ||
+            spec.objective.length < 1 ||
+            spec.objective.length > 4_000 ||
+            !Array.isArray(spec.acceptance) ||
+            spec.acceptance.length > 50 ||
+            spec.acceptance.some((value) => typeof value !== "string" || value.length > 500) ||
+            !Array.isArray(spec.dependencies) ||
+            spec.dependencies.length > 50 ||
+            spec.dependencies.some((value) => typeof value !== "string" || value.length > 100) ||
+            !TEMPLATE_ID.test(spec.template)) {
+            throw new Error(`supervisor plan proposal ${planId} work[${index}] is invalid`);
+        }
+    }
+}
+function validateEvent(event, planId, sequence) {
+    if (event.schema_version !== SUPERVISOR_PLAN_SCHEMA_VERSION ||
+        event.plan_id !== planId ||
+        event.seq !== sequence ||
+        !EVENT_TYPES.has(event.event) ||
+        !validTimestamp(event.ts) ||
+        typeof event.actor !== "string" ||
+        event.actor.length < 1 ||
+        event.actor.length > 200 ||
+        typeof event.reason !== "string" ||
+        event.reason.length < 1 ||
+        event.reason.length > 2_000) {
+        throw new Error(`supervisor plan ${planId} event ${sequence} has an unsupported schema`);
+    }
+    if (event.approval_id !== undefined && !APPROVAL_ID.test(event.approval_id)) {
+        throw new Error(`supervisor plan ${planId} event ${sequence} has an invalid approval id`);
+    }
+    if (event.root_work_id !== undefined && !WORK_ID.test(event.root_work_id)) {
+        throw new Error(`supervisor plan ${planId} event ${sequence} has an invalid root work id`);
+    }
+    if (event.work_ids !== undefined) {
+        if (!Array.isArray(event.work_ids) || event.work_ids.some((id) => !WORK_ID.test(id))) {
+            throw new Error(`supervisor plan ${planId} event ${sequence} has invalid work ids`);
+        }
+    }
+}
+function approvalIsResolved(coordRoot, approvalId) {
+    const path = join(coordRoot, ".harnery", "approvals", approvalId, "decision.json");
+    if (!existsSync(path))
+        return false;
+    try {
+        const value = readJson(path, "workflow approval decision");
+        return value.approval_id === approvalId && ["allow", "deny"].includes(String(value.verdict));
+    }
+    catch {
+        return false;
+    }
+}
+function readJson(path, label) {
+    if (!existsSync(path))
+        throw new Error(`${label} does not exist at ${path}`);
+    const size = statSync(path).size;
+    if (size <= 0 || size > MAX_RECORD_BYTES)
+        throw new Error(`${label} has invalid size ${size}`);
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`cannot parse ${label} at ${path}: ${error.message}`);
+    }
+}
+function plansRoot(coordRoot, goalId) {
+    return join(coordRoot, ".harnery", "supervisors", goalId, "plans");
+}
+function planDir(coordRoot, goalId, planId) {
+    return join(plansRoot(coordRoot, goalId), planId);
+}
+function assertId(value, pattern, label) {
+    if (!pattern.test(value))
+        throw new Error(`invalid ${label} ${JSON.stringify(value)}`);
+}
+function validTimestamp(value) {
+    return typeof value === "string" && value.length <= 40 && Number.isFinite(Date.parse(value));
+}