harnery 0.16.0 → 0.17.0

package/src/commands/supervisor.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { workflowSubscriptionOnly } from "../core/config.ts";
@@ -8,15 +8,21 @@ import { findCoordRoot } from "../core/hooks/resolve/coord-root.ts";
 import type { PolicyIsolation } from "../core/policy/index.ts";
 import { loadPolicyFile } from "../core/policy/index.ts";
 import {
+  approveSupervisorPlan,
+  type CreateSupervisorReplanningInput,
   configureSupervisorService,
   createSupervisor,
   listSupervisors,
   readSupervisor,
+  readSupervisorPlan,
   readSupervisorServiceConfig,
   readSupervisorServiceStatus,
+  rejectSupervisorPlan,
   requestSupervisorServiceStop,
   runSupervisor,
   runSupervisorServiceDaemon,
+  type SupervisorPlanOutcome,
+  type SupervisorPlanRecord,
   type SupervisorRecord,
   type SupervisorRunReport,
   type SupervisorServiceConfig,
@@ -39,6 +45,7 @@ interface CreateOpts {
   acceptPassingProof?: boolean;
   resumeApproved?: boolean;
   retryBlocked?: boolean;
+  replanning?: string;
   json?: boolean;
 }
 
@@ -82,6 +89,7 @@ export function registerSupervisorCommand(program: Command, emit: EmitContext):
     .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: string, opts: CreateOpts) => {
       withSupervisorRoot(emit, (coordRoot) => {
@@ -113,6 +121,7 @@ export function registerSupervisorCommand(program: Command, emit: EmitContext):
               resume_approved: opts.resumeApproved,
               retry_blocked: opts.retryBlocked,
             },
+            replanning: opts.replanning ? readReplanningFile(opts.replanning) : undefined,
           }),
           opts.json,
           emit,
@@ -149,11 +158,102 @@ export function registerSupervisorCommand(program: Command, emit: EmitContext):
       });
     });
 
+  registerPlanCommand(supervisor, emit);
   registerServiceCommand(supervisor, registry, emit);
   registerRunCommand(supervisor, "tick", registry, emit);
   registerRunCommand(supervisor, "run", registry, emit);
 }
 
+function registerPlanCommand(supervisor: Command, emit: EmitContext): void {
+  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: string, opts: { json?: boolean }) => {
+      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: string, planId: string, opts: { json?: boolean }) => {
+      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: string,
+        planId: string,
+        opts: { actor?: string; reason?: string; json?: boolean },
+      ) => {
+        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: string,
+        planId: string,
+        opts: { actor?: string; reason: string; json?: boolean },
+      ) => {
+        withSupervisorRoot(emit, (coordRoot) => {
+          emitPlanOutcome(
+            rejectSupervisorPlan({
+              coordRoot,
+              goalId,
+              planId,
+              actor: opts.actor,
+              reason: opts.reason,
+            }),
+            opts.json,
+            emit,
+          );
+        });
+      },
+    );
+}
+
 function registerServiceCommand(
   supervisor: Command,
   registry: ReturnType<typeof createBuiltinHarnessRegistry>,
@@ -467,6 +567,65 @@ function readTeamFile(path: string): Record<string, WorkflowSpecialistProfile> {
   return value as Record<string, WorkflowSpecialistProfile>;
 }
 
+function readReplanningFile(path: string): CreateSupervisorReplanningInput {
+  const absolute = resolve(path);
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(absolute, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `cannot read supervisor replanning policy at ${absolute}: ${(error as Error).message}`,
+    );
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("supervisor replanning policy must be a JSON object");
+  }
+  const config = value as Record<string, unknown>;
+  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 as Record<string, unknown>).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 as Record<string, unknown>;
+      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: SupervisorRecord,
   json: boolean | undefined,
