@voybio/ace-swarm 0.2.5 → 2.4.0

package/dist/tools-files.js

@@ -1,18 +1,66 @@
 /**
  * File operation tool registrations + new safe-edit and diff tools.
  */
-import { readdirSync } from "node:fs";
-import { isAbsolute, relative } from "node:path";
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { z } from "zod";
-import { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWrite, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
-import { looksLikeSwarmHandoffPath } from "./shared.js";
+import { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWriteAsync, safeWrite, resolveStoreFallbackKeysForPath, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
+import { isInside, looksLikeSwarmHandoffPath, normalizeRelPath } from "./shared.js";
 import { validateAgentStateHandoffPayload, validateArtifactManifestPayload, validateProvenanceLogContent, validateStatusEventsNdjsonContent, validateSwarmHandoffPayload, validateTealConfigContent, validateRuntimeExecutorSessionRegistryPayload, validateRuntimeToolSpecRegistryPayload, validateTrackerSnapshotPayload, validateVericifyBridgeSnapshotPayload, validateVericifyProcessPostLogPayload, validateWorkspaceSessionRegistryPayload, lintHandoffPayload, } from "./schemas.js";
 import { syncTodoStateSafe } from "./todo-state.js";
-import { validateRuntimeProfileContent } from "./runtime-profile.js";
 import { shouldAutoRefreshKanbanForPath, refreshKanbanArtifacts, } from "./kanban.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { appendStatusEventSafe } from "./status-events.js";
-import { safeEditFile, diffContents } from "./safe-edit.js";
+import { safeEditFile, diffContents, applyPatch } from "./safe-edit.js";
+import { readRuntimeProfile, resolveEffectiveSurgicalReadBudget, validateRuntimeProfileContent, } from "./runtime-profile.js";
+import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
+export function planAstgrepRewriteTargets(files) {
+    const affected = [...new Set(files.filter(Boolean))].sort((a, b) => a.localeCompare(b));
+    if (affected.length > 1) {
+        return {
+            ok: false,
+            affected_files: affected,
+            error: `astgrep_rewrite refuses multi-file rewrites (${affected.length} files): ${affected.slice(0, 5).join(", ")}`,
+        };
+    }
+    return {
+        ok: true,
+        affected_files: affected,
+        target_file: affected[0],
+    };
+}
+async function appendAstgrepRewriteTransition(sessionId, to, reason, evidenceRefs) {
+    if (!sessionId)
+        return;
+    await withLocalModelRuntimeRepository(WORKSPACE_ROOT, async (repo) => {
+        await repo.appendTransitionRecord({
+            subject_kind: "plan_step",
+            subject_id: `${sessionId}/astgrep_rewrite`,
+            from: "staged",
+            to,
+            reason,
+            reason_code: to === "promoted" ? "surgical_rewrite" : "surgical_rewrite_failed",
+            evidence_refs: evidenceRefs,
+        });
+    }).catch(() => undefined);
+}
+function astgrepFileToWorkspaceRel(file) {
+    const abs = isAbsolute(file) ? file : resolve(WORKSPACE_ROOT, file);
+    if (!isInside(WORKSPACE_ROOT, abs))
+        return undefined;
+    return normalizeRelPath(relative(WORKSPACE_ROOT, abs));
+}
+async function resolveReadFileLinesBudget() {
+    let modelClass;
+    const statuses = await withLocalModelRuntimeRepository(WORKSPACE_ROOT, async (repo) => repo.listRuntimeStatuses()).catch(() => undefined);
+    modelClass = statuses?.[0]?.model_class;
+    const profile = readRuntimeProfile();
+    const resolved = resolveEffectiveSurgicalReadBudget(profile, modelClass);
+    return {
+        ...resolved,
+        source: modelClass ? "runtime-status" : "runtime-profile",
+    };
+}
 export function registerFileTools(server) {
     // ── Append-only artifact protection ───────────────────────────────
     // These files must only grow; overwrites from the generic write tool
@@ -26,12 +74,12 @@ export function registerFileTools(server) {
         "agent-state/PROVENANCE_LOG.md",
     ]);
     // ── Core file operations ──────────────────────────────────────────
-    server.tool("read_workspace_file", "Read any workspace file by relative path", {
+    server.tool("read_workspace_file", "Read any workspace file by relative path. Prefer outline_file for discovery, read_file_lines for known regions, astgrep_query for symbol lookup. For small_local runs, this is the fallback after surgical reads are insufficient. Cost: heavy for large files.", {
         path: z.string().describe("Relative path from workspace root"),
     }, async ({ path }) => ({
         content: [{ type: "text", text: safeRead(path) }],
     }));
-    server.tool("write_workspace_file", "Write or update a workspace file", {
+    server.tool("write_workspace_file", "Write or update a workspace file. Prefer apply_patch for targeted edits, astgrep_rewrite for structural rewrites. Cost: heavy.", {
         path: z.string().describe("Relative path from workspace root"),
         content: z.string().describe("File content"),
     }, async ({ path, content }) => {
@@ -475,8 +523,10 @@ export function registerFileTools(server) {
             const synced = await syncTodoStateSafe(content);
             todoStateSuffix = `\nTODO state synced: ${synced.path}`;
         }
+        const storeFallbackKeys = resolveStoreFallbackKeysForPath(normalizedPath);
+        const useAsyncStoreAdmission = storeFallbackKeys.length > 0;
         // Keep the file as a materialized projection after the canonical store update.
-        const abs = safeWrite(path, content);
+        const abs = useAsyncStoreAdmission ? await safeWriteAsync(path, content) : safeWrite(path, content);
         let kanbanSuffix = "";
         const shouldRefreshKanban = shouldAutoRefreshKanbanForPath(normalizedPath);
         if (shouldRefreshKanban) {
@@ -544,7 +594,7 @@ export function registerFileTools(server) {
         }
     });
     // ── Safe-edit (new P0 tool) ───────────────────────────────────────
-    server.tool("safe_edit_file", "Edit a file using copy→validate→swap pattern. Automatically rolls back if validation or tests fail.", {
+    server.tool("safe_edit_file", "Edit a file using copy→validate→swap pattern. Automatically rolls back if validation or tests fail. Prefer apply_patch for small targeted edits. Cost: heavy for large files.", {
         path: z.string().describe("Workspace-relative file path to edit"),
         content: z.string().describe("New file content"),
         validation_command: z
@@ -676,5 +726,244 @@ export function registerFileTools(server) {
             ],
         };
     });
+    // ── Surgical read / query / patch tools ──────────────────────────
+    server.tool("read_file_lines", "Read a specific line range from a workspace file. Prefer this over read_workspace_file for large files. Cost: moderate.", {
+        path: z.string().describe("Workspace-relative file path"),
+        start_line: z.number().int().min(1).describe("First line to read (1-indexed)"),
+        end_line: z.number().int().min(1).describe("Last line to read (inclusive)"),
+        symbol_anchor: z.string().optional().describe("Optional symbol name hint for context (informational only)"),
+    }, async ({ path: relPath, start_line, end_line, symbol_anchor }) => {
+        const budget = await resolveReadFileLinesBudget();
+        const requestedLines = end_line - start_line + 1;
+        const budgetText = budget.read_file_lines_max_lines === null
+            ? "unbounded"
+            : String(budget.read_file_lines_max_lines);
+        const headerLines = [
+            `# Budget: model_class=${budget.model_class}; read_file_lines_max_lines=${budgetText}`,
+            `# Budget source: ${budget.source}`,
+        ];
+        if (budget.read_file_lines_max_lines !== null &&
+            requestedLines > budget.read_file_lines_max_lines) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            ...headerLines,
+                            `Error: requested range (${requestedLines} lines) exceeds ${budget.model_class} budget of ${budgetText} lines.`,
+                            "Use outline_file for discovery or astgrep_query for symbol lookup.",
+                        ].join("\n"),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const content = safeRead(relPath);
+        const lines = content.split("\n");
+        const slice = lines.slice(start_line - 1, end_line);
+        const result = slice.map((l, i) => `${start_line + i}: ${l}`).join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        ...headerLines,
+                        `# ${relPath} (lines ${start_line}–${end_line})`,
+                        symbol_anchor ? `# Symbol context: ${symbol_anchor}` : "",
+                        "",
+                        result,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("outline_file", "Return symbol signatures and top-level structure of a file without bodies. Use for discovery before reading specific regions. Cost: cheap.", {
+        path: z.string().describe("Workspace-relative file path"),
+    }, async ({ path: relPath }) => {
+        const content = safeRead(relPath);
+        const lines = content.split("\n");
+        const outlinePatterns = [
+            /^export\s+(async\s+)?function\s+\w+/,
+            /^export\s+(class|interface|type|enum|const|abstract)\s+\w+/,
+            /^(export\s+)?default\s+/,
+            /^\s+(async\s+)?(\w+\s+)?\w+\s*\([^)]*\)\s*[:{]/,
+            /^(function|class|interface|type|enum|const|let|var)\s+\w+/,
+        ];
+        const outline = [];
+        lines.forEach((line, idx) => {
+            if (outlinePatterns.some(p => p.test(line))) {
+                outline.push(`${idx + 1}: ${line.trimEnd()}`);
+            }
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# Outline: ${relPath} (${lines.length} lines total)`,
+                        "",
+                        outline.length > 0 ? outline.join("\n") : "(no symbols found)",
+                    ].join("\n"),
+                }],
+        };
+    });
+    server.tool("astgrep_query", "Search for a structural pattern in workspace files using ast-grep. Returns matching ranges without reading whole files. Cost: cheap.", {
+        pattern: z.string().describe("ast-grep pattern, e.g. 'export function $NAME($$$)'"),
+        lang: z.string().describe("Language: ts, py, rust, go, js"),
+        scope: z.string().optional().describe("Workspace-relative directory to search (default: src)"),
+        max_results: z.number().int().min(1).max(200).optional().describe("Max results to return (default: 50)"),
+    }, async ({ pattern, lang, scope, max_results }) => {
+        const { runAstgrepQuery } = await import("./astgrep-index.js");
+        const root = wsPath(scope ?? "src");
+        const matches = runAstgrepQuery(pattern, lang, [root]);
+        const limited = matches.slice(0, max_results ?? 50);
+        const lines = limited.map((m) => `${m.file}:${m.line}: ${m.text}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# astgrep_query: ${pattern} (${lang})`,
+                        `# Found ${matches.length} matches, showing ${limited.length}`,
+                        "",
+                        ...lines,
+                    ].join("\n"),
+                }],
+        };
+    });
+    server.tool("astgrep_rewrite", "Apply a structural rewrite to one workspace file using ast-grep pattern + replacement. Multi-file rewrites are refused; staged through safe_edit_file. Emits transition-compatible result details. Cost: heavy.", {
+        pattern: z.string().describe("ast-grep pattern to match"),
+        rewrite: z.string().describe("Replacement template (use $NAME etc. from pattern)"),
+        lang: z.string().describe("Language: ts, py, rust, go, js"),
+        scope: z.string().optional().describe("Workspace-relative directory (default: src)"),
+        confirm_multi_file: z.boolean().optional().describe("Deprecated; multi-file rewrites are always refused"),
+        validation_command: z.string().optional().describe("Shell command to validate the staged rewrite before promotion"),
+        test_command: z.string().optional().describe("Shell command to test the staged rewrite before promotion"),
+        session_id: z.string().optional().describe("Optional runtime session id for transition-record emission"),
+    }, async ({ pattern, rewrite, lang, scope, validation_command, test_command, session_id }) => {
+        const { runAstgrepQuery } = await import("./astgrep-index.js");
+        const root = wsPath(scope ?? "src");
+        if (!isInside(WORKSPACE_ROOT, root)) {
+            return {
+                content: [{ type: "text", text: `astgrep_rewrite failed: scope escapes workspace root (${scope})` }],
+                isError: true,
+            };
+        }
+        const matches = runAstgrepQuery(pattern, lang, [root]);
+        const affectedFiles = [...new Set(matches.map(m => m.file))];
+        const plan = planAstgrepRewriteTargets(affectedFiles);
+        if (!plan.ok) {
+            await appendAstgrepRewriteTransition(session_id, "refused", plan.error ?? "astgrep_rewrite refused the requested rewrite", plan.affected_files);
+            return {
+                content: [{
+                        type: "text",
+                        text: plan.error ?? "astgrep_rewrite refused the requested rewrite",
+                    }],
+                isError: true,
+            };
+        }
+        if (matches.length === 0) {
+            return {
+                content: [{ type: "text", text: "No matches found for pattern. No files modified." }],
+            };
+        }
+        const targetRel = astgrepFileToWorkspaceRel(plan.target_file ?? "");
+        if (!targetRel) {
+            return {
+                content: [{ type: "text", text: `astgrep_rewrite failed: matched path escapes workspace root (${plan.target_file ?? ""})` }],
+                isError: true,
+            };
+        }
+        const originalContent = safeRead(targetRel);
+        if (originalContent.startsWith("[FILE NOT FOUND]") || originalContent.startsWith("[ACCESS DENIED]")) {
+            return {
+                content: [{ type: "text", text: `astgrep_rewrite failed: cannot read ${targetRel}\n${originalContent}` }],
+                isError: true,
+            };
+        }
+        const stagingDir = wsPath(".ace-staging", `astgrep-rewrite-${Date.now()}`);
+        const stagedFile = resolve(stagingDir, targetRel);
+        mkdirSync(dirname(stagedFile), { recursive: true });
+        writeFileSync(stagedFile, originalContent, "utf-8");
+        const { spawnSync } = await import("node:child_process");
+        const result = spawnSync("ast-grep", ["--pattern", pattern, "--rewrite", rewrite, "--lang", lang, stagedFile, "--update-all"], { encoding: "utf8", cwd: WORKSPACE_ROOT });
+        if (result.status !== 0) {
+            await appendAstgrepRewriteTransition(session_id, "failed", `astgrep_rewrite failed in staging: ${result.stderr || result.stdout || "unknown error"}`, [targetRel]);
+            return {
+                content: [{ type: "text", text: `astgrep rewrite failed:\n${result.stderr}` }],
+                isError: true,
+            };
+        }
+        const rewrittenContent = readFileSync(stagedFile, "utf-8");
+        const safeResult = safeEditFile({
+            path: targetRel,
+            content: rewrittenContent,
+            validation_command,
+            test_command,
+        });
+        if (!safeResult.ok) {
+            await appendAstgrepRewriteTransition(session_id, "failed", `astgrep_rewrite failed before promotion for ${targetRel}: ${safeResult.error ?? "unknown error"}`, [targetRel]);
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `astgrep_rewrite failed before promotion`,
+                            `Path: ${targetRel}`,
+                            `Error: ${safeResult.error ?? "unknown error"}`,
+                            safeResult.validation_passed !== undefined ? `Validation: ${safeResult.validation_passed ? "passed" : "FAILED"}` : "Validation: not requested",
+                            safeResult.validation_output ? `Validation output:\n${safeResult.validation_output}` : "",
+                            safeResult.test_passed !== undefined ? `Tests: ${safeResult.test_passed ? "passed" : "FAILED"}` : "Tests: not requested",
+                            safeResult.test_output ? `Test output:\n${safeResult.test_output}` : "",
+                            `Staging: ${safeResult.staging_path || stagingDir}`,
+                        ].filter(Boolean).join("\n"),
+                    }],
+                isError: true,
+            };
+        }
+        await appendAstgrepRewriteTransition(session_id, "promoted", `astgrep_rewrite promoted staged rewrite for ${targetRel}`, [targetRel]);
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# astgrep_rewrite completed`,
+                        `Pattern: ${pattern}`,
+                        `Rewrite: ${rewrite}`,
+                        `Files affected: ${affectedFiles.length}`,
+                        `Path: ${targetRel}`,
+                        `Hash: ${safeResult.original_hash} → ${safeResult.new_hash}`,
+                        safeResult.validation_passed !== undefined ? `Validation: ${safeResult.validation_passed ? "passed" : "failed"}` : "Validation: not requested",
+                        safeResult.test_passed !== undefined ? `Tests: ${safeResult.test_passed ? "passed" : "failed"}` : "Tests: not requested",
+                        `Staging: ${safeResult.staging_path}`,
+                        result.stdout ? `\nOutput:\n${result.stdout}` : "",
+                    ].filter(Boolean).join("\n"),
+                }],
+        };
+    });
+    server.tool("apply_patch", "Apply a unified diff patch to a workspace file. Applies the patch to staged content, runs optional validation/tests, and promotes to the target only on success. Cost: moderate.", {
+        path: z.string().describe("Workspace-relative file path to patch"),
+        patch: z.string().describe("Unified diff patch (output of diff -u or similar)"),
+        validation_command: z.string().optional().describe("Shell command to validate after applying (e.g. 'npx tsc --noEmit')"),
+        test_command: z.string().optional().describe("Shell command to run tests after applying"),
+    }, async ({ path: relPath, patch, validation_command, test_command }) => {
+        const result = applyPatch({ path: relPath, patch, validation_command, test_command });
+        if (!result.ok) {
+            return {
+                content: [{ type: "text", text: `apply_patch failed: ${result.error ?? "unknown error"}\n${result.validation_output ?? ""}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# apply_patch: ${relPath}`,
+                        `Status: success`,
+                        result.validation_passed !== undefined ? `Validation: ${result.validation_passed ? "passed" : "failed"}` : "",
+                        result.test_passed !== undefined ? `Tests: ${result.test_passed ? "passed" : "failed"}` : "",
+                        `Staging: ${result.staging_path}`,
+                    ].filter(Boolean).join("\n"),
+                }],
+        };
+    });
 }
 //# sourceMappingURL=tools-files.js.map

