@voybio/ace-swarm 2.4.4 → 2.4.7

package/dist/cli.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_LLM_PROVIDERS, DEFAULTS_ROOT, PACKAGE_ROOT, WORKSPACE_ROOT, fileExists, getAllMcpServerConfigSnippets, getMcpClientInstallHint, getMcpServerConfigSnippet, wsPath, } from "./helpers.js";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { refreshAstgrepIndex } from "./astgrep-index.js";
 import { scanWorkspaceDelta } from "./index-store.js";
 import { startHermesShadowStdioServer, startStdioServer } from "./server.js";
@@ -20,11 +22,13 @@ import { buildOpenAiCompatibleBaseUrl, buildProviderDoctorCommands, defaultModel
 import { diagnoseChatRuntimeConfig, OpenAICompatibleClient, } from "./tui/openai-compatible.js";
 import { runShellCommand } from "./runtime-command.js";
 import { resolveHermesLaunchProfile } from "./hermes/launch-profile.js";
+import { gcStaging } from "./safe-edit.js";
+import { ROLE_TOOL_DEFAULTS } from "./ace-context.js";
 function printHelp() {
     console.log(`ACE Swarm CLI
 
 Usage:
-  ace mcp                      Start MCP server over stdio
+  ace mcp [--profile <name>]   Start MCP server over stdio (host-min|full; default full)
   ace mcp-shadow --tools <csv> Start filtered Hermes-local MCP shadow server over stdio
   ace serve                    Alias for mcp
   ace tui [options]            Launch interactive TUI dashboard
@@ -32,12 +36,36 @@ Usage:
   ace connect [provider]       Register a live local runtime or hosted provider in the store
   ace turnkey [options]        Project minimal workspace bootstrap stubs from the ACE store
   ace doctor [options]         Validate ACE runtime + MCP readiness
-  ace cache [options]          Cache ACE artifacts into ace-state.ace and optionally clean projections
+  ace goal <sub> [options]     Drive a self-paced, evidence-gated goal loop
+  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
+  ace cache [options]          DEPRECATED: ingest+clean only. Use \`ace compact\`.
+  ace migrate [store-path]     Import a legacy file workspace into the store
+  ace repair                   Re-materialize host files and repair store assets
+  ace add skills [name|all]    Install packaged skill packs into the store
+  ace fsck [--json] [--repair] Validate ACEPACK store structure and loose workspace artifacts
+  ace ls [prefix] [options]    List store-backed artifacts (operational / knowledge / state)
+  ace read <path> [options]    Read a store-backed or workspace file (aliases: get, cat)
   ace mcp-config [options]     Print global/client MCP config snippet(s) from store
   ace preconfig                Write .mcp-config/ bundle for all supported clients to workspace root
   ace paths                    Show resolved package/workspace paths
   ace help                     Show help
 
+Options for goal:
+  start "<objective>" [--verify <cmd>] [--budget-hours N] [--max-replans N]
+                      [--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
+  stop <goal_id>               Request a cooperative stop (honoured between steps)
+
+  A goal only reaches \`done\` when its success contract is satisfied: every
+  required artifact exists and every verification command exits 0. Declare one
+  with \`--verify <cmd>\`, or by appending \`verify: <cmd>\` to the objective.
+  A goal that declares neither is refused at \`start\` with \`contract_uncheckable\`,
+  because nothing would stand between the model and \`done\` but its own summary.
+
 Options for tui:
   --provider <name>            Provider override (ollama|llama.cpp|codex|gemini|claude|copilot|...)
   --model <name>               Model name override (defaults from profile/settings discovery)
@@ -64,6 +92,22 @@ Options for init:
   --base-url <url>             Runtime base URL override (local or OpenAI-compatible)
   --ollama-url <url>           Legacy alias for --base-url
 
+Options for turnkey:
+  --no-client-config-bundle    Skip the host-facing config stubs turnkey creates by default
+
+Options for mcp:
+  --profile <host-min|full>    Select the visible tool schema (default: full)
+
+Options for playbook add:
+  --reason-code <code>         Scope the lesson to a matching failure reason code
+
+Options for eval:
+  --model, --models <csv>      Model name or comma-separated model names (required)
+  --battery <path>             Evaluation battery JSON (default: packaged battery)
+  --out <dir>                  Scorecard output directory
+  --adapt                      Compare baseline and playbook-adapted runs
+  --epochs <n>                 Adaptation epochs (only with --adapt; default: 1)
+
 Options for connect:
   llama-server|llama-cli       Optional launcher name for llama.cpp HF runtimes
   --hf <repo>                  Hugging Face model repo or local model identifier
@@ -88,6 +132,16 @@ Options for cache:
   --dry-run                    Preview what would be cached and cleaned (no writes/deletes)
   --no-clean                   Keep workspace ACE artifacts after caching them into ace-state.ace
 
+Options for ls:
+  --keys                       Show raw store keys instead of logical paths
+  --json                       Machine-readable output
+
+Options for read (aliases: get, cat):
+  --out <file>                 Materialize a copy to <file> instead of printing to stdout
+  --source                     Print the resolved source (virtual/store/disk) and key to stderr
+  --prefer <disk|store>        When store and disk copies diverge, force which one is shown
+  --json                       Machine-readable output ({ path, source, key, divergent, content })
+
 Options for mcp-config:
   --client <name>              codex|vscode|copilot|claude|cursor|antigravity
   --all                        Print all client snippets for optional global install
@@ -111,6 +165,75 @@ function readFlagValue(args, flag) {
         return undefined;
     return args[index + 1];
 }
+/** `--flag`, `--flag=value`, or a short `-x`. `-5` is a number, not a flag. */
+function isFlagToken(arg) {
+    return arg.startsWith("--") || /^-[A-Za-z]/.test(arg);
+}
+/**
+ * Positional arguments, with value-taking flags and their values removed.
+ * A bare `.filter(a => !a.startsWith("--"))` drops the flag but keeps its value,
+ * which silently folds `--budget-hours 2` into a goal objective. Supports both
+ * `--flag value` and `--flag=value`, plus `--` as an end-of-flags separator.
+ */
+export function positionalArgs(args, valueFlags) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--") {
+            out.push(...args.slice(i + 1));
+            break;
+        }
+        if (isFlagToken(arg)) {
+            if (!arg.includes("=") && valueFlags.has(arg))
+                i += 1; // consume the value
+            continue;
+        }
+        out.push(arg);
+    }
+    return out;
+}
+export const GOAL_VALUE_FLAGS = new Set([
+    "--budget-hours",
+    "--max-replans",
+    "--max-ticks",
+    "--goal-id",
+    "--verify",
+]);
+/**
+ * A flag's numeric value, or `undefined` when absent. Exits non-zero on anything
+ * that is not a finite number: `Number("abc")` is `NaN`, `typeof NaN` is
+ * `"number"`, so an unvalidated NaN reaches `startGoal`, disables the budget it
+ * was meant to set, and then serialises to `null` — which makes the same budget
+ * fire immediately on the next reload.
+ */
+function readNumberFlag(args, flag) {
+    const raw = readFlagValue(args, flag);
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        console.error(`${flag} expects a number, got: ${raw}`);
+        process.exit(1);
+    }
+    return value;
+}
+/** Every value of a repeatable flag, in order. Supports `--flag v` and `--flag=v`. */
+function readFlagValues(args, flag) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg.startsWith(`${flag}=`))
+            out.push(arg.slice(flag.length + 1));
+        else if (arg === flag && i + 1 < args.length)
+            out.push(args[++i]);
+    }
+    return out.map((v) => v.trim()).filter(Boolean);
+}
+export const PLAYBOOK_ADD_VALUE_FLAGS = new Set([
+    "--section",
+    "--content",
+    "--reason-code",
+]);
 async function runCommandArray(command, args, options) {
     const [bin, ...prefixArgs] = command;
     if (!bin)
@@ -203,6 +326,76 @@ async function probeHermesShadowMcp(cliPath, toolAllowlist) {
         child.stdin.write(mcpFrame({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }));
     });
 }
+// Start a shadow server with an arbitrary scope and return the tool names it actually
+// serves (parsed from the tools/list response). Used to assert that non-coders scopes are
+// really served — not just the hand-picked get_all_agents_summary — which is the WS-A gate.
+async function listHermesShadowTools(cliPath, scope) {
+    return await new Promise((resolveProbe, rejectProbe) => {
+        const child = spawn(process.execPath, [cliPath, "mcp-shadow", "--tools", scope.join(",")], {
+            cwd: PACKAGE_ROOT,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        const finish = () => {
+            const names = new Set();
+            for (const line of stdout.split(/\r?\n/)) {
+                if (!line.includes('"tools"'))
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    for (const tool of parsed.result?.tools ?? []) {
+                        if (typeof tool.name === "string")
+                            names.add(tool.name);
+                    }
+                }
+                catch {
+                    // partial/non-JSON line; ignore
+                }
+            }
+            return names;
+        };
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+            const names = finish();
+            if (names.size > 0)
+                resolveProbe(names);
+            else
+                rejectProbe(new Error(`shadow scope probe timed out${stderr ? `: ${stderr.slice(0, 200)}` : ""}`));
+        }, 2500);
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+            if (stdout.includes('"tools"')) {
+                clearTimeout(timeout);
+                child.kill("SIGTERM");
+                resolveProbe(finish());
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            rejectProbe(error);
+        });
+        child.on("close", () => {
+            clearTimeout(timeout);
+            resolveProbe(finish());
+        });
+        child.stdin.write(mcpFrame({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "ace-doctor", version: "0.0.0" },
+            },
+        }));
+        child.stdin.write(mcpFrame({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
+        child.stdin.write(mcpFrame({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }));
+    });
+}
 async function appendHermesLocalReadinessChecks(checks, profile) {
     const hermesRoot = profile.hermes_root;
     const workerPath = profile.worker_path;
@@ -276,6 +469,27 @@ async function appendHermesLocalReadinessChecks(checks, profile) {
                 detail: error instanceof Error ? error.message : String(error),
             });
         }
+        // WS-A gate: assert a computed non-coders (orchestrator) scope is actually served, so
+        // the D1 zero-tool regression cannot recur for conversational/orchestration turns.
+        try {
+            const orchestratorScope = ROLE_TOOL_DEFAULTS["orchestrator"] ?? [];
+            const served = await listHermesShadowTools(cliPath, orchestratorScope);
+            const covered = orchestratorScope.filter((tool) => served.has(tool));
+            checks.push({
+                name: "ACE shadow MCP non-coders scope",
+                ok: covered.length >= 3,
+                detail: covered.length >= 3
+                    ? `orchestrator scope served ${covered.length}/${orchestratorScope.length} tools (e.g. ${covered.slice(0, 3).join(", ")})`
+                    : `orchestrator scope served only ${covered.length} tools — expected >=3 (D1 zero-tool regression risk)`,
+            });
+        }
+        catch (error) {
+            checks.push({
+                name: "ACE shadow MCP non-coders scope",
+                ok: false,
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
     }
     else {
         checks.push({
@@ -412,6 +626,8 @@ async function runConnect(args) {
         includeClientConfigBundle: false,
         launcherCommand: parsed.launcherCommand,
     });
+    const { waitForPendingLifecycleSweep } = await import("./store/materializers/projection-manager.js");
+    await waitForPendingLifecycleSweep();
     console.log("ACE connect complete");
     console.log(`Workspace: ${WORKSPACE_ROOT}`);
     console.log(`Store: ${storeResult.storePath}`);
@@ -520,6 +736,10 @@ async function runInit(args, mode = "init") {
     // Drain that queue before appending the init run-ledger entry so init/turnkey
     // never race two packed-store writers in the same process.
     await waitForPendingStatusEventMirrors();
+    {
+        const { waitForPendingLifecycleSweep } = await import("./store/materializers/projection-manager.js");
+        await waitForPendingLifecycleSweep();
+    }
     // Record CLI execution in run-ledger for observability
     try {
         await appendRunLedgerEntrySafe({
@@ -616,6 +836,22 @@ async function runDoctor(args) {
                 : "Store-backed MCP snippets are baked into ace-state.ace. Run `ace mcp-config --all` for global install."
             : "No MCP bridge or baked snippets found. Run `ace init` first.",
     });
+    const { fsckWorkspaceStore } = await import("./store/fsck.js");
+    const fsck = fsckWorkspaceStore(WORKSPACE_ROOT);
+    checks.push({
+        name: "ACEPACK fsck",
+        ok: fsck.ok,
+        detail: fsck.ok
+            ? `${fsck.checks.length} checks passed`
+            : `${fsck.checks.filter((check) => !check.ok).length} fsck checks failed; run ace fsck`,
+    });
+    checks.push({
+        name: "ACEPACK store-first mode",
+        ok: true,
+        detail: process.env.ACE_STORE_FIRST === "0"
+            ? "legacy disk precedence enabled via ACE_STORE_FIRST=0; projection allowlist: .agents/ACE/tasks/todo.md"
+            : "store-first reads enabled; projection allowlist: .agents/ACE/tasks/todo.md",
+    });
     const profilePath = `${getWorkspaceStorePath(WORKSPACE_ROOT)}#state/runtime/llm_profile`;
     const hasProfile = Boolean(readLlmProfile());
     checks.push({
@@ -763,7 +999,7 @@ async function runDoctor(args) {
             selectedModel: model,
             available: modelNames.length > 0,
         });
-        checks.push({
+        const requestedModelCheck = {
             name: provider === "ollama" ? "Requested model installed" : "Requested model served",
             ok: hasModel,
             detail: provider === "ollama"
@@ -773,7 +1009,8 @@ async function runDoctor(args) {
                 : hasModel
                     ? `${model} found`
                     : `${model} not reported by llama.cpp (available: ${modelNames.join(", ") || "none"})`,
-        });
+        };
+        checks.push(requestedModelCheck);
         if (provider === "ollama" && !hasModel && repairOllama) {
             const repair = await runShellCommand(`ollama pull ${model}`, {
                 cwd: WORKSPACE_ROOT,
@@ -811,6 +1048,28 @@ async function runDoctor(args) {
                     ? `ollama pull ${model} completed`
                     : `ollama pull ${model} failed with exit ${repair.exit_code}: ${repair.stderr || repair.stdout || "no output"}`,
             });
+            if (repair.exit_code === 0) {
+                try {
+                    modelNames = await listLocalRuntimeModels("ollama", baseUrl);
+                    const repaired = modelNames.includes(model);
+                    requestedModelCheck.ok = repaired;
+                    requestedModelCheck.detail = repaired
+                        ? `${model} found after repair re-probe`
+                        : `${model} still missing after successful pull; runtime re-probe returned ${modelNames.join(", ") || "no models"}`;
+                    checks.push({
+                        name: "Ollama repair re-probe",
+                        ok: repaired,
+                        detail: requestedModelCheck.detail,
+                    });
+                }
+                catch (error) {
+                    checks.push({
+                        name: "Ollama repair re-probe",
+                        ok: false,
+                        detail: `pull succeeded but readiness re-probe failed: ${error instanceof Error ? error.message : String(error)}`,
+                    });
+                }
+            }
         }
     }
     else {
@@ -950,11 +1209,277 @@ async function runMcpConfig(args) {
     const body = readStoredMcpSnippet(client) ?? getMcpServerConfigSnippet(client);
     console.log(body);
 }
+async function runEvalCli(args) {
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+    const { join, resolve } = await import("node:path");
+    const harness = await import("./eval-harness.js");
+    // Ships with the package (`assets` is in package.json files[]). The battery
+    // used to live under test/, which is not published — `ace eval` was therefore
+    // impossible to run from a global install. See E1 in
+    // REPORT_GOAL_EVAL_PLAYBOOK_MITIGATIONS_2026-07-09.md.
+    const defaultBattery = resolve(DEFAULTS_ROOT, "eval-battery", "battery.json");
+    const batteryPath = readFlagValue(args, "--battery") ?? defaultBattery;
+    const models = (readFlagValue(args, "--models") ?? readFlagValue(args, "--model") ?? "").split(",").map((m) => m.trim()).filter(Boolean);
+    const outDir = resolve(WORKSPACE_ROOT, readFlagValue(args, "--out") ?? "agent-state/eval-reports");
+    const adapt = args.includes("--adapt");
+    if (models.length === 0) {
+        console.error("Usage: ace eval [--adapt] --model <name>[,<name>...] [--battery <path>] [--out <dir>]");
+        process.exit(1);
+    }
+    if (adapt) {
+        const adaptation = await import("./playbook-adaptation.js");
+        const epochs = Number(readFlagValue(args, "--epochs") ?? "1");
+        // Validate the battery before creating anything: a bad path used to leave an
+        // empty agent-state/eval-reports/ behind.
+        const battery = harness.loadBattery(batteryPath);
+        mkdirSync(outDir, { recursive: true });
+        console.log(`Adaptation battery: ${battery.tasks.length} tasks (${batteryPath}) × ${models.length} model(s)`);
+        for (const model of models) {
+            const report = await adaptation.runAdaptationCycle({
+                model,
+                batteryPath,
+                workspaceRoot: WORKSPACE_ROOT,
+                epochs: Number.isFinite(epochs) ? epochs : 1,
+                outputDir: outDir,
+            });
+            console.log(`  ${model}: baseline ${report.baseline.summary.passed}/${report.baseline.summary.total}, ` +
+                `adapted ${report.adapted.summary.passed}/${report.adapted.summary.total}, ` +
+                `playbook added=${report.playbook_stats.added} merged=${report.playbook_stats.merged}`);
+            console.log(`    → ${report.report_path}`);
+        }
+        return;
+    }
+    const battery = harness.loadBattery(batteryPath);
+    mkdirSync(outDir, { recursive: true });
+    console.log(`Eval battery: ${battery.tasks.length} tasks (seed ${battery.seed}) × ${models.length} model(s)`);
+    for (const model of models) {
+        const runner = harness.makeLiveRunner(WORKSPACE_ROOT);
+        const card = await harness.runBattery({ battery, model, runner, workspaceRoot: WORKSPACE_ROOT });
+        const stem = `scorecard-${model.replace(/[^a-zA-Z0-9_.-]/g, "_")}`;
+        writeFileSync(join(outDir, `${stem}.json`), JSON.stringify(card, null, 2));
+        writeFileSync(join(outDir, `${stem}.md`), harness.scorecardToMarkdown(card));
+        console.log(`  ${model}: ${card.summary.passed}/${card.summary.total} passed (${(card.summary.success_rate * 100).toFixed(1)}%), ` +
+            `parse_repairs=${card.summary.total_parse_repairs}, false_completions=${card.summary.total_false_completion_demotions}`);
+        console.log(`    → ${join(outDir, `${stem}.md`)}`);
+    }
+}
+async function runPlaybookCli(args) {
+    const { PLAYBOOK_SECTIONS, PLAYBOOK_STATUSES, isPlaybookSection, isPlaybookStatus, PlaybookRepository, materializePlaybookMarkdown, renderPlaybookMarkdown } = await import("./store/repositories/playbook-repository.js");
+    const { curate } = await import("./playbook-curator.js");
+    const repo = new PlaybookRepository(WORKSPACE_ROOT);
+    const subcommand = args[0] ?? "list";
+    if (subcommand === "list") {
+        const section = readFlagValue(args, "--section");
+        const status = readFlagValue(args, "--status");
+        if (section && !isPlaybookSection(section)) {
+            console.error(`--section expects ${PLAYBOOK_SECTIONS.join("|")}, got: ${section}`);
+            process.exit(1);
+        }
+        if (status && !isPlaybookStatus(status)) {
+            console.error(`--status expects ${PLAYBOOK_STATUSES.join("|")}, got: ${status}`);
+            process.exit(1);
+        }
+        const validSection = section && isPlaybookSection(section) ? section : undefined;
+        const validStatus = status && isPlaybookStatus(status) ? status : undefined;
+        materializePlaybookMarkdown(WORKSPACE_ROOT);
+        console.log(renderPlaybookMarkdown(repo, { section: validSection, status: validStatus }));
+        return;
+    }
+    if (subcommand === "show") {
+        const id = args[1];
+        if (!id) {
+            console.error("Usage: ace playbook show <id>");
+            process.exit(1);
+        }
+        const bullet = repo.getBullet(id);
+        if (!bullet) {
+            console.error(`Playbook bullet not found: ${id}`);
+            process.exit(1);
+        }
+        console.log(JSON.stringify(bullet, null, 2));
+        return;
+    }
+    if (subcommand === "add") {
+        const content = readFlagValue(args, "--content") ??
+            positionalArgs(args.slice(1), PLAYBOOK_ADD_VALUE_FLAGS).join(" ").trim();
+        if (!content) {
+            console.error("Usage: ace playbook add --content <text> [--section verification] [--reason-code <code>]");
+            process.exit(1);
+        }
+        const section = readFlagValue(args, "--section") ?? "failure_modes";
+        if (!isPlaybookSection(section)) {
+            console.error(`--section expects ${PLAYBOOK_SECTIONS.join("|")}, got: ${section}`);
+            process.exit(1);
+        }
+        const reason = readFlagValue(args, "--reason-code");
+        const bullet = repo.createBullet({
+            section,
+            scope: reason ? { reason_code: reason } : {},
+            content,
+            evidence_refs: [],
+            provenance: { source: "operator" },
+        });
+        const path = materializePlaybookMarkdown(WORKSPACE_ROOT);
+        console.log(`Added ${bullet.bullet_id}; projection ${path}`);
+        return;
+    }
+    if (subcommand === "tag") {
+        const id = args[1];
+        const tag = args[2] === "helpful" || args[2] === "harmful" ? args[2] : undefined;
+        if (!id || !tag) {
+            console.error("Usage: ace playbook tag <id> helpful|harmful");
+            process.exit(1);
+        }
+        // curate() skips unknown bullet ids (`if (!bullet) continue`), so a typo used
+        // to print success and exit 0.
+        const curated = await curate(repo, [{ type: "TAG", bullet_id: id, tag }]);
+        if (curated.tagged === 0) {
+            console.error(`Playbook bullet not found: ${id}`);
+            process.exit(1);
+        }
+        const path = materializePlaybookMarkdown(WORKSPACE_ROOT);
+        console.log(`Tagged ${id} ${tag}; projection ${path}`);
+        return;
+    }
+    if (subcommand === "gc") {
+        const result = await curate(repo, [], {});
+        const path = materializePlaybookMarkdown(WORKSPACE_ROOT);
+        console.log(`Playbook GC: pruned=${result.pruned} quarantined=${result.quarantined}; projection ${path}`);
+        return;
+    }
+    console.error("Usage: ace playbook list|show <id>|add|tag <id> helpful|harmful|gc");
+    process.exit(1);
+}
+async function runGoalCli(args) {
+    try {
+        await runGoalCliInner(args);
+    }
+    catch (error) {
+        // Name-based rather than `instanceof`: goal-engine.js is dynamically
+        // imported, so the class identity is not guaranteed to be shared.
+        const name = error?.name;
+        if (name === "UnknownGoalError") {
+            console.error(`Unknown goal: ${error.goal_id ?? args[1]}`);
+            process.exit(1);
+        }
+        if (name === "GoalNotResumableError") {
+            console.error(error.message);
+            process.exit(1);
+        }
+        throw error;
+    }
+}
+async function runGoalCliInner(args) {
+    const sub = (args[0] ?? "").toLowerCase();
+    const engine = await import("./goal-engine.js");
+    if (sub === "start") {
+        const objective = positionalArgs(args.slice(1), GOAL_VALUE_FLAGS).join(" ").trim();
+        if (!objective) {
+            console.error('Usage: ace goal start "<objective>" [--verify <cmd>] [--budget-hours N] [--max-replans N] [--max-ticks N] [--goal-id <id>] [--plan-only] [--detach]');
+            process.exit(1);
+        }
+        const started = await engine.startGoal(objective, {
+            budget_hours: readNumberFlag(args, "--budget-hours"),
+            max_replans: readNumberFlag(args, "--max-replans"),
+            max_ticks: readNumberFlag(args, "--max-ticks"),
+            goal_id: readFlagValue(args, "--goal-id"),
+            verify_commands: readFlagValues(args, "--verify"),
+            plan_only: args.includes("--plan-only"),
+        });
+        console.log(`Goal ${started.goal.goal_id}: ${started.goal.status}`);
+        if (!started.ok) {
+            console.error(`  reason: ${started.reason_code}`);
+            (started.blocking_findings ?? []).forEach((f) => console.error(`  - ${f}`));
+            process.exit(2);
+        }
+        if (args.includes("--plan-only"))
+            return;
+        if (args.includes("--detach")) {
+            const { spawn } = await import("node:child_process");
+            const { mkdirSync, openSync } = await import("node:fs");
+            const { join } = await import("node:path");
+            // `stdio: "ignore"` used to discard everything: a detached engine that died
+            // at import time left the goal `executing` with a stale heartbeat and no
+            // diagnostic anywhere. Give the child somewhere to say what happened.
+            const goalsDir = join(WORKSPACE_ROOT, "agent-state", "goals");
+            mkdirSync(goalsDir, { recursive: true });
+            const logPath = join(goalsDir, `${started.goal.goal_id}.log`);
+            const log = openSync(logPath, "a");
+            const child = spawn(process.execPath, [process.argv[1], "goal", "run", started.goal.goal_id], {
+                detached: true,
+                stdio: ["ignore", log, log],
+            });
+            child.unref();
+            console.log(`  detached engine pid=${child.pid}; poll with: ace goal status ${started.goal.goal_id}`);
+            console.log(`  child output: ${logPath}`);
+            return;
+        }
+        const run = await engine.runGoal(started.goal.goal_id);
+        console.log(`Goal ${run.goal.goal_id} finished: ${run.goal.status}${run.goal.reason_code ? ` (${run.goal.reason_code})` : ""}`);
+        return;
+    }
+    if (sub === "run" || sub === "resume") {
+        const goalId = args[1];
+        if (!goalId) {
+            console.error(`Usage: ace goal ${sub} <goal_id>`);
+            process.exit(1);
+        }
+        const run = sub === "resume" ? await engine.resumeGoal(goalId) : await engine.runGoal(goalId);
+        console.log(`Goal ${run.goal.goal_id}: ${run.goal.status}${run.goal.reason_code ? ` (${run.goal.reason_code})` : ""}`);
+        return;
+    }
+    if (sub === "stop") {
+        const goalId = args[1];
+        if (!goalId) {
+            console.error("Usage: ace goal stop <goal_id>");
+            process.exit(1);
+        }
+        const goal = engine.stopGoal(goalId);
+        console.log(`Goal ${goal.goal_id}: stop requested (status ${goal.status}).`);
+        return;
+    }
+    if (sub === "status") {
+        const goalId = args[1];
+        if (goalId) {
+            const view = engine.getGoalStatus(goalId);
+            if (!view) {
+                console.error(`Unknown goal: ${goalId}`);
+                process.exit(1);
+            }
+            console.log(`Goal ${view.goal.goal_id}: ${view.goal.status}`);
+            console.log(`  objective: ${view.goal.objective}`);
+            console.log(`  ticks: ${view.goal.tick_count}  replans: ${view.goal.replan_count}  last_heartbeat: ${view.goal.last_heartbeat_at ?? "-"}`);
+            console.log(`  plan: ${view.plan_status ?? "none"}  ready: ${view.ready_steps.join(", ") || "-"}`);
+            if (view.goal.escalations.length > 0) {
+                console.log("  escalations:");
+                view.goal.escalations.forEach((e) => console.log(`    - [${e.kind}] ${e.reason_code}: ${e.summary}`));
+            }
+            return;
+        }
+        const goals = engine.listGoals();
+        if (goals.length === 0) {
+            console.log("No goals.");
+            return;
+        }
+        for (const g of goals) {
+            console.log(`${g.goal_id}\t${g.status}\t${g.objective}`);
+        }
+        return;
+    }
+    console.error("Usage: ace goal <start|status|stop|resume|run> ...");
+    process.exit(1);
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = (args[0] ?? "mcp").toLowerCase();
     if (command === "mcp" || command === "serve") {
-        await startStdioServer();
+        gcStaging();
+        const profileArg = (readFlagValue(args.slice(1), "--profile") ?? "full").toLowerCase();
+        if (profileArg !== "host-min" && profileArg !== "full") {
+            process.stderr.write(`ace ${command}: error: --profile must be 'host-min' or 'full' (got '${profileArg}')\n`);
+            process.exit(1);
+        }
+        await startStdioServer(true, profileArg);
         return;
     }
     if (command === "mcp-shadow") {
@@ -963,6 +1488,13 @@ async function main() {
             .split(",")
             .map((tool) => tool.trim())
             .filter(Boolean);
+        if (tools.length === 0) {
+            process.stderr.write("ace mcp-shadow: error: --tools must be a non-empty comma-separated list " +
+                "(reason_code=hermes_empty_tool_scope). " +
+                "An empty tool surface means the Hermes model has no ACE capabilities.\n");
+            process.exit(1);
+        }
+        gcStaging();
         await startHermesShadowStdioServer(tools);
         return;
     }
@@ -1146,6 +1678,8 @@ async function main() {
         const { repairWorkspace } = await import("./store/bootstrap-store.js");
         console.log(`Repairing workspace at ${WORKSPACE_ROOT}...`);
         const warnings = await repairWorkspace(WORKSPACE_ROOT);
+        const { waitForPendingLifecycleSweep } = await import("./store/materializers/projection-manager.js");
+        await waitForPendingLifecycleSweep();
         if (warnings.length) {
             for (const w of warnings)
                 console.warn(`  ! ${w}`);
@@ -1157,16 +1691,50 @@ async function main() {
     }
     if (command === "compact") {
         const { compactWorkspace } = await import("./store/bootstrap-store.js");
-        const result = await compactWorkspace(WORKSPACE_ROOT);
+        const noSweep = args.includes("--no-sweep");
+        const result = await compactWorkspace(WORKSPACE_ROOT, { sweep: !noSweep });
         const savedKb = Math.round((result.before - result.after) / 1024);
         console.log(`Store compacted: ${result.before} → ${result.after} bytes (saved ${savedKb}KB)`);
+        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.");
+            }
+        }
+        return;
+    }
+    if (command === "fsck") {
+        const { fsckWorkspaceStore } = await import("./store/fsck.js");
+        const asJson = args.includes("--json");
+        const repair = args.includes("--repair");
+        const result = fsckWorkspaceStore(WORKSPACE_ROOT, { repair });
+        if (asJson) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log("ACE fsck");
+            console.log(`Workspace: ${WORKSPACE_ROOT}`);
+            console.log(`Store: ${result.storePath}`);
+            for (const check of result.checks) {
+                console.log(`- [${check.ok ? "PASS" : "FAIL"}] ${check.name}: ${check.detail}`);
+            }
+            if (result.repaired_paths.length > 0) {
+                console.log("Repaired paths:");
+                for (const path of result.repaired_paths)
+                    console.log(`- ${path}`);
+            }
+        }
+        if (!result.ok)
+            process.exitCode = 1;
         return;
     }
     if (command === "cache") {
         const { cacheWorkspaceArtifacts } = await import("./store/cache-workspace.js");
         const dryRun = args.includes("--dry-run");
         const clean = !args.includes("--no-clean");
+        const stagingGc = dryRun ? gcStaging({ max_age_hours: Number.POSITIVE_INFINITY }) : gcStaging();
         const result = await cacheWorkspaceArtifacts(WORKSPACE_ROOT, { dryRun, clean });
+        console.warn("ace cache is deprecated; use `ace compact` for compaction plus workspace sweep.");
         console.log("ACE cache complete");
         console.log(`Workspace: ${WORKSPACE_ROOT}`);
         console.log(`Store: ${result.storePath}`);
@@ -1174,7 +1742,9 @@ 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}`);
+        console.log(`Removed files: ${result.removed_files} (folded into the store, not lost — read back with \`ace read <path>\`; do not recreate)`);
+        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) {
             console.warn(`Warnings (${result.warnings.length}):`);
             for (const warning of result.warnings)
@@ -1182,6 +1752,28 @@ async function main() {
         }
         return;
     }
+    if (command === "ls") {
+        const { runLsCommand } = await import("./store/store-cli.js");
+        await runLsCommand(WORKSPACE_ROOT, args.slice(1));
+        return;
+    }
+    if (command === "read" || command === "get" || command === "cat") {
+        const { runReadCommand } = await import("./store/store-cli.js");
+        await runReadCommand(WORKSPACE_ROOT, args.slice(1));
+        return;
+    }
+    if (command === "goal") {
+        await runGoalCli(args.slice(1));
+        return;
+    }
+    if (command === "eval") {
+        await runEvalCli(args.slice(1));
+        return;
+    }
+    if (command === "playbook") {
+        await runPlaybookCli(args.slice(1));
+        return;
+    }
     if (command === "help" || command === "--help" || command === "-h") {
         printHelp();
         return;
@@ -1190,8 +1782,28 @@ async function main() {
     printHelp();
     process.exit(1);
 }
-main().catch((err) => {
-    console.error("Fatal error:", err);
-    process.exit(1);
-});
+/**
+ * True when this module is the process entrypoint. `process.argv[1]` is the
+ * path as invoked, which for a global install is the `ace` bin symlink, so both
+ * sides are realpath'd before comparison. Guarding the `main()` call keeps the
+ * module importable (tests exercise `positionalArgs` directly) instead of
+ * running the CLI as an import side effect.
+ */
+function isCliEntrypoint() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isCliEntrypoint()) {
+    main().catch((err) => {
+        console.error("Fatal error:", err);
+        process.exit(1);
+    });
+}
 //# sourceMappingURL=cli.js.map