@voybio/ace-swarm 2.4.8 → 2.4.10

package/dist/vericify-native.d.ts

@@ -0,0 +1,101 @@
+import type { GoalEngineDeps } from './goal-engine.js';
+export interface NativeVericifyConfig {
+    enabled: boolean;
+    executable?: string;
+    data_dir?: string;
+    workspace_root?: string;
+    workspace_id?: string;
+    incarnation?: string;
+    query_timeout_ms?: number;
+    /** Retained for old profiles; window queries never traverse pages. */
+    max_pages?: number;
+    max_bytes?: number;
+    retries?: number;
+    acceptance_wait_ms?: number;
+}
+export interface NativeObservationRef {
+    id: string;
+    attribution: 'Linked' | 'Inferred' | 'Ambiguous' | 'Unknown';
+    native_attribution: 'Linked' | 'Inferred' | 'Ambiguous' | 'Unknown';
+    kind: string;
+    path_display?: string;
+    path_display_truncated?: boolean;
+    change_kind?: string;
+    sequence: string;
+    workspace_id: string;
+    incarnation: string;
+    attempt_linked: false;
+    link_refs: string[];
+    evidence_refs: string[];
+    purpose_refs: Array<{
+        evidence_id: string;
+        basis: string;
+        uncertainty: string;
+    }>;
+    purpose_availability: string;
+    native_purpose_availability: string;
+    purpose_resolved: false;
+    capture_coverage: {
+        source: string;
+        stable_read: string;
+        gaps: string[];
+        omission_reason: string | null;
+    };
+    binding: {
+        protocol: string;
+        workspace_id: string;
+        incarnation: string;
+        sequence: string;
+        snapshot: string;
+    };
+    observed_from: string;
+    observed_to: string;
+}
+export interface NativeReadResult {
+    status: 'available' | 'pending' | 'unavailable';
+    records: NativeObservationRef[];
+    reason_code?: string;
+    query?: Record<string, unknown>;
+    coverage: {
+        /** Completeness of the selected retained history, never universal capture. */
+        complete: boolean;
+        expired_ranges: Array<{
+            first: string;
+            last: string;
+        }>;
+        from_sequence?: string;
+        through_sequence?: string;
+        native_scope?: string;
+        native_coverage?: NativeRecordRef[];
+        host_gaps?: NativeRecordRef[];
+        evidence_unavailable?: Array<{
+            id: string;
+            reason: string;
+        }>;
+        capture_complete?: false | null;
+    };
+    cursor?: string;
+    capabilities: {
+        command_pass: false;
+        ace_attempt_mapping: false;
+    };
+}
+interface NativeRecordRef {
+    id: string;
+    sequence: string;
+    kind: string;
+}
+export declare function getNativeVericifyContext(input: {
+    config: NativeVericifyConfig;
+    workspaceRoot: string;
+    since?: string;
+    window?: {
+        started_at: string;
+        ended_at?: string;
+    };
+}): Promise<NativeReadResult>;
+export declare function createNativeObservationAdapter(config: NativeVericifyConfig, workspaceRoot: string): NonNullable<GoalEngineDeps['observations']> & {
+    supported_requirements: readonly [];
+};
+export {};
+//# sourceMappingURL=vericify-native.d.ts.map

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
 
@@ -78,11 +78,16 @@ create_handoff {
 | `get_lock_table` | Read active resource locks |
 | `get_scheduler_lease` | Read the current scheduler lease |
 
+Dispatch reserves resources and records running work; a worker executes the job
+body. `handoff.lifecycle` is reserved for metadata synchronization and is never
+dispatched. Empty ticks release ownership; `lease_retained` in the dispatch result
+indicates whether execution still holds the lease afterward.
+
 Example — queuing a blocked job:
 
 ```text
 enqueue_job {
-  "kind": "handoff.lifecycle",
+  "kind": "example.analysis",
   "priority": "P1",
   "dependencies": [{ "kind": "handoff", "ref": "HND-20260710-abc12345", "expected": "accepted" }],
   "resource_requirements": ["agent-state/handoff-registry.json"],
@@ -94,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 |
@@ -155,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:
 
@@ -192,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 |
@@ -288,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/docs/troubleshooting.md

@@ -34,6 +34,35 @@ Store-first is normal. `ACE_STORE_FIRST=0` is a legacy diagnostic escape hatch.
 
 Run `ace fsck --json`. A `.corrupt-*` file is a preserved copy, not disposable litter. `ace repair` re-bakes known assets and projections; it does not reconstruct arbitrary corrupt bytes. Restore from a verified backup when structural checks cannot be repaired safely.
 
+## Scheduler
+
+### Jobs are recorded but dispatch reports a held lease
+
+Enqueue and dispatch are separate operations. `get_scheduler_lease` identifies the
+current owner and expiry; `dispatch_jobs` returns `scheduler_lease_held` when
+another owner holds an unexpired lease protecting running work or active locks.
+An idle lease is reclaimed during dispatch without waiting for expiry. Empty
+or dependency-blocked ticks retain no lease, and completing the last running job
+releases it. `lease_acquired` describes admission for the tick; `lease_retained`
+says whether execution still holds ownership afterward. The returned `lease` is
+the admission receipt, even if it was released at the end of the tick.
+
+Handoff creation, acknowledgment, and startup backfill synchronize lifecycle
+metadata without execution dispatch. `handoff.lifecycle` records cannot execute
+through either dispatch tool. Legacy records that appeared to be running are
+parked in `unknown_recovery` with their existing locks preserved until the handoff
+completion receipt resolves them. Backfill also reconciles completed handoffs
+that already have scheduler records; it preserves IDs and history.
+
+Parallel-group promotion leaves undispatched steps planned and retains their job
+IDs. Retrying promotion reuses the same jobs, including when retrying the original
+plan. Resource contention can leave a step queued after successful lease acquisition.
+
+Running work still requires its owning scheduler. Do not adopt another owner's
+identity or delete locks to bypass contention. Check host-agent execution receipts
+before retrying work already launched outside ACE. Ordinary watchdog recovery
+leaves stale jobs parked; acquiring a released lease does not resume those jobs.
+
 ## Providers
 
 ### Ollama unreachable or model missing

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@voybio/ace-swarm",
-  "version": "2.4.8",
-  "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",