package/dist/tools-framework.js

@@ -4,7 +4,7 @@
  */
 import { z } from "zod";
 import { bootstrapStoreWorkspace } from "./store/bootstrap-store.js";
-import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_LLM_PROVIDERS, ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, WORKSPACE_ROOT, classifyPathSource, detectAssetDrift, getAllMcpServerConfigSnippets, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, getMcpClientInstallHint, getMcpServerConfigSnippet, getTaskArtifactPath, isSwarmRole, listAvailableSkills, normalizePathForValidation, resolveWorkspaceRoot, safeRead, safeWrite, withFileLock, wsPath, } from "./helpers.js";
+import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_LLM_PROVIDERS, ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, WORKSPACE_ROOT, classifyPathSource, detectAssetDrift, getAllMcpServerConfigSnippets, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, getMcpClientInstallHint, getMcpServerConfigSnippet, getTaskArtifactPath, isSwarmRole, listAvailableSkills, normalizePathForValidation, resolveWorkspaceRoot, safeRead, safeWriteAsync, withFileLock, wsPath, } from "./helpers.js";
 import { getRoleTitle, MCP_CLIENT_ENUM, scoreDomains, } from "./shared.js";
 import { defaultModelForProvider, } from "./tui/provider-discovery.js";
 import { refreshAstgrepIndex } from "./astgrep-index.js";
