@voybio/ace-swarm 2.4.9 → 2.4.10

package/dist/vericify-native.js

@@ -0,0 +1,221 @@
+/** Optional read-only native consumer. The vendored owner client selects history. */
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+const protocol = 'vericify-readonly-adapter/v1';
+const capabilities = { command_pass: false, ace_attempt_mapping: false };
+const U64_MAX = 18446744073709551615n;
+function decimal(value) {
+    if (typeof value !== 'string' || !/^(0|[1-9][0-9]{0,19})$/.test(value) || BigInt(value) > U64_MAX)
+        throw new ConsumerError('invalid_native_response');
+    return value;
+}
+function text(value) {
+    if (typeof value !== 'string' || value.length < 1 || value.length > 512 || /[\u0000-\u001f]/.test(value))
+        throw new ConsumerError('invalid_native_response');
+    return value;
+}
+class ConsumerError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+function fail(status, reason_code) {
+    return { status, reason_code, records: [], coverage: { complete: false, expired_ranges: [] }, capabilities };
+}
+function bound(value, fallback, low, high) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < low || result > high)
+        throw new ConsumerError('invalid_native_configuration');
+    return result;
+}
+function confidence(value) {
+    const result = String(value ?? '').toLowerCase();
+    return result === 'linked' ? 'Linked' : result === 'inferred' ? 'Inferred' : result === 'ambiguous' ? 'Ambiguous' : 'Unknown';
+}
+function identity(snapshot, config) {
+    if (snapshot.workspace_id !== config.workspace_id || (config.incarnation && snapshot.incarnation !== config.incarnation))
+        throw new ConsumerError('workspace_identity_mismatch');
+    text(snapshot.incarnation);
+    decimal(snapshot.high_water);
+    if (snapshot.record_profile !== 'vericify/records/v1')
+        throw new ConsumerError('incompatible_native_profile');
+}
+function cursorEncode(position) {
+    return 'vcn1:' + Buffer.from(JSON.stringify({ workspace_id: position.workspace_id, incarnation: position.incarnation, sequence: position.sequence })).toString('base64url');
+}
+function cursorDecode(cursor) {
+    try {
+        if (!cursor.startsWith('vcn1:') || cursor.length > 2048)
+            throw new Error();
+        const result = JSON.parse(Buffer.from(cursor.slice(5), 'base64url').toString('utf8'));
+        text(result.workspace_id);
+        text(result.incarnation);
+        decimal(result.sequence);
+        return result;
+    }
+    catch {
+        throw new ConsumerError('invalid_native_cursor');
+    }
+}
+/** Map references already selected/enriched by Vericify. No history scan or join lives here. */
+function observationRef(item, snapshot) {
+    const record = item.record, data = record.payload.data;
+    const selected = item.latest_link?.payload.data ?? data;
+    const capture = data.coverage ?? {};
+    return {
+        id: record.id, attribution: 'Unknown', native_attribution: confidence(selected.attribution?.confidence), kind: 'file_change',
+        ...(typeof data.path?.display === 'string' ? { path_display: data.path.display.slice(0, 512), path_display_truncated: data.path.display.length > 512 } : {}),
+        ...(typeof data.kind === 'string' ? { change_kind: text(data.kind) } : {}),
+        sequence: record.seq, workspace_id: record.workspace_id, incarnation: record.incarnation, attempt_linked: false,
+        link_refs: item.latest_link ? [item.latest_link.id] : [],
+        evidence_refs: Array.isArray(selected.attribution?.evidence_refs) ? selected.attribution.evidence_refs.slice(0, 16).map(text) : [],
+        purpose_refs: Array.isArray(selected.purpose_refs) ? selected.purpose_refs.slice(0, 16).map((ref) => ({ evidence_id: text(ref.evidence_id), basis: text(ref.basis), uncertainty: text(ref.uncertainty) })) : [],
+        purpose_availability: 'unresolved', native_purpose_availability: typeof selected.purpose_availability === 'string' ? text(selected.purpose_availability) : 'unknown', purpose_resolved: false,
+        capture_coverage: {
+            source: typeof capture.source === 'string' ? text(capture.source) : 'unknown',
+            stable_read: typeof capture.stable_read === 'string' ? text(capture.stable_read) : 'unknown',
+            gaps: Array.isArray(capture.gaps) ? capture.gaps.slice(0, 16).map(text) : [],
+            omission_reason: typeof capture.omission_reason === 'string' ? text(capture.omission_reason) : null,
+        },
+        binding: { protocol, workspace_id: record.workspace_id, incarnation: record.incarnation, sequence: record.seq, snapshot: snapshot.binding },
+        observed_from: record.payload.data.observed_from, observed_to: record.payload.data.observed_to,
+    };
+}
+function recordRef(record) {
+    return { id: record.id, sequence: record.seq, kind: record.payload.record_type };
+}
+function nativeFailure(code) {
+    switch (code) {
+        case 'stale_snapshot': return fail('pending', 'native_stale_snapshot');
+        case 'capacity': return fail('pending', 'native_capacity');
+        case 'timeout': return fail('pending', 'query_timeout');
+        case 'missing_history': return fail('unavailable', 'native_history_missing');
+        case 'identity_mismatch': return fail('unavailable', 'workspace_identity_mismatch');
+        case 'incompatible_protocol': return fail('unavailable', 'incompatible_native_protocol');
+        case 'invalid_query': return fail('unavailable', 'invalid_native_query');
+        case 'expired': return fail('unavailable', 'history_expired');
+        default: return fail('unavailable', 'native_query_unavailable');
+    }
+}
+export async function getNativeVericifyContext(input) {
+    const config = input.config;
+    if (!config.enabled)
+        return fail('unavailable', 'native_disabled');
+    if (!config.workspace_root || !config.workspace_id)
+        return fail('unavailable', 'workspace_identity_unconfigured');
+    let workspaceRoot;
+    try {
+        workspaceRoot = realpathSync(input.workspaceRoot);
+        if (workspaceRoot !== realpathSync(resolve(input.workspaceRoot, config.workspace_root)))
+            return fail('unavailable', 'workspace_identity_mismatch');
+    }
+    catch {
+        return fail('unavailable', 'workspace_identity_unavailable');
+    }
+    if (!config.executable || !config.data_dir)
+        return fail('unavailable', 'native_configuration_incomplete');
+    let timeout, maxBytes, retries;
+    try {
+        timeout = bound(config.query_timeout_ms, 15000, 1000, 60000);
+        maxBytes = bound(config.max_bytes, 262144, 4096, 1048576);
+        retries = bound(config.retries, 1, 0, 3);
+    }
+    catch {
+        return fail('unavailable', 'invalid_native_configuration');
+    }
+    let since;
+    try {
+        if (input.since)
+            since = cursorDecode(input.since);
+        if (since && (since.workspace_id !== config.workspace_id || (config.incarnation && since.incarnation !== config.incarnation)))
+            throw new Error();
+    }
+    catch {
+        return fail('unavailable', 'invalid_native_cursor');
+    }
+    // No-window context/delta reads cover all epoch values without Number coercion.
+    let fromMs = '0', toMs = U64_MAX.toString();
+    if (input.window) {
+        const from = Date.parse(input.window.started_at), to = Date.parse(input.window.ended_at ?? new Date().toISOString());
+        if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 0 || to < from)
+            return fail('unavailable', 'invalid_observation_window');
+        fromMs = String(from);
+        toMs = String(to);
+    }
+    const after = since ?? (config.incarnation ? { workspace_id: config.workspace_id, incarnation: config.incarnation, sequence: '0' } : undefined);
+    const clientUrl = new URL('../assets/vendor/vericify-reader.mjs', import.meta.url).href;
+    let owner;
+    try {
+        owner = await import(clientUrl);
+    }
+    catch {
+        return fail('unavailable', 'native_consumer_unavailable');
+    }
+    const end = Date.now() + timeout;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        const remaining = attempt === 0 ? timeout : end - Date.now();
+        if (remaining < 1000)
+            return fail('pending', 'query_timeout');
+        try {
+            const client = owner.openVericifyHistory({ executable: resolve(input.workspaceRoot, config.executable), dataDir: resolve(input.workspaceRoot, config.data_dir), timeoutMs: Math.min(60000, remaining) });
+            if (typeof client.window !== 'function')
+                return fail('unavailable', 'incompatible_native_protocol');
+            // The owner resolves identity, history, latest links and evidence in one pinned native lifetime.
+            const result = await client.window({ workspaceRoot, fromMs, toMs, after, limit: 100, maxBytes });
+            identity(result.snapshot, config);
+            const status = result.state === 'pending' ? 'pending' : result.state === 'expired' ? 'unavailable' : 'available';
+            return {
+                status,
+                ...(result.state === 'pending' ? { reason_code: 'native_window_pending' } : result.state === 'expired' ? { reason_code: 'history_expired' } : {}),
+                records: result.changes.map((item) => observationRef(item, result.snapshot)),
+                query: {
+                    protocol, workspace_id: result.snapshot.workspace_id, incarnation: result.snapshot.incarnation, snapshot: result.snapshot.binding,
+                    ...(result.snapshot.generation !== undefined ? { generation: decimal(result.snapshot.generation) } : {}),
+                    record_profile: result.snapshot.record_profile, high_water: result.high_water.sequence, since: result.query.after_sequence,
+                    window: input.window ?? null, from_ms: fromMs, to_ms: toMs, bytes: Buffer.byteLength(JSON.stringify(result)), attempts: attempt + 1,
+                    state: result.state, scan_complete: result.scan_complete, evidence_complete: result.evidence.complete,
+                },
+                coverage: {
+                    complete: result.complete && result.state === 'complete', expired_ranges: result.expired_ranges,
+                    from_sequence: result.query.after_sequence, through_sequence: result.scanned_through.sequence,
+                    native_scope: result.coverage_scope,
+                    native_coverage: result.coverage.map(recordRef), host_gaps: result.host_gaps.map(recordRef),
+                    evidence_unavailable: result.evidence.unavailable.map((ref) => ({ id: ref.id, reason: ref.reason })),
+                    capture_complete: result.host_gaps.length ? false : null,
+                },
+                // Only acknowledged progress can be resumed. Never substitute the snapshot high-water.
+                cursor: cursorEncode(result.next_after), capabilities,
+            };
+        }
+        catch (error) {
+            if (error instanceof ConsumerError)
+                return fail('unavailable', error.code);
+            if (typeof owner.NativeReadError === 'function' && error instanceof owner.NativeReadError) {
+                const native = error;
+                if (native.retryable && attempt < retries && end - Date.now() >= 1000)
+                    continue;
+                return nativeFailure(native.code);
+            }
+            return fail('unavailable', 'invalid_native_response');
+        }
+    }
+    return fail('pending', 'native_query_unavailable');
+}
+export function createNativeObservationAdapter(config, workspaceRoot) {
+    return {
+        supported_requirements: [],
+        async readWindow(window) {
+            try {
+                if (realpathSync(window.workspace_id) !== realpathSync(workspaceRoot))
+                    return fail('unavailable', 'workspace_identity_mismatch');
+            }
+            catch {
+                return fail('unavailable', 'workspace_identity_unavailable');
+            }
+            return getNativeVericifyContext({ config, workspaceRoot, window });
+        },
+    };
+}
+//# sourceMappingURL=vericify-native.js.map

