@voybio/ace-swarm 2.4.3 → 2.4.6

package/dist/tools-handoff.js

@@ -3,7 +3,8 @@
  */
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
-import { ACE_TASKS_ROOT_REL, normalizePathForValidation, readTaskArtifact, safeWriteAsync, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
+import { ACE_TASKS_ROOT_REL, readTaskArtifact, WORKSPACE_ROOT, } from "./helpers.js";
+import { writeStoreBlobQueued } from "./store/store-artifacts.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";
@@ -241,13 +242,8 @@ export function registerHandoffTools(server) {
                 ],
             };
         }
-        const timeStr = now
-            .toISOString()
-            .replace(/[-:]/g, "")
-            .replace("T", "-")
-            .slice(0, 15);
-        const filePath = wsPath("tasks", `SWARM_HANDOFF.${from}_to_${to}_${timeStr}_${shortId}.json`);
-        await safeWriteAsync(filePath, JSON.stringify(handoff, null, 2));
+        const payloadStoreKey = `state/handoffs/payloads/${handoff.handoff_id}.json`;
+        const payloadPath = await writeStoreBlobQueued(WORKSPACE_ROOT, payloadStoreKey, JSON.stringify(handoff, null, 2), { operation_label: "create_handoff.payload" });
         const registry = await registerHandoffSafe({
             handoff_id: handoff.handoff_id,
             from: handoff.router.from,
@@ -255,14 +251,14 @@ export function registerHandoffTools(server) {
             title: handoff.task.title,
             task_type: handoff.task.type,
             priority: handoff.task.priority,
-            source_file: normalizePathForValidation(filePath),
+            source_file: payloadPath,
         });
         const runLedger = await appendRunLedgerEntrySafe({
             tool: "create_handoff",
             category: "major_update",
             message: `Created handoff ${handoff.handoff_id} (${handoff.router.from} -> ${handoff.router.to})`,
             artifacts: [
-                normalizePathForValidation(filePath),
+                payloadPath,
                 "agent-state/handoff-registry.json",
             ],
             metadata: {
@@ -282,7 +278,7 @@ export function registerHandoffTools(server) {
                         "# Handoff Created",
                         "",
                         `Schema: ${validation.schema}`,
-                        `Saved to: ${filePath}`,
+                        `Saved to: ${payloadPath}`,
                         `Handoff registry: ${registry.path}`,
                         `Run ledger: ${runLedger.path} (${runLedger.entry.id})`,
                         `Scheduler job: ${schedulerSync.job_id} (${schedulerSync.enqueued ? "enqueued" : "already_exists"})`,

package/dist/tools-lifecycle.js

@@ -194,6 +194,8 @@ export function registerLifecycleTools(server) {
                         "",
                         `JSON: ${snapshot.json_path}`,
                         `HTML: ${snapshot.html_path}`,
+                        `Read: ace read agent-state/kanban.json`,
+                        `Open: ace read agent-state/kanban.html --out /tmp/ace-kanban.html && open /tmp/ace-kanban.html`,
                         `Updated: ${snapshot.generated_at}`,
                         `Counts: backlog=${snapshot.counts.backlog}, blocked=${snapshot.counts.blocked}, in_progress=${snapshot.counts.in_progress}, gated=${snapshot.counts.gated}, done=${snapshot.counts.done}`,
                     ].join("\n"),

package/dist/tools-scheduler.js

@@ -2,7 +2,7 @@
  * Job scheduler tool registrations.
  */
 import { z } from "zod";
-import { acknowledgeJob, completeJob, dispatchJobNow, dispatchJobs, enqueueJob, getJobLockTablePath, getJobQueuePath, getSchedulerLeasePath, readJobQueue, readJobLockTable, readSchedulerLease, } from "./job-scheduler.js";
+import { acknowledgeJob, completeJob, dispatchJobNow, dispatchJobs, enqueueJob, getJobLockTablePath, getJobQueuePath, getSchedulerLeasePath, heartbeatJob, reapStaleRunningJobsTick, readJobQueue, readJobLockTable, readSchedulerLease, } from "./job-scheduler.js";
 // Event emission handled in core job-scheduler.ts — no wrapper duplication.
 const PRIORITY_BAND_ENUM = z.enum(["P0", "P1", "P2", "P3"]);
 const JOB_STATUS_ENUM = z.enum([
@@ -196,6 +196,49 @@ export function registerSchedulerTools(server) {
             ],
         };
     });
+    server.tool("heartbeat_job", "Prove liveness for a running job so the heartbeat watchdog does not reap it; renews the owner lease", {
+        job_id: z.string(),
+        owner: z.string().optional().describe("Lease owner identity (defaults to capability-ops)"),
+        lease_ttl_seconds: z.number().int().min(5).max(3600).optional(),
+        now_iso: z.string().optional().describe("Optional deterministic clock override"),
+    }, async ({ job_id, owner, lease_ttl_seconds, now_iso }) => {
+        const result = await heartbeatJob({ job_id, owner, lease_ttl_seconds, now_iso });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? ["✅ Job heartbeat recorded", asJsonBlock(result)].join("\n")
+                        : ["❌ heartbeat_job failed", result.error ?? "Unknown error", asJsonBlock(result)].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("reap_stale_jobs", "Run the heartbeat watchdog once: move running jobs with a stale worker heartbeat into unknown_recovery and release their locks", {
+        heartbeat_stale_seconds: z
+            .number()
+            .int()
+            .min(1)
+            .max(86_400)
+            .optional()
+            .describe("Staleness window in seconds (default 120)"),
+        now_iso: z.string().optional().describe("Optional deterministic clock override"),
+    }, async ({ heartbeat_stale_seconds, now_iso }) => {
+        const result = await reapStaleRunningJobsTick({ heartbeat_stale_seconds, now_iso });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        result.reaped_jobs > 0
+                            ? `🩺 Watchdog reaped ${result.reaped_jobs} stale job(s)`
+                            : "🩺 Watchdog found no stale running jobs",
+                        asJsonBlock(result),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
     server.tool("get_lock_table", "Read the scheduler lock table", {}, async () => ({
         content: [
             {

package/dist/tools-skills.js

@@ -49,9 +49,10 @@ export function registerSkillTools(server) {
             .describe("Optional workspace-relative path for the audit report"),
     }, async ({ write_artifact, artifact_path }) => {
         const result = auditSkillCatalog();
+        const artifactPath = artifact_path || "agent-state/SKILL_AUDIT_REPORT.md";
         const writtenPath = write_artifact === false
             ? undefined
-            : writeSkillAuditReport(result, artifact_path || "agent-state/SKILL_AUDIT_REPORT.md");
+            : writeSkillAuditReport(result, artifactPath);
         const failCount = result.entries.filter((entry) => entry.status === "fail").length;
         const warnCount = result.entries.filter((entry) => entry.status === "warn").length;
         return {
@@ -62,7 +63,7 @@ export function registerSkillTools(server) {
                         `Portable-contract-ready skills: ${result.summary.portable_contract_ready_skills}/${result.summary.total_skills}`,
                         `Fail/Warn: ${failCount}/${warnCount}`,
                         ...(result.rollout_backlog.slice(0, 5).map((line) => `- ${line}`)),
-                        ...(writtenPath ? [`- Artifact written: ${writtenPath}`] : []),
+                        ...(writtenPath ? [`- Artifact: ${artifactPath}`, `- Read: ace read ${artifactPath}`, `- Store path: ${writtenPath}`] : []),
                     ].join("\n"),
                 },
             ],

package/dist/tools-todo.js

@@ -4,7 +4,7 @@
 import { z } from "zod";
 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 { appendTodoItemSafe, getTodoStatePath, readTodoState, syncTodoStateSafe, transitionTodoNodeSafe, } from "./todo-state.js";
 import { appendRunLedgerEntrySafe, getRunLedgerPath, readRunLedger, } from "./run-ledger.js";
 import { refreshKanbanArtifacts } from "./kanban.js";
 export function registerTodoTools(server) {
@@ -19,7 +19,7 @@ export function registerTodoTools(server) {
             },
         ],
     }));
-    server.tool("update_todo", "Replace TODO board content or transition a TODO node status with gate validation", {
+    server.tool("update_todo", "Replace TODO board content, append a new TODO item, or transition a TODO node status with gate validation", {
         new_content: z
             .string()
             .optional()
@@ -30,7 +30,68 @@ export function registerTodoTools(server) {
             .describe("Todo node id to transition (transition mode)"),
         status: TODO_STATUS_ENUM.optional().describe("Target status for transition mode"),
         note: z.string().optional().describe("Optional transition context note"),
-    }, async ({ new_content, node_id, status, note }) => {
+        append_title: z
+            .string()
+            .optional()
+            .describe("Title for a new TODO item to append atomically (append mode). Prefer this over " +
+            "new_content when adding a single item — it is safe under concurrent callers, " +
+            "unlike a read-then-full-replace round trip."),
+        append_section: z
+            .string()
+            .optional()
+            .describe("Section heading to append the new item under (default: Active Work)"),
+        append_depends_on: z
+            .array(z.string())
+            .optional()
+            .describe("Node ids the new append-mode item depends on"),
+        append_id: z
+            .string()
+            .optional()
+            .describe("Optional explicit node id for the new append-mode item"),
+    }, async ({ new_content, node_id, status, note, append_title, append_section, append_depends_on, append_id, }) => {
+        if (typeof append_title === "string") {
+            const appended = await appendTodoItemSafe(append_title, {
+                section: append_section,
+                depends_on: append_depends_on,
+                id: append_id,
+            });
+            if (!appended.ok) {
+                return {
+                    content: [
+                        { type: "text", text: `❌ ${appended.error ?? "Failed to append TODO item."}` },
+                    ],
+                };
+            }
+            const runLedger = await appendRunLedgerEntrySafe({
+                tool: "update_todo",
+                category: "info",
+                message: `Appended TODO item ${appended.node_id}`,
+                artifacts: [`${ACE_TASKS_ROOT_REL}/todo.md`, "agent-state/todo-state.json"],
+                metadata: {
+                    mode: "append",
+                    node_id: appended.node_id,
+                    section: appended.section,
+                },
+            });
+            const kanban = refreshKanbanArtifacts("tool:update_todo");
+            const counts = kanban.counts;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `✅ TODO item appended: ${appended.node_id}`,
+                            `Section: ${appended.section}`,
+                            `TODO state: ${appended.path}`,
+                            `TODO markdown: ${appended.todo_path}`,
+                            `Run ledger: ${runLedger.path} (${runLedger.entry.id})`,
+                            `Kanban updated: ${kanban.html_path}`,
+                            `Kanban counts: backlog=${counts.backlog}, blocked=${counts.blocked}, in_progress=${counts.in_progress}, gated=${counts.gated}, done=${counts.done}`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
         if (typeof new_content === "string") {
             const synced = await syncTodoStateSafe(new_content);
             const path = await safeWriteAsync(resolveWritableTaskPath("todo"), new_content);

package/dist/tools.js

@@ -15,6 +15,7 @@ import { registerGitTools } from "./tools-git.js";
 import { registerMemoryTools } from "./tools-memory.js";
 import { registerDriftTools } from "./tools-drift.js";
 import { registerSchedulerTools } from "./tools-scheduler.js";
+import { registerGoalTools } from "./tools-goal.js";
 import { registerSkillTools } from "./tools-skills.js";
 const TOOL_REGISTRARS = [
     registerAgentTools,
@@ -28,6 +29,7 @@ const TOOL_REGISTRARS = [
     registerMemoryTools,
     registerDriftTools,
     registerSchedulerTools,
+    registerGoalTools,
     registerSkillTools,
 ];
 function createAllowlistedServer(server, allowed) {

package/dist/tui/chat.js

@@ -243,6 +243,10 @@ export class ChatSession extends EventEmitter {
         const activeProvider = this.activeStreamProvider ?? this.provider;
         this.streaming = false;
         if (this.activeAceBridge) {
+            if (this.executionEngine === "hermes_local") {
+                this.hermesExecutor?.interrupt?.();
+                return;
+            }
             this.aceBridge.interrupt();
             return;
         }

package/dist/tui/index.js

@@ -190,7 +190,7 @@ export class AceTui {
         });
         // Handle signals
         process.on("SIGINT", () => {
-            // Ctrl+C during streaming → interrupt; otherwise offer quit
+            // Ctrl+C interrupts an active stream; while idle it is deliberately a no-op.
             if (this.activeChatSession?.isStreaming()) {
                 this.activeChatSession.interrupt();
             }
@@ -332,6 +332,9 @@ export class AceTui {
                 case "w":
                     this.closeCurrentTab();
                     return;
+                case "z":
+                    this.suspend();
+                    return;
             }
         }
         // Alt+number → switch tab

package/dist/tui/ollama.d.ts

@@ -36,6 +36,8 @@ export interface ChatRequest {
     model: string;
     messages: ChatMessage[];
     stream?: boolean;
+    /** "json" for generic JSON mode; a JSON Schema object for schema-constrained generation (Ollama ≥ 0.5). */
+    format?: "json" | Record<string, unknown> | string;
     options?: {
         temperature?: number;
         top_p?: number;

package/dist/tui/openai-compatible.d.ts

@@ -15,6 +15,19 @@ export interface OpenAICompatibleChatRequest {
     messages: OpenAICompatibleChatMessage[];
     temperature?: number;
     topP?: number;
+    maxTokens?: number;
+    responseFormat?: {
+        type: "json_object";
+    } | {
+        type: "json_schema";
+        json_schema: {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean;
+        };
+    } | {
+        type: string;
+    };
     onProviderEvent?: (event: OpenAICompatibleProviderEvent) => void;
 }
 export interface OpenAICompatibleChatChunk {
@@ -66,6 +79,7 @@ export declare class OpenAICompatibleClient {
     private resolveProviderConfig;
     private streamSseData;
 }
+export declare const ANTHROPIC_OPENAI_COMPATIBLE_BASE_URL = "https://api.anthropic.com/v1";
 /**
  * Resolve a GitHub / Copilot token from the environment or `gh` CLI.
  * Checks: GITHUB_TOKEN → GH_TOKEN → `gh auth token` (sync exec).

package/dist/tui/openai-compatible.js

@@ -172,6 +172,8 @@ export class OpenAICompatibleClient {
                         stream: true,
                         temperature: request.temperature,
                         top_p: request.topP,
+                        max_tokens: request.maxTokens,
+                        ...(request.responseFormat ? { response_format: request.responseFormat } : {}),
                     };
                     const streamRes = await fetch(`${config.baseUrl}/chat/completions`, {
                         method: "POST",
@@ -263,6 +265,8 @@ export class OpenAICompatibleClient {
                         stream: false,
                         temperature: request.temperature,
                         top_p: request.topP,
+                        max_tokens: request.maxTokens,
+                        ...(request.responseFormat ? { response_format: request.responseFormat } : {}),
                     };
                     const res = await fetch(`${config.baseUrl}/chat/completions`, {
                         method: "POST",
@@ -348,6 +352,8 @@ export class OpenAICompatibleClient {
                 stream: true,
                 temperature: request.temperature,
                 top_p: request.topP,
+                max_tokens: request.maxTokens,
+                ...(request.responseFormat ? { response_format: request.responseFormat } : {}),
             };
             // llama.cpp rejects custom stream_options; only include for non-llama providers
             if (provider !== 'llama.cpp') {
@@ -485,7 +491,10 @@ export class OpenAICompatibleClient {
             const apiKey = override?.apiKey || providerKey || genericKey || process.env.CODEX_API_KEY?.trim();
             return { provider, baseUrl, apiKey, headers: override?.headers };
         }
-        const resolvedBaseUrl = override?.baseUrl || providerBase || genericBase || "";
+        const resolvedBaseUrl = override?.baseUrl ||
+            providerBase ||
+            genericBase ||
+            (provider === "claude" ? ANTHROPIC_OPENAI_COMPATIBLE_BASE_URL : "");
         const baseUrl = provider === "llama.cpp"
             ? buildOpenAiCompatibleBaseUrl(resolvedBaseUrl)
             : stripTrailingSlash(resolvedBaseUrl);
@@ -559,6 +568,7 @@ function providerEnvPrefix(provider) {
     return provider === "llama.cpp" ? "LLAMA_CPP" : provider.toUpperCase();
 }
 const GITHUB_MODELS_BASE_URL = "https://models.github.com/v1";
+export const ANTHROPIC_OPENAI_COMPATIBLE_BASE_URL = "https://api.anthropic.com/v1";
 /**
  * Resolve a GitHub / Copilot token from the environment or `gh` CLI.
  * Checks: GITHUB_TOKEN → GH_TOKEN → `gh auth token` (sync exec).
@@ -612,7 +622,10 @@ export function diagnoseProviderRuntimeConfig(providerInput, override) {
             message: "Missing API key for provider 'codex'. Set CODEX_API_KEY or OPENAI_API_KEY before sending chat messages.",
         };
     }
-    const baseUrl = stripTrailingSlash(override?.baseUrl || providerBase || genericBase || "");
+    const baseUrl = stripTrailingSlash(override?.baseUrl ||
+        providerBase ||
+        genericBase ||
+        (provider === "claude" ? ANTHROPIC_OPENAI_COMPATIBLE_BASE_URL : ""));
     const apiKey = override?.apiKey || providerKey || genericKey || "";
     const missing = [];
     if (!baseUrl) {

package/dist/tui/provider-discovery.d.ts

@@ -14,6 +14,7 @@
  */
 export declare const DEFAULT_OLLAMA_MODEL = "llama3.1:8b";
 export declare const DEFAULT_LLAMA_CPP_MODEL = "local-model";
+export declare const DEFAULT_HOSTED_MODELS: Readonly<Record<"codex" | "claude" | "gemini" | "copilot", string>>;
 export declare const LOCAL_LLM_PROVIDERS: readonly ["ollama", "llama.cpp"];
 export type LocalLlmProvider = (typeof LOCAL_LLM_PROVIDERS)[number];
 export interface ProviderDiscoveryOptions {

package/dist/tui/provider-discovery.js

@@ -18,9 +18,9 @@ import { join, resolve } from "node:path";
 import { readStoreJsonSync } from "../store/store-snapshot.js";
 export const DEFAULT_OLLAMA_MODEL = "llama3.1:8b";
 export const DEFAULT_LLAMA_CPP_MODEL = "local-model";
-const DEFAULT_HOSTED_MODELS = {
+export const DEFAULT_HOSTED_MODELS = {
     codex: "gpt-5",
-    claude: "claude-3-7-sonnet",
+    claude: "claude-opus-4-8",
     gemini: "gemini-2.5-pro",
     copilot: "copilot/gpt-5-mini",
 };

package/docs/cli-reference.md

@@ -0,0 +1,125 @@
+# CLI Reference
+
+> Companion to the [Quick Start in the README](../README.md#quick-start).
+
+The bare `ace` commands below assume a global install (`npm install -g @voybio/ace-swarm`); without one, prefix each with `npx -y @voybio/ace-swarm` — e.g. `npx -y @voybio/ace-swarm mcp`.
+
+## Commands
+
+```text
++--------------------------------------------+-------------------------------------------------------+
+| Command                                    | Purpose                                               |
++--------------------------------------------+-------------------------------------------------------+
+| `ace mcp [--profile host-min|full]` / `ace serve` | Start MCP server over stdio                    |
+| `ace mcp-shadow --tools <csv>`             | Start filtered shadow MCP server (Hermes use)         |
+| `ace tui [options]`                        | Open the terminal operator surface                    |
+| `ace init [options]`                       | Seed the ACE store and optional host stubs            |
+| `ace connect [provider] [options]`         | Register a live local runtime or hosted provider      |
+| `ace turnkey [options]`                    | Project store-backed host surface stubs               |
+| `ace doctor [options]`                     | Validate ACE runtime + MCP readiness                  |
+| `ace goal <start|status|run|resume|stop>`  | Drive a self-paced, evidence-gated goal loop          |
+| `ace ls [prefix] [--keys] [--json]`        | List store-backed artifacts by logical path           |
+| `ace read <path> [--out f] [--source] [--json] [--prefer disk|store]` | Read a store/workspace file (aliases: get, cat) |
+| `ace fsck [--json] [--repair]`             | Validate ACEPACK structure, CRCs, orphans             |
+| `ace cache [options]`                      | DEPRECATED legacy ingest/clean command; it is not an alias for compaction |
+| `ace compact [--no-sweep]`                 | Compact the store and sweep loose generated artifacts |
+| `ace migrate [store-path]`                 | Import a legacy file workspace into the store         |
+| `ace repair`                               | Re-materialize host files and repair store assets     |
+| `ace add skills [name|all]`                | Install packaged skill packs into the store           |
+| `ace playbook <list|show|add|tag|gc>`      | Inspect and curate the experience playbook            |
+| `ace eval [--adapt] [options]`             | Run the eval harness / adaptation cycle               |
+| `ace mcp-config [--client <name>|--all]`   | Print baked client snippets for optional install      |
+| `ace preconfig`                            | Write .mcp-config/ bundle for all clients             |
+| `ace paths`                                | Show resolved package and workspace paths             |
+| `ace help`                                 | Show help                                             |
++--------------------------------------------+-------------------------------------------------------+
+```
+
+## Examples
+
+```bash
+# Bootstrap a workspace with a hosted provider
+ace init --project "My App" --llm claude --client-config-bundle
+
+# Bootstrap with a local Ollama model and write VS Code MCP config
+ace init --project "My App" --llm ollama --model qwen3:8b \
+  --base-url http://localhost:11434 --mcp-config
+
+# Connect to a running llama.cpp server from a Hugging Face model
+ace connect llama-server --hf bartowski/gemma-3-4b-it-GGUF \
+  --base-url http://localhost:8080
+
+# Run doctor checks with auto-scan of common local endpoints
+ace doctor --scan
+
+# Run doctor checks for a specific provider + model
+ace doctor --llm ollama --model qwen3:8b --base-url http://localhost:11434
+
+# Run optional Hermes checks with user-supplied Hermes/Python
+ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
+  ace doctor --llm llama.cpp --model gemma-3-4b-it --base-url http://localhost:8080 --hermes
+
+# Repair a missing Ollama model and re-probe runtime readiness
+ace doctor --llm ollama --model qwen3:8b --repair-ollama
+
+# Print VS Code MCP config snippet to stdout
+ace mcp-config --client vscode
+
+# Write config bundles for every supported client at workspace root
+ace preconfig
+
+# Launch TUI with optional Hermes engine against a local llama.cpp server
+ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
+  ace tui --provider llama.cpp --base-url http://localhost:8080 --model gemma-3-4b-it --hermes
+
+# Compact the store and sweep loose generated artifacts
+ace compact
+ace compact --no-sweep
+
+# List and read store-backed artifacts a human otherwise can't see on disk
+ace ls agent-state
+ace read agent-state/kanban.json
+ace read agent-state/STORE_AUTHORITY_AUDIT.md --out /tmp/audit.md
+
+# Validate ACEPACK structure/CRCs/orphans, optionally repairing safe issues
+ace fsck
+ace fsck --repair
+
+# Start a self-paced goal, watch it, stop it if needed.
+# The objective needs at least one machine-checkable obligation -- a declared
+# artifact or a `verify: <command>` criterion -- or `start` refuses it with
+# `contract_uncheckable` rather than completing on the model's own say-so.
+ace goal start "Ship the auth module. verify: npm test" --budget-hours 2 --detach
+ace goal status
+ace goal stop <goal_id>
+
+# Experimental: list and inspect the learned experience playbook
+ace playbook list
+ace playbook show pb-1234abcd
+ace playbook add --section verification --content "Require evidence refs before completion."
+ace playbook add --section failure_modes --reason-code false_completion_no_evidence \
+  --content "Require evidence refs before completion."
+ace playbook tag pb-1234abcd helpful
+
+# Experimental: run an eval adaptation cycle
+ace eval --adapt --models qwen3:8b,gemma3:4b --epochs 2 \
+  --battery ./my-battery.json --out agent-state/eval-reports
+```
+
+Playbook sections are `strategies`, `tool_usage`, `failure_modes`, `verification`,
+and `env_facts`; list statuses are `active`, `quarantined`, and `retired`.
+Lessons from every producer without evidence are stored as `quarantined` and
+are not prompt-injected.
+
+## Selected options
+
+- `ace mcp --profile <host-min|full>` selects the visible tool schema; `full` is the default.
+- `ace turnkey --no-client-config-bundle` skips the host-facing config stubs created by default.
+- `ace playbook add --reason-code <code>` scopes a lesson to a matching failure class.
+- `ace eval` accepts `--model`/`--models`, `--battery <path>`, `--out <dir>`, and `--adapt`; `--epochs <n>` applies only to adaptation runs.
+- `ace read` accepts `--source` and `--json` in addition to `--out` and `--prefer`.
+
+Eval is non-destructive by default: every task, model, baseline, and adapted
+epoch runs in a new disposable workspace seeded only from the battery's adjacent
+`fixtures/` directory. Expected artifacts are scored inside that workspace and
+recorded by SHA-256 in the scorecard, so stale project files cannot pass a run.

package/docs/development.md

@@ -0,0 +1,46 @@
+# Development
+
+> Companion to the [README](../README.md).
+
+```bash
+cd ace-mcp-server
+npm install
+npm run build
+npm test
+npm run start
+```
+
+Run the Hermes live driver from a source checkout. The script is included in the npm package as of 2.4.6, but it imports the checkout/package `dist/` tree and is a diagnostic, not a supported production command. It exits nonzero if setup, protocol, or artifact checks fail.
+
+```bash
+npm run build
+# with a local llama.cpp or Ollama runtime running:
+ACE_WORKSPACE_ROOT=$PWD \
+  ACE_HERMES_ROOT=/path/to/hermes-agent \
+  HERMES_PYTHON=/path/to/hermes-python \
+  ACE_LIVE_PROVIDERS=llama.cpp \
+  ACE_LIVE_LLAMA_CPP_BASE_URL=http://127.0.0.1:8080/v1 \
+  ACE_LIVE_LLAMA_CPP_MODEL=gemma-3-4b-it \
+  ACE_LIVE_HERMES_MAX_TURNS=3 \
+  node scripts/dev/run_hermes_crispr_live.mjs
+```
+
+`ACE_LIVE_OUTPUT_ONLY=1` deliberately bypasses tool writing and is only for inspecting raw model output; it cannot satisfy the driver’s evidence-gated job check.
+
+## Key source files
+
+| File | Role |
+|---|---|
+| `src/index.ts` | Package entry point |
+| `src/cli.ts` | CLI command dispatch |
+| `src/server.ts` | MCP server setup and stdio transport |
+| `src/tools.ts` | Tool registration hub (delegates to domain modules) |
+| `src/hermes/session-manager.ts` | `HermesSubprocessExecutor` — Hermes subprocess lifecycle |
+| `src/hermes/bridge-protocol.ts` | Frame decoder for the Hermes bridge protocol |
+| `src/model-bridge.ts` | Model bridge interface and process orchestration |
+| `src/goal-engine.ts` | Goal engine — self-paced, evidence-gated objective loop |
+| `src/job-worker.ts` | In-process job worker for the scheduler execution loop |
+| `src/public-surface.ts` | Public surface audit and schema-bound entry map |
+| `src/store/ace-packed-store.ts` | ACEPACK binary store read/write |
+| `src/local-model-policy.ts` | Operator allow/block policy for local models |
+| `scripts/hermes_bridge_worker.py` | Packaged Python worker for the Hermes bridge |

package/docs/evaluation-safety.md

@@ -0,0 +1,27 @@
+# Evaluation Safety and Reproducibility
+
+`ace eval` executes tasks that may create and modify files. Packaged battery runs are therefore isolated from the caller's checkout.
+
+## Isolation contract
+
+- Each model, epoch, and task receives a fresh temporary workspace.
+- Battery fixtures are copied into that workspace before execution.
+- A task cannot inherit artifacts from an earlier task or epoch.
+- Temporary workspaces are removed after the result and artifact provenance have been recorded.
+
+Do not treat an evaluation task as safe merely because its prompt sounds read-only. Review custom batteries before running them and never configure an evaluation workspace to point at a valuable checkout.
+
+## Provenance
+
+Evaluation results record the task identity, isolated workspace identity, and hashes for produced artifacts. Hashes establish what bytes were evaluated after the temporary workspace is removed; they do not prove that an artifact is semantically correct. Correctness remains the responsibility of the task verifier and its evidence requirements.
+
+For reproducible comparisons, pin the battery, model identifier, provider configuration, ACE version, and relevant environment variables. A provider-backed result may still vary when the remote model or serving stack changes behind a stable name.
+
+## Failure interpretation
+
+- A missing required artifact is a failed task, not a zero-score success.
+- An artifact left by a previous task must never satisfy a later task.
+- Provider launch, timeout, and protocol failures are execution failures and must remain distinguishable from verifier failures.
+- Preserve the result record when diagnosing a failure; do not rely on a temporary workspace surviving cleanup.
+
+See [CLI Reference](cli-reference.md) for command syntax and [Troubleshooting](troubleshooting.md) for common failure paths.

package/docs/experience-playbook.md

@@ -0,0 +1,35 @@
+# Experience Playbook (experimental)
+
+> Companion to the [README](../README.md). This feature is experimental and off by default for prompt injection.
+
+The playbook is an evidence-gated lessons store under `agent-state/playbook/`. Evidence-free lessons from every producer are retained as `quarantined`; only active, scope-matched lessons can be reused across runs.
+
+Prompt injection is off by default. Set `ACE_PLAYBOOK=1` to inject active, scope-matched lessons into the stable system prompt block. Deterministic reflection can run at direct-lane run end while injection is off; disable it with `ACE_PLAYBOOK_REFLECT=0`.
+
+The playbook is conservative by design. Use `ace eval --adapt` to compare baseline and adapted scorecards for your own models before changing defaults. `agent-state/PLAYBOOK.md` is a derived projection and can be regenerated with `ace playbook list`, `add`, `tag`, or `gc`.
+
+The legacy `get_lessons` / `add_lesson` MCP tools read and write playbook bullets.
+`add_lesson` currently creates a quarantined note because its legacy schema has no evidence field.
+
+## CLI
+
+```bash
+# List and inspect lessons
+ace playbook list
+ace playbook show pb-1234abcd
+ace playbook add --section verification --content "Require evidence refs before completion."
+ace playbook tag pb-1234abcd helpful
+ace playbook gc
+
+# Run an eval adaptation cycle and compare scorecards
+ace eval --adapt --model qwen3:8b
+```
+
+The packaged battery ships at `assets/eval-battery/battery.json` and is used by
+default; pass `--battery <path>` to run your own. Each task/model/epoch runs in a
+fresh disposable workspace seeded from the `fixtures/` directory adjacent to
+the battery. Scorecards hash the artifacts created in that run; the caller's
+project and stale artifacts are never used for scoring.
+
+The packaged fixture includes `fixtures/edit-target.js`, used by both
+`edit-1-single` and `env-4-tool`.