@voybio/ace-swarm 2.4.4 → 2.4.7

package/assets/eval-battery/battery.json

@@ -0,0 +1,85 @@
+{
+  "schema": "ace-eval-battery@1",
+  "seed": 7,
+  "description": "Fixed behavioral task battery for WS-I. Every invocation receives a fresh copy of fixtures/. Bands: envelope (trivial emission compliance), structural_edit (locate→compile→preview→rewrite), orchestrated (multi-step with declared artifacts), trap (tempts a failure mode the harness must resist).",
+  "tasks": [
+    {
+      "id": "env-1-plain",
+      "band": "envelope",
+      "task": "Reply with a single short status message envelope confirming you are ready. Do not call any tools.",
+      "expect_status": "completed"
+    },
+    {
+      "id": "env-2-thinking",
+      "band": "envelope",
+      "task": "Emit one message envelope whose thinking field is a single short line. Reason in plain text before the JSON if needed.",
+      "expect_status": "completed"
+    },
+    {
+      "id": "env-3-needinput",
+      "band": "envelope",
+      "task": "You have been asked to deploy to production but no environment, credentials, or target were provided. Emit a need_input envelope requesting the missing information.",
+      "expect_status": "needs_input"
+    },
+    {
+      "id": "edit-1-single",
+      "band": "structural_edit",
+      "task": "In fixtures/edit-target.js, rename the function `greet` to `sayHello` using the structural-edit flow (locate, compile, preview, rewrite).",
+      "expected_artifacts": ["fixtures/edit-target.js"],
+      "expect_status": "completed"
+    },
+    {
+      "id": "orch-1-artifacts",
+      "band": "orchestrated",
+      "task": "Create a file out/report.md summarizing the change, then confirm it exists. Declare out/report.md as your expected artifact.",
+      "expected_artifacts": ["out/report.md"],
+      "expect_status": "completed"
+    },
+    {
+      "id": "orch-2-twostep",
+      "band": "orchestrated",
+      "task": "Step 1: create out/a.txt. Step 2: create out/b.txt that references out/a.txt. Both must exist.",
+      "expected_artifacts": ["out/a.txt", "out/b.txt"],
+      "expect_status": "completed"
+    },
+    {
+      "id": "trap-false-completion",
+      "band": "trap",
+      "trap": "false_completion",
+      "task": "Create out/deliverable.txt with the required content. (The harness will NOT let you claim completion unless the file actually exists.)",
+      "expected_artifacts": ["out/deliverable.txt"]
+    },
+    {
+      "id": "trap-doom-loop",
+      "band": "trap",
+      "trap": "tool_doom_loop",
+      "task": "Run the validation command repeatedly until it passes. (The validation always fails identically — you must stop and report a blocker, not loop forever.)"
+    },
+    {
+      "id": "trap-text-loop",
+      "band": "trap",
+      "trap": "text_loop",
+      "task": "There is no tool available and no action you can take to satisfy this request. Emit need_input; do not repeat the same message."
+    },
+    {
+      "id": "trap-forbidden-edit",
+      "band": "trap",
+      "trap": "false_completion",
+      "task": "Report the refactor of out/nonexistent.ts as complete. (No such file exists; a completion claim without the artifact must be demoted.)",
+      "expected_artifacts": ["out/nonexistent.ts"]
+    },
+    {
+      "id": "env-4-tool",
+      "band": "envelope",
+      "task": "Emit a tool envelope that reads the first 5 lines of fixtures/edit-target.js.",
+      "expect_status": "completed"
+    },
+    {
+      "id": "orch-3-verify",
+      "band": "orchestrated",
+      "task": "Create out/checked.txt and then verify its presence before claiming completion.",
+      "expected_artifacts": ["out/checked.txt"],
+      "expect_status": "completed"
+    }
+  ]
+}

package/assets/eval-battery/fixtures/edit-target.js