@@ -21,6 +21,20 @@ import { auditStoreAuthority, writeStoreAuthorityAuditReport, } from "./store/st
 import { PROVENANCE_CRITICAL_EVENT_TYPES, validateArtifactManifestPayload, validateProvenanceLogContent, validateTealConfigContent, } from "./schemas.js";
 import { readAceTaskContractAssessment } from "./ace-autonomy.js";
 import { listStoreKeysSync, readStoreBlobSync } from "./store/store-snapshot.js";
+function executionRoleForDomain(domain) {
+    switch (domain) {
+        case "venture":
+            return "vos";
+        case "ux":
+            return "ui";
+        case "engineering":
+            return "coders";
+        case "research":
+            return "research";
+        default:
+            return "orchestrator";
+    }
+}
 function getArtifactManifestEntries(payload) {
     if (!payload || typeof payload !== "object" || Array.isArray(payload))
         return [];
@@ -287,7 +301,7 @@ async function appendEvidenceLogEntrySafe(review) {
     const timestamp = new Date().toISOString();
     const anchor = `#ts:${timestamp}`;
     const evidenceRef = `agent-state/EVIDENCE_LOG.md${anchor}`;
-    return withFileLock("agent-state/EVIDENCE_LOG.md", () => {
+    return withFileLock("agent-state/EVIDENCE_LOG.md", async () => {
         const existing = safeRead("agent-state/EVIDENCE_LOG.md");
         const seed = existing.startsWith("[FILE NOT FOUND]") || existing.startsWith("[ACCESS DENIED]")
             ? "# EVIDENCE LOG\n\nAppend-only validation evidence.\n\n## Entries\n"
@@ -319,7 +333,7 @@ async function appendEvidenceLogEntrySafe(review) {
                 })
                 : ["  - none"]),
         ];
-        const path = safeWrite("agent-state/EVIDENCE_LOG.md", `${seed}${lines.join("\n")}\n`);
+        const path = await safeWriteAsync("agent-state/EVIDENCE_LOG.md", `${seed}${lines.join("\n")}\n`);
         return { path, evidenceRef };
     });
 }
