harnery 0.15.0 → 0.17.0

package/src/commands/supervisor.ts

@@ -1,5 +1,5 @@
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+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,12 +8,27 @@ 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,
+  type SupervisorServiceStatus,
+  spawnSupervisorService,
+  supervisorServiceLogPath,
 } from "../core/supervisor/index.ts";
 import type { WorkflowSpecialistProfile } from "../core/workflow/index.ts";
 
@@ -30,6 +45,7 @@ interface CreateOpts {
   acceptPassingProof?: boolean;
   resumeApproved?: boolean;
   retryBlocked?: boolean;
+  replanning?: string;
   json?: boolean;
 }
 
@@ -45,6 +61,13 @@ interface RunOpts {
   json?: boolean;
 }
 
+interface ServiceOpts extends RunOpts {
+  wakeIntervalMs?: string;
+  heartbeatIntervalMs?: string;
+  errorBackoffBaseMs?: string;
+  errorBackoffMaxMs?: string;
+}
+
 export function registerSupervisorCommand(program: Command, emit: EmitContext): void {
   const registry = createBuiltinHarnessRegistry();
   const supervisor = program
@@ -66,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) => {
@@ -97,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,
@@ -133,10 +158,341 @@ 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>,
+  emit: EmitContext,
+): void {
+  const service = supervisor
+    .command("service")
+    .description("Run explicitly enrolled durable goals in a restartable background service.");
+
+  addServiceOptions(
+    service
+      .command("start [goal-ids...]")
+      .description("Configure and start the detached per-repository supervisor service."),
+  )
+    .option("--json", "Emit complete service status as JSON")
+    .action(async (goalIds: string[], opts: ServiceOpts) => {
+      await withSupervisorRootAsync(emit, async (coordRoot) => {
+        prepareServiceConfig(coordRoot, goalIds, opts, registry);
+        const status = await spawnSupervisorService(coordRoot);
+        emitServiceStatus(status, opts.json, emit);
+      });
+    });
+
+  addServiceOptions(
+    service
+      .command("run [goal-ids...]")
+      .description("Run the persistent service loop in the foreground for a process manager."),
+  )
+    .option("--json", "Emit terminal service status as JSON")
+    .action(async (goalIds: string[], opts: ServiceOpts) => {
+      await withSupervisorRootAsync(emit, async (coordRoot) => {
+        const config = prepareServiceConfig(coordRoot, goalIds, opts, registry);
+        const status = await runSupervisorServiceDaemon({
+          coordRoot,
+          engine: serviceEngine(config, registry),
+          onLog: opts.json ? undefined : (line) => emit.text(`${line}\n`),
+        });
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(status);
+        }
+      });
+    });
+
+  service
+    .command("status")
+    .description("Show service liveness, heartbeat, enrolled goals, and durable wake state.")
+    .option("--json", "Emit complete service status as JSON")
+    .action((opts: { json?: boolean }) => {
+      withSupervisorRoot(emit, (coordRoot) => {
+        emitServiceStatus(readSupervisorServiceStatus(coordRoot), opts.json, emit);
+      });
+    });
+
+  service
+    .command("stop")
+    .description("Request a graceful stop; an active goal tick is allowed to finish safely.")
+    .option("--json", "Emit complete service status as JSON")
+    .action(async (opts: { json?: boolean }) => {
+      await withSupervisorRootAsync(emit, async (coordRoot) => {
+        let status = requestSupervisorServiceStop(coordRoot);
+        const deadline = Date.now() + 5_000;
+        while (status.running && Date.now() < deadline) {
+          await delay(50);
+          status = readSupervisorServiceStatus(coordRoot);
+        }
+        emitServiceStatus(status, opts.json, emit);
+      });
+    });
+
+  service
+    .command("logs")
+    .description("Show the tail of the private background-service log.")
+    .option("--lines <n>", "Number of lines to show (default 50)", "50")
+    .action((opts: { lines: string }) => {
+      withSupervisorRoot(emit, (coordRoot) => {
+        const lines = integer(opts.lines) ?? 50;
+        if (lines > 10_000) throw new Error("service log lines must not exceed 10000");
+        const path = supervisorServiceLogPath(coordRoot);
+        if (!existsSync(path)) {
+          emit.text("no supervisor service log\n");
+          return;
+        }
+        const selected = readFileSync(path, "utf8")
+          .split("\n")
+          .slice(-(lines + 1))
+          .join("\n");
+        emit.text(selected.endsWith("\n") ? selected : `${selected}\n`);
+      });
+    });
+
+  service
+    .command("daemon", { hidden: true })
+    .description("Internal detached service entrypoint.")
+    .action(async () => {
+      await withSupervisorRootAsync(emit, async (coordRoot) => {
+        const config = readSupervisorServiceConfig(coordRoot);
+        await runSupervisorServiceDaemon({
+          coordRoot,
+          engine: serviceEngine(config, registry),
+          onLog: (line) => emit.text(`${line}\n`),
+        });
+      });
+    });
+}
+
+function addServiceOptions(command: Command): Command {
+  return command
+    .option("--wake-interval-ms <n>", "State-change poll interval (default 5000)")
+    .option("--heartbeat-interval-ms <n>", "Heartbeat interval (default 2000)")
+    .option("--error-backoff-base-ms <n>", "Initial service-error backoff (default 2000)")
+    .option("--error-backoff-max-ms <n>", "Maximum service-error backoff (default 300000)")
+    .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");
+}
+
+function prepareServiceConfig(
+  coordRoot: string,
+  goalIds: string[],
+  opts: ServiceOpts,
+  registry: ReturnType<typeof createBuiltinHarnessRegistry>,
+): SupervisorServiceConfig {
+  if (goalIds.length === 0) {
+    if (hasServiceConfigOverrides(opts)) {
+      throw new Error("goal ids are required when changing supervisor service options");
+    }
+    return readSupervisorServiceConfig(coordRoot);
+  }
+  if (opts.harness && !registry.get(opts.harness)) {
+    throw new Error(`unknown harness ${JSON.stringify(opts.harness)}`);
+  }
+  const policy = opts.policy ? loadPolicyFile(opts.policy) : undefined;
+  return configureSupervisorService({
+    coordRoot,
+    goalIds,
+    wakeIntervalMs: integer(opts.wakeIntervalMs),
+    heartbeatIntervalMs: integer(opts.heartbeatIntervalMs),
+    errorBackoffBaseMs: integer(opts.errorBackoffBaseMs),
+    errorBackoffMaxMs: integer(opts.errorBackoffMaxMs),
+    engine: {
+      default_harness: opts.harness,
+      cwd: opts.cwd,
+      subscription_only:
+        opts.subscriptionOnly === true ? true : workflowSubscriptionOnly(coordRoot),
+      allow_api_billing: opts.allowApiBilling,
+      policy,
+      isolation: opts.isolation,
+      approval_addressee: opts.approvalTo,
+    },
+  });
+}
+
+function hasServiceConfigOverrides(opts: ServiceOpts): boolean {
+  return Boolean(
+    opts.wakeIntervalMs ||
+      opts.heartbeatIntervalMs ||
+      opts.errorBackoffBaseMs ||
+      opts.errorBackoffMaxMs ||
+      opts.harness ||
+      opts.cwd ||
+      opts.subscriptionOnly ||
+      opts.allowApiBilling ||
+      opts.policy ||
+      opts.isolation ||
+      opts.approvalTo,
+  );
+}
+
+function serviceEngine(
+  config: SupervisorServiceConfig,
+  registry: ReturnType<typeof createBuiltinHarnessRegistry>,
+) {
+  return {
+    spawners: registry.spawners(),
+    defaultHarness: config.engine.default_harness,
+    cwd: config.engine.cwd,
+    subscriptionOnly: config.engine.subscription_only,
+    allowApiBilling: config.engine.allow_api_billing,
+    harnessEvidence: Object.fromEntries(
+      registry
+        .list()
+        .map((adapter) => [
+          adapter.profile.id,
+          { toolEvidence: adapter.profile.capabilities.toolEvidence },
+        ]),
+    ),
+    policy: config.engine.policy,
+    approvalMode: "park" as const,
+    approvalAddressee: config.engine.approval_addressee,
+    isolation: config.engine.isolation,
+    networkAccess: "enabled" as const,
+  };
+}
+
+function emitServiceStatus(
+  status: SupervisorServiceStatus,
+  json: boolean | undefined,
+  emit: EmitContext,
+): void {
+  if (json) {
+    emit.config({ format: "json" });
+    emit.data(status);
+    return;
+  }
+  if (!status.config && !status.record) {
+    emit.text("supervisor service: unconfigured\n");
+    return;
+  }
+  const state = status.running
+    ? (status.record?.state ?? "running")
+    : status.stale
+      ? "stale"
+      : "stopped";
+  const lines = [
+    `supervisor service: ${state}`,
+    `goals: ${status.config?.goal_ids.join(", ") || "none"}`,
+  ];
+  if (status.record) {
+    lines.push(`pid: ${status.record.pid} on ${status.record.host}`);
+    lines.push(`heartbeat: ${status.record.heartbeat_at}`);
+    lines.push(`sweeps: ${status.record.sweep_count}`);
+    if (status.record.active_goal_id) lines.push(`active: ${status.record.active_goal_id}`);
+    if (status.record.next_wake_at) lines.push(`next wake: ${status.record.next_wake_at}`);
+    if (status.record.last_error) lines.push(`error: ${status.record.last_error}`);
+  }
+  const backingOff = Object.entries(status.runtime?.goals ?? {}).filter(
+    ([, runtime]) => runtime.state === "backoff",
+  );
+  if (backingOff.length) {
+    lines.push(`backoff: ${backingOff.map(([goalId]) => goalId).join(", ")}`);
+  }
+  emit.text(`${lines.join("\n")}\n`);
+}
+
 function registerRunCommand(
   supervisor: Command,
   mode: "tick" | "run",
@@ -211,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,
@@ -230,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}`,
@@ -239,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(", ")}`);
   }
@@ -259,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`,
   );
 }
@@ -275,6 +700,68 @@ 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));
+}
+
 function withSupervisorRoot(emit: EmitContext, fn: (coordRoot: string) => void): void {
   const coordRoot = findCoordRoot();
   if (!coordRoot) {

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,
@@ -5,6 +23,33 @@ export {
   type SupervisorRunReport,
   type SupervisorStopReason,
 } from "./runner.ts";
+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.ts";
 export {
   assertSupervisorId,
   type CreateSupervisorInput,

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();
+  }
+}