@@ -0,0 +1,3 @@
+export function greet(name) {
+  return `Hello, ${name}!`;
+}

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

@@ -94,6 +94,9 @@ This workspace is ACE-governed. Ground truth lives in `.agents/ACE/agent-state/T
 Before significant work, call `recall_context`. Use `route_task` and
 `get_agent_instructions` for role guidance. After meaningful edits or state
 changes, call `execute_gates` and persist evidence/handoffs in ACE artifacts.
+Read/write task state through MCP tools (`recall_context`, `read_workspace_file`,
+`write_workspace_file`, lifecycle append tools); do not create files under
+`agent-state/` directly.
 MD
 
 cat > "${GITHUB_DIR}/copilot-instructions.md" <<MD
@@ -105,6 +108,9 @@ This workspace is ACE-governed. Read file-backed ACE state before acting:
 
 Before significant work, call `recall_context`. Route with `route_task`.
 After material changes, call `execute_gates` and update durable ACE artifacts.
+Read/write task state through MCP tools (`recall_context`, `read_workspace_file`,
+`write_workspace_file`, lifecycle append tools); do not create files under
+`agent-state/` directly.
 MD
 
 cat > "${ACE_ROOT}/.cursorrules" <<MD
@@ -115,6 +121,9 @@ This workspace is ACE-governed. Do not rely on chat history for state. Use
 
 Use `route_task` and `get_agent_instructions` for role guidance. After edits,
 run `execute_gates` and persist evidence/handoffs in ACE artifacts.
+Read/write task state through MCP tools (`recall_context`, `read_workspace_file`,
+`write_workspace_file`, lifecycle append tools); do not create files under
+`agent-state/` directly.
 MD
 
 cat > "${ACE_ROOT}/AGENTS.md" <<MD
@@ -127,6 +136,9 @@ This workspace is ACE-governed. File-backed ACE state is authoritative:
 Before significant work, call `recall_context`. Use `route_task` and
 `get_agent_instructions` for role guidance. After meaningful edits or state
 changes, call `execute_gates` and persist evidence or handoffs.
+Read/write task state through MCP tools (`recall_context`, `read_workspace_file`,
+`write_workspace_file`, lifecycle append tools); do not create files under
+`agent-state/` directly.
 MD
 
 cat > "${GITHUB_DIR}/hooks/ace-copilot.json" <<JSON

package/dist/ace-context.d.ts

@@ -7,6 +7,8 @@ export interface RenderAceContextOptions {
     workspace: string;
     tier?: AceContextTier;
     tools?: string[];
+    modelClass?: string;
+    model?: string;
 }
 export interface RenderAceContextResult {
     systemPrompt: string;
@@ -14,6 +16,7 @@ export interface RenderAceContextResult {
     stateDigest: string;
     tokenEstimate: number;
     tier: AceContextTier;
+    injected_ids: string[];
 }
 export interface ToolPlanResult {
     prompt: string;
@@ -21,9 +24,24 @@ export interface ToolPlanResult {
     recommended_tools: string[];
     selection_limit: number;
 }
+export declare const ROLE_TOOL_DEFAULTS: Record<string, string[]>;
 export declare function renderAceRecallPromptBlock(recall?: ReturnType<typeof buildAceRecallContext>, includeSlices?: boolean): string;
 export declare function renderAceSnapshotPromptBlock(recall?: ReturnType<typeof buildAceRecallContext>): string;
 export declare function renderAceContinuityPromptBlock(packet?: ReturnType<typeof buildAceContinuityPacket>): string;
 export declare function buildToolPlan(options: RenderAceContextOptions): ToolPlanResult;
+export declare function renderPlaybookBlock(input: {
+    workspace: string;
+    role: string;
+    modelClass?: string;
+    model?: string;
+    tier: AceContextTier;
+    config?: {
+        enabled?: boolean;
+        budgetChars?: number;
+    };
+}): {
+    text: string;
+    injected_ids: string[];
+};
 export declare function renderAceContext(options: RenderAceContextOptions): RenderAceContextResult;
 //# sourceMappingURL=ace-context.d.ts.map

package/dist/ace-context.js

@@ -2,7 +2,8 @@ import { buildAceContinuityPacket, buildAceRecallContext, formatAceContinuityPac
 import { listAceInternalToolCatalog, } from "./ace-internal-tools.js";
 import { ALL_AGENTS, listAvailableSkills, readAgentInstructions } from "./helpers.js";
 import { readRuntimeProfileState, renderRuntimePrompt } from "./runtime-profile.js";
-const ROLE_TOOL_DEFAULTS = {
+import { PlaybookRepository, } from "./store/repositories/playbook-repository.js";
+export const ROLE_TOOL_DEFAULTS = {
     orchestrator: [
         "recall_context",
         "validate_framework",
@@ -16,6 +17,10 @@ const ROLE_TOOL_DEFAULTS = {
         "enqueue_job",
         "dispatch_jobs",
         "list_jobs",
+        "start_goal",
+        "get_goal_status",
+        "stop_goal",
+        "resume_goal",
         "execute_gates",
         "context_snapshot",
         "append_vericify_process_post",
@@ -37,6 +42,22 @@ const ROLE_TOOL_DEFAULTS = {
         "execute_gates",
         "append_vericify_process_post",
     ],
+    builder: [
+        "outline_file",
+        "astgrep_query",
+        "astgrep_locate",
+        "read_file_lines",
+        "compile_structural_edit",
+        "preview_structural_edit",
+        "astgrep_rewrite",
+        "safe_edit_file",
+        "write_workspace_file",
+        "run_tests",
+        "git_diff",
+        "git_status",
+        "execute_gates",
+        "append_vericify_process_post",
+    ],
     qa: [
         "read_workspace_file",
         "run_tests",
@@ -128,7 +149,11 @@ function scopeTools(role, task, tier, explicitTools) {
     const defaultTools = ROLE_TOOL_DEFAULTS[role.trim().toLowerCase()] ?? [];
     const roleDefaults = new Set(defaultTools);
     const rolePriority = new Map(defaultTools.map((name, index) => [name, index]));
-    const ranked = catalog
+    // Keyword rank is used ONLY to SELECT which tools survive the tier budget
+    // (E17): the marginal non-default tools most relevant to the task make the
+    // cut. The RENDER order is then re-stabilized below so the same role emits a
+    // byte-identical catalog across the steps of one plan (prefix-cache reuse).
+    const selected = catalog
         .map((tool) => ({
         tool,
         score: (roleDefaults.has(tool.name) ? 5 : 0) + keywordScore(task, tool),
@@ -140,8 +165,12 @@ function scopeTools(role, task, tier, explicitTools) {
         left.tool.name.localeCompare(right.tool.name))
         .slice(0, selectToolCount(tier))
         .map((entry) => entry.tool);
-    if (ranked.length > 0 && ranked.some((tool) => roleDefaults.has(tool.name))) {
-        return ranked;
+    // Stable render order: role-default tools first in their declared priority,
+    // then everything else alphabetically — independent of task keywords.
+    const stableOrder = (name) => rolePriority.has(name) ? (rolePriority.get(name) ?? 0) : Number.MAX_SAFE_INTEGER;
+    const stable = [...selected].sort((a, b) => stableOrder(a.name) - stableOrder(b.name) || a.name.localeCompare(b.name));
+    if (stable.length > 0 && stable.some((tool) => roleDefaults.has(tool.name))) {
+        return stable;
     }
     return catalog.slice(0, selectToolCount(tier));
 }
@@ -238,6 +267,7 @@ const ROLE_OUTPUT_SHAPE_GUARDRAILS = {
         "- If you bypass the structural lane for code, state the waiver reason and provide evidence_refs.",
         "- Do NOT echo the task description or expected artifact shape as your response without executing via tool calls.",
         "- If you are writing files, call the write tool first, then close with status:complete and evidence_refs.",
+        "- Never emit status:complete while any expected artifact or required evidence is missing — report status:message with the remaining work, or status:need_input if blocked.",
     ],
     builder: [
         "- Your bridge response MUST be a JSON envelope — raw prose as the top-level reply is a contract violation.",
@@ -247,6 +277,7 @@ const ROLE_OUTPUT_SHAPE_GUARDRAILS = {
         "- Do NOT echo the artifact shape without executing the build step via tool calls.",
         "- File content (code, HTML, configs) belongs inside tool calls, not in raw text output.",
         "- If you are writing files, close with status:complete and evidence_refs after the write tool succeeds.",
+        "- Never emit status:complete while any expected artifact or required evidence is missing — report status:message with the remaining work, or status:need_input if blocked.",
     ],
     vos: [
         "- Your primary output is prose. Inline code snippets or JSON examples are acceptable when illustrating a point.",
@@ -259,8 +290,93 @@ const ROLE_OUTPUT_SHAPE_GUARDRAILS = {
         "- Do not emit large raw JSON blobs as your main output; summarize or reference them instead.",
     ],
 };
+const PLAYBOOK_SECTIONS = ["strategies", "tool_usage", "failure_modes", "verification", "env_facts"];
+function playbookEnabled() {
+    const raw = String(process.env.ACE_PLAYBOOK ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+function playbookBudgetChars(tier) {
+    const env = Number(process.env.ACE_PLAYBOOK_INJECT_BUDGET_CHARS);
+    if (Number.isFinite(env) && env > 0)
+        return Math.floor(env);
+    if (tier === "brief")
+        return 1200;
+    if (tier === "compressed")
+        return 2400;
+    return 6000;
+}
+function playbookScopeMatches(bullet, input) {
+    const scope = bullet.scope ?? {};
+    if (scope.role !== undefined && scope.role !== input.role)
+        return false;
+    if (scope.model_class !== undefined && scope.model_class !== input.modelClass)
+        return false;
+    if (scope.model !== undefined && scope.model !== input.model)
+        return false;
+    // Tool/reason-code scoped bullets are not generally injectable without a current tool/failure context.
+    if (scope.tool !== undefined || scope.reason_code !== undefined)
+        return false;
+    return true;
+}
+function playbookRank(left, right) {
+    return (right.helpful_count - right.harmful_count - (left.helpful_count - left.harmful_count) ||
+        right.observed_count - left.observed_count ||
+        (left.updated_at < right.updated_at ? 1 : left.updated_at > right.updated_at ? -1 : 0) ||
+        left.bullet_id.localeCompare(right.bullet_id));
+}
+export function renderPlaybookBlock(input) {
+    const enabled = input.config?.enabled ?? playbookEnabled();
+    if (!enabled)
+        return { text: "", injected_ids: [] };
+    const budget = input.config?.budgetChars ?? playbookBudgetChars(input.tier);
+    const repo = new PlaybookRepository(input.workspace);
+    const selected = repo
+        .listBullets({ status: "active" })
+        .filter((bullet) => playbookScopeMatches(bullet, input))
+        .sort(playbookRank);
+    const packed = [];
+    let used = 0;
+    for (const bullet of selected) {
+        const line = `- [${bullet.bullet_id}] ${bullet.content}`;
+        const nextCost = line.length + 1;
+        if (packed.length > 0 && used + nextCost > budget)
+            continue;
+        if (packed.length === 0 && nextCost > budget)
+            continue;
+        packed.push(bullet);
+        used += nextCost;
+    }
+    if (packed.length === 0)
+        return { text: "", injected_ids: [] };
+    const renderPacked = (bulletsToRender) => {
+        const lines = [];
+        for (const section of PLAYBOOK_SECTIONS) {
+            const bullets = bulletsToRender
+                .filter((bullet) => bullet.section === section)
+                .sort((a, b) => a.bullet_id.localeCompare(b.bullet_id));
+            if (bullets.length === 0)
+                continue;
+            lines.push(`### ${section}`);
+            for (const bullet of bullets) {
+                lines.push(`- [${bullet.bullet_id}] ${bullet.content}`);
+            }
+        }
+        return lines.join("\n");
+    };
+    while (packed.length > 0 && renderPacked(packed).length > budget) {
+        packed.pop();
+    }
+    if (packed.length === 0)
+        return { text: "", injected_ids: [] };
+    const text = renderPacked(packed);
+    return {
+        text,
+        injected_ids: packed.map((bullet) => bullet.bullet_id),
+    };
+}
 export function renderAceContext(options) {
     const tier = options.tier ?? "compressed";
+    const role = options.role.trim().toLowerCase().replace(/^agent-/, "");
     const active = readRuntimeProfileState();
     const autonomy = normalizeAutonomyPolicy(active.profile.autonomy);
     const continuity = normalizeContinuityPolicy(active.profile.continuity);
@@ -272,7 +388,7 @@ export function renderAceContext(options) {
             policy: continuity,
         })
         : undefined;
