@voybio/ace-swarm 0.1.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. It is built around a Zarrita-backed `.agents/ACE/ace-state.zarr` store, 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
 
@@ -12,11 +12,11 @@ Modern coding agents can already read files, write code, run commands, and call
 - Handoffs should be typed, evidence-linked, and validated.
 - Shared workflow state should live in the workspace, not only in chat history.
 - Local models should get the same structure and observability as hosted models.
-- Bootstrap should be contained and reversible: ACE writes into `.agents/ACE/ace-state.zarr`.
+- Bootstrap should be contained and reversible: ACE writes into `.agents/ACE/ace-state.ace`.
 
 ### 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,23 +31,66 @@ 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.
 
-## Zarr State Model
+ACE also provides scheduler primitives for queued work, dependency gates, leases, and resource locks so multi-agent runs stay coordinated.
 
-ACE uses `@zarrita/core` and `@zarrita/storage` to present `.agents/ACE/ace-state.zarr` as a hierarchical store.
-Zarrita.js supplies the Zarr v3 groups, arrays, and typed views; ACE supplies `AcePackedStore`, the single-file local backend that keeps the store portable and atomic.
+## 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-state.ace
+├── Header (128 bytes)
+│     magic · version · flags
+│     kv_index_offset · kv_index_length · kv_chunk_end
+│     evt_offset · evt_length · evt_count · evt_base_id
+├── KV Chunk Region  (append-only, random-access)
+│     knowledge/agents/{name}/{file}  →  agent instruction text
+│     knowledge/skills/{name}/{file}  →  skill content
+│     topology/{kind}                 →  swarm registry, route tables
+│     state/{...}                     →  handoffs, todo, ledger, scheduler
+│     meta/{...}                      →  schema version, project name
+│     Each chunk: [uint32 length][bytes]
+└── Columnar Event Section  (rewritten on commit)
+      uint32    event count
+      int64[N]  timestamps      (epoch ms, big-endian)
+      uint8[N]  kinds           (EntityKind enum)
+      uint8[N]  sources         (ContentSource enum)
+      uint8[N]  flags           (0x01 = deleted)
+      uint32[N] payload offsets (→ payload pool)
+      uint32[N] payload lengths
+      uint32    pool length
+      bytes[M]  payload pool    (UTF-8 JSON blobs)
+```
+
+### KV region — random-access blob cache
+
+All persistent state — agent instructions, skills, topology, task indexes, scheduler queues — lives in the KV region. Each key maps to an immutable chunk appended at write time. `commit()` rewrites the KV index (a small JSON map at the file tail) to reflect the live keys. `compact()` rewrites the KV region to remove dead space from overwritten keys, atomically via tmp-rename.
+
+Write cost: O(1) append + O(index_size) index rewrite.
+Read cost: O(1) seek + O(chunk_length) read.
+
+### Columnar event section — typed handoff log
+
+Every `appendEntry()` call — handoffs, status events, ledger entries, session events — lands in an in-memory buffer and is flushed to the columnar section on `commit()`. The columnar layout stores fixed-width fields (timestamp, kind, source, flags) separately from payloads. This means:
+
+- Scanning "all handoffs in the last hour" reads only `timestamps[]` + `kinds[]` — 9 bytes per event, never touching the payload pool.
+- 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.
 
 ### Why one state file
 
-| One `.zarr` authority | What it avoids |
+| One `.ace` authority | What it avoids |
 |---|---|
-| One read/write source of truth | Hundreds of generated state files drifting apart |
-| Zarr groups and arrays | Hand-rolled file sprawl for runtime state, instructions, and indexes |
-| Typed hot fields | Repeated JSON parsing for counters and scheduler state |
+| Single append-only file | Hundreds of generated state files drifting apart |
+| KV region with typed keys | Hand-rolled file sprawl for runtime state, instructions, indexes |
+| Columnar event log | Repeated full-JSON parsing for timestamp and kind scanning |
 | Store-backed projections | External tools reading the same truth through different paths |
 
-The store holds runtime state, agent instructions, skills, topology, schemas, and indexes. Materialized files exist only when an external client still needs a path on disk.
+The store holds runtime state, agent instructions, skills, topology, schemas, and the complete event history. Materialized files exist only when an external client still needs a path on disk.
 
 ## Quick Start
 
@@ -87,9 +130,9 @@ If you already have a local runtime running, `ace doctor --scan` will probe comm
 
 ## What Bootstrap Writes
 
-ACE bootstrap is intentionally contained. The store is authoritative at `.agents/ACE/ace-state.zarr`; only a few host-facing files land in the workspace when requested.
+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.
 
-- `.agents/ACE/ace-state.zarr` — runtime state, agent instructions, skills, topology, schemas, and indexes
+- `.agents/ACE/ace-state.ace` — runtime state, agent instructions, skills, topology, schemas, and the event log
 - `.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`
@@ -115,7 +158,7 @@ Developer or MCP host
   |
   +-- .agents/ACE/
   |       |
-  |       +-- ace-state.zarr
+  |       +-- ace-state.ace
   |       +-- ace-hook-context.json
   |       +-- tasks/todo.md
   |       `-- host config bundles
@@ -134,16 +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 `.zarr` 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         | 208 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                 |
 +----------------------+--------------------------------------------------------------+
 ```
 
@@ -162,7 +205,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 ollama` or `ace init --llm llama.cpp` seeds the profile inside `.agents/ACE/ace-state.zarr`.
+- `ace init --llm ollama` or `ace init --llm llama.cpp` seeds the profile inside `.agents/ACE/ace-state.ace`.
 - `ace doctor` verifies that the selected runtime is reachable and configured.
 - `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.
@@ -199,7 +242,6 @@ If you want local agents with memory, evidence, and handoff discipline, this is
 +---------------------------------------------+---------------------------------------------------+
 ```
 
-
 ## Development
 
 ```bash
@@ -216,10 +258,8 @@ See [CHANGELOG.md](./CHANGELOG.md) for release history.
 
 - [Claude Code overview](https://docs.anthropic.com/en/docs/claude-code/overview)
 - [OpenAI connectors and MCP servers](https://platform.openai.com/docs/guides/tools-remote-mcp?lang=python)
-- [Introducing GPT-5.2-Codex](https://openai.com/index/introducing-gpt-5-2-codex/)
 - [Ollama tool calling and agent loops](https://docs.ollama.com/capabilities/tool-calling)
 - [llama.cpp](https://github.com/ggerganov/llama.cpp)
-- [Zarrita.js](https://zarrita.dev/)
 - [Model Context Protocol SDKs](https://modelcontextprotocol.io/docs/sdk)
 
 ## License

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/assets/scripts/ace-hook-dispatch.mjs

@@ -206,7 +206,7 @@ function buildRoleToolHint(role) {
  * Try to read the store-materialized 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 .zarr store directly.
+ * never needs to open the .ace store directly.
  */
 function tryReadHookContextSnapshot(workspaceRoot) {
   const snapshotPath = resolve(workspaceRoot, ACE_ROOT, "ace-hook-context.json");

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.zarr` 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.zarr` 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