@voybio/ace-swarm 0.2.5 → 2.4.0

package/CHANGELOG.md

@@ -35,9 +35,19 @@
 - Expanded hook dispatch context to emit role-aware ACE tool hints from session, subagent, and tool lifecycle events.
 - Updated bootstrap and config rendering to generate multi-host hook artifacts under `.vscode`, `.cursor`, and `.mcp-config`.
 
+**Store-Unity Migration:**
+- Added `src/store/workspace-store-paths.ts` as the canonical resolver for the canonical/legacy ACE store transition. Every command that opens ACEPACK now uses this shared module; no command assembles `.agents/ACE/ace-state.ace` by hand.
+- `agent-state/ace-state.ace` is the canonical store for new and adopted workspaces. `.agents/ACE/ace-state.ace` is retained as a supported legacy input and fallback — not a second active write target.
+- Added `ensureCanonicalWorkspaceStore()`: legacy-only workspaces are atomically adopted into the canonical path on the first mutating operation (bootstrap, install, repair, compact, preconfig). The legacy file is preserved as a fallback after adoption.
+- Dual-store conflicts (both files exist with different content) surface an explicit warning and halt mutating commands rather than silently merging or overwriting.
+- Added `resolveWorkspaceStorePath()` for read-only resolution: returns the active path and mode without writing anything.
+- Bootstrap, skill install/list, repair, compact, and preconfig all updated to use the shared resolver.
+- CLI help text, doctor messages, and run-ledger artifacts updated to describe `agent-state/ace-state.ace` as canonical.
+- Added `test/store-unity-release.test.mjs` as a dedicated release gate covering legacy adoption, dual-store conflict, canonical-only skill install/repair/compact, and a source-scan guard that fails on new hard-coded legacy path references outside the resolver module.
+
 ### Validation
 
-- Verified `208/208` tests passing (up from 202) with full orchestrator supervisor, model bridge, and compliance enforcement coverage.
+- Verified `319/319` tests passing (up from 208) with full orchestrator supervisor, model bridge, compliance enforcement, and store-unity migration coverage.
 
 ## [2.2.0] - 2026-03-26
 

package/README.md

@@ -2,7 +2,7 @@
 
 Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted coding.
 
-`ace-swarm` provides Claude Code, Codex, Cursor, VS Code, and provider-backed 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.
+`ace-swarm` provides Claude Code, Codex, Cursor, GitHub Copilot CLI, VS Code, and provider-backed 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 — `agent-state/ace-state.ace` — with `.agents/ACE/ace-state.ace` kept only as a legacy fallback for older workspaces.
 
 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 provider-backed runs, ACE provides task context, tool surfaces, status events, evidence trails, and resumable state.
 
@@ -13,7 +13,7 @@ Modern coding agents can already read files, write code, run commands, and call
 - Shared workflow state should live in the workspace, not only in chat history.
 - ACE-Orchestrator is the default entrypoint, and every provider can delegate through the full agent set.
 - Provider-backed runs should get the same structure and observability.
-- Bootstrap should be contained and reversible: ACE writes into `.agents/ACE/ace-state.ace`.
+- Bootstrap should be contained and reversible: ACE writes into `agent-state/ace-state.ace`, with legacy fallback reads from `.agents/ACE/ace-state.ace` where needed.
 
 ### Serving model providers
 
@@ -21,6 +21,8 @@ ACE provides model providers with the context they cannot infer on their own: ta
 
 - `ace init --llm <provider>` records the selected runtime profile in the store.
 - `ace doctor` validates local or hosted runtime wiring, checks the selected model when the provider exposes listings, and keeps the runtime honest.
+- `ace doctor --scan` probes common Ollama and llama.cpp endpoints and writes the selected profile back into the store.
+- `ace tui` is provider-aware for `ollama`, `llama.cpp`, `codex`, `claude`, `gemini`, and `copilot` when credentials or base URLs are configured.
 - `ace mcp` and `ace tui` expose the same workspace truth to the host, the terminal, and the model.
 
 ## Why This Exists Now
@@ -38,7 +40,7 @@ ACE also provides scheduler primitives for queued work, dependency gates, leases
 
 ## ACEPACK State Model
 
