@voybio/ace-swarm 0.2.0 → 0.2.1

package/README.md

@@ -2,9 +2,9 @@
 
 Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted coding.
 
-`ace-swarm` gives Claude Code, Codex, Cursor, VS Code, and local-model workflows a shared runtime: durable workspace state, typed handoffs, scheduler primitives, change intelligence, and operator tooling. All state lives in a single binary file — `.agents/ACE/ace-state.ace` — so the workspace keeps one source of truth instead of a forest of generated state files.
+`ace-swarm` provides Claude Code, Codex, Cursor, VS Code, and local-model workflows with a shared runtime: durable workspace state, typed handoffs, scheduler support, change intelligence, and operator tooling. All state lives in a single binary file — `.agents/ACE/ace-state.ace` — so the workspace keeps one source of truth instead of a forest of generated state files.
 
-Modern coding agents can already read files, write code, run commands, and call tools. The missing layer is coordination that survives restarts, model switches, and multi-agent work. ACE fills that gap by keeping the workflow in the store and projecting only the few files external clients still need. For local models, ACE provides the eyes and ears they usually lack: task context, tool surfaces, status events, evidence trails, and resumable state.
+Modern coding agents can already read files, write code, run commands, and call tools. The missing layer is coordination that survives restarts, model switches, and multi-agent work. ACE keeps the workflow in the store and projects only the files external clients still need. For local models, ACE provides task context, tool surfaces, status events, evidence trails, and resumable state.
 
 ## ACE Manifesto
 
@@ -16,7 +16,7 @@ Modern coding agents can already read files, write code, run commands, and call
 
 ### Serving local models
 
-ACE is the eyes and ears for local models. It gives them the context they cannot infer on their own: task state, tool surfaces, status events, evidence trails, and the next move in the loop.
+ACE provides local models with the context they cannot infer on their own: task state, tool surfaces, status events, evidence trails, and the next move in the loop.
 
 - `ace init --llm ollama` or `ace init --llm llama.cpp` records a local runtime profile in the store.
 - `ace doctor` discovers the endpoint, checks the selected model, and keeps the runtime honest.
@@ -31,7 +31,9 @@ Frontier models are getting more capable and more restricted at the same time. P
 - Ollama and llama.cpp keep local models in play.
 - MCP remains the common protocol surface across clients and runtimes.
 
-ACE sits underneath that stack. It does not compete with the host you already use. It gives that host a durable local runtime.
+ACE sits underneath that stack. It does not compete with the host you already use. It provides that host with a durable local runtime.
+
+ACE also provides scheduler primitives for queued work, dependency gates, leases, and resource locks so multi-agent runs stay coordinated.
 
 ## ACEPACK State Model
 
@@ -175,18 +177,16 @@ Developer or MCP host
 +----------------------+--------------------------------------------------------------+
 | Surface              | Current scope                                                |
 +----------------------+--------------------------------------------------------------+
-| Runtime roles        | 17 runtime roles: 4 swarm roles + 13 composable roles        |
-| Skills               | 15 packaged skills                                           |
-| MCP server           | stdio server for tools, prompts, resources, and workflows    |
-| Durable state        | single .ace authority for handoffs, status events, todo      |
-|                      | state, run ledger, job queue, and discovery                  |
-| Projections          | hook context, todo surface, and host configs when needed      |
-| Coordination         | priority dispatch, dependency gates, leases, resource locks  |
+| Runtime roles        | swarm and composable runtime roles                           |
+| Skills               | packaged skills                                              |
+| MCP server           | stdio surface for tools, prompts, resources, and workflows   |
+| Durable state        | single .ace authority for handoffs, status events, todos, run ledger, job queue, and discovery |
+| Projections          | hook context, todo surface, and host config bundles          |
+| Coordination         | scheduler queues, dependency gates, leases, and resource locks |
 | Change intelligence  | delta scan, semantic snapshots, drift reports, rewrite hints |
