@voybio/ace-swarm 0.2.4 → 2.4.0

package/assets/scripts/ace-hook-dispatch.mjs

@@ -28,6 +28,9 @@ const ACE_CORE_FILES = [
   "agent-state/SCOPE.md",
   "agent-state/EVIDENCE_LOG.md",
 ];
+const STORE_MAGIC = "ACEPACK1";
+const STORE_HEADER_SIZE = 32;
+const HOOK_CONTEXT_STORE_KEY = "state/runtime/hook_context";
 
 const PROTECTED_PATH_FRAGMENTS = [
   ".github/hooks/",
@@ -114,9 +117,61 @@ function resolveAcePath(workspaceRoot, relativePath) {
   return canonical;
 }
 
+function getWorkspaceStorePath(workspaceRoot) {
+  const canonical = resolve(workspaceRoot, "agent-state", "ace-state.ace");
+  if (existsSync(canonical)) return canonical;
+  return resolve(workspaceRoot, ACE_ROOT, "ace-state.ace");
+}
+
+function readStoreUint64(buffer, offset) {
+  return buffer.readUInt32BE(offset) * 2 ** 32 + buffer.readUInt32BE(offset + 4);
+}
+
+function readStoreBlob(workspaceRoot, key) {
+  const storePath = getWorkspaceStorePath(workspaceRoot);
+  if (!existsSync(storePath)) return undefined;
+  try {
+    const file = readFileSync(storePath);
+    if (file.length < STORE_HEADER_SIZE) return undefined;
+    if (file.subarray(0, 8).toString("utf8") !== STORE_MAGIC) return undefined;
+    const indexOffset = readStoreUint64(file, 16);
+    const indexLength = readStoreUint64(file, 24);
+    const index = JSON.parse(file.subarray(indexOffset, indexOffset + indexLength).toString("utf8"));
+    const entry = index?.[key];
+    if (!entry || typeof entry.offset !== "number" || typeof entry.length !== "number") {
+      return undefined;
+    }
+    const start = entry.offset + 4;
+    const end = start + entry.length;
+    return file.subarray(start, end).toString("utf8");
+  } catch {
+    return undefined;
+  }
+}
+
 function readIfPresent(workspaceRoot, relativePath) {
   const absolute = resolveAcePath(workspaceRoot, relativePath);
-  if (!existsSync(absolute)) return undefined;
+  if (!existsSync(absolute)) {
+    const normalized = String(relativePath).replace(/\\/g, "/").replace(/^\.?\//, "");
+    const logicalPath = normalized.startsWith(`${ACE_ROOT}/`)
+      ? normalized.slice(`${ACE_ROOT}/`.length)
+      : normalized;
+    const rel = logicalPath.startsWith("agent-state/") ? logicalPath.slice("agent-state/".length) : "";
+    const keys = [];
+    if (rel) {
+      keys.push(`state/artifacts/agent-state/${rel}`);
+      keys.push(`knowledge/agent-state/${rel}`);
+      if (rel === "ACE_WORKFLOW.md") {
+        keys.unshift("knowledge/runtime/ACE_WORKFLOW.md");
+        keys.push("knowledge/kernel/ACE_WORKFLOW.md");
+      }
+    }
+    for (const key of keys) {
+      const blob = readStoreBlob(workspaceRoot, key);
+      if (typeof blob === "string") return blob;
+    }
+    return undefined;
+  }
   try {
     return readFileSync(absolute, "utf8");
   } catch {
@@ -203,12 +258,19 @@ function buildRoleToolHint(role) {
 }
 
 /**
- * Try to read the store-materialized hook context snapshot.
+ * Try to read the store-backed hook context snapshot.
  * Returns the parsed snapshot or undefined if not present / unreadable.
- * When present this is the single authoritative source; the dispatcher
- * never needs to open the .ace store directly.
  */
 function tryReadHookContextSnapshot(workspaceRoot) {
+  const storeRaw = readStoreBlob(workspaceRoot, HOOK_CONTEXT_STORE_KEY);
+  if (typeof storeRaw === "string") {
+    try {
+      const parsed = JSON.parse(storeRaw);
+      if (parsed?.schema_version === 1) return parsed;
+    } catch {
+      // Fall through to legacy file compatibility.
+    }
+  }
   const snapshotPath = resolve(workspaceRoot, ACE_ROOT, "ace-hook-context.json");
   if (!existsSync(snapshotPath)) return undefined;
   try {
@@ -222,7 +284,7 @@ function tryReadHookContextSnapshot(workspaceRoot) {
 }
 
 function aceContext(workspaceRoot) {
-  // ── Fast path: store-materialized snapshot ──────────────────────────────
+  // ── Fast path: store-backed snapshot ────────────────────────────────────
   const snapshot = tryReadHookContextSnapshot(workspaceRoot);
   if (snapshot) {
     const taskObjective = snapshot.task?.content
@@ -233,7 +295,9 @@ function aceContext(workspaceRoot) {
     const scopeReminder = scopeLines.length
       ? `ACE scope reminder: ${truncate(scopeLines.slice(0, 4).join(" "), 220)}`
       : undefined;
-    const hasAgentState = existsSync(resolve(workspaceRoot, ACE_ROOT, "agent-state"));
+    const hasAgentState =
+      existsSync(resolve(workspaceRoot, ACE_ROOT, "agent-state")) ||
+      existsSync(resolve(workspaceRoot, "agent-state", "ace-state.ace"));
     const hasSkills = existsSync(resolve(workspaceRoot, ACE_ROOT, "skills")) ||
       existsSync(resolve(workspaceRoot, ".agents", "skills"));
     return {

package/assets/scripts/render-mcp-configs.sh

@@ -12,6 +12,9 @@ CURSOR_DIR="${ACE_ROOT}/.cursor"
 VSCODE_DIR="${ACE_ROOT}/.vscode"
 HOOK_COMMAND="node ./.agents/ACE/scripts/ace/ace-hook-dispatch.mjs"
 HOOK_COMMAND_WINDOWS="node .\\\\.agents\\\\ACE\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs"
+NODE_BIN_DIR="$(dirname -- "$(command -v node)")"
+CLI_ENTRY="${WORKSPACE_ROOT}/dist/cli.js"
+MCP_LAUNCH="export PATH=\"${NODE_BIN_DIR}:\$PATH\" && if ! command -v node >/dev/null 2>&1; then [ -s \"\$HOME/.zprofile\" ] && . \"\$HOME/.zprofile\"; [ -s \"\$HOME/.zshrc\" ] && . \"\$HOME/.zshrc\"; fi && cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" node \"${CLI_ENTRY}\" mcp"
 
 mkdir -p "${MCP_CONFIG_DIR}"
 mkdir -p "${GITHUB_DIR}/hooks"
@@ -25,7 +28,18 @@ cat > "${MCP_CONFIG_DIR}/vscode.mcp.json" <<JSON
     "ace-swarm": {
       "type": "stdio",
       "command": "/bin/zsh",
-      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+      "args": ["-lc", "${MCP_LAUNCH}"]
+    }
+  }
+}
+JSON
+
+cat > "${WORKSPACE_ROOT}/.mcp.json" <<JSON
+{
+  "mcpServers": {
+    "ace-swarm": {
+      "command": "/bin/zsh",
+      "args": ["-lc", "${MCP_LAUNCH}"]
     }
   }
 }
@@ -36,7 +50,7 @@ cat > "${MCP_CONFIG_DIR}/cursor.mcp.json" <<JSON
   "mcpServers": {
     "ace-swarm": {
       "command": "/bin/zsh",
-      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+      "args": ["-lc", "${MCP_LAUNCH}"]
     }
   }
 }
@@ -47,7 +61,7 @@ cat > "${MCP_CONFIG_DIR}/claude_desktop_config.json" <<JSON
   "mcpServers": {
     "ace-swarm": {
       "command": "/bin/zsh",
-      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+      "args": ["-lc", "${MCP_LAUNCH}"]
     }
   }
 }
@@ -58,7 +72,7 @@ cat > "${MCP_CONFIG_DIR}/antigravity.mcp.json" <<JSON
   "mcpServers": {
     "ace-swarm": {
       "command": "/bin/zsh",
-      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+      "args": ["-lc", "${MCP_LAUNCH}"]
     }
   }
 }
@@ -68,7 +82,7 @@ cat > "${MCP_CONFIG_DIR}/codex.config.toml" <<TOML
 # ACE instructions are scaffolded into .agents/ACE/AGENTS.md during bootstrap.
 [mcp_servers.ace-swarm]
 command = "/bin/zsh"
-args = ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+args = ["-lc", "${MCP_LAUNCH}"]
 TOML
 
 cat > "${ACE_ROOT}/CLAUDE.md" <<MD

package/dist/ace-context.js

@@ -1,6 +1,6 @@
 import { buildAceContinuityPacket, buildAceRecallContext, formatAceContinuityPacketMarkdown, formatAceRecallMarkdown, normalizeAutonomyPolicy, normalizeContinuityPolicy, } from "./ace-autonomy.js";
 import { listAceInternalToolCatalog, } from "./ace-internal-tools.js";
-import { ALL_AGENTS, readAgentInstructions } from "./helpers.js";
+import { ALL_AGENTS, listAvailableSkills, readAgentInstructions } from "./helpers.js";
 import { readRuntimeProfileState, renderRuntimePrompt } from "./runtime-profile.js";
 const ROLE_TOOL_DEFAULTS = {
     orchestrator: [
@@ -156,6 +156,23 @@ function buildPlanningCatalog(role, task, tier) {
         .slice(0, limit)
         .map((entry) => entry.tool);
 }
+function inferRelevantSkills(task) {
+    const lowered = task.toLowerCase();
+    const skillSignals = [
+        { name: "state-auditor", pattern: /\b(state|drift|authority|audit)\b/ },
+        { name: "handoff-lint", pattern: /\b(handoff|transition|payload)\b/ },
+        { name: "schema-forge", pattern: /\b(schema|contract|interface)\b/ },
+        { name: "release-sentry", pattern: /\b(ship|release|promotion|rollback)\b/ },
+        { name: "risk-quant", pattern: /\b(risk|blocker|severity)\b/ },
+        { name: "eval-harness", pattern: /\b(eval|regression|verify|validation)\b/ },
+        { name: "incident-commander", pattern: /\b(incident|outage|blocker storm)\b/ },
+        { name: "problem-triage", pattern: /\b(triage|classify|scope)\b/ },
+    ];
+    const available = new Set(listAvailableSkills().map((skill) => skill.name));
+    return skillSignals
+        .filter((signal) => signal.pattern.test(lowered) && available.has(signal.name))
+        .map((signal) => signal.name);
+}
 export function buildToolPlan(options) {
     const tier = options.tier ?? "compressed";
     const catalog = Array.isArray(options.tools) && options.tools.length > 0
@@ -211,6 +228,7 @@ export function renderAceContext(options) {
     const roleInstructions = resolveRoleInstructions(options.role);
     const toolCatalog = renderToolCatalogMarkdown(tools, tier);
     const stateDigest = recall.task_contract.summary;
+    const relevantSkills = inferRelevantSkills(options.task);
     const systemPrompt = [
         runtimePrompt,
         "",
@@ -223,6 +241,9 @@ export function renderAceContext(options) {
         "## Tool Scope",
         toolCatalog || "- No ACE tools available.",
         "",
+        "## Relevant Skills",
+        relevantSkills.length > 0 ? `- ${relevantSkills.join(", ")}` : "- No task-specific skill hint matched.",
+        "",
         "## 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.",

package/dist/ace-server-instructions.js

@@ -229,10 +229,10 @@ 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:",
-        "- `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.",
+        "- `agent-state/*` is the visible runtime state surface for this workspace.",
+        "- `agent-state/ace-state.ace` is the canonical store path; legacy nested store layouts are compatibility fallback only.",
         "- `.agents/ACE/tasks/todo.md` is the human-facing todo surface.",
-        "- `.agents/ACE/ace-hook-context.json` is the compact hook snapshot.",
+        "- Hook context is store-backed in `agent-state/ace-state.ace` and consumed without extra workspace projections.",
         "",
         `Workspace digest hint: ${buildAceDigest(workspaceRoot)}.`,
     ].join("\n");

package/dist/ace-state-resolver.js

@@ -95,9 +95,11 @@ export function resolveAceStateLayout(workspaceRoot) {
         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,
+        hookSnapshotPath: readStoreBlobSync(workspaceRoot, "state/runtime/hook_context") != null
+            ? toVirtualStorePath(storePath, "state/runtime/hook_context")
+            : 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,

package/dist/astgrep-index.d.ts

@@ -1,3 +1,11 @@
+export interface AstgrepMatch {
+    file: string;
+    line: number;
+    column: number;
+    text: string;
+    context_lines?: string[];
+}
+export declare function runAstgrepQuery(pattern: string, lang: string, roots: string[], _contextLines?: number): AstgrepMatch[];
 export interface RefreshAstgrepIndexInput {
     scope?: string;
     append_evidence?: boolean;
@@ -20,5 +28,5 @@ export interface RefreshAstgrepIndexResult {
         todo_signals: number;
     };
 }
-export declare function refreshAstgrepIndex(input?: RefreshAstgrepIndexInput): RefreshAstgrepIndexResult;
+export declare function refreshAstgrepIndex(input?: RefreshAstgrepIndexInput): Promise<RefreshAstgrepIndexResult>;
 //# sourceMappingURL=astgrep-index.d.ts.map

package/dist/astgrep-index.js

@@ -1,8 +1,19 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
-import { appendStatusEvent } from "./status-events.js";
+import { appendStatusEventSafe } from "./status-events.js";
 import { safeRead, safeWrite, WORKSPACE_ROOT, wsPath } from "./helpers.js";
+export function runAstgrepQuery(pattern, lang, roots, _contextLines) {
+    const cmd = detectAstgrepCommand();
+    const raw = runAstgrep(cmd, pattern, lang, roots);
+    return raw.slice(0, 200).map((m) => ({
+        file: m.file ?? "",
+        line: m.range?.start?.line ?? 0,
+        column: m.range?.start?.column ?? 0,
+        text: m.text ?? "",
+        context_lines: [],
+    }));
+}
 const CODE_EXTENSIONS = new Set(["ts", "tsx", "js", "mjs", "cjs", "py", "rs", "go"]);
 const EXCLUDE_DIRS = new Set([
     ".git",
@@ -180,7 +191,7 @@ function appendEvidenceLine(timestamp, astgrepCmd, stats) {
     ].join("\n");
     safeWrite("agent-state/EVIDENCE_LOG.md", `${seed}${entry}\n`);
 }
-export function refreshAstgrepIndex(input = {}) {
+export async function refreshAstgrepIndex(input = {}) {
     const generatedAt = new Date().toISOString();
     const scope = resolveScope(input.scope);
     const appendEvidence = input.append_evidence ?? true;
@@ -440,7 +451,7 @@ export function refreshAstgrepIndex(input = {}) {
     if (emitEvent) {
         const status = astgrepCmd ? "pass" : "blocked";
         const eventType = astgrepCmd ? "DISCOVERY_INDEX_READY" : "DISCOVERY_SCOPE_BLOCKED";
-        const event = appendStatusEvent({
+        const event = await appendStatusEventSafe({
             source_module: "capability-astgrep",
             event_type: eventType,
             status,

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { ACE_ROOT_REL, 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 { 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 { refreshAstgrepIndex } from "./astgrep-index.js";
 import { scanWorkspaceDelta } from "./index-store.js";
 import { startStdioServer } from "./server.js";
@@ -8,9 +8,10 @@ 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 { withStoreWriteCoordinator } from "./store/write-coordinator.js";
 import { getWorkspaceStorePath, readStoreBlobSync, readStoreJsonSync, } from "./store/store-snapshot.js";
+import { ensureCanonicalWorkspaceStore } from "./store/workspace-store-paths.js";
 import { readFileSync } from "node:fs";
 import { runTui } from "./tui/index.js";
 import { buildOpenAiCompatibleBaseUrl, buildProviderDoctorCommands, defaultModelForProvider, discoverProviderContext, isLocalLlmProvider, normalizeLocalBaseUrl, normalizeProvider, scanLocalModelRuntimes, } from "./tui/provider-discovery.js";
@@ -25,6 +26,7 @@ Usage:
   ace init [options]           Bootstrap the ACE store into current workspace
   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 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
@@ -37,7 +39,7 @@ Options for tui:
   --ollama-url <url>           Legacy alias for --base-url
 
 Options for init:
-  --project <name>             Project name stored in ${ACE_ROOT_REL}/ace-state.ace metadata
+  --project <name>             Project name stored in agent-state/ace-state.ace metadata
   --force                      Overwrite scaffolded files if they already exist
   --mcp-config                 Also write .vscode/mcp.json workspace bridge
   --client-config-bundle       Also write minimal workspace host stubs (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md)
@@ -47,18 +49,23 @@ Options for init:
   --ollama-url <url>           Legacy alias for --base-url
 
 Options for doctor:
-  --llm <provider>             ollama|llama.cpp|codex|claude|gemini|copilot|... (default: auto from ${ACE_ROOT_REL}/ace-state.ace)
+  --llm <provider>             ollama|llama.cpp|codex|claude|gemini|copilot|... (default: auto from agent-state/ace-state.ace)
   --model <name>               Model name override
   --base-url <url>             Runtime base URL override
   --ollama-url <url>           Legacy alias for --base-url
   --scan                       Probe common local Ollama + llama.cpp endpoints when URL is unset
 
+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 mcp-config:
-  --client <name>              codex|vscode|claude|cursor|antigravity
+  --client <name>              codex|vscode|copilot|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.
+supported MCP client plus a root .mcp.json for GitHub Copilot CLI. Run once after ace init.
+Each file includes the install hint for its client.
 `);
 }
 function readFlagValue(args, flag) {
@@ -111,7 +118,7 @@ function parseLlmOptions(args) {
 }
 async function writeLlmProfile(profile) {
     const storePath = getWorkspaceStorePath(WORKSPACE_ROOT);
-    await withStoreWriteQueue(storePath, async () => {
+    await withStoreWriteCoordinator(storePath, async () => {
         const payload = {
             provider: profile.provider,
             model: profile.model,
@@ -143,12 +150,12 @@ async function writeLlmProfile(profile) {
         finally {
             await store.close();
         }
-    });
+    }, { operation_label: "writeLlmProfile" });
     return `${storePath}#state/runtime/llm_profile`;
 }
 async function recordDiscoveryProfile(input) {
     const storePath = getWorkspaceStorePath(WORKSPACE_ROOT);
-    await withStoreWriteQueue(storePath, async () => {
+    await withStoreWriteCoordinator(storePath, async () => {
         const store = await openStore(storePath);
         try {
             const discovery = new DiscoveryRepository(store);
@@ -171,7 +178,7 @@ async function recordDiscoveryProfile(input) {
         finally {
             await store.close();
         }
-    });
+    }, { operation_label: "recordDiscoveryProfile" });
 }
 async function runInit(args, mode = "init") {
     const projectName = readFlagValue(args, "--project");
@@ -192,7 +199,7 @@ async function runInit(args, mode = "init") {
         model: llm.llmModel ?? undefined,
         baseUrl: llm.llmBaseUrl ?? undefined,
     });
-    const astIndex = refreshAstgrepIndex({
+    const astIndex = await refreshAstgrepIndex({
         scope: ".",
         append_evidence: true,
         emit_event: true,
@@ -248,7 +255,7 @@ async function runInit(args, mode = "init") {
             message: `ace ${mode} completed: ${storeResult.materialized.length} bootstrap files materialized`,
             artifacts: [
                 `${ACE_TASKS_ROOT_REL}/`,
-                `${ACE_ROOT_REL}/ace-state.ace`,
+                storeResult.storePath,
                 delta.index_path,
                 astIndex.output_json_path,
             ],
@@ -335,7 +342,7 @@ async function runDoctor(args) {
         ok: hasProfile,
         detail: hasProfile
             ? profilePath
-            : `Missing ${ACE_ROOT_REL}/ace-state.ace#state/runtime/llm_profile. Run \`ace init --llm <provider>\` or \`ace doctor --scan\` for a local runtime.`,
+            : `Missing agent-state/ace-state.ace#state/runtime/llm_profile. Run \`ace init --llm <provider>\` or \`ace doctor --scan\` for a local runtime.`,
     });
     let provider = llm.llmProvider;
     let model = llm.llmModel;
@@ -378,7 +385,7 @@ async function runDoctor(args) {
         }
     }
     if (!provider) {
-        throw new Error(`No runtime provider configured. Use --llm <provider>, bootstrap one into ${ACE_ROOT_REL}/ace-state.ace#state/runtime/llm_profile, or run \`ace doctor --scan\` for a local runtime.`);
+        throw new Error(`No runtime provider configured. Use --llm <provider>, bootstrap one into agent-state/ace-state.ace#state/runtime/llm_profile, or run \`ace doctor --scan\` for a local runtime.`);
     }
     if (!model) {
         model = defaultModelForProvider(provider);
@@ -515,16 +522,21 @@ 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.`);
+    const resolved = await ensureCanonicalWorkspaceStore(WORKSPACE_ROOT, {
+        operationLabel: "runPreconfig",
+    });
+    if (resolved.mode === "missing") {
+        console.error(`No ACE store found. Expected canonical ${resolved.canonicalPath}; legacy fallback ${resolved.legacyPath} was also not found. Run 'ace init' first.`);
         process.exit(1);
     }
-    const store = await openStore(storePath);
+    for (const w of resolved.warnings) {
+        console.warn(`[preconfig] ${w}`);
+    }
+    const store = await openStore(resolved.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`);
+        console.log(`ACE preconfig complete — wrote ${written.length} files to .mcp-config/ and root .mcp.json\n`);
         for (const p of written) {
             console.log(`  ${p}`);
         }
@@ -644,7 +656,7 @@ async function main() {
     }
     if (command === "migrate") {
         const { importFromFileWorkspace } = await import("./store/importer.js");
-        const storePath = args[1] ?? `${WORKSPACE_ROOT}/.agents/ACE/ace-state.ace`;
+        const storePath = args[1] ?? getWorkspaceStorePath(WORKSPACE_ROOT);
         console.log(`Migrating file workspace at ${WORKSPACE_ROOT} to store at ${storePath}...`);
         const result = await importFromFileWorkspace(WORKSPACE_ROOT, storePath);
         console.log(`Migration complete:`);
@@ -680,6 +692,26 @@ async function main() {
         console.log(`Store compacted: ${result.before} → ${result.after} bytes (saved ${savedKb}KB)`);
         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 result = await cacheWorkspaceArtifacts(WORKSPACE_ROOT, { dryRun, clean });
+        console.log("ACE cache complete");
+        console.log(`Workspace: ${WORKSPACE_ROOT}`);
+        console.log(`Store: ${result.storePath}`);
+        console.log(`Scanned files: ${result.scanned_files}`);
+        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}`);
+        if (result.warnings.length > 0) {
+            console.warn(`Warnings (${result.warnings.length}):`);
+            for (const warning of result.warnings)
+                console.warn(`  ! ${warning}`);
+        }
+        return;
+    }
     if (command === "help" || command === "--help" || command === "-h") {
         printHelp();
         return;

package/dist/handoff-registry.js

@@ -4,7 +4,7 @@ import { openStore } from "./store/ace-packed-store.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 { withStoreWriteCoordinator } from "./store/write-coordinator.js";
 import { waitForPendingStatusEventMirrors } from "./status-events.js";
 import { waitForTodoStoreMirror } from "./todo-state.js";
 const HANDOFF_REGISTRY_REL = "agent-state/handoff-registry.json";
@@ -299,7 +299,7 @@ export async function registerHandoffSafe(input) {
         return withFileLock(HANDOFF_REGISTRY_REL, () => registerHandoff(input));
     }
     return withFileLock(HANDOFF_REGISTRY_REL, async () => {
-        return withStoreWriteQueue(storePath, async () => {
+        return withStoreWriteCoordinator(storePath, async () => {
             const store = await openStore(storePath);
             try {
                 const repo = new HandoffRepository(store);
@@ -346,7 +346,7 @@ export async function registerHandoffSafe(input) {
             finally {
                 await store.close();
             }
-        });
+        }, { operation_label: "registerHandoffSafe" });
     });
 }
 /**
@@ -361,7 +361,7 @@ export async function acknowledgeHandoffSafe(input) {
         return withFileLock(HANDOFF_REGISTRY_REL, () => acknowledgeHandoff(input));
     }
     return withFileLock(HANDOFF_REGISTRY_REL, async () => {
-        return withStoreWriteQueue(storePath, async () => {
+        return withStoreWriteCoordinator(storePath, async () => {
             const store = await openStore(storePath);
             try {
                 const repo = new HandoffRepository(store);
@@ -420,7 +420,7 @@ export async function acknowledgeHandoffSafe(input) {
             finally {
                 await store.close();
             }
-        });
+        }, { operation_label: "acknowledgeHandoffSafe" });
     });
 }
 //# sourceMappingURL=handoff-registry.js.map

package/dist/helpers/artifacts.d.ts

@@ -0,0 +1,19 @@
+import { type AgentRole, type KernelKey, type TaskKey } from "./constants.js";
+export interface SkillReference {
+    name: string;
+    path: string;
+    source: "workspace" | "package-defaults" | "store";
+}
+export declare function getAgentInstructionPath(role: AgentRole): string | undefined;
+export declare function getAgentManifestPath(role: AgentRole): string | undefined;
+export declare function readAgentInstructions(role: AgentRole): string;
+export declare function readAgentManifest(role: AgentRole): string;
+export declare function getTaskArtifactPath(key: TaskKey): string | undefined;
+export declare function readTaskArtifact(key: TaskKey): string;
+export declare function getKernelArtifactPath(key: KernelKey): string | undefined;
+export declare function readKernelArtifact(key: KernelKey): string;
+export declare function resolveWritableTaskPath(key: TaskKey): string;
+export declare function listAvailableSkills(): SkillReference[];
+export declare function getSkillPath(name: string): string | undefined;
+export declare function readSkillInstructions(name: string): string;
+//# sourceMappingURL=artifacts.d.ts.map