@@ -534,6 +548,12 @@ export function registerFrameworkTools(server) {
             recommendedSubagents.add("memory");
         }
         return {
+            structuredContent: {
+                detected_domain: detected,
+                suggested_execution_role: executionRoleForDomain(detected),
+                default_entry_agent: "orchestrator",
+                task_contract_ok: taskContract.ok,
+            },
             content: [
                 {
                     type: "text",
@@ -635,7 +655,7 @@ export function registerFrameworkTools(server) {
             model: resolvedLlmModel ?? undefined,
             baseUrl: resolvedLlmBaseUrl ?? undefined,
         });
-        const astIndex = refreshAstgrepIndex({
+        const astIndex = await refreshAstgrepIndex({
             scope: ".",
             append_evidence: true,
             emit_event: true,
@@ -662,7 +682,7 @@ export function registerFrameworkTools(server) {
             category: "major_update",
             message: "Bootstrapped ACE workspace state",
             artifacts: [
-                `${ACE_ROOT_REL}/ace-state.ace`,
+                storeResult.storePath,
                 `${ACE_TASKS_ROOT_REL}/todo.md`,
                 normalizePathForValidation(delta.index_path),
                 "agent-state/AST_GREP_INDEX.json",

package/dist/tools-handoff.js

@@ -3,7 +3,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
-import { ACE_TASKS_ROOT_REL, normalizePathForValidation, readTaskArtifact, safeWrite, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
+import { ACE_TASKS_ROOT_REL, normalizePathForValidation, readTaskArtifact, safeWriteAsync, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
 import { ROLE_ENUM, HANDOFF_VALIDATION_MODE, HANDOFF_LIFECYCLE_STATUS_ENUM, } from "./shared.js";
 import { validateHandoffPayload, validateSwarmHandoffPayload, lintHandoffPayload, } from "./schemas.js";
 import { acknowledgeHandoffSafe, getHandoffRegistryPath, readHandoffRegistry, registerHandoffSafe, } from "./handoff-registry.js";
@@ -247,7 +247,7 @@ export function registerHandoffTools(server) {
             .replace("T", "-")
             .slice(0, 15);
         const filePath = wsPath("tasks", `SWARM_HANDOFF.${from}_to_${to}_${timeStr}_${shortId}.json`);
-        safeWrite(filePath, JSON.stringify(handoff, null, 2));
+        await safeWriteAsync(filePath, JSON.stringify(handoff, null, 2));
         const registry = await registerHandoffSafe({
             handoff_id: handoff.handoff_id,
             from: handoff.router.from,

package/dist/tools-lifecycle.js

@@ -2,8 +2,8 @@
  * Lifecycle tool registrations: status events, circuit breaker, and kanban.
  */
 import { z } from "zod";
-import { safeRead, safeWrite } from "./helpers.js";
-import { appendStatusEventSafe, getStatusEventsPath, readStatusEvents, } from "./status-events.js";
+import { safeRead, safeWriteAsync } from "./helpers.js";
+import { appendStatusEventSafe, getStatusEventsPath, readStatusEvents } from "./status-events.js";
 import { refreshKanbanArtifacts } from "./kanban.js";
 export function registerLifecycleTools(server) {
     server.tool("emit_status_event", "Append a schema-valid lifecycle event into agent-state/STATUS_EVENTS.ndjson", {
@@ -119,7 +119,7 @@ export function registerLifecycleTools(server) {
             ? "# STATUS\n\n"
             : current.trimEnd();
         const next = `${seed}\n- [${timestamp}] CIRCUIT_BREAKER_OPENED: ${reason}${owner ? ` (owner: ${owner})` : ""}\n`;
-        const statusPath = safeWrite("agent-state/STATUS.md", next);
+        const statusPath = await safeWriteAsync("agent-state/STATUS.md", next);
         const event = await appendStatusEventSafe({
             source_module: "capability-ops",
             event_type: "CIRCUIT_BREAKER_OPENED",
@@ -158,7 +158,7 @@ export function registerLifecycleTools(server) {
             ? "# STATUS\n\n"
             : current.trimEnd();
         const next = `${seed}\n- [${timestamp}] CIRCUIT_BREAKER_CLOSED: ${reason}\n`;
-        const statusPath = safeWrite("agent-state/STATUS.md", next);
+        const statusPath = await safeWriteAsync("agent-state/STATUS.md", next);
         const event = await appendStatusEventSafe({
             source_module: "capability-ops",
             event_type: "CIRCUIT_BREAKER_CLOSED",

package/dist/tools-memory.js

@@ -3,7 +3,7 @@
  */
 import { existsSync } from "node:fs";
 import { z } from "zod";
-import { resolveWorkspaceRoot, safeRead, safeWrite, wsPath } from "./helpers.js";
+import { resolveWorkspaceRoot, safeRead, safeWriteAsync, wsPath } from "./helpers.js";
 import { isReadError } from "./shared.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { appendStatusEventSafe } from "./status-events.js";
@@ -13,7 +13,7 @@ import { openStore } from "./store/ace-packed-store.js";
 import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { ContextSnapshotRepository } from "./store/repositories/context-snapshot-repository.js";
 import { getWorkspaceStorePath, storeExistsSync, toVirtualStorePath, } from "./store/store-snapshot.js";
-import { withStoreWriteQueue } from "./store/write-queue.js";
+import { withStoreWriteCoordinator } from "./store/write-coordinator.js";
 const CONTEXT_STORE_REL = "agent-state/context-snapshots";
 export function registerMemoryTools(server) {
     server.tool("context_snapshot", "Capture a named context snapshot for later retrieval (decisions, progress, state)", {
@@ -41,7 +41,7 @@ export function registerMemoryTools(server) {
         let path = wsPath(CONTEXT_STORE_REL, `${name}.json`);
         if (storeExistsSync(root) && existsSync(getWorkspaceStorePath(root))) {
             const storePath = getWorkspaceStorePath(root);
-            const saved = await withStoreWriteQueue(storePath, async () => {
+            const saved = await withStoreWriteCoordinator(storePath, async () => {
                 const store = await openStore(storePath);
                 try {
                     const repo = new ContextSnapshotRepository(store);
@@ -62,7 +62,7 @@ export function registerMemoryTools(server) {
                 finally {
                     await store.close();
                 }
-            });
+            }, { operation_label: "contextSnapshotSave" });
             path = toVirtualStorePath(storePath, `state/memory/context_snapshots/${saved.file}`);
         }
         else {
@@ -82,7 +82,7 @@ export function registerMemoryTools(server) {
                 .slice(0, 48);
             const filename = `${slug}.json`;
             path = wsPath(CONTEXT_STORE_REL, filename);
-            safeWrite(path, JSON.stringify(snapshot, null, 2));
+            await safeWriteAsync(path, JSON.stringify(snapshot, null, 2));
             const indexPath = wsPath(CONTEXT_STORE_REL, "index.json");
             const indexRaw = safeRead(indexPath);
             let index = { snapshots: [] };
@@ -97,7 +97,7 @@ export function registerMemoryTools(server) {
             index.snapshots = index.snapshots.filter((s) => s.name !== name);
             index.snapshots.push({ name, file: filename, timestamp, summary });
             index.snapshots.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
-            safeWrite(indexPath, JSON.stringify(index, null, 2));
+            await safeWriteAsync(indexPath, JSON.stringify(index, null, 2));
         }
         const ledger = await appendRunLedgerEntrySafe({
             tool: "context_snapshot",

package/dist/tools-todo.js

@@ -2,7 +2,7 @@
  * TODO, task management, and run-ledger tool registrations.
  */
 import { z } from "zod";
-import { ACE_TASKS_ROOT_REL, readTaskArtifact, resolveWritableTaskPath, safeWrite, } from "./helpers.js";
+import { ACE_TASKS_ROOT_REL, readTaskArtifact, resolveWritableTaskPath, safeWriteAsync, } from "./helpers.js";
 import { TODO_STATUS_ENUM } from "./shared.js";
 import { getTodoStatePath, readTodoState, syncTodoStateSafe, transitionTodoNodeSafe, } from "./todo-state.js";
 import { appendRunLedgerEntrySafe, getRunLedgerPath, readRunLedger, } from "./run-ledger.js";
@@ -33,7 +33,7 @@ export function registerTodoTools(server) {
     }, async ({ new_content, node_id, status, note }) => {
         if (typeof new_content === "string") {
             const synced = await syncTodoStateSafe(new_content);
-            const path = safeWrite(resolveWritableTaskPath("todo"), new_content);
+            const path = await safeWriteAsync(resolveWritableTaskPath("todo"), new_content);
             const runLedger = await appendRunLedgerEntrySafe({
                 tool: "update_todo",
                 category: "major_update",

package/dist/tracker-adapters.d.ts

@@ -67,7 +67,7 @@ export declare function validateTrackerSnapshotContent(raw: string): ValidationR
 export declare function loadTrackerSnapshot(explicitPath?: string): TrackerSnapshotResult;
 export declare function readTrackerSnapshot(): TrackerSnapshot;
 export declare function getTrackerSnapshotPath(): string;
-export declare function writeTrackerSnapshot(snapshot: TrackerSnapshot): string;
+export declare function writeTrackerSnapshot(snapshot: TrackerSnapshot): Promise<string>;
 export declare function listTrackerAdapterKinds(): string[];
 export declare function getTrackerAdapter(kind?: string): IssueTrackerAdapter;
 export declare function buildDefaultTrackerSnapshot(kind?: TrackerAdapterKind): TrackerSnapshot;