@@ -486,7 +645,7 @@ function emitSupervisor(
   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}`,
@@ -495,6 +654,15 @@ function emitSupervisor(
     `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(", ")}`);
   }
@@ -515,6 +683,7 @@ function emitSupervisorReport(
     `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`,
   );
 }
@@ -531,6 +700,64 @@ function integer(value: string | undefined): number | undefined {
   return Number.parseInt(value, 10);
 }
 
+function jsonInteger(value: unknown, field: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || (value as number) < 1) {
+    throw new Error(`${field} must be a positive integer`);
+  }
+  return value as number;
+}
+
+function jsonBoolean(value: unknown, field: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw new Error(`${field} must be boolean`);
+  return value;
+}
+
+function emitPlan(plan: SupervisorPlanRecord, json: boolean | undefined, emit: EmitContext): void {
+  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: SupervisorPlanOutcome,
+  json: boolean | undefined,
+  emit: EmitContext,
+): void {
+  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: SupervisorPlanRecord): string {
+  return `${plan.request.id}  ${plan.status.padEnd(18)}  ${plan.request.prior_root_work_id}`;
+}
+
 function delay(ms: number): Promise<void> {
   return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
 }

package/src/core/supervisor/index.ts

@@ -1,3 +1,21 @@
+export { approveSupervisorPlan, rejectSupervisorPlan } from "./plan-api.ts";
+export { readSupervisorPlan, readSupervisorPlans } from "./plan-read.ts";
+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.ts";
 export {
   type RunSupervisorInput,
   runSupervisor,

package/src/core/supervisor/plan-api.ts

@@ -0,0 +1,47 @@
+import type { SupervisorPlanOutcome } from "./plan-types.ts";
+import { applySupervisorPlanProposal, rejectSupervisorPlanProposal } from "./planning.ts";
+import { acquireSupervisorLease, readSupervisorIgnoringLease } from "./state.ts";
+
+export function approveSupervisorPlan(input: {
+  coordRoot: string;
+  goalId: string;
+  planId: string;
+  actor?: string;
+  reason?: string;
+}): SupervisorPlanOutcome {
+  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: {
+  coordRoot: string;
+  goalId: string;
+  planId: string;
+  actor?: string;
+  reason: string;
+}): SupervisorPlanOutcome {
+  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/src/core/supervisor/plan-read.ts

@@ -0,0 +1,299 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  SUPERVISOR_PLAN_SCHEMA_VERSION,
+  type SupervisorPlanEvent,
+  type SupervisorPlanEventType,
+  type SupervisorPlanHistory,
+  type SupervisorPlanProposal,
+  type SupervisorPlanRecord,
+  type SupervisorPlanRequest,
+} from "./plan-types.ts";
+
+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<SupervisorPlanEventType>([
+  "plan.awaiting_approval",
+  "plan.resumed",
+  "plan.proposed",
+  "plan.applied",
+  "plan.rejected",
+  "plan.attention",
+  "plan.failed",
+]);
+
+export function readSupervisorPlans(
+  coordRootRaw: string,
+  goalId: string,
+  originalRootWorkId: string,
+): SupervisorPlanHistory {
+  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<number>();
+  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<string>();
+  const materializedWork = new Set<string>();
+  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: string,
+  goalId: string,
+  planId: string,
+): SupervisorPlanRecord {
+  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<SupervisorPlanRequest>(join(dir, "request.json"), "plan request");
+  validateRequest(request, goalId, planId);
+  const proposalPath = join(dir, "proposal.json");
+  const proposal = existsSync(proposalPath)
+    ? readJson<SupervisorPlanProposal>(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: string,
+  events: SupervisorPlanEvent[],
+  proposal: SupervisorPlanProposal | undefined,
+): Pick<SupervisorPlanRecord, "status" | "approval_id" | "root_work_id" | "work_ids" | "reason"> {
+  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: string, planId: string): SupervisorPlanEvent[] {
+  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: SupervisorPlanEvent;
+    try {
+      event = JSON.parse(line) as SupervisorPlanEvent;
+    } catch (error) {
+      throw new Error(
+        `cannot parse supervisor plan ${planId} event ${index + 1}: ${(error as Error).message}`,
+      );
+    }
+    validateEvent(event, planId, index + 1);
+    return event;
+  });
+}
+
+function validateRequest(request: SupervisorPlanRequest, goalId: string, planId: string): void {
+  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: SupervisorPlanProposal, planId: string): void {
+  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: SupervisorPlanEvent, planId: string, sequence: number): void {
+  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: string, approvalId: string): boolean {
+  const path = join(coordRoot, ".harnery", "approvals", approvalId, "decision.json");
+  if (!existsSync(path)) return false;
+  try {
+    const value = readJson<Record<string, unknown>>(path, "workflow approval decision");
+    return value.approval_id === approvalId && ["allow", "deny"].includes(String(value.verdict));
+  } catch {
+    return false;
+  }
+}
+
+function readJson<T>(path: string, label: string): T {
+  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")) as T;
+  } catch (error) {
+    throw new Error(`cannot parse ${label} at ${path}: ${(error as Error).message}`);
+  }
+}
+
+function plansRoot(coordRoot: string, goalId: string): string {
+  return join(coordRoot, ".harnery", "supervisors", goalId, "plans");
+}
+
+function planDir(coordRoot: string, goalId: string, planId: string): string {
+  return join(plansRoot(coordRoot, goalId), planId);
+}
+
+function assertId(value: string, pattern: RegExp, label: string): void {
+  if (!pattern.test(value)) throw new Error(`invalid ${label} ${JSON.stringify(value)}`);
+}
+
+function validTimestamp(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 40 && Number.isFinite(Date.parse(value));
+}