-ACE uses a custom binary format called ACEPACK to present `.agents/ACE/ace-state.ace` as a structured single-file store. The file has three regions:
+ACE uses a custom binary format called ACEPACK to present `agent-state/ace-state.ace` as a structured single-file store. Existing workspaces that still carry `.agents/ACE/ace-state.ace` are read through the legacy fallback path. The file has three regions:
 
 ```
 ace-state.ace
@@ -80,7 +82,7 @@ Every `appendEntry()` call — handoffs, status events, ledger entries, session
 - Per-event overhead is ~19 bytes fixed vs ~150 bytes for equivalent JSON.
 - At 100,000 events, the fixed columns are ~1.9 MB; a full JSON log would be ~15 MB.
 
-Events accumulate for the workspace lifetime and survive `compact()`. Full historical replay is always available. See `HOT_COLD_EVENT_TIERING.md` for the future branch that adds compressed batch archiving for very long-lived workspaces.
+Events accumulate for the workspace lifetime and survive `compact()`. Full historical replay is always available.
 
 ### Why one state file
 
@@ -98,7 +100,7 @@ The store holds runtime state, agent instructions, skills, topology, schemas, an
 Bootstrap a workspace:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project"
+npx -y @voybio/ace-swarm turnkey --project "My Project"
 ace mcp
 ```
 
@@ -111,7 +113,7 @@ initiate ACE
 Local-model path with Ollama:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b --base-url http://localhost:11434
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b --base-url http://localhost:11434
 ollama serve
 ollama pull llama3.1:8b
 ace doctor --llm ollama --model llama3.1:8b --base-url http://localhost:11434
@@ -121,7 +123,7 @@ ace mcp
 Local-model path with llama.cpp:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project" --llm llama.cpp --model local-model --base-url http://localhost:8080
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm llama.cpp --model local-model --base-url http://localhost:8080
 llama-server -m /path/to/model.gguf --port 8080
 ace doctor --llm llama.cpp --model local-model --base-url http://localhost:8080
 ace mcp
@@ -132,7 +134,7 @@ If you already have a local runtime running, `ace doctor --scan` will probe comm
 Hosted provider path with Codex:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project" --llm codex --model gpt-5
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm codex --model gpt-5
 export OPENAI_API_KEY=...
 ace doctor --llm codex --model gpt-5
 ace mcp
@@ -140,9 +142,10 @@ ace mcp
 
 ## What Bootstrap Writes
 
-ACE bootstrap is intentionally contained. The store is authoritative at `.agents/ACE/ace-state.ace`; only a few host-facing files land in the workspace when requested.
+ACE bootstrap is intentionally contained. The store is authoritative at `agent-state/ace-state.ace`; only a few host-facing files land in the workspace when requested.
 
-- `.agents/ACE/ace-state.ace` — runtime state, agent instructions, skills, topology, schemas, and the event log
+- `agent-state/ace-state.ace` — runtime state, agent instructions, skills, topology, schemas, and the event log
+- `.agents/ACE/ace-state.ace` — legacy fallback for existing workspaces
 - `.agents/ACE/ace-hook-context.json` — compact hook snapshot for external clients
 - `.agents/ACE/tasks/todo.md` — human-facing todo surface
 - Optional workspace-root stubs — `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, and `.vscode/mcp.json`
@@ -159,6 +162,11 @@ Developer or MCP host
   |       |
   |       `-- calls ace-swarm over MCP
   |
+  +-- agent-state/
+  |       |
+  |       +-- ace-state.ace
+  |       +-- STATUS.md / TASK.md / HANDOFF.json projections
+  |
   +-- ace mcp
   |       |
   |       +-- tools, prompts, resources
@@ -168,7 +176,6 @@ Developer or MCP host
   |
   +-- .agents/ACE/
   |       |
-  |       +-- ace-state.ace
   |       +-- ace-hook-context.json
   |       +-- tasks/todo.md
   |       `-- host config bundles
@@ -190,7 +197,7 @@ Developer or MCP host
 | 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 |
+| Durable state        | single `agent-state/ace-state.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 |
@@ -215,7 +222,7 @@ In that setup, the host remains the interface. ACE becomes the state contract un
 
 Local models are good at generating text. They usually need help seeing the workspace, hearing the handoff trail, and remembering what changed two turns ago. ACE closes that gap.
 