-| Terminal UI          | provider-aware TUI with chat, tabs, telemetry, agent tabs    |
-| Local models         | Ollama and llama.cpp bootstrap, doctor checks, model bridge, |
-|                      | tool loops                                                   |
-| Verification         | 242 tests passing in the current suite                       |
+| Terminal UI          | provider-aware TUI with chat, tabs, telemetry, and agent UI  |
+| Local models         | Ollama and llama.cpp bootstrap, doctor checks, and bridges   |
+| Verification         | automated test suite and regression coverage                 |
 +----------------------+--------------------------------------------------------------+
 ```
 

package/assets/agent-state/EVIDENCE_LOG.md

@@ -4,4 +4,4 @@ Append-only chain-of-custody for checks, decisions, and execution proofs.
 
 ## Entries
 
-- 2026-03-03T00:00:00Z | bootstrap initialized | evidence_ref: `EVIDENCE_LOG.md#ts:2026-03-03T00:00:00Z`
+- {{BOOTSTRAP_TIMESTAMP}} | bootstrap initialized | evidence_ref: `EVIDENCE_LOG.md#ts:{{BOOTSTRAP_TIMESTAMP}}`

package/assets/agent-state/STATUS.md

@@ -1,8 +1,8 @@
 # STATUS
 
-- Current role: `capability-skeptic`
+- Current role: `ace-orchestrator`
 - Current phase: `STATE_ANALYSIS`
 - Active pipeline: `standard`
 - Blockers: `none`
 - Current objective delta: `bootstrap complete, awaiting first scoped objective`
-- Last update: `2026-03-03T00:00:00Z`
+- Last update: `{{BOOTSTRAP_TIMESTAMP}}`

package/dist/ace-autonomy.js

@@ -1,7 +1,8 @@
-import { safeRead, wsPath } from "./helpers.js";
+import { resolveWorkspaceRoot, safeRead, wsPath } from "./helpers.js";
 import { readRunLedger } from "./run-ledger.js";
 import { isReadError } from "./shared.js";
 import { readStatusEvents } from "./status-events.js";