package/dist/verification-worker.d.ts

@@ -0,0 +1,2 @@
+export declare function runVerificationWorker(root: string, jobId: string): Promise<void>;
+//# sourceMappingURL=verification-worker.d.ts.map

package/dist/verification-worker.js

@@ -0,0 +1,31 @@
+/** Detached execution process; the MCP server owns no long verification request. */
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { withWorkspaceRoot } from './helpers.js';
+import { registerJobHandler, runJobWorkerOnce } from './job-worker.js';
+import { readJobQueue } from './job-scheduler.js';
+import { executeHostVerificationJob } from './host-verification-job.js';
+export async function runVerificationWorker(root, jobId) {
+    await withWorkspaceRoot(root, async () => {
+        registerJobHandler('goal.verify', async ({ job }) => {
+            await executeHostVerificationJob(root, job.job_id);
+            return { success: true, evidence_ref: `goal:${String(job.payload.goal_id)}:verification:${job.job_id}` };
+        });
+        for (;;) {
+            const job = readJobQueue().jobs.find(j => j.job_id === jobId);
+            if (!job || ['done', 'failed', 'failed_terminal', 'canceled', 'unknown_recovery'].includes(job.status))
+                return;
+            const tick = await runJobWorkerOnce({ owner: 'capability-ops', job_ids: [jobId] });
+            if (tick.executed.length)
+                return;
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+    });
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const [root, jobId] = process.argv.slice(2);
+    if (!root || !jobId)
+        throw new Error('Verification worker requires workspace and job id.');
+    await runVerificationWorker(root, jobId).catch(error => { console.error(error); process.exitCode = 1; });
+}
+//# sourceMappingURL=verification-worker.js.map

package/docs/mcp-tool-reference.md

@@ -1,8 +1,8 @@
 # MCP Tool Reference
 
-> Companion to the [README](../README.md). The full MCP surface spans **119 registered tools** across 13 domain modules, plus resources and prompts. For premium hosts (Claude Code, Codex), the curated `ace mcp --profile host-min` exposes 22 high-value tools; the rest remain reachable via `run_orchestrator` delegation or `--profile full`.
+> Companion to the [README](../README.md). The full MCP surface spans **121 registered tools** across 13 domain modules, plus resources and prompts. For premium hosts (Claude Code, Codex), `ace mcp --profile host-min` exposes 30 tools, including work-state and stop/resume operations. Optional `run_local_model`, `run_orchestrator`, `emit_status_event` and `append_vericify_process_post` are available through `--profile full`.
 
-ACE exposes tools through a domain-modular registration system (`src/tools.ts` delegates to 13 domain modules). Tools can be allow-listed at startup; `ace mcp-shadow` uses this to give Hermes a scoped tools-only subset. Public `ace mcp` always exposes the full prompts and resources surface; its visible tool schema depends on `--profile` (119 tools for `full`, 22 for `host-min`). `ace mcp-shadow` instead exposes only its explicitly allow-listed tools and omits prompts and resources.
+ACE exposes tools through a domain-modular registration system (`src/tools.ts` delegates to 13 domain modules). Tools can be allow-listed at startup; `ace mcp-shadow` uses this to give Hermes a scoped tools-only subset. Public `ace mcp` always exposes the full prompts and resources surface; its visible tool schema depends on `--profile` (121 tools for `full`, 30 for `host-min`). `ace mcp-shadow` instead exposes only its explicitly allow-listed tools and omits prompts and resources.
 
 ## Agent & Runtime
 
@@ -99,13 +99,33 @@ enqueue_job {
 
 | Tool | Purpose |
 |---|---|
-| `start_goal` | Compile an objective into a validated plan and open a goal record |
-| `get_goal_status` | Read goal status, tick/replan counts, ready steps, and escalations |
-| `resume_goal` | Resume a stopped or escalated goal from its persisted state |
+| `start_goal` | Choose `executor:"host"` or `executor:"engine"` explicitly; host plans return their first assignment |
+| `next_step` | Receive/resume a ready host assignment with dependency results; never takes another participant's running step |
+| `complete_step` | Record a host outcome once, update linked views, optionally begin the successor; identical retries replay the original response |
+| `get_goal_status` | `view:"compact"` returns bounded verification, blockers and executable next actions; default/`view:"full"` retains complete records |
+| `resume_goal` | Resume an engine goal; for host goals, preserve running work and explicitly retry blocked work or interrupted verification |
 | `stop_goal` | Operator stop for a running goal |
 
 A goal reaches `done` only through evidence-gated success; it otherwise leaves `executing` through budget exhaustion, operator stop, or an escalated blocker. The same loop is available from the CLI as `ace goal start|status|run|resume|stop`.
 
+Host loop: `start_goal({executor:"host", agent:"codex", steps:[{id:"S1", task:"Implement"}]})` returns an assignment. Do the work with the host's tools, then call `complete_step` with its `goal_id`, `step_id`, `attempt`, and `{status, summary}`. `continue:true` returns the next assignment in that response. Use a stable `agent` label across restarts; `recall_context` recovers it. The attached host performs the step work; ACE does not launch a model for it. Final acceptance runs in a detached scheduler worker, with no external observation capture.
+
+Goal-end acceptance enqueues background verification and promptly returns an immutable `verification:"pending"` receipt with an executable `get_goal_status({goal_id, view:"compact", agent})` action. Follow it to confirm success, inspect a bounded failure preview, or receive `next_step` for corrective work. Identical completion retries return the entire original reply verbatim. Compact status targets 4 KiB of structured JSON and retains counts and a `view:"full"` locator when optional previews are shortened; full plans, attempts and failure output are preserved.
+Requirement changes use optional `outcome.requirement_updates: [{step_id, reason, task?, expected_artifacts?, required_evidence_refs?}]`. ACE reopens only those steps and their dependents, retains earlier results, and charges a total correction allowance only if the operator explicitly supplied one. The completion response names reopened steps or changes pending admission; unrelated sibling outcomes stay intact.
+
+
+`verify` declares goal-end shell checks as strings or `{cmd,stall_min?,kill_min?,deadline_min?}` objects. The command defaults flag a suspected stall after 10 minutes of silence and terminate its entire process group after 60 minutes of silence total (50 more minutes after the warning). `stall_min:0` disables silence detection, `kill_min:0` disables automatic stall termination, and a total deadline exists only when `deadline_min` is supplied. Compact status includes the verification job, worker identity, command duration, time since output and a bounded output tail; full logs live under `.ace-runtime/verification/<job_id>/`. A server restart retains live/uncertain work; explicit recovery reruns checks only after old processes are confirmed gone. The existing scheduler tracks both worker and command identities so stale heartbeats cannot release live work’s locks.
+
+`run_tests` accepts the same three policy fields directly. `safe_edit_file`, `apply_patch`, structural rewrites and executable gates accept them in `command_policy`. These commands run asynchronously and emit MCP progress notifications when the request supplies a progress token. Clients must opt into `resetTimeoutOnProgress` to extend their request wait; an explicit `maxTotalTimeout` still bounds the client’s patience. This does not reset ACE’s command progress timestamps. A client wait timeout or connection loss does not cancel the work; explicit operator cancellation and declared command deadlines still do. Learned-payload validation can remain blocking and uses the same progress notifications. Native local-model and orchestrated child-step turn counts default to unlimited; external Hermes adapter and client settings are configured separately.
+
+Three consecutive unchanged failure sets park a goal for review instead of exhausting a default correction count. Failure identity retains meaningful output, test names and evidence references; changed failures can continue beyond three corrections. Host contact/age is advisory and never authorizes automatic reassignment.
+
+`verify` checks determine acceptance. Without shell checks, a permitted host goal completes as **done (not machine-verified)**. Required final `expected_artifacts` are rechecked at closure even without shell commands; missing deliverables create bounded corrective work. Existing string entries declare required final deliverables. Object entries such as `{path:"scratch.txt", transient:true}` declare outputs required at step completion but not at goal closure; `{path:"optional.txt", required:false}` remains optional. Requirement updates accept the same object metadata. Step `required_evidence_refs` and an optional `required_observation` still apply. Optional native observation is configured under `observability.vericify_bridge.native`; missing reads do not block unrelated work. Native records retain their own IDs/confidence, with ACE attempt attribution Unknown. The current native adapter cannot satisfy `action` or `command_pass` requirements and reports that capability gap explicitly. A capable adapter may use bounded late acceptance in the existing verification job; resume then collects evidence for the original attempt instead of repeating the edit or changing its receipt.
+
+Host goals are unlimited unless started with explicit `budget_hours`; goals without the new marker, including legacy goals and `G-learning`, have no deadline. Explicit hours bound new assignments from the retained start and may exceed 24; engine goals also have no implicit deadline or 200-tick ceiling, and explicit deadlines may exceed 24 hours. In-flight outcomes and final acceptance survive expiry. A blocked host can recover through `resume_goal({goal_id,budget_hours:3})` or `resume_goal({goal_id,max_replans:3})`, using a sufficient nondecreasing total allowance. Hours do not restart the clock; a finite deadline cannot be imposed on an unlimited goal through resume. All provided changes are validated before either takes effect, and decreases are refused. Raised replan allowance admits pending dependency closures with their retained IDs; any remainder stays in `goal.pending_follow_ups`. Compact status retains sufficient recovery arguments in `operator_proposal` with `requires_operator_approval:true`, outside executable `options`. Deadline/replan exhaustion leaves `options:[]` and waits on `operator:budget`/`operator:replan_budget`. The host must obtain operator approval before submitting those arguments, including when it receives a proposal from plain `resume_goal`. Status and plain resume never raise an allowance. This is an instruction boundary: MCP does not authenticate whether the caller obtained approval. Clearing a legacy unmarked deadline blocker needs no increase and remains an executable option. Plain resume/restart changes no allowance, and completion receipts stay identical after recovery.
+
+Link existing todos with `todo_ids: {S1:"todo-id"}`. Linked todo completion routes to the step. A handoff may carry `step_ref:{goal_id,step_id}`, the submitting `agent` and optional `recipient_agent`; `ack_handoff({status:"accepted",agent:recipient})` transfers ownership and advances the attempt. A sender's old completion is then stale. Standalone todos/handoffs keep their existing behavior.
+
 ## Files & Structural Editing
 
 | Tool | Purpose |
@@ -160,7 +180,7 @@ A goal reaches `done` only through evidence-gated success; it otherwise leaves `
 |---|---|
 | `context_snapshot` | Capture a structured context snapshot for the current session |
 | `build_continuity_packet` | Build a continuity packet for cross-session handoff |
-| `recall_context` | Recall an exact snapshot name, or list all snapshots when no name is supplied |
+| `recall_context` | Return current work, a running assignment and linked context by default; `list: true` lists snapshots; `name` retrieves one |
 
 Example — before switching models mid-task:
 
@@ -197,11 +217,22 @@ emit_status_event {
 
 | Tool | Purpose |
 |---|---|
-| `get_todo` | Read the current todo surface |
-| `get_todo_state` | Read structured todo state from the store |
-| `update_todo` | Update one or more todo items |
+| `get_todo` | Import changed native rows and read the todo board, with import warnings |
+| `get_todo_state` | Import changed native rows and return authoritative task records |
+| `update_todo` | Append, transition, or explicitly delete (`delete_id`) a task; `new_content` imports edits and retains omitted tasks |
 | `get_run_ledger` | Read the run ledger (history of major tool invocations) |
 
+Todo statuses are `backlog`, `in_progress`, `blocked`, `gated`, `done`, and `cancelled`.
+`pending` remains the repository spelling of backlog. A cancelled dependency does not satisfy
+`done`. Native edits are imported on todo reads and mutations; malformed, duplicate or absent
+rows produce `import_warnings` and retain canonical records. `get_todo` returns the canonical
+board even when the native file is awaiting repair. Use `delete_id` for intentional removal;
+`new_content` no longer deletes omitted tasks. Prefer append and transition operations for
+concurrent work. Whole-content field edits do not provide a three-way merge.
+
+Kanban distinguishes cancelled work from completion. During debounce, tools report a
+scheduled refresh and retain the last actual generation timestamp; a trailing render follows.
+
 ## Vericify (Verification)
 
 | Tool | Purpose |
@@ -293,3 +324,7 @@ Prompts:
 `ace-astgrep`, `ace-codemunch`, `ace-coders`, `ace-codesnipe`, `ace-eval`, `ace-genesis`, `ace-handoff`, `ace-initiate`, `ace-lessons`, `ace-memory`, `ace-observability`, `ace-orchestrator`, `ace-release`, `ace-runtime-executor`, `ace-security`, `ace-skill`, `ace-skills-index`, `ace-ui`, and `ace-vos`.
 
 For schema-exact tool inputs, use MCP `tools/list`; for the release-bound schema files and their surface mappings, run `audit_public_surface`. This avoids maintaining a second hand-copied schema that can silently diverge from the registered Zod contracts.
+
+Host learning uses optional `complete_step.outcome.learned` (up to three cited lessons, one skill and one instruction proposal). The response reports acceptance errors and a bounded correction option. Mechanical checks earn `checked`; only exact failing-command recovery earns `demonstrated`. Role instructions remain proposed until operator approval. `get_skill_instructions` is available in `host-min`; active skills under `learned/<slug>` appear in the normal catalog.
+
+`ace learn list|show|approve|retire|export|report` provides operator control outside the normal step loop. `ACE_LEARN=0` disables automatic learning without deleting knowledge. Only explicit approval activates a proposed role instruction or distiller overlay. Configure bounded defaults through `learning:` in the existing `ACE_WORKFLOW.md`; instruction approval remains required. Exports with episode citations are reviewable source documents, not an automatic publication.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@voybio/ace-swarm",
-  "version": "2.4.9",
-  "description": "ACE Framework MCP server and CLI — single-file ACEPACK state, local-model serving, agent orchestration, and host compliance enforcement.",
+  "version": "2.4.10",
+  "description": "ACE Framework MCP server and CLI \u2014 single-file ACEPACK state, local-model serving, agent orchestration, and host compliance enforcement.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,8 +23,21 @@
     "dist/**/*.d.ts",
     "scripts/hermes_bridge_worker.py",
     "scripts/dev/run_hermes_crispr_live.mjs",
+    "scripts/dev/run-tests-isolated.mjs",
+    "scripts/dev/test-isolation-guard.mjs",
+    "scripts/dev/test-preload.mjs",
+    "scripts/dev/test-source-inventory.mjs",
     "assets",
-    "docs",
+    "docs/cli-reference.md",
+    "docs/evaluation-safety.md",
+    "docs/experience-playbook.md",
+    "docs/hermes.md",
+    "docs/library-api.md",
+    "docs/mcp-tool-reference.md",
+    "docs/provider-security.md",
+    "docs/state-model.md",
+    "docs/troubleshooting.md",
+    "docs/tui-operator-guide.md",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -38,14 +51,14 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test 'test/*.test.mjs' 'test/**/*.test.mjs'",
-    "test:real-astgrep": "npm run build && ACE_TEST_REAL_ASTGREP=1 node --test test/astgrep-real-cli.test.mjs",
+    "test": "npm run build && node scripts/dev/run-tests-isolated.mjs",
+    "test:real-astgrep": "npm run build && ACE_TEST_REAL_ASTGREP=1 node scripts/dev/run-tests-isolated.mjs test/astgrep-real-cli.test.mjs",
     "start": "node dist/cli.js mcp",
     "dev": "tsc && node dist/cli.js mcp",
     "init": "node dist/cli.js init",
     "turnkey": "node dist/cli.js turnkey",
     "mcp-config": "node dist/cli.js mcp-config",
-    "prepublishOnly": "npm run build"
+    "prepack": "node scripts/dev/prepack.mjs"
   },
   "keywords": [
     "mcp",

package/scripts/dev/run-tests-isolated.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Run the whole test process outside the developer's workspace, including fallbacks.
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, statSync, symlinkSync, writeFileSync, realpathSync, renameSync, unlinkSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { spawn, spawnSync, execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { testSourceFiles, findTestDependencies } from './test-source-inventory.mjs';
+
+const source = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+// Darwin sockaddr_un paths are short. Keep every allocated fixture beneath a
+// canonical short base so native control sockets fit without moving outside it.
+const sandbox = mkdtempSync(join(process.platform === 'darwin' ? '/private/tmp' : tmpdir(), 'at-'));
+const checkout = join(sandbox, "checkout");
+mkdirSync(checkout);
+const fixtures = join(sandbox, 'fixtures'); const registry = join(sandbox, 'owned-node-processes');
+mkdirSync(fixtures); mkdirSync(registry);
+
+function stateHashes(root) {
+  const values = {};
+  function visit(path) {
+    if (!existsSync(path)) return;
+    if (statSync(path).isDirectory()) {
+      for (const child of readdirSync(path)) visit(join(path, child));
+    } else values[relative(root, path)] = createHash("sha256").update(readFileSync(path)).digest("hex");
+  }
+  for (const name of ["agent-state", ".agents/ACE"]) visit(join(root, name));
+  return values;
+}
+
+const protectedBefore = stateHashes(source);
+// Include current edits and new tests, but never copy a live store or host state.
+const files = testSourceFiles(source);
+for (const name of new Set(files)) {
+  if (/^(?:agent-state|\.agents|\.git|node_modules|dist)(?:\/|$)/.test(name)) continue;
+  const from = join(source, name);
+  if (!existsSync(from) || !statSync(from).isFile()) continue;
+  mkdirSync(dirname(join(checkout, name)), { recursive: true });
+  cpSync(from, join(checkout, name));
+}
+cpSync(join(source, "dist"), join(checkout, "dist"), { recursive: true });
+symlinkSync(findTestDependencies(source), join(checkout, "node_modules"), "dir");
+writeFileSync(join(checkout, '.ace-test-source-files.json'), JSON.stringify(files));
+
+const runId = randomUUID(); const leaseFile = join(sandbox, 'lease.json'); const sessionFile = join(sandbox, 'session.json');
+const sentinel = join(checkout, '.ace-test-protected-sentinel'); writeFileSync(sentinel, 'Protected disposable source sentinel\n');
+const sentinelBefore = readFileSync(sentinel);
+const nativeSentinel = join(sandbox, 'outside-fixture-sentinel');
+writeFileSync(nativeSentinel, 'Protected disposable non-source sentinel\n');
+const nativeSentinelBefore = readFileSync(nativeSentinel);
+const lease = status => writeFileSync(leaseFile, JSON.stringify({ version: 1, run_id: runId, status }));
+lease('active');
+writeFileSync(sessionFile, JSON.stringify({ run_id: runId, lease_file: leaseFile, fixtures_root: realpathSync(fixtures), registry_root: registry, sentinel }));
+const preload = join(checkout, 'scripts', 'dev', 'test-preload.mjs');
+// On macOS, a verified Seatbelt profile also covers shell/native descendants.
+// Availability varies under an outer sandbox, so never infer enforcement from
+// the executable merely existing. The self-test touches a disposable sentinel.
+let osBoundary = { mode: process.platform === 'darwin' ? 'unavailable' : 'not_supported' };
+let command = process.execPath; let prefix = [];
+const processRequests = join(sandbox, 'process-info-requests'); const processResponses = join(sandbox, 'process-info-responses');
+mkdirSync(processRequests); mkdirSync(processResponses);
+if (process.platform === 'darwin' && existsSync('/usr/bin/sandbox-exec')) {
+  const writable = [fixtures, registry, processRequests, processResponses].map(path => `(subpath ${JSON.stringify(realpathSync.native(path))})`).join(' ');
+  const seatbelt = `(version 1) (allow default) (deny file-write*) (allow file-write* ${writable} (literal "/dev/null") (literal "/dev/tty") (literal "/dev/stdout") (literal "/dev/stderr") (subpath "/dev/fd"))`;
+  const probePath = join(checkout, '.ace-test-os-sentinel'); const original = 'Protected native sentinel\n'; writeFileSync(probePath, original);
+  const result = spawnSync('/usr/bin/sandbox-exec', ['-p', seatbelt, '/bin/sh', '-c', 'printf mutation > "$1"', 'isolation-probe', probePath], { encoding: 'utf8' });
+  const preserved = readFileSync(probePath, 'utf8') === original;
+  if (!preserved) { lease('quarantined'); throw new Error('OS isolation self-test failed: a disposable protected sentinel was writable'); }
+  if (result.status === 1 && /Operation not permitted|Permission denied/.test(result.stderr)) {
+    osBoundary = { mode: 'seatbelt', self_test: 'native write refused' }; command = '/usr/bin/sandbox-exec'; prefix = ['-p', seatbelt, process.execPath];
+  } else osBoundary = { mode: 'unavailable', reason: (result.stderr || result.error?.message || `probe exit ${result.status}`).trim() };
+}
+if (process.env.ACE_TEST_REQUIRE_OS_BOUNDARY === '1' && osBoundary.mode !== 'seatbelt') { lease('quarantined'); throw new Error(`Required OS test boundary unavailable: ${JSON.stringify(osBoundary)}`); }
+// Seatbelt can restrict Darwin process inspection even though file reads work.
+// Broker only fixed, read-only ps fields through the unsandboxed owning runner.
+// Responses are fresh OS output, never inferred from a heartbeat or PID alone.
+const session = JSON.parse(readFileSync(sessionFile, 'utf8'));
+session.process_info_broker = osBoundary.mode === 'seatbelt';
+session.process_info_requests = processRequests; session.process_info_responses = processResponses;
+writeFileSync(sessionFile, JSON.stringify(session));
+const brokerStats = { requests: 0, failed: 0 };
+function serveProcessInfo() {
+  for (const name of readdirSync(processRequests).slice(0, 64)) {
+    if (!/^[a-f0-9-]+\.json$/.test(name)) continue;
+    let request;
+    try { request = JSON.parse(readFileSync(join(processRequests, name), 'utf8')); } catch { continue; }
+    if (request.run_id !== runId || !Number.isSafeInteger(request.pid) || request.pid <= 1 || !['start', 'stat', 'both'].includes(request.fields)) { unlinkSync(join(processRequests, name)); continue; }
+    const psArgs = ['-p', String(request.pid), ...(request.fields === 'stat' ? [] : ['-o', 'lstart=']), ...(request.fields === 'start' ? [] : ['-o', 'stat='])];
+    let response;
+    try { response = { ok: true, stdout: execFileSync('ps', psArgs, { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'pipe'] }) }; }
+    catch (error) { brokerStats.failed++; response = { ok: false, stdout: String(error.stdout ?? ''), stderr: String(error.stderr ?? ''), status: error.status ?? null, code: error.code ?? 'PROCESS_INFO_UNAVAILABLE' }; }
+    brokerStats.requests++;
+    const path = join(processResponses, name); writeFileSync(`${path}.tmp`, JSON.stringify({ ...response, pid: request.pid, run_id: runId, checked_at: Date.now() })); renameSync(`${path}.tmp`, path); unlinkSync(join(processRequests, name));
+  }
+}
+const broker = session.process_info_broker ? setInterval(serveProcessInfo, 5) : undefined;
+console.error(`[test isolation] OS source boundary: ${osBoundary.mode}`);
+const requested = process.argv.slice(2);
+const probe = requested[0] === '--probe'; if (probe) requested.shift();
+if (probe && !requested.length) throw new Error('Usage: run-tests-isolated.mjs --probe <probe.mjs> [arguments]');
+const args = requested.length ? requested : ["test/*.test.mjs", "test/**/*.test.mjs"];
+console.error(`[test isolation] Disposable checkout: ${checkout}`);
+const childEnv = { ...process.env, ACE_WORKSPACE_ROOT: fixtures, INIT_CWD: checkout, PWD: checkout, ACE_TEST_SESSION_FILE: sessionFile,
+  ACE_TEST_ISOLATION: '1', ACE_TEST_RUN_ID: runId, ACE_TEST_LEASE_FILE: leaseFile,
+  ACE_TEST_NATIVE_SENTINEL_PATH: nativeSentinel,
+  ACE_TEST_PROBE: probe ? '1' : '0',
+  NODE_OPTIONS: [process.env.NODE_OPTIONS ?? '', `--import=${pathToFileURL(preload).href}`].join(' ').trim() };
+delete childEnv.ACE_TUI_WORKSPACE_ROOT;
+delete childEnv.ACE_TEST_WORKER_ROOT;
+const child = spawn(command, [...prefix, ...(probe ? args : ["--test", ...args])], {
+  cwd: checkout,
+  env: childEnv,
+  stdio: "inherit",
+});
+const outcome = await new Promise((resolveExit, reject) => {
+  child.on("error", reject);
+  child.on("close", (code, signal) => resolveExit({ code, signal }));
+});
+function ownedProcesses() {
+  return readdirSync(registry).flatMap(name => {
+    try {
+      const record = JSON.parse(readFileSync(join(registry, name), 'utf8'));
+      try { process.kill(record.pid, 0); } catch (error) { if (error.code === 'ESRCH') return []; return [{ ...record, state: 'uncertain' }]; }
+      try {
+        const actual = execFileSync('ps', ['-p', String(record.pid), '-o', 'lstart=', '-o', 'stat='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        const match = actual.match(/^(.*?)\s+([A-Za-z+<>NsLslWEIXZ-]+)$/);
+        if (match?.[2].includes('Z')) return [];
+        if (record.identity && match && match[1].replace(/\s+/g, ' ') !== record.identity) return [];
+        return [{ ...record, state: record.identity && match ? 'alive' : 'uncertain' }];
+      } catch { return [{ ...record, state: 'uncertain' }]; }
+    } catch { return []; }
+  });
+}
+const configuredWait = Number(process.env.ACE_TEST_CHILD_WAIT_MS ?? 15000);
+const waitUntil = Date.now() + (Number.isFinite(configuredWait) && configuredWait >= 0 ? configuredWait : 15000);
+let retained = ownedProcesses();
+while (retained.length && Date.now() < waitUntil) {
+  await new Promise(resolveWait => setTimeout(resolveWait, 100)); retained = ownedProcesses();
+}
+// Closing the allocation is an instruction to test writers, not a total-runtime
+// kill of healthy work. Unfinished/uncertain descendants quarantine this run.
+lease(retained.length ? 'quarantined' : 'closed');
+if (broker) clearInterval(broker);
+// close fires after the test runner and its workers have finished, not when an
+// alphabetically-last test happens to run. The copy's source root is a sentinel:
+// fixtures must use their disposable workspace, including in spawned children.
+const unexpected = Object.keys(stateHashes(checkout));
+const protectedAfter = stateHashes(source);
+const changed = [...new Set([...Object.keys(protectedBefore), ...Object.keys(protectedAfter)])]
+  .filter((name) => protectedBefore[name] !== protectedAfter[name]);
+const sentinelChanged = !readFileSync(sentinel).equals(sentinelBefore);
+const nativeSentinelChanged = !existsSync(nativeSentinel) || !readFileSync(nativeSentinel).equals(nativeSentinelBefore);
+const quarantined = Boolean(retained.length || unexpected.length || changed.length || sentinelChanged || nativeSentinelChanged);
+if (quarantined) lease('quarantined');
+writeFileSync(join(sandbox, "isolation.json"), JSON.stringify({ checkout, outcome, unexpected, protected_source_changes: changed, sentinel_changed: sentinelChanged, native_sentinel_changed: nativeSentinelChanged, retained_owned_node_processes: retained, allocation: quarantined ? 'quarantined' : 'closed', os_boundary: osBoundary, process_info_broker: { enabled: session.process_info_broker, ...brokerStats } }, null, 2));
+if (quarantined) {
+  console.error(`[test isolation] Unauthorized fixture writes: ${unexpected.join(", ") || "none"}; source changes: ${changed.join(", ") || "none"}`);
+  if (nativeSentinelChanged) console.error('[test isolation] Native write outside allocated fixtures changed a disposable sentinel.');
+  if (retained.length) console.error(`[test isolation] Allocation quarantined; ${retained.length} owned Node descendants remain alive or uncertain. Lease closed; no claim of finished child work.`);
+  process.exitCode = 1;
+} else {
+  console.error("[test isolation] No source-state changes or fallback writes into the disposable source root.");
+  process.exitCode = outcome.code ?? 1;
+}

package/scripts/dev/run_hermes_crispr_live.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import './test-isolation-guard.mjs';
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";

package/scripts/dev/test-isolation-guard.mjs

@@ -0,0 +1,20 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, sep } from 'node:path';
+
+const denied = detail => { throw new Error(`ACE test isolation required: ${detail}. Use node scripts/dev/run-tests-isolated.mjs.`); };
+export function assertTestIsolation() {
+  if (process.env.ACE_TEST_ISOLATION !== '1' || !globalThis[Symbol.for('ace.test.preload')]) denied('the isolation preloader must run before test imports');
+  let roots, lease;
+  try {
+    roots = JSON.parse(process.env.ACE_TEST_ALLOWED_ROOTS ?? 'null');
+    lease = JSON.parse(readFileSync(process.env.ACE_TEST_LEASE_FILE, 'utf8'));
+  } catch { denied('missing fixture allocation or lease'); }
+  if (!Array.isArray(roots) || !roots.length || roots.some(root => typeof root !== 'string' || !isAbsolute(root))) denied('invalid fixture roots');
+  if (lease.status !== 'active' || lease.run_id !== process.env.ACE_TEST_RUN_ID) denied('the fixture lease is no longer active');
+  let workspace;
+  try { workspace = realpathSync.native(process.env.ACE_TEST_WORKER_ROOT); } catch { denied('missing worker allocation'); }
+  if (!roots.some(root => {
+    try { const base = realpathSync.native(root); const path = relative(base, workspace); return statSync(base).isDirectory() && path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path); } catch { return false; }
+  })) denied('worker root is outside the fixture allocation');
+}
+assertTestIsolation();