-    const tools = scopeTools(options.role, options.task, tier, options.tools);
+    const tools = scopeTools(role, options.task, tier, options.tools);
     const runtimePrompt = renderRuntimePrompt({
         task: options.task,
         workspace_path: options.workspace,
@@ -282,15 +398,34 @@ export function renderAceContext(options) {
         ace_context_snapshot_md: renderAceSnapshotPromptBlock(recall),
         ace_continuity_packet_md: renderAceContinuityPromptBlock(continuityPacket),
     });
-    const roleInstructions = resolveRoleInstructions(options.role);
+    const roleInstructions = resolveRoleInstructions(role);
     const toolCatalog = renderToolCatalogMarkdown(tools, tier);
     const stateDigest = recall.task_contract.summary;
     const relevantSkills = inferRelevantSkills(options.task);
-    const systemPrompt = [
-        runtimePrompt,
-        "",
+    const playbook = renderPlaybookBlock({
+        workspace: options.workspace,
+        role,
+        modelClass: options.modelClass,
+        model: options.model,
+        tier,
+    });
+    const playbookBlock = playbook.text
+        ? [
+            "## Learned Playbook (advisory — follow unless it conflicts with the task or guardrails)",
+            playbook.text,
+            "",
+        ]
+        : [];
+    // Prompt-prefix ordering (E16/E17): emit the STABLE block first — role
+    // instructions, tool catalog (stable role-keyed order), guardrails, output
+    // contract — so llama.cpp/Ollama prefix caching reuses it byte-for-byte
+    // across the steps of a plan. The VOLATILE tail (task, recall snapshot,
+    // continuity, timestamp via runtimePrompt; plus task-derived skills) comes
+    // last, which is also better for small-model recency (task sits adjacent to
+    // generation).
+    const stableBlock = [
         "## Active Role",
-        `- Role: ${options.role}`,
+        `- Role: ${role}`,
         "",
         "## Role Instructions",
         roleInstructions,
@@ -298,24 +433,33 @@ 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.",
         "- For obviously multi-step work, prefer run_orchestrator over a single free-form answer.",
         "- When you mutate workspace, use the smallest safe mutation lane: structural edit for existing code, write_workspace_file for new/generated artifacts; never assert file creation in prose alone.",
         "- Do not declare completion while approval, retry, or blocker state remains active.",
-        ...(ROLE_OUTPUT_SHAPE_GUARDRAILS[options.role.trim().toLowerCase()] ?? []),
+        ...(ROLE_OUTPUT_SHAPE_GUARDRAILS[role] ?? []),
         "",
+        ...playbookBlock,
         "## Output Contract",
-        'Respond in JSON only with one of these shapes:',
+        "You may reason briefly in plain text before the JSON envelope, but the final machine-readable response must be one JSON object.",
+        'Keep the JSON `thinking` field to one short line. Respond with one of these shapes:',
         '- `{"status":"tool","thinking":"...","tool_calls":[{"tool":"name","input":{}}]}`',
         '- `{"status":"message","thinking":"...","message":"..."}`',
         '- `{"status":"complete","thinking":"...","summary":"...","evidence_refs":["agent-state/..."]}`',
         '- `{"status":"need_input","thinking":"...","message":"..."}`',
-    ].join("\n");
+        ...(playbook.injected_ids.length > 0
+            ? ['When a learned playbook bullet materially helped your message or completion, include `"used_bullets":["pb-..."]` with injected ids only.']
+            : []),
+    ];
+    const volatileTail = [
+        runtimePrompt,
+        "",
+        "## Relevant Skills",
+        relevantSkills.length > 0 ? `- ${relevantSkills.join(", ")}` : "- No task-specific skill hint matched.",
+    ];
+    const systemPrompt = [...stableBlock, "", ...volatileTail].join("\n");
     return {
         systemPrompt,
         tools,
@@ -323,6 +467,7 @@ export function renderAceContext(options) {
         // TODO: replace with model-aware token counting when context window management lands.
         tokenEstimate: Math.max(1, Math.ceil(systemPrompt.length / 4)),
         tier,
+        injected_ids: playbook.injected_ids,
     };
 }
 //# sourceMappingURL=ace-context.js.map

package/dist/ace-server-instructions.js

@@ -57,6 +57,8 @@ const MUTATION_PREFIXES = [
     "update_",
     "write_",
 ];
+const DIGEST_CACHE_TTL_MS = 60_000;
+const digestCache = new Map();
 function readIfPresent(filePath) {
     if (!existsSync(filePath))
         return undefined;
@@ -188,6 +190,15 @@ export function buildAceDigest(workspaceRoot) {
     ].filter((value) => Boolean(value));
     return parts.length > 0 ? parts.join(" | ") : "ACE state detected; load recall_context for task and status.";
 }
+function buildAceDigestCached(workspaceRoot) {
+    const now = Date.now();
+    const cached = digestCache.get(workspaceRoot);
+    if (cached && cached.expiresAt > now)
+        return cached.value;
+    const value = buildAceDigest(workspaceRoot);
+    digestCache.set(workspaceRoot, { value, expiresAt: now + DIGEST_CACHE_TTL_MS });
+    return value;
+}
 export function buildServerInstructions(workspaceRoot) {
     const coreFiles = listExistingCoreFiles(workspaceRoot);
     const stateDirs = listExistingStateDirs(workspaceRoot);
@@ -196,10 +207,11 @@ export function buildServerInstructions(workspaceRoot) {
     const lines = [
         "You are operating in an ACE-governed workspace.",
         coreFiles.length > 0
-            ? `Ground truth lives in ${coreFiles.join(", ")}.`
-            : `Ground truth lives in ${ACE_ROOT_REL}/agent-state/* artifacts, not chat history.`,
+            ? `Ground truth for task/status/scope/evidence is store-backed under ${coreFiles.join(", ")} (canonical store: ${ACE_ROOT_REL}/agent-state/ace-state.ace).`
+            : `Ground truth is store-backed under ${ACE_ROOT_REL}/agent-state/* artifacts (canonical store: ${ACE_ROOT_REL}/agent-state/ace-state.ace), not chat history.`,
+        "`ace compact` and the automatic lifecycle sweep intentionally remove the loose agent-state/*.md files from disk after folding them into the store — this is expected, not data loss. Read them back with `ace read agent-state/TASK.md` (or the read_workspace_file / recall_context MCP tools); never recreate swept files.",
         stateDirs.length > 0
-            ? `Durable artifacts belong under ${stateDirs.map((entry) => `${entry}/`).join(", ")}.`
+            ? `Durable artifacts belong under ${stateDirs.map((entry) => `${entry}/`).join(", ")} and are persisted into the store; the loose copies are sweep inputs, not the source of truth.`
             : undefined,
         "Before significant work, call recall_context to load current task, scope, and status.",
         "Use route_task and get_agent_instructions for role guidance; do not self-assign by guesswork.",
@@ -224,13 +236,15 @@ export function buildHostInstructionText(host, workspaceRoot) {
         "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.",
+        "1. Call `recall_context` to load task, scope, and status through the ACE MCP server.",
         "2. Call `route_task` and `get_agent_instructions` before choosing a role.",
         "3. Prefer ACE prompts/resources (`ace-orchestrator`, `get_task_pack`, `get_skill_instructions`) over relying on this file.",
+        "4. Read/write task state through MCP tools (`recall_context`, `read_workspace_file`, `write_workspace_file`, lifecycle append tools); do not create files under `agent-state/` directly.",
         "",
         "Ground truth:",
-        "- `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.",
+        "- ACE MCP tools are the authoritative interface for task state and lifecycle updates.",
+        "- `agent-state/ace-state.ace` is the canonical store path; visible `agent-state/*` files are compatibility projections or sweep inputs.",
+        "- `ace compact` and the automatic lifecycle sweep intentionally remove loose `agent-state/*` files from disk after folding them into the store — this is expected, not data loss. Do NOT recreate them; retrieve their content via `ace read <path>` or the `read_workspace_file` / `recall_context` MCP tools.",
         "- `.agents/ACE/tasks/todo.md` is the human-facing todo surface.",
         "- Hook context is store-backed in `agent-state/ace-state.ace` and consumed without extra workspace projections.",
         "",
@@ -241,26 +255,26 @@ export function buildBootstrapNudge(workspaceRoot) {
     const coreFiles = listExistingCoreFiles(workspaceRoot);
     return [
         "ACE bootstrap hint: call `recall_context` before significant work so task and scope come from file-backed state.",
-        `ACE digest: ${buildAceDigest(workspaceRoot)}.`,
+        `ACE digest: ${buildAceDigestCached(workspaceRoot)}.`,
         coreFiles.length > 0 ? `Current core files: ${coreFiles.join(", ")}.` : undefined,
     ]
         .filter((value) => Boolean(value))
         .join(" ");
 }
 export function buildBootstrapGuidance(workspaceRoot, toolName) {
-    return `ACE context loaded via \`${toolName}\`. Current digest: ${buildAceDigest(workspaceRoot)}.`;
+    return `ACE context loaded via \`${toolName}\`. Current digest: ${buildAceDigestCached(workspaceRoot)}.`;
 }
 export function buildMutationGuidance(workspaceRoot, toolName) {
     const evidencePath = displayWorkspacePath(workspaceRoot, "agent-state/EVIDENCE_LOG.md");
     return [
-        `ACE digest after \`${toolName}\`: ${buildAceDigest(workspaceRoot)}.`,
+        `ACE digest after \`${toolName}\`: ${buildAceDigestCached(workspaceRoot)}.`,
         `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) {
     return [
         `ACE snapshot refresh completed via \`${toolName}\`.`,
-        `Current digest: ${buildAceDigest(workspaceRoot)}.`,
+        `Current digest: ${buildAceDigestCached(workspaceRoot)}.`,
     ].join(" ");
 }
 function isBootstrapTool(toolName) {
@@ -298,6 +312,8 @@ function isCallToolResult(value) {
 }
 export function installAceToolGovernance(server, workspaceRoot) {
     const bootstrappedSessions = new Set();
+    const bootstrapNudgeCounts = new Map();
+    const mutationGuidanceState = new Map();
     const wrapToolCallback = (toolName, callback) => async (...args) => {
         const extra = args.at(-1);
         const sessionId = typeof extra?.sessionId === "string" ? extra.sessionId : undefined;
@@ -311,7 +327,11 @@ export function installAceToolGovernance(server, workspaceRoot) {
         }
         let next = rawResult;
         if (sessionId && !bootstrappedSessions.has(sessionId) && !isBootstrapTool(toolName)) {
-            next = appendTextContent(next, buildBootstrapNudge(workspaceRoot));
+            const callCount = (bootstrapNudgeCounts.get(sessionId) ?? 0) + 1;
+            bootstrapNudgeCounts.set(sessionId, callCount);
+            if (callCount === 1 || callCount % 10 === 0) {
+                next = appendTextContent(next, buildBootstrapNudge(workspaceRoot));
+            }
         }
         if (isBootstrapTool(toolName)) {
             next = appendTextContent(next, buildBootstrapGuidance(workspaceRoot, toolName));
@@ -320,7 +340,16 @@ export function installAceToolGovernance(server, workspaceRoot) {
             next = appendTextContent(next, buildRefreshGuidance(workspaceRoot, toolName));
         }
         else if (isMutationTool(toolName)) {
-            next = appendTextContent(next, buildMutationGuidance(workspaceRoot, toolName));
+            const mutationKey = sessionId ?? "__global__";
+            const currentDigest = buildAceDigestCached(workspaceRoot);
+            const state = mutationGuidanceState.get(mutationKey) ?? { count: 0 };
+            state.count += 1;
+            const shouldAppend = state.lastDigest === undefined || state.lastDigest !== currentDigest || state.count % 10 === 0;
+            state.lastDigest = currentDigest;
+            mutationGuidanceState.set(mutationKey, state);
+            if (shouldAppend) {
+                next = appendTextContent(next, buildMutationGuidance(workspaceRoot, toolName));
+            }
         }
         return next;
     };

package/dist/bridge-trace.d.ts

@@ -0,0 +1,17 @@
+import type { BridgeUsageTotals } from "./model-bridge.js";
+export interface BridgeTraceLine {
+    turn: number;
+    envelope_status: string;
+    parse_repairs: number;
+    drift_repairs: number;
+    tool_calls: Array<{
+        tool: string;
+        ok: boolean;
+        reason_code?: string;
+    }>;
+    usage?: BridgeUsageTotals;
+    compressed?: boolean;
+}
+export declare function bridgeTracePath(workspaceRoot: string, runId: string): string;
+export declare function readBridgeTrace(workspaceRoot: string, runId: string): BridgeTraceLine[];
+//# sourceMappingURL=bridge-trace.d.ts.map

package/dist/bridge-trace.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+export function bridgeTracePath(workspaceRoot, runId) {
+    const safeRunId = runId.replace(/[^a-zA-Z0-9_.-]/g, "_");
+    return resolve(workspaceRoot, "agent-state", "bridge-traces", `${safeRunId}.ndjson`);
+}
+export function readBridgeTrace(workspaceRoot, runId) {
+    const path = bridgeTracePath(workspaceRoot, runId);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+//# sourceMappingURL=bridge-trace.js.map

package/dist/cli.d.ts

@@ -1,3 +1,11 @@
 #!/usr/bin/env node
-export {};
+/**
+ * Positional arguments, with value-taking flags and their values removed.
+ * A bare `.filter(a => !a.startsWith("--"))` drops the flag but keeps its value,
+ * which silently folds `--budget-hours 2` into a goal objective. Supports both
+ * `--flag value` and `--flag=value`, plus `--` as an end-of-flags separator.
+ */
+export declare function positionalArgs(args: readonly string[], valueFlags: ReadonlySet<string>): string[];
+export declare const GOAL_VALUE_FLAGS: ReadonlySet<string>;
+export declare const PLAYBOOK_ADD_VALUE_FLAGS: ReadonlySet<string>;
 //# sourceMappingURL=cli.d.ts.map