harnery 0.17.0 → 0.18.0

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

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { readWorkItem } from "../work/read.ts";
 import {
   SUPERVISOR_PLAN_SCHEMA_VERSION,
   type SupervisorPlanEvent,
@@ -25,6 +26,7 @@ const EVENT_TYPES = new Set<SupervisorPlanEventType>([
   "plan.resumed",
   "plan.proposed",
   "plan.applied",
+  "plan.completed",
   "plan.rejected",
   "plan.attention",
   "plan.failed",
@@ -46,6 +48,8 @@ export function readSupervisorPlans(
       generation: 0,
       applied_work_ids: [],
       materialized_work_ids: [],
+      milestones_completed: 0,
+      completed: false,
     };
   }
   const entries = readdirSync(root, { withFileTypes: true })
@@ -64,6 +68,8 @@ export function readSupervisorPlans(
   }
   let activeRoot = originalRootWorkId;
   let generation = 0;
+  let milestonesCompleted = 0;
+  let completed = false;
   const appliedWork = new Set<string>();
   const materializedWork = new Set<string>();
   for (const plan of plans) {
@@ -76,14 +82,30 @@ export function readSupervisorPlans(
     if (plan.status !== "applied" || !plan.root_work_id) continue;
     activeRoot = plan.root_work_id;
     generation++;
+    if (
+      plan.proposal?.milestone &&
+      readWorkItem(coordRoot, plan.root_work_id).projection.state === "succeeded"
+    ) {
+      milestonesCompleted++;
+    }
     for (const workId of plan.work_ids) appliedWork.add(workId);
   }
+  const completedPlans = plans.filter((plan) => plan.status === "completed");
+  if (
+    completedPlans.length > 1 ||
+    (completedPlans.length === 1 && completedPlans[0] !== plans.at(-1))
+  ) {
+    throw new Error(`supervisor ${goalId} has invalid completion history`);
+  }
+  completed = completedPlans.length === 1;
   return {
     plans,
     active_root_work_id: activeRoot,
     generation,
     applied_work_ids: [...appliedWork],
     materialized_work_ids: [...materializedWork],
+    milestones_completed: milestonesCompleted,
+    completed,
     latest: plans.at(-1),
   };
 }
@@ -115,6 +137,10 @@ function deriveStatus(
   proposal: SupervisorPlanProposal | undefined,
 ): Pick<SupervisorPlanRecord, "status" | "approval_id" | "root_work_id" | "work_ids" | "reason"> {
   const latest = events.at(-1);
+  const completed = [...events].reverse().find((event) => event.event === "plan.completed");
+  if (completed) {
+    return { status: "completed", work_ids: [], reason: completed.reason };
+  }
   const applied = [...events].reverse().find((event) => event.event === "plan.applied");
   if (applied) {
     return {
@@ -180,6 +206,8 @@ function validateRequest(request: SupervisorPlanRequest, goalId: string, planId:
     !Number.isSafeInteger(request.sequence) ||
     request.sequence < 1 ||
     request.sequence > MAX_PLANS ||
+    (request.trigger !== undefined &&
+      !["initial", "recovery", "milestone"].includes(request.trigger)) ||
     typeof request.trigger_fingerprint !== "string" ||
     request.trigger_fingerprint.length < 1 ||
     request.trigger_fingerprint.length > 64_000 ||
@@ -195,7 +223,7 @@ function validateProposalEnvelope(proposal: SupervisorPlanProposal, planId: stri
   if (
     proposal.schema_version !== SUPERVISOR_PLAN_SCHEMA_VERSION ||
     proposal.plan_id !== planId ||
-    !["apply", "attention"].includes(proposal.decision) ||
+    !["apply", "complete", "attention"].includes(proposal.decision) ||
     typeof proposal.rationale !== "string" ||
     proposal.rationale.length < 1 ||
     proposal.rationale.length > 2_000 ||
@@ -207,6 +235,35 @@ function validateProposalEnvelope(proposal: SupervisorPlanProposal, planId: stri
   ) {
     throw new Error(`supervisor plan proposal ${planId} has an unsupported schema`);
   }
+  if (proposal.milestone !== undefined) {
+    const milestone = proposal.milestone;
+    if (
+      !Number.isSafeInteger(milestone.sequence) ||
+      milestone.sequence < 1 ||
+      milestone.sequence > 20 ||
+      typeof milestone.title !== "string" ||
+      milestone.title.length < 1 ||
+      milestone.title.length > 200 ||
+      typeof milestone.objective !== "string" ||
+      milestone.objective.length < 1 ||
+      milestone.objective.length > 4_000 ||
+      !Array.isArray(milestone.acceptance) ||
+      milestone.acceptance.length < 1 ||
+      milestone.acceptance.length > 50 ||
+      milestone.acceptance.some(
+        (criterion) =>
+          typeof criterion !== "string" || criterion.length < 1 || criterion.length > 500,
+      )
+    ) {
+      throw new Error(`supervisor plan proposal ${planId} milestone is invalid`);
+    }
+  }
+  if (
+    (proposal.decision === "attention" || proposal.decision === "complete") &&
+    (proposal.root !== "" || proposal.work.length > 0 || proposal.milestone !== undefined)
+  ) {
+    throw new Error(`supervisor plan proposal ${planId} terminal decision contains work`);
+  }
   for (const [index, spec] of proposal.work.entries()) {
     if (
       !spec ||

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

@@ -35,12 +35,20 @@ export interface SupervisorPlanRequest {
   id: string;
   goal_id: string;
   sequence: number;
+  trigger?: "initial" | "recovery" | "milestone";
   trigger_fingerprint: string;
   prior_root_work_id: string;
   workflow_run_id: string;
   created_at: string;
 }
 
+export interface SupervisorPlanMilestone {
+  sequence: number;
+  title: string;
+  objective: string;
+  acceptance: string[];
+}
+
 export interface SupervisorPlanWorkSpec {
   key: string;
   title: string;
@@ -53,10 +61,11 @@ export interface SupervisorPlanWorkSpec {
 export interface SupervisorPlanProposal {
   schema_version: typeof SUPERVISOR_PLAN_SCHEMA_VERSION;
   plan_id: string;
-  decision: "apply" | "attention";
+  decision: "apply" | "complete" | "attention";
   rationale: string;
   root: string;
   work: SupervisorPlanWorkSpec[];
+  milestone?: SupervisorPlanMilestone;
   proposed_at: string;
 }
 
@@ -65,6 +74,7 @@ export type SupervisorPlanEventType =
   | "plan.resumed"
   | "plan.proposed"
   | "plan.applied"
+  | "plan.completed"
   | "plan.rejected"
   | "plan.attention"
   | "plan.failed";
@@ -88,6 +98,7 @@ export type SupervisorPlanStatus =
   | "resumable"
   | "proposed"
   | "applied"
+  | "completed"
   | "rejected"
   | "attention"
   | "failed";
@@ -109,6 +120,8 @@ export interface SupervisorPlanHistory {
   generation: number;
   applied_work_ids: string[];
   materialized_work_ids: string[];
+  milestones_completed: number;
+  completed: boolean;
   latest?: SupervisorPlanRecord;
 }
 

package/src/core/supervisor/planning.ts

@@ -14,6 +14,7 @@ import { dirname, join, resolve } from "node:path";
 import { createWorkItem, readWorkItem } from "../work/index.ts";
 import {
   type EngineOpts,
+  readWorkflowProof,
   runWorkflow,
   WorkflowParkedError,
   workflowScriptDigest,
@@ -22,6 +23,7 @@ import { readSupervisorPlan, readSupervisorPlans } from "./plan-read.ts";
 import {
   SUPERVISOR_PLAN_SCHEMA_VERSION,
   type SupervisorPlanEvent,
+  type SupervisorPlanMilestone,
   type SupervisorPlanOutcome,
   type SupervisorPlanProposal,
   type SupervisorPlanRequest,
@@ -60,6 +62,7 @@ export async function runSupervisorPlanner(
     generation: input.record.projection.plan_generation,
     work: input.record.work,
   });
+  const trigger = planTrigger(input.record);
   const resumable =
     history.latest?.status === "resumable" &&
     history.latest.request.trigger_fingerprint === triggerFingerprint &&
@@ -68,7 +71,13 @@ export async function runSupervisorPlanner(
       : undefined;
   const request = resumable
     ? resumable.request
-    : createPlanRequest(coordRoot, input.record, history.plans.length + 1, triggerFingerprint);
+    : createPlanRequest(
+        coordRoot,
+        input.record,
+        history.plans.length + 1,
+        triggerFingerprint,
+        trigger,
+      );
   const scriptPath = planScriptPath(coordRoot, input.record.intent.id, request.id);
   if (resumable) {
     appendPlanEvent(coordRoot, input.record.intent.id, request.id, {
@@ -96,6 +105,7 @@ export async function runSupervisorPlanner(
       report.result,
       input.record,
       history.materialized_work_ids.length,
+      request.trigger ?? "recovery",
     );
     writeExclusiveJson(
       planProposalPath(coordRoot, input.record.intent.id, request.id),
@@ -157,8 +167,12 @@ export function applySupervisorPlanProposal(input: {
   const policy = input.record.intent.replanning;
   if (!policy) throw new Error(`supervisor ${input.record.intent.id} does not allow replanning`);
   const plan = readSupervisorPlan(coordRoot, input.record.intent.id, input.planId);
-  if (plan.status === "applied") return outcome(plan);
-  if (plan.status !== "proposed" || !plan.proposal || plan.proposal.decision !== "apply") {
+  if (plan.status === "applied" || plan.status === "completed") return outcome(plan);
+  if (
+    plan.status !== "proposed" ||
+    !plan.proposal ||
+    !["apply", "complete"].includes(plan.proposal.decision)
+  ) {
     throw new Error(`supervisor plan ${input.planId} cannot be applied from ${plan.status}`);
   }
   if (plan.request.prior_root_work_id !== input.record.projection.root_work_id) {
@@ -176,7 +190,16 @@ export function applySupervisorPlanProposal(input: {
     plan.proposal,
     input.record,
     history.materialized_work_ids.filter((workId) => !workId.startsWith(`${input.planId}-`)).length,
+    plan.request.trigger ?? "recovery",
   );
+  if (proposal.decision === "complete") {
+    appendPlanEvent(coordRoot, input.record.intent.id, input.planId, {
+      event: "plan.completed",
+      actor: input.actor,
+      reason: input.reason ?? proposal.rationale,
+    });
+    return outcome(readSupervisorPlan(coordRoot, input.record.intent.id, input.planId));
+  }
   const ids = new Map<string, string>();
   const created: string[] = [];
   for (const spec of proposal.work) {
@@ -268,6 +291,7 @@ function createPlanRequest(
   record: SupervisorRecord,
   sequence: number,
   triggerFingerprint: string,
+  trigger: NonNullable<SupervisorPlanRequest["trigger"]>,
 ): SupervisorPlanRequest {
   const policy = record.intent.replanning;
   if (!policy) throw new Error(`supervisor ${record.intent.id} does not allow replanning`);
@@ -280,36 +304,47 @@ function createPlanRequest(
     id: planId,
     goal_id: record.intent.id,
     sequence,
+    trigger,
     trigger_fingerprint: triggerFingerprint,
     prior_root_work_id: record.projection.root_work_id,
     workflow_run_id: `${planId}-workflow`,
     created_at: new Date().toISOString(),
   };
+  const script = plannerScript(coordRoot, record, planId, trigger);
   const dir = planDir(coordRoot, record.intent.id, planId);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   chmodSync(dir, 0o700);
   writeExclusiveJson(join(dir, "request.json"), request, "supervisor plan request");
-  const script = plannerScript(record, planId);
   writeExclusive(join(dir, "planner.mjs"), script, "supervisor planner script");
   return request;
 }
 
-function plannerScript(record: SupervisorRecord, planId: string): string {
+function plannerScript(
+  coordRoot: string,
+  record: SupervisorRecord,
+  planId: string,
+  trigger: NonNullable<SupervisorPlanRequest["trigger"]>,
+): string {
   const policy = record.intent.replanning;
   if (!policy) throw new Error(`supervisor ${record.intent.id} does not allow replanning`);
   const prompt = [
-    "You are producing a bounded replacement plan for a durable supervised goal.",
-    "The current graph is blocked and cannot make a legal scheduling step.",
-    "Return decision=apply with a new immutable root graph, or decision=attention when human judgment is required.",
-    "Never claim work is complete. Never request a workflow outside the frozen template catalog.",
+    "You are producing one bounded replacement plan or milestone decision for a durable supervised goal.",
+    record.intent.mission
+      ? "Return decision=apply with the next immutable milestone graph, decision=complete only when mission acceptance is met, or decision=attention when human judgment is required."
+      : "Return decision=apply with a replacement immutable root graph, or decision=attention when human judgment is required.",
+    "Never claim mission completion unless the frozen mission acceptance is met. Never request a workflow outside the frozen template catalog.",
     "Dependencies may name an active work ID or an earlier key in your proposed work array.",
     "Every proposed item must be reachable from root. The root must be a proposed key using a root-capable template.",
     `Plan id: ${planId}`,
+    `Planning trigger: ${trigger}`,
     `Goal: ${record.intent.title}`,
+    `Mission: ${JSON.stringify(record.intent.mission ?? null)}`,
     `Original root: ${record.intent.root_work_id}`,
     `Active root: ${record.projection.root_work_id}`,
     `Remaining work attempts: ${record.projection.attempts_remaining}`,
     `Remaining replans: ${record.projection.replans_remaining}`,
+    `Completed milestones: ${record.projection.milestones_completed}`,
+    `Remaining milestones: ${record.projection.milestones_remaining}`,
     `Latest planner outcome: ${JSON.stringify(
       record.plans.at(-1)
         ? {
@@ -328,13 +363,32 @@ function plannerScript(record: SupervisorRecord, planId: string): string {
         dependencies: work.intent.dependencies,
         state: work.projection.state,
         reason: work.projection.reason,
+        proof: work.projection.proof_path
+          ? (() => {
+              const proof = readWorkflowProof(coordRoot, work.projection.latest_run_id!);
+              return {
+                run_id: proof.run.id,
+                status: proof.run.status,
+                acceptance: proof.acceptance.summary,
+                repository: {
+                  head_changed: proof.repository.drift.head_changed,
+                  dirty_paths_added: proof.repository.drift.dirty_paths_added,
+                  incomplete: proof.repository.drift.incomplete,
+                },
+                unknowns: proof.unknowns.map((unknown) => unknown.code),
+              };
+            })()
+          : null,
       })),
     )}`,
   ].join("\n\n");
   const schema = {
     type: "object",
     properties: {
-      decision: { type: "string", enum: ["apply", "attention"] },
+      decision: {
+        type: "string",
+        enum: record.intent.mission ? ["apply", "complete", "attention"] : ["apply", "attention"],
+      },
       rationale: { type: "string" },
       root: { type: "string" },
       work: {
@@ -352,13 +406,29 @@ function plannerScript(record: SupervisorRecord, planId: string): string {
           required: ["key", "title", "objective", "acceptance", "dependencies", "template"],
         },
       },
+      milestone: {
+        type: "object",
+        properties: {
+          sequence: { type: "number" },
+          title: { type: "string" },
+          objective: { type: "string" },
+          acceptance: { type: "array", items: { type: "string" } },
+        },
+        required: ["sequence", "title", "objective", "acceptance"],
+      },
     },
     required: ["decision", "rationale", "root", "work"],
   };
   return [
     `export const meta = ${JSON.stringify({ name: `replan-${planId}` })};`,
     "export default async ({ agent, stage }) => {",
-    '  stage("Replan blocked goal");',
+    `  stage(${JSON.stringify(
+      trigger === "initial"
+        ? "Plan initial mission milestone"
+        : trigger === "milestone"
+          ? "Reassess completed milestone"
+          : "Replan blocked goal",
+    )});`,
     `  return await agent(${JSON.stringify(prompt)}, ${JSON.stringify({
       specialist: policy.planner_specialist,
       schema,
@@ -374,6 +444,7 @@ function normalizeProposal(
   raw: unknown,
   record: SupervisorRecord,
   previouslyApplied: number,
+  trigger: NonNullable<SupervisorPlanRequest["trigger"]>,
 ): SupervisorPlanProposal {
   const policy = record.intent.replanning;
   if (!policy) throw new Error(`supervisor ${record.intent.id} does not allow replanning`);
@@ -381,12 +452,17 @@ function normalizeProposal(
     throw new Error("planner result must be an object");
   }
   const value = raw as Record<string, unknown>;
-  const decision = enumValue(value.decision, ["apply", "attention"], "plan decision");
+  const decision = enumValue(value.decision, ["apply", "complete", "attention"], "plan decision");
   const rationale = bounded(value.rationale, "plan rationale", MAX_REASON);
   const root = typeof value.root === "string" ? value.root.trim() : "";
   if (!Array.isArray(value.work)) throw new Error("plan work must be an array");
-  if (decision === "attention") {
-    if (root || value.work.length > 0) throw new Error("attention plan must not contain work");
+  if (decision === "attention" || decision === "complete") {
+    if (root || value.work.length > 0 || value.milestone !== undefined) {
+      throw new Error(`${decision} plan must not contain work or milestone data`);
+    }
+    if (decision === "complete" && (!record.intent.mission || trigger !== "milestone")) {
+      throw new Error("mission completion may be proposed only at a milestone boundary");
+    }
     return {
       schema_version: SUPERVISOR_PLAN_SCHEMA_VERSION,
       plan_id: planId,
@@ -397,6 +473,17 @@ function normalizeProposal(
       proposed_at: new Date().toISOString(),
     };
   }
+  const milestone = record.intent.mission
+    ? normalizeMilestone(value.milestone, record.projection.milestones_completed + 1)
+    : undefined;
+  if (!record.intent.mission && value.milestone !== undefined) {
+    throw new Error("non-mission replacement plan must not contain milestone data");
+  }
+  if (milestone && milestone.sequence > record.intent.mission!.max_milestones) {
+    throw new Error(
+      `milestone ${milestone.sequence} exceeds mission limit ${record.intent.mission!.max_milestones}`,
+    );
+  }
   if (value.work.length < 1 || value.work.length > policy.max_work_items_per_plan) {
     throw new Error(`plan work must contain 1 to ${policy.max_work_items_per_plan} items`);
   }
@@ -477,10 +564,45 @@ function normalizeProposal(
     rationale,
     root,
     work,
+    ...(milestone ? { milestone } : {}),
     proposed_at: new Date().toISOString(),
   };
 }
 
+function normalizeMilestone(raw: unknown, expectedSequence: number): SupervisorPlanMilestone {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("mission plan must contain a milestone object");
+  }
+  const value = raw as Record<string, unknown>;
+  if (value.sequence !== expectedSequence) {
+    throw new Error(`milestone sequence must be ${expectedSequence}`);
+  }
+  if (!Array.isArray(value.acceptance) || value.acceptance.length < 1) {
+    throw new Error("milestone acceptance must be a non-empty array");
+  }
+  if (value.acceptance.length > 50) throw new Error("milestone acceptance exceeds 50 criteria");
+  return {
+    sequence: expectedSequence,
+    title: bounded(value.title, "milestone title", 200),
+    objective: bounded(value.objective, "milestone objective", 4_000),
+    acceptance: value.acceptance.map((criterion, index) =>
+      bounded(criterion, `milestone acceptance[${index}]`, 500),
+    ),
+  };
+}
+
+function planTrigger(record: SupervisorRecord): NonNullable<SupervisorPlanRequest["trigger"]> {
+  if (
+    record.intent.mission &&
+    record.projection.plan_generation === 0 &&
+    record.work.length === 0
+  ) {
+    return "initial";
+  }
+  const root = record.work.find((work) => work.intent.id === record.projection.root_work_id);
+  return record.intent.mission && root?.projection.state === "succeeded" ? "milestone" : "recovery";
+}
+
 function appendPlanEvent(
   coordRootRaw: string,
   goalId: string,

package/src/core/supervisor/read.ts

@@ -4,6 +4,7 @@ export {
   type SupervisorPlanEvent,
   type SupervisorPlanEventType,
   type SupervisorPlanHistory,
+  type SupervisorPlanMilestone,
   type SupervisorPlanOutcome,
   type SupervisorPlanProposal,
   type SupervisorPlanRecord,
@@ -37,6 +38,7 @@ export {
   type SupervisorAutomationPolicy,
   type SupervisorIntent,
   type SupervisorLimits,
+  type SupervisorMission,
   type SupervisorNextAction,
   type SupervisorProjection,
   type SupervisorRecord,

package/src/core/supervisor/runner.ts

@@ -97,9 +97,13 @@ export async function runSupervisor(input: RunSupervisorInput): Promise<Supervis
 
       const before = graphFingerprint(record);
       let changed = false;
-      if (record.projection.next_action === "replan") {
+      if (
+        record.projection.next_action === "replan" ||
+        record.projection.next_action === "plan_initial" ||
+        record.projection.next_action === "plan_milestone"
+      ) {
         log(
-          `[${record.intent.title}] replan active graph generation ${record.projection.plan_generation}`,
+          `[${record.intent.title}] ${record.projection.next_action} at graph generation ${record.projection.plan_generation}`,
         );
         const plan = await runSupervisorPlanner({
           coordRoot,
@@ -118,6 +122,9 @@ export async function runSupervisor(input: RunSupervisorInput): Promise<Supervis
             record,
           );
         }
+        if (record.projection.state === "succeeded") {
+          return report("succeeded", record.projection.reason, record);
+        }
         if (record.projection.state !== "ready") {
           return report(stopForProjection(record.projection), record.projection.reason, record);
         }

package/src/core/supervisor/service.ts

@@ -616,9 +616,12 @@ function projectionFingerprint(projection: SupervisorRecord["projection"]): stri
     projection.attempts_used,
     projection.attempts_remaining,
     projection.root_work_id,
+    projection.root_materialized,
     projection.plan_generation,
     projection.replans_used,
     projection.replans_remaining,
+    projection.milestones_completed,
+    projection.milestones_remaining,
     projection.pending_plan_id,
     projection.latest_plan_status,
     projection.ready_work,