-- `ace init --llm <provider>` seeds the profile inside `.agents/ACE/ace-state.ace`.
+- `ace init --llm <provider>` seeds the profile inside `agent-state/ace-state.ace`.
 - `ace doctor` verifies that the selected runtime is configured and, when possible, reachable.
 - `ace tui` can talk to either local runtime and surface the same workspace state the MCP server sees.
 - The ACE model bridge gives local runs tool selection, execution flow, and persisted state instead of a fragile one-shot chat loop.

package/assets/agent-state/EVIDENCE_LOG.md

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

package/assets/agent-state/MODULES/roles/capability-framework.json

@@ -0,0 +1,41 @@
+{
+  "id": "capability-framework",
+  "version": "1.0.0",
+  "objective": "Validate ACE framework contracts, execute gate bundles, and enforce state integrity checks",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "TEAL_CONFIG.md",
+      "critical": true
+    },
+    {
+      "file": "QUALITY_GATES.md",
+      "critical": true
+    },
+    {
+      "file": "HANDOFF.json",
+      "critical": true
+    },
+    {
+      "file": "MODULES/registry.json",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "EVIDENCE_LOG.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "STATUS_EVENTS.ndjson",
+      "validation_gate": "gate-autonomy"
+    }
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ESCALATE_TO_CAPABILITY_OPS"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-git.json

@@ -0,0 +1,33 @@
+{
+  "id": "capability-git",
+  "version": "1.0.0",
+  "objective": "Execute repository initialization and commit operations with traceable evidence",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "STATUS.md",
+      "critical": false
+    },
+    {
+      "file": "EVIDENCE_LOG.md",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "EVIDENCE_LOG.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "STATUS_EVENTS.ndjson",
+      "validation_gate": "gate-autonomy"
+    }
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ESCALATE_TO_CAPABILITY_OPS"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-safety.json

@@ -0,0 +1,37 @@
+{
+  "id": "capability-safety",
+  "version": "1.0.0",
+  "objective": "Apply safety checks and fail-closed validation before mutating critical ACE artifacts",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "HANDOFF.json",
+      "critical": false
+    },
+    {
+      "file": "QUALITY_GATES.md",
+      "critical": true
+    },
+    {
+      "file": "EVIDENCE_LOG.md",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "EVIDENCE_LOG.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "STATUS_EVENTS.ndjson",
+      "validation_gate": "gate-autonomy"
+    }
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "BLOCK_AND_ESCALATE"
+  }
+}

package/assets/agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json

@@ -145,6 +145,27 @@
         "registry_path": {
           "type": "string",
           "minLength": 1
+        },
+        "surgical_read_budgets": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "small_local": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "mid": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "frontier": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 1
+            }
+          }
         }
       }
     },

package/assets/agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json

@@ -163,6 +163,46 @@
           "items": {
             "$ref": "#/$defs/tool_call"
           }
+        },
+        "turn_outcome": {
+          "type": "string",
+          "enum": [
+            "no_op_success",
+            "meaningful_completion",
+            "escalation_blocker"
+          ]
+        },
+        "outcome_reason": {
+          "type": "string"
+        }
+      }
+    },
+    "output_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "emit_to",
+        "silent_unless_blocked",
+        "require_approval_before_emit"
+      ],
+      "properties": {
+        "emit_to": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "tui",
+              "tracker",
+              "handoff",
+              "vericify"
+            ]
+          }
+        },
+        "silent_unless_blocked": {
+          "type": "boolean"
+        },
+        "require_approval_before_emit": {
+          "type": "boolean"
         }
       }
     },
@@ -278,6 +318,9 @@
             "failed"
           ]
         },
+        "output_policy": {
+          "$ref": "#/$defs/output_policy"
+        },
         "turns": {
           "type": "array",
           "items": {

package/assets/agent-state/MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json

@@ -72,6 +72,17 @@
           "last_error": {
             "type": "string"
           },
+          "hook_health": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "degraded",
+              "failed"
+            ]
+          },
+          "hook_summary": {
+            "type": "string"
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"

package/assets/agent-state/STATUS.md

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

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,