harnery 0.17.0 → 0.19.0

package/src/core/supervisor/read.ts

@@ -1,13 +1,27 @@
-export { readSupervisorPlan, readSupervisorPlans } from "./plan-read.ts";
 export {
+  readSupervisorPlan,
+  readSupervisorPlanReviewReceipt,
+  readSupervisorPlans,
+} from "./plan-read.ts";
+export {
+  MAX_SUPERVISOR_PLAN_REVIEWERS,
+  MAX_SUPERVISOR_PLAN_REVISION_ROUNDS,
   SUPERVISOR_PLAN_SCHEMA_VERSION,
   type SupervisorPlanEvent,
   type SupervisorPlanEventType,
   type SupervisorPlanHistory,
+  type SupervisorPlanMilestone,
   type SupervisorPlanOutcome,
   type SupervisorPlanProposal,
   type SupervisorPlanRecord,
   type SupervisorPlanRequest,
+  type SupervisorPlanReviewFinding,
+  type SupervisorPlanReviewReceipt,
+  type SupervisorPlanReviewReviewer,
+  type SupervisorPlanReviewRound,
+  type SupervisorPlanReviewStatus,
+  type SupervisorPlanReviewSummary,
+  type SupervisorPlanReviewVerdict,
   type SupervisorPlanStatus,
   type SupervisorPlanTemplate,
   type SupervisorPlanWorkSpec,
@@ -37,6 +51,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,

package/src/core/supervisor/state.ts

@@ -20,6 +20,8 @@ import type { WorkflowSpecialistProfile } from "../workflow/types.ts";
 import { readSupervisorPlans } from "./plan-read.ts";
 import {
   type CreateSupervisorReplanningInput,
+  MAX_SUPERVISOR_PLAN_REVIEWERS,
+  MAX_SUPERVISOR_PLAN_REVISION_ROUNDS,
   type SupervisorPlanHistory,
   type SupervisorPlanRecord,
   type SupervisorReplanningPolicy,
@@ -30,6 +32,8 @@ export const SUPERVISOR_INTENT_SCHEMA_VERSION = 1 as const;
 
 const GOAL_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 const MAX_TITLE = 200;
+const MAX_OBJECTIVE = 4_000;
+const MAX_ACCEPTANCE = 50;
 const MAX_INTENT_BYTES = 256 * 1024;
 const MAX_TEMPLATES = 20;
 const TEMPLATE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -50,6 +54,18 @@ export interface SupervisorAutomationPolicy {
   retry_blocked: boolean;
 }
 
+export interface SupervisorMission {
+  objective: string;
+  acceptance: string[];
+  max_milestones: number;
+}
+
+export interface CreateSupervisorMissionInput {
+  objective: string;
+  acceptance: readonly string[];
+  maxMilestones?: number;
+}
+
 export interface SupervisorIntent {
   schema_version: typeof SUPERVISOR_INTENT_SCHEMA_VERSION;
   id: string;
@@ -58,6 +74,7 @@ export interface SupervisorIntent {
   specialists: Record<string, WorkflowSpecialistProfile>;
   limits: SupervisorLimits;
   automation: SupervisorAutomationPolicy;
+  mission?: SupervisorMission;
   replanning?: SupervisorReplanningPolicy;
   created_at: string;
 }
@@ -77,6 +94,8 @@ export type SupervisorNextAction =
   | "review"
   | "retry"
   | "replan"
+  | "plan_initial"
+  | "plan_milestone"
   | "review_plan"
   | "none";
 
@@ -84,6 +103,7 @@ export interface SupervisorProjection {
   id: string;
   title: string;
   root_work_id: string;
+  root_materialized: boolean;
   state: SupervisorState;
   reason: string;
   next_action: SupervisorNextAction;
@@ -98,6 +118,8 @@ export interface SupervisorProjection {
   plan_generation: number;
   replans_used: number;
   replans_remaining: number;
+  milestones_completed: number;
+  milestones_remaining: number;
   pending_plan_id?: string;
   latest_plan_status?: SupervisorPlanRecord["status"];
   governed_work_ids: string[];
@@ -112,32 +134,58 @@ export interface SupervisorRecord {
 
 export interface CreateSupervisorInput {
   coordRoot: string;
-  rootWorkId: string;
+  rootWorkId?: string;
   specialists: Readonly<Record<string, WorkflowSpecialistProfile>>;
   title?: string;
   id?: string;
   limits?: Partial<SupervisorLimits>;
   automation?: Partial<SupervisorAutomationPolicy>;
+  mission?: CreateSupervisorMissionInput;
   replanning?: CreateSupervisorReplanningInput;
 }
 
 export function createSupervisor(input: CreateSupervisorInput): SupervisorRecord {
   const coordRoot = resolve(input.coordRoot);
-  assertWorkId(input.rootWorkId);
-  const root = readWorkItem(coordRoot, input.rootWorkId);
   const id = input.id ?? newSupervisorId();
   assertSupervisorId(id);
+  const mission = input.mission ? normalizeMission(input.mission) : undefined;
+  if (mission && !input.replanning) {
+    throw new Error("supervisor mission requires a replanning policy");
+  }
+  if (!input.rootWorkId && !mission) {
+    throw new Error(
+      "supervisor creation without root work requires a mission and replanning policy",
+    );
+  }
+  if (input.rootWorkId) assertWorkId(input.rootWorkId);
+  const root = input.rootWorkId ? readWorkItem(coordRoot, input.rootWorkId) : undefined;
+  const limits = normalizeLimits(input.limits);
   const replanning = input.replanning
-    ? normalizeReplanning(input.replanning, input.specialists)
+    ? normalizeReplanning(input.replanning, input.specialists, limits)
     : undefined;
+  if (
+    mission &&
+    !input.rootWorkId &&
+    replanning &&
+    replanning.max_replans <= mission.max_milestones
+  ) {
+    throw new Error(
+      "objective-first mission max_replans must exceed max_milestones to reserve completion review",
+    );
+  }
   const intent: SupervisorIntent = {
     schema_version: SUPERVISOR_INTENT_SCHEMA_VERSION,
     id,
-    title: bounded(input.title ?? root.intent.title, "supervisor title", MAX_TITLE),
-    root_work_id: input.rootWorkId,
+    title: bounded(
+      input.title ?? root?.intent.title ?? missionTitle(mission!),
+      "supervisor title",
+      MAX_TITLE,
+    ),
+    root_work_id: input.rootWorkId ?? missionRootId(id),
     specialists: normalizeWorkflowSpecialists(input.specialists),
-    limits: normalizeLimits(input.limits),
+    limits,
     automation: normalizeAutomation(input.automation),
+    ...(mission ? { mission } : {}),
     ...(replanning ? { replanning } : {}),
     created_at: new Date().toISOString(),
   };
@@ -248,7 +296,11 @@ function readSupervisorInternal(
   const coordRoot = resolve(coordRootRaw);
   const intent = readSupervisorIntent(coordRoot, goalId);
   const plans = readSupervisorPlans(coordRoot, intent.id, intent.root_work_id);
-  const work = collectSupervisorWork(coordRoot, plans.active_root_work_id);
+  const activeRootExists = workIntentExists(coordRoot, plans.active_root_work_id);
+  if (!activeRootExists && (!intent.mission || plans.generation > 0)) {
+    throw new Error(`supervisor ${intent.id} root work is missing`);
+  }
+  const work = activeRootExists ? collectSupervisorWork(coordRoot, plans.active_root_work_id) : [];
   const governed = collectGovernedWork(coordRoot, intent.root_work_id, plans, work);
   return {
     intent,
@@ -267,7 +319,6 @@ function deriveProjection(
   ignoreLease: boolean,
 ): SupervisorProjection {
   const root = work.find((record) => record.intent.id === plans.active_root_work_id);
-  if (!root) throw new Error(`supervisor ${intent.id} root work is missing`);
   const attemptsUsed = governed.reduce((sum, record) => sum + record.projection.attempts_used, 0);
   const readyWork = work
     .filter((record) => record.projection.state === "ready")
@@ -311,10 +362,18 @@ function deriveProjection(
     ...cancelled,
     ...terminalBlocked,
   ]);
+  const initialRootAccepted =
+    intent.mission !== undefined &&
+    governed.some(
+      (record) =>
+        record.intent.id === intent.root_work_id && record.projection.state === "succeeded",
+    );
+  const milestonesCompleted = plans.milestones_completed + (initialRootAccepted ? 1 : 0);
   const base = {
     id: intent.id,
     title: intent.title,
     root_work_id: plans.active_root_work_id,
+    root_materialized: root !== undefined,
     work_ids: work.map((record) => record.intent.id),
     ready_work: readyWork,
     resumable_work: resumableWork,
@@ -326,6 +385,8 @@ function deriveProjection(
     plan_generation: plans.generation,
     replans_used: plans.plans.length,
     replans_remaining: Math.max(0, (intent.replanning?.max_replans ?? 0) - plans.plans.length),
+    milestones_completed: milestonesCompleted,
+    milestones_remaining: Math.max(0, (intent.mission?.max_milestones ?? 0) - milestonesCompleted),
     pending_plan_id: plans.latest?.status === "proposed" ? plans.latest.request.id : undefined,
     latest_plan_status: plans.latest?.status,
     governed_work_ids: governed.map((record) => record.intent.id),
@@ -338,11 +399,11 @@ function deriveProjection(
       next_action: "wait_for_run",
     };
   }
-  if (root.projection.state === "succeeded") {
+  if (intent.mission && plans.completed) {
     return {
       ...base,
       state: "succeeded",
-      reason: "root work was explicitly accepted",
+      reason: "mission completion was explicitly accepted",
       next_action: "none",
     };
   }
@@ -370,6 +431,64 @@ function deriveProjection(
       next_action: "replan",
     };
   }
+  const triggerFingerprint = supervisorGraphFingerprint({
+    rootWorkId: plans.active_root_work_id,
+    generation: plans.generation,
+    work,
+  });
+  const latestHandledSameGraph =
+    plans.latest?.request.trigger_fingerprint === triggerFingerprint &&
+    plans.latest.request.prior_root_work_id === plans.active_root_work_id &&
+    plans.latest.status === "attention";
+  if (latestHandledSameGraph && plans.latest) {
+    return {
+      ...base,
+      state: "awaiting_attention",
+      reason: plans.latest.reason ?? `plan ${plans.latest.request.id} requires attention`,
+      next_action: "none",
+    };
+  }
+  if (!root && intent.mission) {
+    if (!intent.replanning || plans.plans.length >= intent.replanning.max_replans) {
+      return {
+        ...base,
+        state: "budget_exhausted",
+        reason: "mission exhausted its planning budget before creating an initial milestone",
+        next_action: "none",
+      };
+    }
+    return {
+      ...base,
+      state: "ready",
+      reason: "mission is ready for its initial bounded milestone plan",
+      next_action: "plan_initial",
+    };
+  }
+  if (!root) throw new Error(`supervisor ${intent.id} root work is missing`);
+  if (root.projection.state === "succeeded" && intent.mission) {
+    if (!intent.replanning || plans.plans.length >= intent.replanning.max_replans) {
+      return {
+        ...base,
+        state: "budget_exhausted",
+        reason: "mission exhausted its planning budget at a milestone boundary",
+        next_action: "none",
+      };
+    }
+    return {
+      ...base,
+      state: "ready",
+      reason: `milestone ${plans.milestones_completed} is accepted and requires mission reassessment`,
+      next_action: "plan_milestone",
+    };
+  }
+  if (root.projection.state === "succeeded") {
+    return {
+      ...base,
+      state: "succeeded",
+      reason: "root work was explicitly accepted",
+      next_action: "none",
+    };
+  }
   const resumableDispatchable = intent.automation.resume_approved ? resumableWork : [];
   const attemptDispatchable = [
     ...readyWork,
@@ -448,15 +567,6 @@ function deriveProjection(
       next_action: "none",
     };
   }
-  const triggerFingerprint = supervisorGraphFingerprint({
-    rootWorkId: plans.active_root_work_id,
-    generation: plans.generation,
-    work,
-  });
-  const latestHandledSameGraph =
-    plans.latest?.request.trigger_fingerprint === triggerFingerprint &&
-    plans.latest.request.prior_root_work_id === plans.active_root_work_id &&
-    plans.latest.status === "attention";
   const canReplan =
     intent.replanning !== undefined &&
     plans.plans.length < intent.replanning.max_replans &&
@@ -484,14 +594,6 @@ function deriveProjection(
       next_action: "none",
     };
   }
-  if (latestHandledSameGraph && plans.latest) {
-    return {
-      ...base,
-      state: "awaiting_attention",
-      reason: plans.latest.reason ?? `plan ${plans.latest.request.id} requires attention`,
-      next_action: "none",
-    };
-  }
   return {
     ...base,
     state: "blocked",
@@ -531,6 +633,19 @@ function validateIntent(intent: SupervisorIntent, goalId: string): void {
   }
   bounded(intent.title, "supervisor title", MAX_TITLE);
   assertWorkId(intent.root_work_id);
+  if (intent.mission) {
+    const normalizedMission = normalizeMission({
+      objective: intent.mission.objective,
+      acceptance: intent.mission.acceptance,
+      maxMilestones: intent.mission.max_milestones,
+    });
+    if (JSON.stringify(normalizedMission) !== JSON.stringify(intent.mission)) {
+      throw new Error(`supervisor intent ${goalId} mission is not canonical`);
+    }
+    if (!intent.replanning) {
+      throw new Error(`supervisor intent ${goalId} mission requires replanning`);
+    }
+  }
   const specialists = normalizeWorkflowSpecialists(intent.specialists);
   if (JSON.stringify(specialists) !== JSON.stringify(intent.specialists)) {
     throw new Error(`supervisor intent ${goalId} specialists are not canonical`);
@@ -543,7 +658,33 @@ function validateIntent(intent: SupervisorIntent, goalId: string): void {
   ) {
     throw new Error(`supervisor intent ${goalId} automation policy is not canonical`);
   }
-  if (intent.replanning) validateReplanning(intent.replanning, specialists, goalId);
+  if (intent.replanning) validateReplanning(intent.replanning, specialists, intent.limits, goalId);
+}
+
+function normalizeMission(input: CreateSupervisorMissionInput): SupervisorMission {
+  if (!Array.isArray(input.acceptance)) {
+    throw new Error("supervisor mission acceptance must be an array");
+  }
+  if (input.acceptance.length < 1 || input.acceptance.length > MAX_ACCEPTANCE) {
+    throw new Error(`supervisor mission acceptance must contain 1 to ${MAX_ACCEPTANCE} criteria`);
+  }
+  const acceptance = input.acceptance.map((criterion, index) =>
+    bounded(criterion, `supervisor mission acceptance[${index}]`, 500),
+  );
+  if (new Set(acceptance).size !== acceptance.length) {
+    throw new Error("supervisor mission acceptance criteria must be unique");
+  }
+  return {
+    objective: bounded(input.objective, "supervisor mission objective", MAX_OBJECTIVE),
+    acceptance,
+    max_milestones: positive(input.maxMilestones ?? 4, "supervisor mission max_milestones", 20),
+  };
+}
+
+function missionTitle(mission: SupervisorMission): string {
+  return mission.objective.length <= MAX_TITLE
+    ? mission.objective
+    : `${mission.objective.slice(0, MAX_TITLE - 1).trimEnd()}…`;
 }
 
 function normalizeLimits(input: Partial<SupervisorLimits> | undefined): SupervisorLimits {
@@ -582,6 +723,7 @@ function normalizeAutomation(
 function normalizeReplanning(
   input: CreateSupervisorReplanningInput,
   specialistsInput: Readonly<Record<string, WorkflowSpecialistProfile>>,
+  limits: SupervisorLimits,
 ): SupervisorReplanningPolicy {
   const specialists = normalizeWorkflowSpecialists(specialistsInput);
   const plannerSpecialist = bounded(input.plannerSpecialist, "planner specialist", 100);
@@ -631,6 +773,9 @@ function normalizeReplanning(
   if (maxWorkItemsPerPlan > maxTotalWorkItems) {
     throw new Error("replanning max_work_items_per_plan cannot exceed max_total_work_items");
   }
+  const review = input.review
+    ? normalizeReviewPolicy(input.review, specialists, plannerSpecialist, limits)
+    : undefined;
   return {
     planner_specialist: plannerSpecialist,
     auto_apply: boolean(input.autoApply ?? false, "replanning auto_apply"),
@@ -638,12 +783,60 @@ function normalizeReplanning(
     max_work_items_per_plan: maxWorkItemsPerPlan,
     max_total_work_items: maxTotalWorkItems,
     templates,
+    ...(review ? { review } : {}),
+  };
+}
+
+function normalizeReviewPolicy(
+  input: NonNullable<CreateSupervisorReplanningInput["review"]>,
+  specialists: Record<string, WorkflowSpecialistProfile>,
+  plannerSpecialist: string,
+  limits: SupervisorLimits,
+): NonNullable<SupervisorReplanningPolicy["review"]> {
+  if (!Array.isArray(input.reviewerSpecialists) || input.reviewerSpecialists.length < 1) {
+    throw new Error("replanning review requires at least one reviewer specialist");
+  }
+  if (input.reviewerSpecialists.length > MAX_SUPERVISOR_PLAN_REVIEWERS) {
+    throw new Error(
+      `replanning review cannot exceed ${MAX_SUPERVISOR_PLAN_REVIEWERS} reviewer specialists`,
+    );
+  }
+  const reviewerSpecialists = input.reviewerSpecialists.map((specialist, index) =>
+    bounded(specialist, `reviewer specialist[${index}]`, 100),
+  );
+  if (new Set(reviewerSpecialists).size !== reviewerSpecialists.length) {
+    throw new Error("replanning reviewer specialists must be unique");
+  }
+  for (const specialist of reviewerSpecialists) {
+    if (!specialists[specialist]) {
+      throw new Error(`reviewer specialist ${specialist} is not present in the frozen team`);
+    }
+    if (specialist === plannerSpecialist) {
+      throw new Error("reviewer specialist cannot be the planner specialist");
+    }
+  }
+  const maxRevisionRounds = nonNegative(
+    input.maxRevisionRounds,
+    "replanning review max_revision_rounds",
+    MAX_SUPERVISOR_PLAN_REVISION_ROUNDS,
+  );
+  const worstCaseAgents =
+    1 + reviewerSpecialists.length * (maxRevisionRounds + 1) + maxRevisionRounds;
+  if (worstCaseAgents > limits.max_agents_per_work) {
+    throw new Error(
+      `replanning review worst-case ${worstCaseAgents} agents exceeds max_agents_per_work ${limits.max_agents_per_work}`,
+    );
+  }
+  return {
+    reviewer_specialists: reviewerSpecialists,
+    max_revision_rounds: maxRevisionRounds,
   };
 }
 
 function validateReplanning(
   policy: SupervisorReplanningPolicy,
   specialists: Record<string, WorkflowSpecialistProfile>,
+  limits: SupervisorLimits,
   goalId: string,
 ): void {
   if (!specialists[policy.planner_specialist]) {
@@ -676,6 +869,37 @@ function validateReplanning(
     rootCapable ||= template.root;
   }
   if (!rootCapable) throw new Error(`supervisor ${goalId} has no root-capable replanning template`);
+  if (policy.review !== undefined) {
+    const review = policy.review;
+    if (
+      !Array.isArray(review.reviewer_specialists) ||
+      review.reviewer_specialists.length < 1 ||
+      review.reviewer_specialists.length > MAX_SUPERVISOR_PLAN_REVIEWERS ||
+      !Number.isSafeInteger(review.max_revision_rounds) ||
+      review.max_revision_rounds < 0 ||
+      review.max_revision_rounds > MAX_SUPERVISOR_PLAN_REVISION_ROUNDS
+    ) {
+      throw new Error(`supervisor ${goalId} replanning review policy is invalid`);
+    }
+    if (new Set(review.reviewer_specialists).size !== review.reviewer_specialists.length) {
+      throw new Error(`supervisor ${goalId} replanning reviewers are not unique`);
+    }
+    for (const specialist of review.reviewer_specialists) {
+      if (!specialists[specialist]) {
+        throw new Error(`supervisor ${goalId} reviewer specialist is not in the frozen team`);
+      }
+      if (specialist === policy.planner_specialist) {
+        throw new Error(`supervisor ${goalId} reviewer specialist cannot be planner`);
+      }
+    }
+    const worstCaseAgents =
+      1 +
+      review.reviewer_specialists.length * (review.max_revision_rounds + 1) +
+      review.max_revision_rounds;
+    if (worstCaseAgents > limits.max_agents_per_work) {
+      throw new Error(`supervisor ${goalId} review policy exceeds the agent budget`);
+    }
+  }
 }
 
 function collectGovernedWork(
@@ -685,8 +909,10 @@ function collectGovernedWork(
   active: WorkRecord[],
 ): WorkRecord[] {
   const governed = new Map<string, WorkRecord>();
-  for (const record of collectSupervisorWork(coordRoot, originalRootWorkId)) {
-    governed.set(record.intent.id, record);
+  if (workIntentExists(coordRoot, originalRootWorkId)) {
+    for (const record of collectSupervisorWork(coordRoot, originalRootWorkId)) {
+      governed.set(record.intent.id, record);
+    }
   }
   for (const workId of plans.applied_work_ids)
     governed.set(workId, readWorkItem(coordRoot, workId));
@@ -694,6 +920,14 @@ function collectGovernedWork(
   return [...governed.values()];
 }
 
+function workIntentExists(coordRoot: string, workId: string): boolean {
+  return existsSync(join(resolve(coordRoot), ".harnery", "work", workId, "intent.json"));
+}
+
+function missionRootId(goalId: string): string {
+  return `${goalId.slice(0, 87)}-mission-root`;
+}
+
 function supervisorDir(coordRoot: string, goalId: string): string {
   assertSupervisorId(goalId);
   return join(resolve(coordRoot), ".harnery", "supervisors", goalId);
@@ -767,6 +1001,13 @@ function positive(value: unknown, field: string, max: number): number {
   return value as number;
 }
 
+function nonNegative(value: unknown, field: string, max: number): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) > max) {
+    throw new Error(`${field} must be an integer between 0 and ${max}`);
+  }
+  return value as number;
+}
+
 function boolean(value: unknown, field: string): boolean {
   if (typeof value !== "boolean") throw new Error(`supervisor ${field} must be boolean`);
   return value;

package/src/core/workflow/engine.ts

@@ -58,6 +58,7 @@ import type {
   HarnessName,
   RunReport,
   SpawnResult,
+  StageSchema,
   WorkflowAgentProof,
   WorkflowContext,
   WorkflowEvidenceRecord,
@@ -423,6 +424,9 @@ async function executeWorkflow(
     const assignment = resolveSpecialistAssignment(specialists, prompt, requestedOpts);
     const agentOpts = assignment.opts;
     const assignmentPrompt = assignment.prompt;
+    const dispatchPrompt = agentOpts.schema
+      ? withSchemaContract(assignmentPrompt, agentOpts.schema)
+      : assignmentPrompt;
     let reservedForDispatch = 0;
     let spawnCountClaimed = false;
     const harness = agentOpts.harness ?? defaultHarness;
@@ -487,7 +491,7 @@ async function executeWorkflow(
         max_attempts: maxAttempts,
         max_turns: agentOpts.maxTurns ?? DEFAULT_MAX_TURNS,
         timeout_ms: agentOpts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-        prompt_bytes: Buffer.byteLength(assignmentPrompt),
+        prompt_bytes: Buffer.byteLength(dispatchPrompt),
         isolation,
         network_access: networkAccess,
         current_cost_usd: round4(costUsd + reservedCostUsd),
@@ -609,7 +613,7 @@ async function executeWorkflow(
       });
       log(`[${name}] ${currentStage || "(no stage)"} → ${id} [${harness}] ${label}`);
 
-      let attemptPrompt = assignmentPrompt;
+      let attemptPrompt = dispatchPrompt;
       let last: SpawnResult | null = null;
       let agentCostUsd = 0;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -678,12 +682,16 @@ async function executeWorkflow(
         }
 
         journal("agent.schema_retry", { id, attempt, problems });
-        // Feed the validation failure back verbatim — the retry prompt carries
-        // exactly what was wrong, which is what makes bounded retry converge.
+        // Keep the original cache identity while making the actual output
+        // contract explicit. A full bounded copy of the rejected value lets the
+        // child repair omissions instead of reconstructing an unseen object.
         attemptPrompt =
-          `${assignmentPrompt}\n\nYour previous reply failed validation:\n` +
+          `${dispatchPrompt}\n\nYour previous reply failed validation. ` +
+          `Return a complete replacement value, not a patch.\n\n` +
+          `Previous reply (JSON string): ${JSON.stringify(boundedSchemaReply(last.text))}\n\n` +
+          `Validation problems:\n` +
           `${problems.map((p) => `  - ${p}`).join("\n")}\n` +
-          `Reply with ONLY the corrected JSON object. No prose, no code fences.`;
+          `Reply with ONLY the corrected JSON value. No prose, no code fences.`;
       }
 
       const reason = last?.ok
@@ -892,6 +900,21 @@ async function executeWorkflow(
   }
 }
 
+const MAX_SCHEMA_RETRY_REPLY = 16_000;
+
+function withSchemaContract(prompt: string, schema: StageSchema): string {
+  return (
+    `${prompt}\n\nOutput contract:\n` +
+    `Return ONLY one JSON value matching this schema. Do not use prose or code fences.\n` +
+    `${JSON.stringify(schema)}`
+  );
+}
+
+function boundedSchemaReply(value: string): string {
+  if (value.length <= MAX_SCHEMA_RETRY_REPLY) return value;
+  return `${value.slice(0, MAX_SCHEMA_RETRY_REPLY)}\n[truncated by Harnery]`;
+}
+
 /** Stable identity for one agent() call, for the resume cache. The ORIGINAL
  * prompt (never a retry-mutated one) plus everything that changes behavior. */
 function agentCallKey(

package/src/core/workflow/types.ts

@@ -206,6 +206,12 @@ export interface StageSchema {
   required?: string[];
   /** type=array */
   items?: StageSchema;
+  minItems?: number;
+  maxItems?: number;
+  /** type=string */
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
   /** any type: closed value set (compared with ===) */
   enum?: Array<string | number | boolean>;
 }