@voybio/ace-swarm 2.4.8 → 2.4.10

package/dist/ace-server-instructions.js

@@ -1,27 +1,17 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { readAceLogicalFile, resolveAceLogicalPath, resolveAceStateLayout, } from "./ace-state-resolver.js";
+import { formatCurrentWork, resolveCurrentWork } from "./ace-autonomy.js";
+import { withWorkspaceRoot } from "./helpers/workspace-root.js";
+import { readAceLogicalFile, } from "./ace-state-resolver.js";
+import { getHostBinding } from './host-work-context.js';
 const ACE_ROOT_REL = ".agents/ACE";
-const CORE_FILES = [
-    "agent-state/TASK.md",
-    "agent-state/STATUS.md",
-    "agent-state/SCOPE.md",
-    "agent-state/EVIDENCE_LOG.md",
-];
-const STATE_DIRS = [
-    "agent-state",
-    "global-state",
-    "venture-state",
-    "brand-state",
-    "engineering-state",
-];
 const BOOTSTRAP_TOOLS = new Set([
     "bootstrap_state",
     "recall_context",
     "build_continuity_packet",
 ]);
 // Named set — new refresh_* tools must be added here explicitly.
-// These tools rewrite snapshot files but don't need EVIDENCE_LOG reconciliation guidance.
+// Refreshes invalidate the current-work digest too.
 const REFRESH_TOOLS = new Set([
     "refresh_astgrep_index",
     "refresh_tracker_snapshot",
@@ -30,6 +20,7 @@ const REFRESH_TOOLS = new Set([
 // Named set — tools that mutate state but do not match any MUTATION_PREFIXES entry.
 // New mutation tools with non-standard prefixes must be added here explicitly.
 const NAMED_MUTATION_TOOLS = new Set([
+    'next_step',
     "rewrite_targets",
     "apply_patch",
     "astgrep_rewrite",
@@ -64,18 +55,8 @@ const MUTATION_PREFIXES = [
     "update_",
     "write_",
 ];
-const DIGEST_CACHE_TTL_MS = 60_000;
+const DIGEST_CACHE_TTL_MS = 2_000;
 const digestCache = new Map();
-function readIfPresent(filePath) {
-    if (!existsSync(filePath))
-        return undefined;
-    try {
-        return readFileSync(filePath, "utf-8");
-    }
-    catch {
-        return undefined;
-    }
-}
 function nonEmptyLines(input) {
     return input
         .split(/\r?\n/)
@@ -90,34 +71,6 @@ function truncate(input, max = 140) {
         return input;
     return `${input.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
 }
-function resolveWorkspacePath(workspaceRoot, relativePath) {
-    if (relativePath === "agent-state") {
-        const layout = resolveAceStateLayout(workspaceRoot);
-        if (layout.physicalMode === "top_level") {
-            return resolve(workspaceRoot, "agent-state");
-        }
-        return resolve(workspaceRoot, ACE_ROOT_REL, "agent-state");
-    }
-    if (relativePath.startsWith("agent-state/")) {
-        return (resolveAceLogicalPath(workspaceRoot, relativePath) ??
-            resolve(workspaceRoot, ACE_ROOT_REL, relativePath));
-    }
-    const canonicalRel = relativePath.startsWith(`${ACE_ROOT_REL}/`)
-        ? relativePath
-        : `agent-state|global-state|venture-state|brand-state|engineering-state`
-            .split("|")
-            .some((prefix) => relativePath === prefix || relativePath.startsWith(`${prefix}/`))
-            ? `${ACE_ROOT_REL}/${relativePath}`
-            : relativePath;
-    const canonicalPath = resolve(workspaceRoot, canonicalRel);
-    if (canonicalRel !== relativePath) {
-        const legacyPath = resolve(workspaceRoot, relativePath);
-        if (!existsSync(canonicalPath) && existsSync(legacyPath)) {
-            return legacyPath;
-        }
-    }
-    return canonicalPath;
-}
 function displayWorkspacePath(workspaceRoot, relativePath) {
     if (relativePath === "agent-state" || relativePath.startsWith("agent-state/")) {
         return relativePath;
@@ -138,64 +91,8 @@ function displayWorkspacePath(workspaceRoot, relativePath) {
     }
     return canonicalRel;
 }
-function listExistingCoreFiles(workspaceRoot) {
-    return CORE_FILES.filter((relativePath) => Boolean(resolveAceLogicalPath(workspaceRoot, relativePath)))
-        .map((relativePath) => displayWorkspacePath(workspaceRoot, relativePath));
-}
-function listExistingStateDirs(workspaceRoot) {
-    return STATE_DIRS.filter((relativePath) => existsSync(resolveWorkspacePath(workspaceRoot, relativePath)))
-        .map((relativePath) => displayWorkspacePath(workspaceRoot, relativePath));
-}
-function extractObjective(taskRaw) {
-    if (!taskRaw)
-        return undefined;
-    const match = taskRaw.match(/## Objective\s+([\s\S]*?)(?:\n## |\n# |$)/);
-    if (match?.[1]) {
-        return truncate(oneLine(match[1]));
-    }
-    const bodyLine = nonEmptyLines(taskRaw).find((line) => !line.startsWith("#"));
-    if (bodyLine) {
-        return truncate(oneLine(bodyLine));
-    }
-    const heading = taskRaw.match(/^#\s+(.+)$/m)?.[1];
-    return heading ? truncate(oneLine(heading)) : undefined;
-}
-function extractStatusValue(statusRaw, label) {
-    if (!statusRaw)
-        return undefined;
-    const pattern = new RegExp(`^- ${label}:\\s*(.+)$`, "m");
-    const match = statusRaw.match(pattern);
-    return match?.[1] ? truncate(oneLine(match[1])) : undefined;
-}
-function extractAutonomyHint(workspaceRoot) {
-    const workflowRaw = readAceLogicalFile(workspaceRoot, "agent-state/ACE_WORKFLOW.md");
-    if (!workflowRaw)
-        return undefined;
-    const hints = [];
-    if (/^\s*orchestrator_preflight:\s*true\s*$/m.test(workflowRaw)) {
-        hints.push("orchestrator preflight");
-    }
-    if (/^\s*recall_context:\s*true\s*$/m.test(workflowRaw)) {
-        hints.push("context recall");
-    }
-    const reviewMode = workflowRaw.match(/^\s*review_mode:\s*["']?([A-Za-z0-9_-]+)["']?\s*$/m)?.[1];
-    if (reviewMode) {
-        hints.push(`review mode ${reviewMode}`);
-    }
-    return hints.length > 0 ? hints.join(", ") : undefined;
-}
 export function buildAceDigest(workspaceRoot) {
-    const taskRaw = readAceLogicalFile(workspaceRoot, "agent-state/TASK.md");
-    const statusRaw = readAceLogicalFile(workspaceRoot, "agent-state/STATUS.md");
-    const objective = extractObjective(taskRaw);
-    const phase = extractStatusValue(statusRaw, "Current phase");
-    const blockers = extractStatusValue(statusRaw, "Blockers");
-    const parts = [
-        objective ? `task=${objective}` : undefined,
-        phase ? `phase=${phase}` : undefined,
-        blockers ? `blockers=${blockers}` : undefined,
-    ].filter((value) => Boolean(value));
-    return parts.length > 0 ? parts.join(" | ") : "ACE state detected; load recall_context for task and status.";
+    return formatCurrentWork(resolveCurrentWork({ workspaceRoot }), "line");
 }
 function buildAceDigestCached(workspaceRoot) {
     const now = Date.now();
@@ -207,87 +104,34 @@ function buildAceDigestCached(workspaceRoot) {
     return value;
 }
 export function buildServerInstructions(workspaceRoot) {
-    const coreFiles = listExistingCoreFiles(workspaceRoot);
-    const stateDirs = listExistingStateDirs(workspaceRoot);
-    const digest = buildAceDigest(workspaceRoot);
-    const autonomyHint = extractAutonomyHint(workspaceRoot);
-    const lines = [
-        "You are operating in an ACE-governed workspace.",
-        coreFiles.length > 0
-            ? `Ground truth for task/status/scope/evidence is store-backed under ${coreFiles.join(", ")} (canonical store: ${ACE_ROOT_REL}/agent-state/ace-state.ace).`
-            : `Ground truth is store-backed under ${ACE_ROOT_REL}/agent-state/* artifacts (canonical store: ${ACE_ROOT_REL}/agent-state/ace-state.ace), not chat history.`,
-        "`ace compact` and the automatic lifecycle sweep intentionally remove loose agent-state/* files from disk after folding them into the store — this is expected, not data loss, and applies to every swept artifact (kanban, run-ledger, handoffs, playbook, tracker snapshots, etc.), not only TASK/STATUS/SCOPE/EVIDENCE_LOG. If a path is not on disk, call list_workspace on its directory to see the full store-backed listing (or `ace ls` from the CLI), then read it back with read_workspace_file (or `ace read <path>`); never recreate swept files.",
-        stateDirs.length > 0
-            ? `Durable artifacts belong under ${stateDirs.map((entry) => `${entry}/`).join(", ")} and are persisted into the store; the loose copies are sweep inputs, not the source of truth.`
-            : undefined,
-        "Before significant work, call recall_context to load current task, scope, and status.",
-        "Use route_task and get_agent_instructions for role guidance; do not self-assign by guesswork.",
-        "After meaningful edits or state changes, call execute_gates and persist evidence/handoffs in ACE artifacts.",
-        "For delegated or long-running work, use create_handoff / ack_handoff and append_vericify_process_post instead of ad-hoc status notes.",
-        "For self-paced, evidence-gated multi-step objectives beyond this session, use start_goal / get_goal_status / resume_goal / stop_goal (or `ace goal` from the CLI).",
-        "Prefer the matching MCP tool over ad-hoc shell/chat tracking: git_status / git_diff / git_log / git_commit for git; enqueue_job / dispatch_jobs / heartbeat_job / get_lock_table for background jobs; snapshot_state / semantic_diff / drift_report / rewrite_targets for change intelligence.",
-        "skill_catalog_summary / skill_audit / problem_triage surface packaged skills; get_todo / update_todo / get_run_ledger is the human-facing todo surface; scan_workspace_delta / web_research_packet / codemunch_snapshot / codemunch_index cover workspace-wide search and indexing.",
-        `Current ACE digest: ${digest}.`,
-        autonomyHint ? `Runtime autonomy signals: ${autonomyHint}.` : undefined,
-    ];
-    return lines.filter((line) => Boolean(line)).join("\n");
-}
-export function buildHostInstructionText(host, workspaceRoot) {
-    const hostLabel = {
-        claude: "Claude Code",
-        copilot: "GitHub Copilot",
-        cursor: "Cursor",
-        codex: "Codex",
-    }[host];
     return [
-        `# ACE Bootstrap For ${hostLabel}`,
-        "",
-        "This is a thin ACE bootstrap stub.",
-        "Full instructions, skills, task packs, and runtime state live in ACE artifacts and should be accessed through the ACE MCP server.",
-        "",
-        "Session start protocol:",
-        "1. Call `recall_context` to load task, scope, and status through the ACE MCP server.",
-        "2. Call `route_task` and `get_agent_instructions` before choosing a role.",
-        "3. Prefer ACE prompts/resources (`ace-orchestrator`, `get_task_pack`, `get_skill_instructions`) over relying on this file.",
-        "4. Read/write task state through MCP tools (`recall_context`, `read_workspace_file`, `write_workspace_file`, lifecycle append tools); do not create files under `agent-state/` directly.",
-        "5. For self-paced, evidence-gated multi-step objectives beyond this session, use `start_goal` / `get_goal_status` / `resume_goal` / `stop_goal` (or `ace goal` from the CLI).",
-        "6. Also prefer the matching MCP domain over ad-hoc equivalents for git, background jobs/scheduler, change intelligence, discovery/indexing, skills, and todo — see docs/mcp-tool-reference.md for the full per-domain tool catalog.",
+        "You are working in an ACE workspace. ACE keeps the durable state of the work so you can spend your turns doing it.",
         "",
-        "Ground truth:",
-        "- ACE MCP tools are the authoritative interface for task state and lifecycle updates.",
-        "- `agent-state/ace-state.ace` is the canonical store path; visible `agent-state/*` files are compatibility projections or sweep inputs.",
-        "- `ace compact` and the automatic lifecycle sweep intentionally remove loose `agent-state/*` files from disk after folding them into the store — this is expected, not data loss, for any swept artifact. Do NOT recreate them; if a path isn't on disk, call `list_workspace` on its directory (or `ace ls`) to see the full store-backed listing, then retrieve it via `ace read <path>` or the `read_workspace_file` / `recall_context` MCP tools.",
-        "- `.agents/ACE/tasks/todo.md` is the human-facing todo surface.",
-        "- Hook context is store-backed in `agent-state/ace-state.ace` and consumed without extra workspace projections.",
+        formatCurrentWork(resolveCurrentWork({ workspaceRoot }), "block"),
         "",
-        `Workspace digest hint: ${buildAceDigest(workspaceRoot)}.`,
+        "Goal work: next_step → do the work with your own tools → complete_step (updates linked work and returns the next step). Create a host-authored plan with start_goal executor:host.",
+        "Verification runs in the background. A pending receipt is not goal completion: use get_goal_status view:compact; retain live work. Goals have no default time or step ceiling. Budget increases require operator approval; operator_proposal is not authorization. Never approve your own increase. stop_goal pauses work; resume_goal preserves accepted attempts.",
+        "Standalone tasks: update_todo to start or finish; create_handoff to delegate to another agent.",
+        "After a restart or compaction: recall_context returns the current work.",
+        "State lives in agent-state/ace-state.ace. For a missing file, inspect list_workspace/read_workspace_file; report failed readback as missing history. Claim preservation only with verified readback.",
+        "Other ACE tools are optional; see docs/mcp-tool-reference.md.",
     ].join("\n");
 }
+export function buildHostInstructionText(host, workspaceRoot) {
+    const hostLabel = { claude: "Claude Code", copilot: "GitHub Copilot", cursor: "Cursor", codex: "Codex" }[host];
+    return `# ACE Bootstrap For ${hostLabel}\n\n${buildServerInstructions(workspaceRoot)}\n`;
+}
 export function buildBootstrapNudge(workspaceRoot) {
-    const coreFiles = listExistingCoreFiles(workspaceRoot);
-    return [
-        "ACE bootstrap hint: call `recall_context` before significant work so task and scope come from file-backed state.",
-        `ACE digest: ${buildAceDigestCached(workspaceRoot)}.`,
-        coreFiles.length > 0 ? `Current core files: ${coreFiles.join(", ")}.` : undefined,
-    ]
-        .filter((value) => Boolean(value))
-        .join(" ");
+    return buildAceDigestCached(workspaceRoot);
 }
-export function buildBootstrapGuidance(workspaceRoot, toolName) {
-    return `ACE context loaded via \`${toolName}\`. Current digest: ${buildAceDigestCached(workspaceRoot)}.`;
+export function buildBootstrapGuidance(workspaceRoot, _toolName) {
+    return buildAceDigest(workspaceRoot);
 }
-export function buildMutationGuidance(workspaceRoot, toolName) {
-    const evidencePath = displayWorkspacePath(workspaceRoot, "agent-state/EVIDENCE_LOG.md");
-    return [
-        `ACE digest after \`${toolName}\`: ${buildAceDigestCached(workspaceRoot)}.`,
-        `If this changed code or state, reconcile \`${evidencePath}\`, run \`execute_gates\` when appropriate, and use structured handoffs/process posts for delegated follow-up.`,
-    ].join(" ");
+export function buildMutationGuidance(workspaceRoot, _toolName) {
+    return buildAceDigest(workspaceRoot);
 }
-export function buildRefreshGuidance(workspaceRoot, toolName) {
-    return [
-        `ACE snapshot refresh completed via \`${toolName}\`.`,
-        `Current digest: ${buildAceDigestCached(workspaceRoot)}.`,
-    ].join(" ");
+export function buildRefreshGuidance(workspaceRoot, _toolName) {
+    return buildAceDigest(workspaceRoot);
 }
 function isBootstrapTool(toolName) {
     return BOOTSTRAP_TOOLS.has(toolName);
@@ -329,7 +173,21 @@ export function installAceToolGovernance(server, workspaceRoot) {
     const wrapToolCallback = (toolName, callback) => async (...args) => {
         const extra = args.at(-1);
         const sessionId = typeof extra?.sessionId === "string" ? extra.sessionId : undefined;
-        const rawResult = await callback(...args);
+        const activeStep = withWorkspaceRoot(workspaceRoot, () => getHostBinding(sessionId));
+        if (activeStep && !['next_step', 'complete_step', 'start_goal'].includes(toolName)) {
+            const { recordHostContact } = await import('./host-goal-engine.js');
+            await withWorkspaceRoot(workspaceRoot, () => recordHostContact(activeStep)).catch(error => console.error(`ACE contact pending: ${String(error)}`));
+        }
+        const rawResult = await withWorkspaceRoot(workspaceRoot, () => callback(...args));
+        if (['run_tests', 'execute_gates', 'safe_edit_file', 'apply_patch'].includes(toolName)) {
+            const { recordHostToolEvidence } = await import('./host-goal-engine.js');
+            await withWorkspaceRoot(workspaceRoot, () => recordHostToolEvidence(toolName, rawResult, activeStep)).catch(error => console.error(`ACE step evidence pending: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        if (isMutationTool(toolName) || isRefreshTool(toolName) || isBootstrapTool(toolName))
+            digestCache.delete(workspaceRoot);
+        // These responses already contain current work. Replays must remain byte-for-byte stable.
+        if (['next_step', 'complete_step'].includes(toolName) || (toolName === 'start_goal' && args[0]?.executor === 'host'))
+            return rawResult;
         const failed = Boolean(rawResult && typeof rawResult === "object" && rawResult.isError);
         if (sessionId && !failed && isBootstrapTool(toolName)) {
             bootstrappedSessions.add(sessionId);
@@ -345,7 +203,7 @@ export function installAceToolGovernance(server, workspaceRoot) {
                 next = appendTextContent(next, buildBootstrapNudge(workspaceRoot));
             }
         }
-        if (isBootstrapTool(toolName)) {
+        if (isBootstrapTool(toolName) && !failed) {
             next = appendTextContent(next, buildBootstrapGuidance(workspaceRoot, toolName));
         }
         else if (isRefreshTool(toolName)) {
@@ -353,7 +211,7 @@ export function installAceToolGovernance(server, workspaceRoot) {
         }
         else if (isMutationTool(toolName)) {
             const mutationKey = sessionId ?? "__global__";
-            const currentDigest = buildAceDigestCached(workspaceRoot);
+            const currentDigest = buildAceDigest(workspaceRoot);
             const state = mutationGuidanceState.get(mutationKey) ?? { count: 0 };
             state.count += 1;
             const shouldAppend = state.lastDigest === undefined || state.lastDigest !== currentDigest || state.count % 10 === 0;
@@ -382,11 +240,7 @@ export function installAceToolGovernance(server, workspaceRoot) {
     };
 }
 export function buildHookAdditionalContext(workspaceRoot) {
-    const parts = [
-        buildServerInstructions(workspaceRoot),
-        `State digest: ${buildAceDigest(workspaceRoot)}.`,
-    ];
-    return parts.join("\n");
+    return formatCurrentWork(resolveCurrentWork({ workspaceRoot }), "block");
 }
 export function buildScopeReminder(workspaceRoot) {
     const scopeRaw = readAceLogicalFile(workspaceRoot, "agent-state/SCOPE.md");

package/dist/cli.js

@@ -37,6 +37,7 @@ Usage:
   ace turnkey [options]        Project minimal workspace bootstrap stubs from the ACE store
   ace doctor [options]         Validate ACE runtime + MCP readiness
   ace goal <sub> [options]     Drive a self-paced, evidence-gated goal loop
+  ace learn <sub> [args]       List, show, approve, retire, export or report learned artifacts
   ace playbook <sub> [args]    Inspect and curate the experience playbook (experimental)
   ace eval [--adapt] [options] Run the eval harness / playbook adaptation cycle (experimental)
   ace compact [--no-sweep]     Compact the store and sweep loose generated artifacts
@@ -57,7 +58,8 @@ Options for goal:
                       [--max-ticks N] [--goal-id <id>] [--plan-only] [--detach]
   status [<goal_id>]           List goals, or show one goal's plan and escalations
   run <goal_id>                Drive an already-executing goal to a terminal state
-  resume <goal_id>             Revive a planning/blocked/stopped goal, then drive it
+  resume <goal_id> [--budget-hours N] [--max-replans N]
+                              Raise explicit allowances if authorized, then resume
   stop <goal_id>               Request a cooperative stop (honoured between steps)
 
   A goal only reaches \`done\` when its success contract is satisfied: every
@@ -1019,7 +1021,6 @@ async function runDoctor(args) {
         if (provider === "ollama" && !hasModel && repairOllama) {
             const repair = await runShellCommand(`ollama pull ${model}`, {
                 cwd: WORKSPACE_ROOT,
-                timeout_ms: 10 * 60_000,
             });
             await appendRunLedgerEntrySafe({
                 tool: "doctor",
@@ -1429,7 +1430,7 @@ async function runGoalCliInner(args) {
             console.error(`Usage: ace goal ${sub} <goal_id>`);
             process.exit(1);
         }
-        const run = sub === "resume" ? await engine.resumeGoal(goalId) : await engine.runGoal(goalId);
+        const run = sub === "resume" ? await engine.resumeGoal(goalId, {}, { budget_hours: readNumberFlag(args, "--budget-hours"), max_replans: readNumberFlag(args, "--max-replans") }) : await engine.runGoal(goalId);
         console.log(`Goal ${run.goal.goal_id}: ${run.goal.status}${run.goal.reason_code ? ` (${run.goal.reason_code})` : ""}`);
         return;
     }
@@ -1439,7 +1440,7 @@ async function runGoalCliInner(args) {
             console.error("Usage: ace goal stop <goal_id>");
             process.exit(1);
         }
-        const goal = engine.stopGoal(goalId);
+        const goal = await engine.stopGoal(goalId);
         console.log(`Goal ${goal.goal_id}: stop requested (status ${goal.status}).`);
         return;
     }
@@ -1703,8 +1704,10 @@ async function main() {
         if (result.sweep) {
             console.log(`Sweep: folded ${result.sweep.cached_files} artifact(s) into the store, freed ${result.sweep.removed_files} loose file(s) from disk, semantic GC removed ${result.sweep.removed_semantic_cache_files}`);
             if (result.sweep.removed_files > 0) {
-                console.log("  Swept files are stored, not lost — read them back with `ace read <path>` (e.g. `ace read agent-state/TASK.md`). Do not recreate them.");
+                console.log(`  Verified source readbacks: ${result.sweep.verified_sources.filter((source) => source.removed).length}. Receipts and exact source bytes are retained under state/migrations/.`);
             }
+            for (const warning of result.sweep.warnings)
+                console.warn(`  ! ${warning}`);
         }
         return;
     }
@@ -1747,7 +1750,7 @@ async function main() {
         console.log(`Cached files: ${result.cached_files}`);
         console.log(`Kept projected files: ${result.kept_projected_files}`);
         console.log(`Skipped files: ${result.skipped_files}`);
-        console.log(`Removed files: ${result.removed_files} (folded into the store, not lost — read back with \`ace read <path>\`; do not recreate)`);
+        console.log(`Removed files: ${result.removed_files}; verified source readbacks: ${result.verified_sources.filter((source) => source.removed).length}`);
         console.log(`Semantic cache GC removed files: ${result.removed_semantic_cache_files}`);
         console.log(`Staging GC removed entries: ${stagingGc.removed_entries}`);
         if (result.warnings.length > 0) {
@@ -1775,6 +1778,41 @@ async function main() {
         await runEvalCli(args.slice(1));
         return;
     }
+    if (command === 'learn') {
+        const rest = args.slice(1);
+        try {
+            const { listLearning, showLearning, approveLearning, retireLearning, exportLearning, learningReport } = await import('./learning-controls.js');
+            const sub = rest[0] ?? 'list';
+            let result;
+            if (sub === 'list')
+                result = listLearning(WORKSPACE_ROOT);
+            else if (sub === 'show') {
+                result = showLearning(WORKSPACE_ROOT, rest[1]);
+                if (!result)
+                    throw Error('Learning item not found: ' + rest[1]);
+            }
+            else if (sub === 'approve') {
+                await approveLearning(WORKSPACE_ROOT, rest[1]);
+                result = { approved: rest[1] };
+            }
+            else if (sub === 'retire') {
+                await retireLearning(WORKSPACE_ROOT, rest[1], readFlagValue(rest, '--reason') ?? '');
+                result = { retired: rest[1] };
+            }
+            else if (sub === 'export')
+                result = await exportLearning(WORKSPACE_ROOT, readFlagValue(rest, '--to') ?? 'docs/learned');
+            else if (sub === 'report')
+                result = learningReport(WORKSPACE_ROOT);
+            else
+                throw Error('Usage: ace learn list|show <id>|approve <id>|retire <id> --reason <text>|export --to docs/learned|report');
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            console.error(String(error));
+            process.exitCode = 1;
+        }
+        return;
+    }
     if (command === "playbook") {
         await runPlaybookCli(args.slice(1));
         return;

package/dist/experience-reflector.d.ts

@@ -10,4 +10,11 @@ export interface ReflectDeterministicInput {
     maxOpsPerRun?: number;
 }
 export declare function reflectDeterministic(input: ReflectDeterministicInput): PlaybookDeltaOp[];
+import type { TaskStep, ObservedRun } from './orchestrator-supervisor.js';
+import type { GoalRecord } from './store/repositories/goal-repository.js';
+export declare function normalizedFailureLines(text: string): string[];
+export declare function failureSignature(text: string): string | undefined;
+export declare function exactRedGreen(runs: ObservedRun[]): Array<[ObservedRun, ObservedRun]>;
+export declare function learningTaskText(step: TaskStep): string;
+export declare function reflectFromStepOutcome(step: TaskStep, goal: Pick<GoalRecord, 'goal_id'>): PlaybookDeltaOp[];
 //# sourceMappingURL=experience-reflector.d.ts.map

package/dist/experience-reflector.js

@@ -59,4 +59,43 @@ export function reflectDeterministic(input) {
     }
     return ops.slice(0, input.maxOpsPerRun ?? 3);
 }
+// Attached hosts use their existing plan attempts, never local bridge traces.
+import { createHash } from 'node:crypto';
+export function normalizedFailureLines(text) {
+    return text.split(/\r?\n/).filter(line => /(error|fail|assert|exception|not ok|✗|denied|timeout)/i.test(line)).map(line => line
+        .replace(/\b\d{4}-\d\d-\d\d[T ][\d:.]+Z?\b/g, '<time>')
+        .replace(/(?:[A-Za-z]:[\\/]|\/)[^\s'"`:)]+(?::\d+(?::\d+)?)?/g, '<path>')
+        .replace(/:\d+(?::\d+)?/g, ':<line>')
+        .replace(/\b[0-9a-f]{8,}\b/gi, '<id>')
+        .replace(/"[^"\n]*"|'[^'\n]*'|`[^`\n]*`/g, '<value>')
+        .replace(/\s+/g, ' ').trim()).filter(Boolean);
+}
+export function failureSignature(text) {
+    const lines = normalizedFailureLines(text).slice(0, 3);
+    return lines.length ? createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 12) : undefined;
+}
+export function exactRedGreen(runs) {
+    return runs.flatMap((run, index) => {
+        if (run.attribution !== 'Linked' || run.outcome !== 'failed' || run.exit_code === null || run.exit_code === 0)
+            return [];
+        const pass = runs.slice(index + 1).find(next => next.attribution === 'Linked' && next.command === run.command && next.cwd === run.cwd && next.outcome === 'ok' && next.exit_code === 0 && next.at >= run.at);
+        return pass ? [[run, pass]] : [];
+    });
+}
+export function learningTaskText(step) {
+    const owned = step.attempts_log?.flatMap(a => a.checks ?? []);
+    return owned?.length ? owned.map(c => c.command).join('\n') : step.task;
+}
+export function reflectFromStepOutcome(step, goal) {
+    const log = step.attempts_log ?? [], current = log.at(-1), previous = log.at(-2);
+    if (!current)
+        return [];
+    const paths = [...new Set([...(step.expected_artifacts ?? []).map(a => a.path), ...current.evidence_refs, ...(previous?.evidence_refs ?? [])].filter(ref => !/^(ep:|ace:|goal:|https?:|vericify:)/.test(ref)).map(p => p.replace(/\\/g, '/').replace(/^\.\//, '').split('/').slice(0, 2).join('/')))];
+    const tags = ['test', 'build', 'store', 'todo', 'handoff', 'scheduler', 'migration', 'docs', 'release', 'mcp', 'hook', 'schema'].filter(tag => learningTaskText(step).toLowerCase().includes(tag));
+    const ep = (attempt) => `ep:${goal.goal_id}:${step.step_id}:${attempt}`;
+    const contrast = current.status === 'done' && previous?.failure_signature && previous.status !== 'done' ? [{ signature: previous.failure_signature, excerpt: previous.failure_excerpt ?? previous.summary, refs: [ep(previous.attempt), ep(current.attempt), ...previous.evidence_refs, ...current.evidence_refs], paths }] : [];
+    for (const [failed, passed] of exactRedGreen(current.observed_runs ?? []))
+        contrast.push({ signature: failureSignature(failed.output_tail ?? '') ?? 'command-failed', excerpt: failed.output_tail ?? `Command failed: ${failed.command}`, refs: [ep(current.attempt), failed.record_id, passed.record_id, ...current.evidence_refs], paths: [...new Set([...(failed.paths ?? []), ...(passed.paths ?? [])])] });
+    return contrast.map(pair => ({ type: 'ADD', section: 'failure_modes', status: 'quarantined', scope: { role: step.role, paths: pair.paths, task_tags: tags, failure_signature: pair.signature }, content: `When ${pair.excerpt.split('\n')[0]} occurred at ${step.role}/${pair.paths.join(', ')}, the passing attempt did: ${current.summary.slice(0, 300)}`, evidence_refs: pair.refs, provenance: { source: 'harvest', run_id: ep(current.attempt) } }));
+}
 //# sourceMappingURL=experience-reflector.js.map

package/dist/goal-engine.d.ts

@@ -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}.
@@ -30,6 +33,7 @@ import type { BridgeResult } from "./model-bridge.js";
 import { type TaskPlan, type TaskStep } from "./orchestrator-supervisor.js";
 import type { ProposePlanResult } from "./plan-proposal.js";
 import { GoalRepository, type GoalEscalationKind, type GoalRecord, type SuccessContract } from "./store/repositories/goal-repository.js";
+import { type CommandOptions, type CommandPolicy } from './progress-command.js';
 export type { GoalRecord, GoalStatus, GoalBudgets, SuccessContract, } from "./store/repositories/goal-repository.js";
 export interface CompiledPlan {
     proposal: ProposePlanResult;
@@ -40,6 +44,20 @@ export interface CompiledPlan {
     };
 }
 export interface GoalEngineDeps {
+    observations?: {
+        supported_requirements?: readonly ("action" | "command_pass")[];
+        late_evidence?: {
+            wait_ms: number;
+            poll_ms?: number;
+        };
+        readWindow: (window: NonNullable<TaskStep["observation_window"]>) => Promise<{
+            status: "available" | "pending" | "unavailable";
+            records: NonNullable<TaskStep["observation_refs"]>;
+            reason_code?: string;
+            query?: Record<string, unknown>;
+            coverage?: Record<string, unknown>;
+        }>;
+    };
     workspaceRoot?: string;
     /** Millisecond clock (injectable so budgets/heartbeats are deterministic). */
     now?: () => number;
@@ -48,7 +66,9 @@ export interface GoalEngineDeps {
     /** Compiles an objective into a validated proposal. Default: proposePlan+validatePlan. */
     compilePlan?: (objective: string) => Promise<CompiledPlan>;
     /** Runs a verification command; ok === (exit 0). Default: exec in workspace. */
-    runVerification?: (command: string, workspaceRoot: string) => Promise<{
+    runVerification?: (command: string, workspaceRoot: string, options?: CommandOptions & {
+        timeout_ms?: number;
+    }) => Promise<{
         ok: boolean;
         output: string;
     }>;
@@ -62,7 +82,7 @@ export interface GoalEngineDeps {
         summary: string;
         payload: Record<string, unknown>;
     }) => Promise<void>;
-    /** Vericify process-post sink. Default: appendVericifyProcessPostSafe. */
+    /** Vericify process-post sink. Default: appendAutomaticVericifyProcessPostSafe. */
     appendProcessPost?: (input: {
         kind: GoalEscalationKind | "progress" | "completion";
         summary: string;
@@ -71,13 +91,39 @@ export interface GoalEngineDeps {
     }) => Promise<void>;
 }
 export interface StartGoalOptions {
+    executor?: "engine" | "host";
+    agent?: string;
+    session_id?: string;
+    steps?: Array<{
+        id?: string;
+        task: string;
+        role?: string;
+        depends_on?: string[];
+        expected_artifacts?: Array<string | {
+            path: string;
+            required?: boolean;
+            transient?: boolean;
+        }>;
+        required_evidence_refs?: string[];
+        required_observation?: "action" | "command_pass";
+    }>;
+    todo_ids?: Record<string, string>;
     budget_hours?: number;
     max_ticks?: number;
     max_replans?: number;
     plan_only?: boolean;
     goal_id?: string;
     /** Shell commands that must exit 0 before the goal can reach `done`. */
-    verify_commands?: string[];
+    verify_commands?: VerificationCommand[];
+}
+export type VerificationCommand = string | ({
+    cmd: string;
+} & CommandPolicy);
+export declare const verificationCommandText: (command: VerificationCommand) => string;
+export interface ResumeGoalOptions {
+    /** New total allowance from the original start, not a restart of the clock. */
+    budget_hours?: number;
+    max_replans?: number;
 }
 interface ResolvedDeps {
     workspaceRoot: string;
@@ -91,6 +137,7 @@ interface ResolvedDeps {
     emitStatusEvent: NonNullable<GoalEngineDeps["emitStatusEvent"]>;
     appendProcessPost: NonNullable<GoalEngineDeps["appendProcessPost"]>;
 }
+export declare function resolveGoalDeps(deps?: GoalEngineDeps): ResolvedDeps;
 /**
  * The number of machine-checkable obligations in a contract. Zero means the
  * only thing standing between the model and `status: "done"` is the model's own
@@ -104,6 +151,10 @@ export interface StartGoalResult {
     goal: GoalRecord;
     reason_code?: string;
     blocking_findings?: string[];
+    assignment?: import('./host-goal-engine.js').Assignment;
+    now?: string;
+    message?: string;
+    waiting_on?: string[];
 }
 export declare function startGoal(objective: string, options?: StartGoalOptions, deps?: GoalEngineDeps): Promise<StartGoalResult>;
 export interface TickGoalResult {
@@ -119,6 +170,7 @@ export interface ContractCheckResult {
     missing_artifacts: string[];
     missing_evidence_refs: string[];
     failed_commands: string[];
+    failure_signatures?: string[];
     /** True when the contract carries zero enforceable obligations. Never `ok`. */
     uncheckable: boolean;
 }
@@ -128,8 +180,11 @@ export interface RunGoalResult {
     plan?: TaskPlan;
 }
 export declare function runGoal(goalId: string, deps?: GoalEngineDeps): Promise<RunGoalResult>;
-export declare function resumeGoal(goalId: string, deps?: GoalEngineDeps): Promise<RunGoalResult>;
-export declare function stopGoal(goalId: string, deps?: GoalEngineDeps): GoalRecord;
+export declare function resumeGoal(goalId: string, deps?: GoalEngineDeps, options?: ResumeGoalOptions): Promise<RunGoalResult>;
+/** Operator-approved increases retain the original clock and all accepted work. */
+export declare function recoverEngineGoalBudgets(goalId: string, options: ResumeGoalOptions, deps?: GoalEngineDeps): Promise<GoalRecord>;
+export { beginStep, completeStep, applyHostResultToStep } from './host-goal-engine.js';
+export declare function stopGoal(goalId: string, deps?: GoalEngineDeps): Promise<GoalRecord>;
 export interface GoalStatusView {
     goal: GoalRecord;
     plan?: TaskPlan;
@@ -152,4 +207,6 @@ export declare class GoalNotResumableError extends Error {
     readonly name = "GoalNotResumableError";
     constructor(goal_id: string, message: string);
 }
+/** Learning groups related failures; loop detection must also retain exact test identities. */
+export declare function failureProgressSignature(text: string): string;
 //# sourceMappingURL=goal-engine.d.ts.map