+import { getWorkspaceStorePath, readStoreJsonSync, storeExistsSync, toVirtualStorePath, } from "./store/store-snapshot.js";
 export const ACE_TASK_CONTRACT_FILES = [
     "agent-state/TASK.md",
     "agent-state/SCOPE.md",
@@ -102,6 +103,27 @@ function readStringArray(value) {
     return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
 }
 function loadSnapshotIndex() {
+    const workspaceRoot = resolveWorkspaceRoot();
+    if (storeExistsSync(workspaceRoot)) {
+        const storeIndex = readStoreJsonSync(workspaceRoot, "state/memory/context_snapshots/index.json");
+        const snapshots = Array.isArray(storeIndex?.snapshots) ? storeIndex.snapshots : undefined;
+        if (snapshots) {
+            return {
+                snapshots: snapshots
+                    .map((entry) => {
+                    const item = coerceObject(entry);
+                    const name = readString(item?.name);
+                    const file = readString(item?.file);
+                    const timestamp = readString(item?.timestamp);
+                    const summary = readString(item?.summary);
+                    if (!name || !file || !timestamp || !summary)
+                        return undefined;
+                    return { name, file, timestamp, summary };
+                })
+                    .filter((entry) => Boolean(entry)),
+            };
+        }
+    }
     const raw = safeRead("agent-state/context-snapshots/index.json");
     if (isReadError(raw))
         return undefined;
@@ -240,6 +262,21 @@ export function readAceContextSnapshot(name) {
         : index.snapshots[0];
     if (!selected)
         return undefined;
+    const workspaceRoot = resolveWorkspaceRoot();
+    if (storeExistsSync(workspaceRoot)) {
+        const storePath = getWorkspaceStorePath(workspaceRoot);
+        const key = `state/memory/context_snapshots/${selected.file}`;
+        const record = readStoreJsonSync(workspaceRoot, key);
+        if (record) {
+            return {
+                name: selected.name,
+                timestamp: selected.timestamp,
+                summary: selected.summary,
+                path: toVirtualStorePath(storePath, key),
+                content: clipText(JSON.stringify(record, null, 2), 1200),
+            };
+        }
+    }
     const relPath = wsPath("agent-state", "context-snapshots", selected.file);
     const content = safeRead(relPath);
     if (isReadError(content))

package/dist/ace-context.js

@@ -5,7 +5,9 @@ import { readRuntimeProfileState, renderRuntimePrompt } from "./runtime-profile.
 const ROLE_TOOL_DEFAULTS = {
     orchestrator: [
         "recall_context",
+        "validate_framework",
         "route_task",
+        "run_orchestrator",
         "run_local_model",
         "get_vericify_context",
         "get_vericify_delta",
@@ -221,6 +223,12 @@ export function renderAceContext(options) {
         "## Tool Scope",
         toolCatalog || "- No ACE tools available.",
         "",
+        "## Compact Guardrails",
+        "- Stop if you are about to claim tested, verified, or passed without evidence.",
+        "- If ACE state is thin or contradictory, call recall_context or validate_framework before improvising.",
+        "- For obviously multi-step work, prefer run_orchestrator over a single free-form answer.",
+        "- Do not declare completion while approval, retry, or blocker state remains active.",
+        "",
         "## Output Contract",
         'Respond in JSON only with one of these shapes:',
         '- `{"status":"tool","thinking":"...","tool_calls":[{"tool":"name","input":{}}]}`',

package/dist/ace-server-instructions.js

@@ -1,18 +1,19 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { readAceLogicalFile, resolveAceLogicalPath, resolveAceStateLayout, } from "./ace-state-resolver.js";
 const ACE_ROOT_REL = ".agents/ACE";
 const CORE_FILES = [
-    `${ACE_ROOT_REL}/agent-state/TASK.md`,
-    `${ACE_ROOT_REL}/agent-state/STATUS.md`,
-    `${ACE_ROOT_REL}/agent-state/SCOPE.md`,
-    `${ACE_ROOT_REL}/agent-state/EVIDENCE_LOG.md`,
+    "agent-state/TASK.md",
+    "agent-state/STATUS.md",
+    "agent-state/SCOPE.md",
+    "agent-state/EVIDENCE_LOG.md",
 ];
 const STATE_DIRS = [
-    `${ACE_ROOT_REL}/agent-state`,
-    `${ACE_ROOT_REL}/global-state`,
-    `${ACE_ROOT_REL}/venture-state`,
-    `${ACE_ROOT_REL}/brand-state`,
-    `${ACE_ROOT_REL}/engineering-state`,
+    "agent-state",
+    "global-state",
+    "venture-state",
+    "brand-state",
+    "engineering-state",
 ];
 const BOOTSTRAP_TOOLS = new Set([
     "bootstrap_state",
@@ -81,6 +82,17 @@ function truncate(input, max = 140) {
     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`
@@ -97,11 +109,33 @@ function resolveWorkspacePath(workspaceRoot, relativePath) {
     }
     return canonicalPath;
 }
+function displayWorkspacePath(workspaceRoot, relativePath) {
+    if (relativePath === "agent-state" || relativePath.startsWith("agent-state/")) {
+        return 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 (existsSync(canonicalPath)) {
+        return canonicalRel;
+    }
+    if (canonicalRel !== relativePath && existsSync(resolve(workspaceRoot, relativePath))) {
+        return relativePath;
+    }
+    return canonicalRel;
+}
 function listExistingCoreFiles(workspaceRoot) {
-    return CORE_FILES.filter((relativePath) => existsSync(resolveWorkspacePath(workspaceRoot, relativePath)));
+    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)));
+    return STATE_DIRS.filter((relativePath) => existsSync(resolveWorkspacePath(workspaceRoot, relativePath)))
+        .map((relativePath) => displayWorkspacePath(workspaceRoot, relativePath));
 }
 function extractObjective(taskRaw) {
     if (!taskRaw)
@@ -125,7 +159,7 @@ function extractStatusValue(statusRaw, label) {
     return match?.[1] ? truncate(oneLine(match[1])) : undefined;
 }
 function extractAutonomyHint(workspaceRoot) {
-    const workflowRaw = readIfPresent(resolveWorkspacePath(workspaceRoot, "agent-state/ACE_WORKFLOW.md"));
+    const workflowRaw = readAceLogicalFile(workspaceRoot, "agent-state/ACE_WORKFLOW.md");
     if (!workflowRaw)
         return undefined;
     const hints = [];
@@ -142,8 +176,8 @@ function extractAutonomyHint(workspaceRoot) {
     return hints.length > 0 ? hints.join(", ") : undefined;
 }
 export function buildAceDigest(workspaceRoot) {
-    const taskRaw = readIfPresent(resolveWorkspacePath(workspaceRoot, "agent-state/TASK.md"));
-    const statusRaw = readIfPresent(resolveWorkspacePath(workspaceRoot, "agent-state/STATUS.md"));
+    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");
@@ -187,7 +221,7 @@ export function buildHostInstructionText(host, workspaceRoot) {
         `# ACE Bootstrap For ${hostLabel}`,
         "",
         "This is a thin ACE bootstrap stub.",
-        "Full instructions, skills, task packs, and runtime state live inside `.agents/ACE/ace-state.ace` and should be accessed through the ACE MCP server.",
+        "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 from ACE state.",
@@ -195,7 +229,8 @@ export function buildHostInstructionText(host, workspaceRoot) {
         "3. Prefer ACE prompts/resources (`ace-orchestrator`, `get_task_pack`, `get_skill_instructions`) over relying on this file.",
         "",
         "Ground truth:",
-        "- `.agents/ACE/ace-state.ace` is authoritative.",
+        "- `agent-state/*` is the logical state surface; the resolver reads it from top-level, nested, or store-backed layouts.",
+        "- `.agents/ACE/ace-state.ace` remains the canonical store-backed projection when that layout is used.",
         "- `.agents/ACE/tasks/todo.md` is the human-facing todo surface.",
         "- `.agents/ACE/ace-hook-context.json` is the compact hook snapshot.",
         "",
@@ -216,9 +251,10 @@ export function buildBootstrapGuidance(workspaceRoot, toolName) {
     return `ACE context loaded via \`${toolName}\`. Current digest: ${buildAceDigest(workspaceRoot)}.`;
 }
 export function buildMutationGuidance(workspaceRoot, toolName) {
+    const evidencePath = displayWorkspacePath(workspaceRoot, "agent-state/EVIDENCE_LOG.md");
     return [
         `ACE digest after \`${toolName}\`: ${buildAceDigest(workspaceRoot)}.`,
-        `If this changed code or state, reconcile \`${ACE_ROOT_REL}/agent-state/EVIDENCE_LOG.md\`, run \`execute_gates\` when appropriate, and use structured handoffs/process posts for delegated follow-up.`,
+        `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 buildRefreshGuidance(workspaceRoot, toolName) {
@@ -312,12 +348,12 @@ export function buildHookAdditionalContext(workspaceRoot) {
     return parts.join("\n");
 }
 export function buildScopeReminder(workspaceRoot) {
-    const scopeRaw = readIfPresent(resolveWorkspacePath(workspaceRoot, "agent-state/SCOPE.md"));
+    const scopeRaw = readAceLogicalFile(workspaceRoot, "agent-state/SCOPE.md");
     if (!scopeRaw)
         return undefined;
     const scopeLines = nonEmptyLines(scopeRaw).filter((line) => !line.startsWith("#"));
     if (scopeLines.length === 0) {
-        return `ACE scope reminder: review ${ACE_ROOT_REL}/agent-state/SCOPE.md before mutating files or state.`;
+        return `ACE scope reminder: review ${displayWorkspacePath(workspaceRoot, "agent-state/SCOPE.md")} before mutating files or state.`;
     }
     return `ACE scope reminder: ${truncate(oneLine(scopeLines.slice(0, 4).join(" ")), 220)}`;
 }

package/dist/ace-state-resolver.d.ts

@@ -0,0 +1,18 @@
+export type AcePhysicalMode = "top_level" | "nested_projection" | "store_projection" | "missing";
+export interface AceStateResolution {
+    workspaceRoot: string;
+    logicalStateRoot: "agent-state";
+    physicalMode: AcePhysicalMode;
+    taskPath?: string;
+    statusPath?: string;
+    scopePath?: string;
+    evidencePath?: string;
+    storePath?: string;
+    hookSnapshotPath?: string;
+    isAcePresent: boolean;
+    missingCriticalArtifacts: string[];
+}
+export declare function readAceLogicalFile(workspaceRoot: string, relativePath: string): string | undefined;
+export declare function resolveAceLogicalPath(workspaceRoot: string, relativePath: string): string | undefined;
+export declare function resolveAceStateLayout(workspaceRoot: string): AceStateResolution;
+//# sourceMappingURL=ace-state-resolver.d.ts.map

package/dist/ace-state-resolver.js

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { getWorkspaceStorePath, readStoreBlobSync, toVirtualStorePath } from "./store/store-snapshot.js";
+import { isOperationalArtifactPath, operationalArtifactKey, } from "./store/store-artifacts.js";
+const CRITICAL_LOGICAL_PATHS = [
+    "agent-state/TASK.md",
+    "agent-state/STATUS.md",
+    "agent-state/SCOPE.md",
+];
+const DISPLAY_LOGICAL_PATHS = [
+    "agent-state/TASK.md",
+    "agent-state/STATUS.md",
+    "agent-state/SCOPE.md",
+    "agent-state/EVIDENCE_LOG.md",
+];
+function workspacePath(root, relativePath) {
+    return resolve(root, relativePath);
+}
+function nestedAcePath(root, relativePath) {
+    return resolve(root, ".agents", "ACE", relativePath);
+}
+function readFileIfPresent(filePath) {
+    if (!existsSync(filePath))
+        return undefined;
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function storeFallbackKeys(relativePath) {
+    const keys = [];
+    if (isOperationalArtifactPath(relativePath)) {
+        keys.push(operationalArtifactKey(relativePath));
+    }
+    keys.push(`knowledge/${relativePath}`);
+    return keys;
+}
+export function readAceLogicalFile(workspaceRoot, relativePath) {
+    const direct = readFileIfPresent(workspacePath(workspaceRoot, relativePath));
+    if (direct !== undefined)
+        return direct;
+    const nested = readFileIfPresent(nestedAcePath(workspaceRoot, relativePath));
+    if (nested !== undefined)
+        return nested;
+    for (const key of storeFallbackKeys(relativePath)) {
+        const storeValue = readStoreBlobSync(workspaceRoot, key);
+        if (typeof storeValue === "string")
+            return storeValue;
+    }
+    return undefined;
+}
+export function resolveAceLogicalPath(workspaceRoot, relativePath) {
+    const direct = workspacePath(workspaceRoot, relativePath);
+    if (existsSync(direct))
+        return direct;
+    const nested = nestedAcePath(workspaceRoot, relativePath);
+    if (existsSync(nested))
+        return nested;
+    const storePath = getWorkspaceStorePath(workspaceRoot);
+    if (!existsSync(storePath))
+        return undefined;
+    for (const key of storeFallbackKeys(relativePath)) {
+        if (typeof readStoreBlobSync(workspaceRoot, key) === "string") {
+            return toVirtualStorePath(storePath, key);
+        }
+    }
+    return undefined;
+}
+export function resolveAceStateLayout(workspaceRoot) {
+    const storePath = getWorkspaceStorePath(workspaceRoot);
+    const nestedStateDir = nestedAcePath(workspaceRoot, "agent-state");
+    const topLevelStateDir = workspacePath(workspaceRoot, "agent-state");
+    const topLevelPresent = DISPLAY_LOGICAL_PATHS.some((relativePath) => existsSync(workspacePath(workspaceRoot, relativePath)));
+    const nestedPresent = DISPLAY_LOGICAL_PATHS.some((relativePath) => existsSync(nestedAcePath(workspaceRoot, relativePath)));
+    const storePresent = existsSync(storePath);
+    let physicalMode = "missing";
+    if (topLevelPresent || existsSync(topLevelStateDir)) {
+        physicalMode = "top_level";
+    }
+    else if (nestedPresent || existsSync(nestedStateDir)) {
+        physicalMode = "nested_projection";
+    }
+    else if (storePresent) {
+        physicalMode = "store_projection";
+    }
+    const missingCriticalArtifacts = CRITICAL_LOGICAL_PATHS.filter((relativePath) => typeof readAceLogicalFile(workspaceRoot, relativePath) !== "string");
+    return {
+        workspaceRoot,
+        logicalStateRoot: "agent-state",
+        physicalMode,
+        taskPath: resolveAceLogicalPath(workspaceRoot, "agent-state/TASK.md"),
+        statusPath: resolveAceLogicalPath(workspaceRoot, "agent-state/STATUS.md"),
+        scopePath: resolveAceLogicalPath(workspaceRoot, "agent-state/SCOPE.md"),
+        evidencePath: resolveAceLogicalPath(workspaceRoot, "agent-state/EVIDENCE_LOG.md"),
+        storePath: storePresent ? storePath : undefined,
+        hookSnapshotPath: existsSync(nestedAcePath(workspaceRoot, "ace-hook-context.json"))
+            ? nestedAcePath(workspaceRoot, "ace-hook-context.json")
+            : undefined,
+        isAcePresent: physicalMode !== "missing" ||
+            CRITICAL_LOGICAL_PATHS.some((relativePath) => typeof readAceLogicalFile(workspaceRoot, relativePath) === "string"),
+        missingCriticalArtifacts,
+    };
+}
+//# sourceMappingURL=ace-state-resolver.js.map

package/dist/cli.js

@@ -6,8 +6,10 @@ import { startStdioServer } from "./server.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { waitForPendingStatusEventMirrors } from "./status-events.js";
 import { bootstrapStoreWorkspace } from "./store/bootstrap-store.js";
+import { HostFileMaterializer } from "./store/materializers/host-file-materializer.js";
 import { openStore } from "./store/ace-packed-store.js";
 import { withStoreWriteQueue } from "./store/write-queue.js";
+import { DiscoveryRepository } from "./store/repositories/discovery-repository.js";
 import { getWorkspaceStorePath, readStoreBlobSync, readStoreJsonSync, } from "./store/store-snapshot.js";
 import { readFileSync } from "node:fs";
 import { runTui } from "./tui/index.js";
@@ -23,6 +25,7 @@ Usage:
   ace turnkey [options]        Project minimal workspace bootstrap stubs from the ACE store
   ace doctor [options]         Validate local LLM + MCP readiness
   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
 
@@ -52,6 +55,9 @@ Options for doctor:
 Options for mcp-config:
   --client <name>              codex|vscode|claude|cursor|antigravity
   --all                        Print all client snippets for optional global install
+
+preconfig writes .mcp-config/ at the workspace root with ready-to-use config files for every
+supported MCP client. Run once after ace init. Each file includes the install hint for its client.
 `);
 }
 function readFlagValue(args, flag) {
@@ -152,6 +158,33 @@ async function writeLlmProfile(profile) {
     });
     return `${storePath}#state/runtime/llm_profile`;
 }
+async function recordDiscoveryProfile(input) {
+    const storePath = getWorkspaceStorePath(WORKSPACE_ROOT);
+    await withStoreWriteQueue(storePath, async () => {
+        const store = await openStore(storePath);
+        try {
+            const discovery = new DiscoveryRepository(store);
+            await discovery.record({
+                provider: input.provider,
+                available: input.available,
+                endpoint: input.baseUrl,
+                models: input.models,
+                metadata: input.selectedModel
+                    ? {
+                        profile_model: input.selectedModel,
+                        runtime_kind: "local",
+                    }
+                    : {
+                        runtime_kind: "local",
+                    },
+            });
+            await store.commit();
+        }
+        finally {
+            await store.close();
+        }
+    });
+}
 async function runInit(args, mode = "init") {
     const projectName = readFlagValue(args, "--project");
     const force = args.includes("--force");
@@ -400,6 +433,13 @@ async function runDoctor(args) {
         });
     }
     const hasModel = modelNames.includes(model);
+    await recordDiscoveryProfile({
+        provider,
+        baseUrl,
+        models: modelNames,
+        selectedModel: model,
+        available: modelNames.length > 0,
+    });
     checks.push({
         name: provider === "ollama" ? "Requested model installed" : "Requested model served",
         ok: hasModel,
@@ -437,6 +477,29 @@ function parseClientFlag(args) {
     }
     return match;
 }
+async function runPreconfig() {
+    const storePath = wsPath(".agents", "ACE", "ace-state.ace");
+    if (!fileExists(storePath)) {
+        console.error(`No ACE store found at ${storePath}. Run 'ace init' first.`);
+        process.exit(1);
+    }
+    const store = await openStore(storePath);
+    try {
+        const mat = new HostFileMaterializer(store, WORKSPACE_ROOT);
+        const written = await mat.materializeMcpBundle();
+        console.log(`ACE preconfig complete — wrote ${written.length} files to .mcp-config/\n`);
+        for (const p of written) {
+            console.log(`  ${p}`);
+        }
+        console.log("\nInstall hints:");
+        for (const client of ALL_MCP_CLIENTS) {
+            console.log(`  ${client}: ${getMcpClientInstallHint(client)}`);
+        }
+    }
+    finally {
+        await store.close();
+    }
+}
 async function runMcpConfig(args) {
     const all = args.includes("--all");
     const explicitClient = parseClientFlag(args);
@@ -504,6 +567,10 @@ async function main() {
         await runMcpConfig(args.slice(1));
         return;
     }
+    if (command === "preconfig") {
+        await runPreconfig();
+        return;
+    }
     if (command === "paths") {
         console.log(`PACKAGE_ROOT=${PACKAGE_ROOT}`);
         console.log(`DEFAULTS_ROOT=${DEFAULTS_ROOT}`);

package/dist/handoff-registry.js

@@ -1,10 +1,12 @@
 import { resolveWorkspaceRoot, safeRead, safeWrite, wsPath, withFileLock } from "./helpers.js";
 import { isReadError } from "./shared.js";
 import { openStore } from "./store/ace-packed-store.js";
-import { VericifyProjector } from "./store/materializers/vericify-projector.js";
+import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { HandoffRepository } from "./store/repositories/handoff-repository.js";
 import { getWorkspaceStorePath, listStoreKeysSync, readStoreJsonSync, storeExistsSync, } from "./store/store-snapshot.js";
 import { withStoreWriteQueue } from "./store/write-queue.js";
+import { waitForPendingStatusEventMirrors } from "./status-events.js";
+import { waitForTodoStoreMirror } from "./todo-state.js";
 const HANDOFF_REGISTRY_REL = "agent-state/handoff-registry.json";
 function workspaceRoot() {
     return resolveWorkspaceRoot();
@@ -291,6 +293,8 @@ export function getHandoffRegistryPath() {
 export async function registerHandoffSafe(input) {
     const root = workspaceRoot();
     const storePath = getWorkspaceStorePath(root);
+    await waitForTodoStoreMirror();
+    await waitForPendingStatusEventMirrors();
     if (!storeExistsSync(root)) {
         return withFileLock(HANDOFF_REGISTRY_REL, () => registerHandoff(input));
     }
@@ -332,9 +336,8 @@ export async function registerHandoffSafe(input) {
                     },
                 });
                 await store.commit();
-                const projector = new VericifyProjector(store, root);
-                await projector.projectHandoffs();
-                await store.commit();
+                const projections = new ProjectionManager(store, root);
+                await projections.projectAfterCommit(["handoffs"]);
                 return {
                     record: toLegacyHandoffRecord(record),
                     path: wsPath(HANDOFF_REGISTRY_REL),
@@ -352,6 +355,8 @@ export async function registerHandoffSafe(input) {
 export async function acknowledgeHandoffSafe(input) {
     const root = workspaceRoot();
     const storePath = getWorkspaceStorePath(root);
+    await waitForTodoStoreMirror();
+    await waitForPendingStatusEventMirrors();
     if (!storeExistsSync(root)) {
         return withFileLock(HANDOFF_REGISTRY_REL, () => acknowledgeHandoff(input));
     }
@@ -403,9 +408,8 @@ export async function acknowledgeHandoffSafe(input) {
                     },
                 });
                 await store.commit();
-                const projector = new VericifyProjector(store, root);
-                await projector.projectHandoffs();
-                await store.commit();
+                const projections = new ProjectionManager(store, root);
+                await projections.projectAfterCommit(["handoffs"]);
                 return {
                     ok: true,
                     path,