@voybio/ace-swarm 2.4.8 → 2.4.10

package/dist/goal-engine.js

@@ -1,5 +1,8 @@
 /**
- * ACE Goal Engine (WS-F).
+ * ACE Goal Engine (WS-F), with attached MCP execution for host-authored plans.
+ * Host goals use the same filesystem records and plan primitives through
+ * next_step/complete_step. They enforce their declared contract and explicitly
+ * label completion without verification commands as not machine-verified.
  *
  * `startGoal("<objective>")` compiles a plan with ACE's own planner, then a
  * self-paced driver loop (`runGoal`) executes it step-by-step under evidence-
@@ -9,7 +12,7 @@
  * structurally impossible (there is no code path from a model message to
  * `status: "done"`).
  *
- * That guarantee rests on the success contract carrying at least one
+ * In the engine-executed path, that guarantee rests on the success contract carrying at least one
  * machine-checkable obligation. A contract with none is refused at `startGoal`
  * and again at verify time with `contract_uncheckable`, never satisfied
  * vacuously — see {@link enforceableObligationCount}.
@@ -27,14 +30,19 @@
  * hermetically in tests with a stub bridge.
  */
 import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { isAbsolute, join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
 import { amendTaskPlan, applyBridgeResultToStep, createTaskPlan, deriveTaskPlanStatus, getReadyTaskSteps, markTaskStepStatus, } from "./orchestrator-supervisor.js";
 import { proposePlan, validatePlan } from "./plan-proposal.js";
 import { resolveWorkspaceRoot } from "./helpers.js";
-import { appendVericifyProcessPostSafe } from "./vericify-bridge.js";
+import { appendAutomaticVericifyProcessPostSafe } from "./vericify-bridge.js";
 import { appendStatusEventSafe } from "./status-events.js";
 import { GoalRepository, defaultGoalBudgets, newGoalId, } from "./store/repositories/goal-repository.js";
 import { PlaybookRepository } from "./store/repositories/playbook-repository.js";
+import { failureSignature } from './experience-reflector.js';
+import { runProgressCommand } from './progress-command.js';
+export const verificationCommandText = (command) => typeof command === 'string' ? command : command.cmd;
 // ── Defaults for the injectable seams ────────────────────────────────────────
 function defaultArtifactExists(path, workspaceRoot) {
     if (!path || path.trim().length === 0)
@@ -43,16 +51,9 @@ function defaultArtifactExists(path, workspaceRoot) {
     const abs = isAbsolute(clean) ? clean : join(workspaceRoot, clean);
     return existsSync(abs);
 }
-async function defaultRunVerification(command, workspaceRoot) {
-    const { exec } = await import("node:child_process");
-    return await new Promise((resolve) => {
-        exec(command, { cwd: workspaceRoot, timeout: 10 * 60 * 1000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
-            resolve({
-                ok: !error,
-                output: `${stdout ?? ""}${stderr ? `\n${stderr}` : ""}`.trim(),
-            });
-        });
-    });
+async function defaultRunVerification(command, workspaceRoot, options) {
+    return runProgressCommand(command, workspaceRoot, { ...options,
+        ...(options?.timeout_ms !== undefined ? { deadline_min: options.timeout_ms / 60000 } : {}) });
 }
 async function defaultSpawnStep(step, _plan, _goal) {
     const { runLocalModelTask } = await import("./local-model-runtime.js");
@@ -66,7 +67,7 @@ async function defaultSpawnStep(step, _plan, _goal) {
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function resolveDeps(deps = {}) {
+export function resolveGoalDeps(deps = {}) {
     const workspaceRoot = deps.workspaceRoot ?? resolveWorkspaceRoot();
     const repo = new GoalRepository(workspaceRoot);
     return {
@@ -98,7 +99,7 @@ function resolveDeps(deps = {}) {
                 const kind = input.kind === "progress" || input.kind === "completion" || input.kind === "blocker"
                     ? input.kind
                     : "blocker";
-                await appendVericifyProcessPostSafe({
+                await appendAutomaticVericifyProcessPostSafe({
                     run_id: "workspace:current",
                     agent_id: "ace-goal-engine",
                     kind: kind === "completion" ? "completion" : kind === "progress" ? "progress" : "blocker",
@@ -109,6 +110,7 @@ function resolveDeps(deps = {}) {
             }),
     };
 }
+const resolveDeps = resolveGoalDeps;
 // ── Success-contract compilation ─────────────────────────────────────────────
 const CRITERION_VERIFICATION_HINT = /^\s*verify\s*:\s*(.+)$/i;
 const OBJECTIVE_VERIFICATION_HINT = /(?:^|[.!?]\s+)verify\s*:\s*(.+)$/i;
@@ -203,15 +205,18 @@ function compileSuccessContract(proposal, input = {}) {
     for (const command of extractVerificationCommands(input.objective ?? "", "objective")) {
         commands.add(command);
     }
-    for (const command of input.verify_commands ?? []) {
-        const trimmed = command.trim();
+    for (const declaration of input.verify_commands ?? []) {
+        const trimmed = verificationCommandText(declaration).trim();
         if (trimmed)
             commands.add(trimmed);
     }
     return {
         expected_artifacts: Array.from(expected.values()),
         required_evidence_refs: Array.from(evidence),
-        verification_commands: Array.from(commands),
+        verification_commands: Array.from(commands).map(command => {
+            const declaration = input.verify_commands?.find(c => verificationCommandText(c).trim() === command);
+            return declaration && typeof declaration !== 'string' ? { ...declaration, cmd: command } : command;
+        }),
         gate_ids: [],
         uncompilable_criteria: uncompilable,
     };
@@ -252,6 +257,10 @@ async function escalate(d, goal, kind, reasonCode, summary) {
     });
 }
 export async function startGoal(objective, options = {}, deps = {}) {
+    if (options.executor === 'host') {
+        const { startHostGoal } = await import('./host-goal-engine.js');
+        return startHostGoal(objective, options, deps);
+    }
     const d = resolveDeps(deps);
     const trimmed = objective.trim();
     // `typeof NaN === "number"`, and NaN silently disables a budget in memory
@@ -259,11 +268,11 @@ export async function startGoal(objective, options = {}, deps = {}) {
     // budget fire immediately after the record is reloaded. Neither is a budget.
     const budgets = {
         ...defaultGoalBudgets(),
-        ...(Number.isFinite(options.budget_hours)
-            ? { max_wall_clock_ms: Math.max(1, options.budget_hours) * 60 * 60 * 1000 }
+        ...(Number.isFinite(options.budget_hours) && options.budget_hours > 0 && Number.isFinite(options.budget_hours * 3600000)
+            ? { max_wall_clock_ms: options.budget_hours * 3600000, deadline_explicit: true }
             : {}),
-        ...(Number.isFinite(options.max_ticks) ? { max_ticks: options.max_ticks } : {}),
-        ...(Number.isFinite(options.max_replans) ? { max_replans: options.max_replans } : {}),
+        ...(Number.isSafeInteger(options.max_ticks) && options.max_ticks >= 0 ? { max_ticks: options.max_ticks, tick_budget_explicit: true } : {}),
+        ...(Number.isSafeInteger(options.max_replans) && options.max_replans >= 0 ? { max_replans: options.max_replans, replan_budget_explicit: true } : {}),
     };
     const iso = new Date(d.now()).toISOString();
     let goal = {
@@ -366,6 +375,8 @@ export async function tickGoal(goalId, deps = {}) {
     const d = resolveDeps(deps);
     const goal = requireGoal(d, goalId);
     const plan = requirePlan(d, goal);
+    if (goal.executor === 'host')
+        return { goal, plan, progressed: false };
     const ready = getReadyTaskSteps(plan);
     if (ready.length === 0) {
         return { goal, plan, progressed: false };
@@ -400,8 +411,13 @@ export async function tickGoal(goalId, deps = {}) {
             reason_code: "spawn_threw",
         };
     }
-    nextPlan = applyBridgeResultToStep(nextPlan, step.step_id, result);
+    nextPlan = applyBridgeResultToStep(d.repo.getPlan(goalId) ?? nextPlan, step.step_id, result);
     const finalStep = nextPlan.steps.find((s) => s.step_id === step.step_id);
+    // Preserve the bridge's existing evidence declarations alongside tool receipts.
+    // New references distinguish progress; they do not prove changed path contents.
+    if (finalStep && result.evidence_refs?.length) {
+        finalStep.evidence_refs = [...new Set([...(finalStep.evidence_refs ?? []), ...result.evidence_refs])];
+    }
     // Re-hydrate so any field mutated *during* the spawn (e.g. an operator
     // stop_requested via stopGoal) is preserved rather than clobbered by this
     // tick's stale in-memory snapshot.
@@ -449,17 +465,21 @@ export async function checkSuccessContract(d, goal) {
         if (!d.artifactExists(ref, d.workspaceRoot))
             missingEvidence.push(ref);
     }
-    const failed = [];
-    for (const command of contract.verification_commands) {
-        const outcome = await d.runVerification(command, d.workspaceRoot);
-        if (!outcome.ok)
+    const failed = [], signatures = [];
+    for (const declaration of contract.verification_commands) {
+        const command = verificationCommandText(declaration);
+        const outcome = await d.runVerification(command, d.workspaceRoot, typeof declaration === 'string' ? undefined : declaration);
+        if (!outcome.ok) {
             failed.push(command);
+            signatures.push(`${command}:${failureProgressSignature(outcome.output)}`);
+        }
     }
     return {
         ok: missing.length === 0 && missingEvidence.length === 0 && failed.length === 0,
         missing_artifacts: missing,
         missing_evidence_refs: missingEvidence,
         failed_commands: failed,
+        failure_signatures: signatures,
         uncheckable: false,
     };
 }
@@ -487,12 +507,14 @@ function playbookRetryNote(workspaceRoot, reasonCode) {
 export async function runGoal(goalId, deps = {}) {
     const d = resolveDeps(deps);
     let goal = requireGoal(d, goalId);
+    if (goal.executor === 'host')
+        return { goal, plan: d.repo.getPlan(goalId) };
     if (goal.status !== "executing" && goal.status !== "verifying") {
         return { goal, plan: d.repo.getPlan(goalId) };
     }
     let backoff = BACKOFF_START_MS;
-    // Bounded by max_ticks; the loop can only exit through an explicit terminal
-    // transition below, never by a model asserting completion.
+    // Productive work has no implicit tick or elapsed-time ceiling. Only an
+    // operator allowance, unchanged failures, or an explicit transition stops it.
     for (;;) {
         goal = requireGoal(d, goalId);
         // 1. Operator stop.
@@ -543,8 +565,21 @@ export async function runGoal(goalId, deps = {}) {
                 d.repo.saveGoal(goal);
                 break;
             }
-            // Missing evidence → synthesize a remediation step (counts as a replan).
-            if (goal.replan_count >= goal.budgets.max_replans) {
+            // Repeated unchanged failures park the loop; different failures are progress.
+            const repeated = observeFailure(goal, JSON.stringify({
+                artifacts: [...check.missing_artifacts].sort(), evidence: [...check.missing_evidence_refs].sort(),
+                commands: [...(check.failure_signatures ?? check.failed_commands)].sort(),
+            }));
+            if (repeated && !(goal.budgets.replan_budget_explicit && goal.replan_count >= goal.budgets.max_replans)) {
+                goal.status = 'blocked';
+                goal.reason_code = 'repeated_failure';
+                goal = d.repo.saveGoal(goal);
+                await escalate(d, goal, 'blocker', 'repeated_failure', 'The same success-contract failure repeated three times without progress; operator review is required.');
+                d.repo.saveGoal(goal);
+                break;
+            }
+            // An explicit operator cap is still honored; defaults never limit corrections.
+            if (goal.budgets.replan_budget_explicit && goal.replan_count >= goal.budgets.max_replans) {
                 const replanCode = "goal_budget_exhausted:max_replans";
                 goal.status = "blocked";
                 goal.reason_code = replanCode;
@@ -584,14 +619,24 @@ export async function runGoal(goalId, deps = {}) {
             goal = d.repo.saveGoal(goal);
             await d.appendProcessPost({
                 kind: "progress",
-                summary: `Goal ${goalId}: success contract unmet, synthesized remediation step (replan ${goal.replan_count}/${goal.budgets.max_replans}).`,
+                summary: `Goal ${goalId}: success contract unmet, synthesized remediation step (replan ${goal.replan_count}${goal.budgets.replan_budget_explicit ? `/${goal.budgets.max_replans}` : ''}).`,
             });
             backoff = BACKOFF_START_MS;
             continue;
         }
         // 4. Plan blocked/failed → classify and either replan or park.
         if (status === "blocked" || status === "failed") {
-            if (goal.replan_count >= goal.budgets.max_replans) {
+            const failures = plan.steps.filter(s => s.status === 'blocked' || s.status === 'failed')
+                .map(s => JSON.stringify({ task: s.task, failure: failureProgressSignature(s.blocked_reason ?? s.result_summary ?? s.status), evidence: [...(s.evidence_refs ?? [])].sort() })).sort();
+            if (observeFailure(goal, JSON.stringify(failures)) && !(goal.budgets.replan_budget_explicit && goal.replan_count >= goal.budgets.max_replans)) {
+                goal.status = 'blocked';
+                goal.reason_code = 'repeated_failure';
+                goal = d.repo.saveGoal(goal);
+                await escalate(d, goal, 'blocker', 'repeated_failure', `The same step failure repeated three times without progress (${blockedReasons(plan)}).`);
+                d.repo.saveGoal(goal);
+                break;
+            }
+            if (goal.budgets.replan_budget_explicit && goal.replan_count >= goal.budgets.max_replans) {
                 goal.status = "blocked";
                 goal.reason_code = "plan_blocked";
                 goal = d.repo.saveGoal(goal);
@@ -637,7 +682,7 @@ export async function runGoal(goalId, deps = {}) {
             d.repo.savePlan(goalId, retried);
             await d.appendProcessPost({
                 kind: "progress",
-                summary: `Goal ${goalId}: plan ${status}, retrying blocked steps (replan ${goal.replan_count}/${goal.budgets.max_replans}).`,
+                summary: `Goal ${goalId}: plan ${status}, retrying blocked steps (replan ${goal.replan_count}${goal.budgets.replan_budget_explicit ? `/${goal.budgets.max_replans}` : ''}).`,
             });
             backoff = BACKOFF_START_MS;
             continue;
@@ -661,8 +706,8 @@ export async function runGoal(goalId, deps = {}) {
             d.repo.saveGoal(goal);
             break;
         }
-        // A step is still running (an engine restarted mid-step). Back off, but charge
-        // the wait against max_ticks so an in-flight step cannot stall the goal forever.
+        // A step is still running (an engine restarted mid-step). Wait cooperatively;
+        // operator allowances apply only when explicitly supplied.
         goal.tick_count += 1;
         goal = d.repo.saveGoal(goal);
         await d.sleep(backoff);
@@ -671,10 +716,24 @@ export async function runGoal(goalId, deps = {}) {
     return { goal, plan: d.repo.getPlan(goalId) };
 }
 // ── resumeGoal / stopGoal / status ───────────────────────────────────────────
-export async function resumeGoal(goalId, deps = {}) {
+export async function resumeGoal(goalId, deps = {}, options = {}) {
     const d = resolveDeps(deps);
-    const goal = requireGoal(d, goalId);
+    let goal = requireGoal(d, goalId);
     const plan = d.repo.getPlan(goalId);
+    if (goal.executor === 'host') {
+        const resumed = await withHostResume(d, goalId, options);
+        if (resumed.plan?.steps.some(step => step.observation_check && step.observation_check.attempt === step.attempt && ['pending', 'unmet', 'unsupported'].includes(step.observation_check.status)) && !resumed.goal.reason_code?.startsWith('follow-up budget reached') && resumed.goal.reason_code !== 'host_budget_exhausted') {
+            const { retryHostVerification } = await import('./host-goal-engine.js');
+            return retryHostVerification(goalId, deps);
+        }
+        if (resumed.goal.status !== 'done' && !resumed.goal.reason_code?.startsWith('follow-up budget reached') && resumed.goal.reason_code !== 'host_budget_exhausted' && !resumed.goal.pending_follow_ups?.length && resumed.plan?.steps.every(s => ['done', 'skipped'].includes(s.status))) {
+            const { retryHostVerification } = await import('./host-goal-engine.js');
+            return retryHostVerification(goalId, deps);
+        }
+        return resumed;
+    }
+    if (options.budget_hours !== undefined || options.max_replans !== undefined)
+        goal = await recoverEngineGoalBudgets(goalId, options, deps);
     if (plan) {
         // A step left `running` means the engine died mid-step — reset it to planned
         // (the supervisor's own revisit pattern) so it re-executes on resume.
@@ -705,6 +764,7 @@ export async function resumeGoal(goalId, deps = {}) {
         goal.status = "executing";
         goal.stop_requested = false;
         goal.reason_code = undefined;
+        goal.failure_repetition = undefined;
         d.repo.saveGoal(goal);
     }
     // `--plan-only` parks at `planning` with a compiled plan. Resuming is the
@@ -721,9 +781,94 @@ export async function resumeGoal(goalId, deps = {}) {
     }
     return runGoal(goalId, deps);
 }
-export function stopGoal(goalId, deps = {}) {
+/** Operator-approved increases retain the original clock and all accepted work. */
+export async function recoverEngineGoalBudgets(goalId, options, deps = {}) {
+    const d = resolveDeps(deps);
+    const { withStoreWriteCoordinator } = await import('./store/write-coordinator.js');
+    return withStoreWriteCoordinator(d.repo.planPath(goalId), async () => {
+        const goal = requireGoal(d, goalId);
+        if (goal.executor === 'host')
+            throw new Error('Use host budget recovery for a host goal.');
+        const hours = options.budget_hours, replans = options.max_replans;
+        if (hours !== undefined) {
+            if (!Number.isFinite(hours) || hours <= 0 || !Number.isSafeInteger(hours * 3600000))
+                throw new Error('budget_hours must yield a finite positive millisecond allowance.');
+            if (!goal.budgets.deadline_explicit)
+                throw new Error('Cannot impose a finite deadline on an unlimited goal through resume; no explicit deadline exists.');
+            if (hours * 3600000 < goal.budgets.max_wall_clock_ms)
+                throw new Error('Cannot lower budget_hours; resume only increases the total allowance.');
+        }
+        if (replans !== undefined) {
+            if (!Number.isSafeInteger(replans) || replans < 0)
+                throw new Error('max_replans must be a nonnegative safe integer.');
+            if (!goal.budgets.replan_budget_explicit)
+                throw new Error('Cannot replace an unlimited replan allowance with a finite allowance through resume.');
+            if (replans < goal.budgets.max_replans)
+                throw new Error('Cannot lower max_replans; resume only increases the total allowance.');
+        }
+        if (hours !== undefined)
+            goal.budgets.max_wall_clock_ms = hours * 3600000;
+        if (replans !== undefined)
+            goal.budgets.max_replans = replans;
+        return d.repo.saveGoal(goal);
+    }, { operation_label: 'engine_budget_recovery' });
+}
+async function withHostResume(d, goalId, options) {
+    const { withStoreWriteCoordinator } = await import('./store/write-coordinator.js');
+    return withStoreWriteCoordinator(d.repo.planPath(goalId), async () => {
+        const goal = requireGoal(d, goalId);
+        let plan = requirePlan(d, goal);
+        const { recoverHostBudgetsLocked } = await import('./host-goal-engine.js');
+        plan = recoverHostBudgetsLocked(goal, plan, options, d.now());
+        if (goal.status === 'done' || goal.reason_code?.startsWith('follow-up budget reached') || goal.reason_code === 'host_budget_exhausted') {
+            d.repo.savePlan(goalId, plan);
+            d.repo.saveGoal(goal);
+            return { goal, plan };
+        }
+        if (plan.steps.some(step => step.observation_check && step.observation_check.attempt === step.attempt && ['pending', 'unmet', 'unsupported'].includes(step.observation_check.status))) {
+            d.repo.savePlan(goalId, plan);
+            d.repo.saveGoal(goal);
+            return { goal, plan };
+        }
+        // retryHostVerification clears a stop and advances check identity together.
+        goal.failure_repetition = undefined;
+        if (goal.reason_code === 'repeated_failure')
+            goal.reason_code = undefined;
+        if (plan.steps.every(s => ['done', 'skipped'].includes(s.status))) {
+            d.repo.savePlan(goalId, plan);
+            d.repo.saveGoal(goal);
+            return { goal, plan };
+        }
+        // Explicit recovery permits a new attempt on blocked work; in-flight host work is never reset.
+        for (const step of plan.steps)
+            if (['blocked', 'failed'].includes(step.status) && !step.waiting_on?.startsWith('handoff:')) {
+                step.status = 'planned';
+                step.blocked_reason = undefined;
+            }
+        plan.status = deriveTaskPlanStatus(plan);
+        goal.status = 'executing';
+        goal.stop_requested = false;
+        goal.reason_code = undefined;
+        d.repo.savePlan(goalId, plan);
+        d.repo.saveGoal(goal);
+        return { goal, plan };
+    }, { operation_label: 'host_resume_goal' });
+}
+export { beginStep, completeStep, applyHostResultToStep } from './host-goal-engine.js';
+export async function stopGoal(goalId, deps = {}) {
     const d = resolveDeps(deps);
     const goal = requireGoal(d, goalId);
+    if (goal.executor === 'host') {
+        const { withStoreWriteCoordinator } = await import('./store/write-coordinator.js');
+        return withStoreWriteCoordinator(d.repo.planPath(goalId), async () => {
+            const fresh = requireGoal(d, goalId);
+            if (fresh.status !== 'done') {
+                fresh.stop_requested = true;
+                fresh.status = 'stopped';
+            }
+            return d.repo.saveGoal(fresh);
+        }, { operation_label: 'host_stop_goal' });
+    }
     goal.stop_requested = true;
     return d.repo.saveGoal(goal);
 }
@@ -777,15 +922,26 @@ function requirePlan(d, goal) {
     return plan;
 }
 function budgetExhausted(d, goal) {
-    if (goal.tick_count >= goal.budgets.max_ticks)
+    if (goal.budgets.tick_budget_explicit && goal.tick_count >= goal.budgets.max_ticks)
         return "max_ticks";
-    if (goal.started_at) {
+    if (goal.budgets.deadline_explicit && goal.started_at) {
         const elapsed = d.now() - Date.parse(goal.started_at);
         if (elapsed >= goal.budgets.max_wall_clock_ms)
             return "max_wall_clock";
     }
     return undefined;
 }
+function observeFailure(goal, signature) {
+    const previous = goal.failure_repetition;
+    goal.failure_repetition = { signature, count: previous?.signature === signature ? previous.count + 1 : 1 };
+    return goal.failure_repetition.count >= 3;
+}
+/** Learning groups related failures; loop detection must also retain exact test identities. */
+export function failureProgressSignature(text) {
+    const normalized = stripVTControlCharacters(text).replace(/\r\n/g, '\n')
+        .replace(/\b\d{4}-\d\d-\d\d[T ][\d:.]+Z?\b/g, '<time>').trim();
+    return `${failureSignature(normalized) ?? 'failure'}:${createHash('sha256').update(normalized).digest('hex')}`;
+}
 function blockedReasons(plan) {
     return plan.steps
         .filter((s) => s.status === "blocked" || s.status === "failed")

package/dist/handoff-registry.d.ts

@@ -6,6 +6,10 @@ export interface HandoffLifecycleEvent {
     note?: string;
 }
 export interface HandoffRecord {
+    step_ref?: {
+        goal_id: string;
+        step_id: string;
+    };
     handoff_id: string;
     created_at: string;
     updated_at: string;
@@ -24,6 +28,10 @@ export interface HandoffRegistryFile {
     handoffs: Record<string, HandoffRecord>;
 }
 export interface RegisterHandoffInput {
+    step_ref?: {
+        goal_id: string;
+        step_id: string;
+    };
     handoff_id: string;
     from: string;
     to: string;
@@ -68,4 +76,6 @@ export declare function registerHandoffSafe(input: RegisterHandoffInput): Promis
  * Concurrency-safe variant of acknowledgeHandoff.
  */
 export declare function acknowledgeHandoffSafe(input: AcknowledgeHandoffInput): Promise<HandoffAckResult>;
+/** Called after the goal plan is saved; this packed record is a repairable view. */
+export declare function syncLinkedHandoffStepSafe(id: string, summary: string): Promise<void>;
 //# sourceMappingURL=handoff-registry.d.ts.map

package/dist/handoff-registry.js

@@ -68,6 +68,7 @@ function parseRegistry(raw) {
                 task_type: typeof row.task_type === "string" ? row.task_type : undefined,
                 priority: typeof row.priority === "string" ? row.priority : undefined,
                 source_file: typeof row.source_file === "string" ? row.source_file : undefined,
+                step_ref: row.step_ref,
                 status: row.status === "open" ||
                     row.status === "accepted" ||
                     row.status === "blocked" ||
@@ -168,6 +169,7 @@ function toLegacyHandoffRecord(record) {
         task_type: typeof metadata.task_type === "string" ? metadata.task_type : record.task,
         priority: typeof metadata.priority === "string" ? metadata.priority : undefined,
         source_file: typeof metadata.source_file === "string" ? metadata.source_file : undefined,
+        step_ref: metadata.step_ref,
         status,
         history: normalizeHistory(metadata.history, status, updatedAt),
     };
@@ -229,6 +231,7 @@ export function registerHandoff(input) {
         task_type: input.task_type,
         priority: input.priority,
         source_file: input.source_file,
+        step_ref: input.step_ref,
         status: "open",
         history: [
             {
@@ -291,6 +294,13 @@ export function getHandoffRegistryPath() {
  * Concurrency-safe variant of registerHandoff.
  */
 export async function registerHandoffSafe(input) {
+    if (input.step_ref) {
+        const { withLinkedHandoff } = await import('./host-goal-engine.js');
+        return withLinkedHandoff(input.step_ref, { id: input.handoff_id, status: 'open', actor: input.actor ?? input.from, to: input.to }, () => registerHandoffStoreSafe(input));
+    }
+    return registerHandoffStoreSafe(input);
+}
+async function registerHandoffStoreSafe(input) {
     const root = workspaceRoot();
     const storePath = getWorkspaceStorePath(root);
     await waitForTodoStoreMirror();
@@ -325,6 +335,7 @@ export async function registerHandoffSafe(input) {
                         task_type: input.task_type,
                         priority: input.priority,
                         source_file: input.source_file,
+                        step_ref: input.step_ref,
                         history: [
                             {
                                 timestamp_utc: now,
@@ -353,6 +364,34 @@ export async function registerHandoffSafe(input) {
  * Concurrency-safe variant of acknowledgeHandoff.
  */
 export async function acknowledgeHandoffSafe(input) {
+    const record = readHandoffRegistry().handoffs[input.handoff_id];
+    if (record?.step_ref) {
+        const { withLinkedHandoff, completeStep } = await import('./host-goal-engine.js');
+        const actor = input.actor;
+        if (!actor || actor !== record.to)
+            return { ok: false, path: getHandoffRegistryPath(), error: `Linked handoff belongs to ${record.to}; supply that agent label.` };
+        if (input.status === 'completed') {
+            if (record.status === 'completed')
+                return acknowledgeHandoffStoreSafe(input);
+            const { GoalRepository } = await import('./store/repositories/goal-repository.js');
+            const step = new GoalRepository(workspaceRoot()).getPlan(record.step_ref.goal_id)?.steps.find(s => s.step_id === record.step_ref.step_id);
+            if (!step)
+                return { ok: false, path: getHandoffRegistryPath(), error: 'Linked step missing' };
+            const result = await completeStep(record.step_ref.goal_id, record.step_ref.step_id, { status: 'done', summary: input.note || record.title, evidence: [{ ref: `handoff:${record.handoff_id}`, kind: 'note', detail: input.note }] }, { agent: actor, attempt: step.attempt ?? 0 });
+            if (!result.ok || result.status !== 'done')
+                return { ok: false, path: getHandoffRegistryPath(), error: result.message ?? `Step retained as ${result.status}: ${result.summary}` };
+            return acknowledgeHandoffStoreSafe(input);
+        }
+        try {
+            return await withLinkedHandoff(record.step_ref, { id: record.handoff_id, status: input.status, actor, to: record.to }, () => acknowledgeHandoffStoreSafe(input));
+        }
+        catch (error) {
+            return { ok: false, path: getHandoffRegistryPath(), error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    return acknowledgeHandoffStoreSafe(input);
+}
+async function acknowledgeHandoffStoreSafe(input) {
     const root = workspaceRoot();
     const storePath = getWorkspaceStorePath(root);
     await waitForTodoStoreMirror();
@@ -423,4 +462,24 @@ export async function acknowledgeHandoffSafe(input) {
         }, { operation_label: "acknowledgeHandoffSafe" });
     });
 }
+/** Called after the goal plan is saved; this packed record is a repairable view. */
+export async function syncLinkedHandoffStepSafe(id, summary) {
+    const root = workspaceRoot(), path = getWorkspaceStorePath(root);
+    await withStoreWriteCoordinator(path, async () => {
+        const store = await openStore(path);
+        try {
+            const repo = new HandoffRepository(store), record = await repo.get(id);
+            if (!record)
+                throw new Error(`Linked handoff missing: ${id}`);
+            if (record.status !== 'closed') {
+                await repo.update(id, { status: 'closed', metadata: { ...record.metadata, legacy_status: 'completed', history: [...(record.metadata?.history ?? []), { timestamp_utc: new Date().toISOString(), status: 'completed', actor: 'goal-step', note: summary }] } });
+                await store.commit();
+                await new ProjectionManager(store, root).projectAfterCommit(['handoffs']);
+            }
+        }
+        finally {
+            await store.close({ commit: false });
+        }
+    }, { operation_label: 'linked_handoff_view' });
+}
 //# sourceMappingURL=handoff-registry.js.map

package/dist/helpers/artifacts.d.ts

@@ -6,7 +6,9 @@ export interface SkillReference {
 }
 export declare function getAgentInstructionPath(role: AgentRole): string | undefined;
 export declare function getAgentManifestPath(role: AgentRole): string | undefined;
-export declare function readAgentInstructions(role: AgentRole): string;
+export declare function readAgentInstructions(role: AgentRole, options?: {
+    includeLearned?: boolean;
+}): string;
 export declare function readAgentManifest(role: AgentRole): string;
 export declare function getTaskArtifactPath(key: TaskKey): string | undefined;
 export declare function readTaskArtifact(key: TaskKey): string;
@@ -15,5 +17,7 @@ export declare function readKernelArtifact(key: KernelKey): string;
 export declare function resolveWritableTaskPath(key: TaskKey): string;
 export declare function listAvailableSkills(): SkillReference[];
 export declare function getSkillPath(name: string): string | undefined;
-export declare function readSkillInstructions(name: string): string;
+export declare function readSkillInstructions(name: string, options?: {
+    includeLearned?: boolean;
+}): string;
 //# sourceMappingURL=artifacts.d.ts.map

package/dist/helpers/artifacts.js

@@ -1,3 +1,4 @@
+import { approvedInstructionText, approvedDistillerText } from '../learning-overlays.js';
 import { existsSync, readdirSync } from "node:fs";
 import { resolve } from "node:path";
 import { AGENT_FILES, AGENT_MANIFEST_FILES, DEFAULT_AGENT_INSTRUCTION_FILES, DEFAULT_AGENT_MANIFEST_FILES, DEFAULT_KERNEL_FILES, DEFAULTS_SKILLS_ROOT, DEFAULT_TASK_FILES, KERNEL_FILES, STORE_AGENT_FILES, STORE_KERNEL_FILES, STORE_TASK_FILES, TASK_FILES, } from "./constants.js";
@@ -30,12 +31,13 @@ export function getAgentManifestPath(role) {
     const workspaceCandidates = toAbsoluteWorkspaceCandidates(AGENT_MANIFEST_FILES[role]);
     return firstExistingPath([...workspaceCandidates, DEFAULT_AGENT_MANIFEST_FILES[role]]);
 }
-export function readAgentInstructions(role) {
+export function readAgentInstructions(role, options = {}) {
     const store = readStoreText(STORE_AGENT_FILES[role].instructions.map((file) => `knowledge/agents/${STORE_AGENT_FILES[role].agent}/${file}`));
+    const overlay = options.includeLearned ? approvedInstructionText(currentWorkspaceRoot(), role) : "";
     if (store)
-        return store.text;
+        return store.text + overlay;
     const workspaceCandidates = toAbsoluteWorkspaceCandidates(AGENT_FILES[role]);
-    return readFirstAvailable([...workspaceCandidates, DEFAULT_AGENT_INSTRUCTION_FILES[role]]).text;
+    return readFirstAvailable([...workspaceCandidates, DEFAULT_AGENT_INSTRUCTION_FILES[role]]).text + overlay;
 }
 export function readAgentManifest(role) {
     const store = readStoreText(STORE_AGENT_FILES[role].manifests.map((file) => `knowledge/agents/${STORE_AGENT_FILES[role].agent}/${file}`));
@@ -136,7 +138,7 @@ export function getSkillPath(name) {
     const exact = skills.find((skill) => skill.name.toLowerCase() === target);
     return exact?.path;
 }
-export function readSkillInstructions(name) {
+export function readSkillInstructions(name, options = {}) {
     const target = name.trim().toLowerCase();
     const match = listAvailableSkills().find((skill) => skill.name.toLowerCase() === target);
     if (!match) {
@@ -145,8 +147,8 @@ export function readSkillInstructions(name) {
             .join(", ")}`;
     }
     if (match.source === "store") {
-        return readStoreText([`knowledge/skills/${match.name}/SKILL.md`])?.text ?? "";
+        return (readStoreText([`knowledge/skills/${match.name}/SKILL.md`])?.text ?? "") + (options.includeLearned && target === 'learn-from-work' ? approvedDistillerText(currentWorkspaceRoot()) : '');
     }
-    return readText(match.path);
+    return readText(match.path) + (options.includeLearned && target === 'learn-from-work' ? approvedDistillerText(currentWorkspaceRoot()) : '');
 }
 //# sourceMappingURL=artifacts.js.map