@voybio/ace-swarm 2.4.7 → 2.4.9

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/logo/ace-logo.png" alt="ACE — Autonomous Coding Entity" width="640">
+</p>
+
 # ACE Swarm MCP Server and CLI
 
 Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted coding.

package/dist/ace-server-instructions.js

@@ -31,6 +31,13 @@ const REFRESH_TOOLS = new Set([
 // New mutation tools with non-standard prefixes must be added here explicitly.
 const NAMED_MUTATION_TOOLS = new Set([
     "rewrite_targets",
+    "apply_patch",
+    "astgrep_rewrite",
+    "reap_stale_jobs",
+    "heartbeat_job",
+    "generate_kanban_ui",
+    "codemunch_snapshot",
+    "codemunch_index",
 ]);
 const MUTATION_PREFIXES = [
     "ack_",
@@ -209,7 +216,7 @@ export function buildServerInstructions(workspaceRoot) {
         coreFiles.length > 0
             ? `Ground truth for task/status/scope/evidence is store-backed under ${coreFiles.join(", ")} (canonical store: ${ACE_ROOT_REL}/agent-state/ace-state.ace).`
             : `Ground truth is store-backed under ${ACE_ROOT_REL}/agent-state/* artifacts (canonical store: ${ACE_ROOT_REL}/agent-state/ace-state.ace), not chat history.`,
-        "`ace compact` and the automatic lifecycle sweep intentionally remove the loose agent-state/*.md files from disk after folding them into the store — this is expected, not data loss. Read them back with `ace read agent-state/TASK.md` (or the read_workspace_file / recall_context MCP tools); never recreate swept files.",
+        "`ace compact` and the automatic lifecycle sweep intentionally remove loose agent-state/* files from disk after folding them into the store — this is expected, not data loss, and applies to every swept artifact (kanban, run-ledger, handoffs, playbook, tracker snapshots, etc.), not only TASK/STATUS/SCOPE/EVIDENCE_LOG. If a path is not on disk, call list_workspace on its directory to see the full store-backed listing (or `ace ls` from the CLI), then read it back with read_workspace_file (or `ace read <path>`); never recreate swept files.",
         stateDirs.length > 0
             ? `Durable artifacts belong under ${stateDirs.map((entry) => `${entry}/`).join(", ")} and are persisted into the store; the loose copies are sweep inputs, not the source of truth.`
             : undefined,
@@ -217,6 +224,9 @@ export function buildServerInstructions(workspaceRoot) {
         "Use route_task and get_agent_instructions for role guidance; do not self-assign by guesswork.",
         "After meaningful edits or state changes, call execute_gates and persist evidence/handoffs in ACE artifacts.",
         "For delegated or long-running work, use create_handoff / ack_handoff and append_vericify_process_post instead of ad-hoc status notes.",
+        "For self-paced, evidence-gated multi-step objectives beyond this session, use start_goal / get_goal_status / resume_goal / stop_goal (or `ace goal` from the CLI).",
+        "Prefer the matching MCP tool over ad-hoc shell/chat tracking: git_status / git_diff / git_log / git_commit for git; enqueue_job / dispatch_jobs / heartbeat_job / get_lock_table for background jobs; snapshot_state / semantic_diff / drift_report / rewrite_targets for change intelligence.",
+        "skill_catalog_summary / skill_audit / problem_triage surface packaged skills; get_todo / update_todo / get_run_ledger is the human-facing todo surface; scan_workspace_delta / web_research_packet / codemunch_snapshot / codemunch_index cover workspace-wide search and indexing.",
         `Current ACE digest: ${digest}.`,
         autonomyHint ? `Runtime autonomy signals: ${autonomyHint}.` : undefined,
     ];
@@ -240,11 +250,13 @@ export function buildHostInstructionText(host, workspaceRoot) {
         "2. Call `route_task` and `get_agent_instructions` before choosing a role.",
         "3. Prefer ACE prompts/resources (`ace-orchestrator`, `get_task_pack`, `get_skill_instructions`) over relying on this file.",
         "4. Read/write task state through MCP tools (`recall_context`, `read_workspace_file`, `write_workspace_file`, lifecycle append tools); do not create files under `agent-state/` directly.",
+        "5. For self-paced, evidence-gated multi-step objectives beyond this session, use `start_goal` / `get_goal_status` / `resume_goal` / `stop_goal` (or `ace goal` from the CLI).",
+        "6. Also prefer the matching MCP domain over ad-hoc equivalents for git, background jobs/scheduler, change intelligence, discovery/indexing, skills, and todo — see docs/mcp-tool-reference.md for the full per-domain tool catalog.",
         "",
         "Ground truth:",
         "- ACE MCP tools are the authoritative interface for task state and lifecycle updates.",
         "- `agent-state/ace-state.ace` is the canonical store path; visible `agent-state/*` files are compatibility projections or sweep inputs.",
-        "- `ace compact` and the automatic lifecycle sweep intentionally remove loose `agent-state/*` files from disk after folding them into the store — this is expected, not data loss. Do NOT recreate them; retrieve their content via `ace read <path>` or the `read_workspace_file` / `recall_context` MCP tools.",
+        "- `ace compact` and the automatic lifecycle sweep intentionally remove loose `agent-state/*` files from disk after folding them into the store — this is expected, not data loss, for any swept artifact. Do NOT recreate them; if a path isn't on disk, call `list_workspace` on its directory (or `ace ls`) to see the full store-backed listing, then retrieve it via `ace read <path>` or the `read_workspace_file` / `recall_context` MCP tools.",
         "- `.agents/ACE/tasks/todo.md` is the human-facing todo surface.",
         "- Hook context is store-backed in `agent-state/ace-state.ace` and consumed without extra workspace projections.",
         "",

package/dist/cli.js

@@ -98,8 +98,13 @@ Options for turnkey:
 Options for mcp:
   --profile <host-min|full>    Select the visible tool schema (default: full)
 
-Options for playbook add:
-  --reason-code <code>         Scope the lesson to a matching failure reason code
+Options for playbook:
+  list [--section <s>] [--status <s>]   List playbook bullets (default subcommand)
+  show <id>                             Show one bullet as JSON
+  add --content <text> [--section <s>]  Add a bullet
+      [--reason-code <code>]              Scope the lesson to a matching failure reason code
+  tag <id> helpful|harmful              Curate a bullet's helpful/harmful tag
+  gc                                    Prune and quarantine curated bullets
 
 Options for eval:
   --model, --models <csv>      Model name or comma-separated model names (required)

package/dist/job-scheduler.d.ts

@@ -103,8 +103,12 @@ export interface DispatchJobsInput {
 }
 export interface DispatchJobsResult {
     ok: boolean;
+    reason_code?: "scheduler_lease_held";
+    error?: string;
     owner: string;
     lease_acquired: boolean;
+    /** Whether execution still retains ownership after this tick. */
+    lease_retained: boolean;
     lease: SchedulerLeaseFile;
     queue_path: string;
     lock_path: string;
@@ -210,6 +214,13 @@ export declare function readSchedulerLease(): SchedulerLeaseFile | undefined;
  */
 export declare const DEFAULT_HEARTBEAT_STALE_MS = 120000;
 export declare function enqueueJob(input: EnqueueJobInput): Promise<EnqueueJobResult>;
+/** Mirror handoff lifecycle without admitting or executing a job. */
+export declare function syncHandoffLifecycleJob(input: EnqueueJobInput & {
+    job_id: string;
+    now_iso?: string;
+}): Promise<EnqueueJobResult & {
+    enqueued: boolean;
+}>;
 export declare function acknowledgeJob(input: AckJobInput): Promise<AckJobResult>;
 export declare function dispatchJobs(input?: DispatchJobsInput): Promise<DispatchJobsResult>;
 export declare function dispatchJobNow(input: DispatchJobNowInput): Promise<DispatchJobNowResult>;

package/dist/job-scheduler.js

@@ -328,7 +328,7 @@ export function readSchedulerLease() {
     const root = resolveWorkspaceRoot();
     if (storeExistsSync(root)) {
         const stored = readStoreJsonSync(root, "state/scheduler/lease");
-        if (stored)
+        if (stored !== undefined)
             return stored ?? undefined;
     }
     const raw = safeRead(SCHEDULER_LEASE_REL);
@@ -336,28 +336,46 @@ export function readSchedulerLease() {
         return undefined;
     return parseLease(raw);
 }
+/** Serialize admission as well as persistence across processes. */
+async function withSchedulerTransaction(fn) {
+    const storePath = getWorkspaceStorePath(resolveWorkspaceRoot());
+    return withFileLock(SCHEDULER_LOCK_REL, () => withStoreWriteCoordinator(storePath, fn, { operation_label: "scheduler_transaction" }));
+}
+function hasExecutionOwnership(queue, locks) {
+    return queue.jobs.some((job) => job.status === "running" ||
+        (job.status === "unknown_recovery" && job.reason_code === "handoff_execution_unverified")) ||
+        locks.locks.some((lock) => isJobLockActive(lock));
+}
+function leaseForAcquisition() {
+    // Called inside the transaction: legacy idle leases can be reclaimed immediately.
+    return hasExecutionOwnership(readJobQueue(), readJobLockTable()) ? readSchedulerLease() : undefined;
+}
+// Only called from withSchedulerTransaction. Do not reacquire the store coordinator.
 async function persistSchedulerState(input) {
     const root = resolveWorkspaceRoot();
+    const lease = hasExecutionOwnership(input.queue, input.locks) ? input.lease : undefined;
     if (!storeExistsSync(root)) {
+        // Legacy workspaces share the same cross-process transaction lock. Do not
+        // create a partial store that would hide their handoffs, events, and todos.
         safeWrite(JOB_QUEUE_REL, JSON.stringify({ ...input.queue, updated_at: nowIso() }, null, 2));
         safeWrite(JOB_LOCK_TABLE_REL, JSON.stringify({ ...input.locks, updated_at: nowIso() }, null, 2));
-        safeWrite(SCHEDULER_LEASE_REL, JSON.stringify(input.lease ?? null, null, 2));
+        safeWrite(SCHEDULER_LEASE_REL, JSON.stringify(lease ?? null, null, 2));
         return;
     }
-    const storePath = getWorkspaceStorePath(root);
-    await withStoreWriteCoordinator(storePath, async () => {
-        const store = await openStore(storePath);
-        try {
-            const repo = new SchedulerRepository(store);
-            await repo.replaceState(input);
-            await store.commit();
-            const projections = new ProjectionManager(store, root);
-            await projections.projectAfterCommit(["scheduler"]);
-        }
-        finally {
-            await store.close();
-        }
-    }, { operation_label: "persistSchedulerState" });
+    const store = await openStore(getWorkspaceStorePath(root));
+    try {
+        const repo = new SchedulerRepository(store);
+        await repo.replaceState({
+            ...input,
+            lease,
+        });
+        await store.commit();
+        const projections = new ProjectionManager(store, root);
+        await projections.projectAfterCommit(["scheduler"]);
+    }
+    finally {
+        await store.close();
+    }
 }
 function compareJobs(a, b) {
     const priorityCmp = PRIORITY_WEIGHT[a.priority] - PRIORITY_WEIGHT[b.priority];
@@ -607,7 +625,7 @@ function hasActiveLeaseForOwner(lease, owner, now) {
     return expires.getTime() > now.getTime();
 }
 function ensureLeaseForOwner(owner, now, ttlSeconds = defaultLeaseTtlSeconds()) {
-    const leaseResult = acquireLease(readSchedulerLease(), owner, ttlSeconds, now);
+    const leaseResult = acquireLease(leaseForAcquisition(), owner, ttlSeconds, now);
     if (!leaseResult.acquired) {
         return leaseResult;
     }
@@ -703,6 +721,8 @@ function startJobNow(job, table, lease, now, buf, sourceTool) {
 function reconcileRecoveryState(queue, table, now, recoveryMode, buf) {
     let recovered = 0;
     for (const job of queue.jobs) {
+        if (job.kind === "handoff.lifecycle")
+            continue;
         if (job.status === "unknown_recovery") {
             releaseLocksForRecoveredJob(table, job.job_id, "recovery_hold", now);
             continue;
@@ -754,6 +774,8 @@ function reapStaleRunningJobs(queue, table, now, staleMs, buf) {
         return [];
     const reaped = [];
     for (const job of queue.jobs) {
+        if (job.kind === "handoff.lifecycle")
+            continue;
         if (job.status !== "running")
             continue;
         const activeLocks = table.locks.filter((lock) => lock.job_id === job.job_id && lock.status === "active");
@@ -801,7 +823,7 @@ function reapStaleRunningJobs(queue, table, now, staleMs, buf) {
 }
 export async function enqueueJob(input) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
+    const result = await withSchedulerTransaction(async () => {
         if (!input.kind || input.kind.trim().length === 0) {
             const queue = readJobQueue();
             return {
@@ -900,9 +922,73 @@ export async function enqueueJob(input) {
     await flushTransitionEvents(buf);
     return result;
 }
+/** Mirror handoff lifecycle without admitting or executing a job. */
+export async function syncHandoffLifecycleJob(input) {
+    return withSchedulerTransaction(async () => {
+        const queue = readJobQueue();
+        const locks = readJobLockTable();
+        const now = parseDate(input.now_iso) ?? new Date();
+        let job = queue.jobs.find((row) => row.job_id === input.job_id);
+        if (job && (job.kind !== "handoff.lifecycle" || job.payload.handoff_id !== input.payload?.handoff_id)) {
+            return {
+                ok: false,
+                enqueued: false,
+                path: getJobQueuePath(),
+                queue,
+                nack: { reason_code: "duplicate_job_id", reason: "Job belongs to another lifecycle or execution." },
+            };
+        }
+        const enqueued = !job;
+        if (!job) {
+            job = {
+                job_id: input.job_id,
+                kind: "handoff.lifecycle",
+                payload: input.payload ?? {},
+                status: "blocked",
+                priority: toPriority(input.priority),
+                dependencies: input.dependencies ?? [],
+                resource_requirements: normalizeResources(input.resource_requirements),
+                attempt: 0,
+                max_attempts: 3,
+                backoff_ms: 5000,
+                created_at: nowIso(now),
+                accepted_at: nowIso(now),
+            };
+            queue.jobs.push(job);
+        }
+        job.payload = { ...job.payload, ...input.payload };
+        if (job.payload.status === "completed") {
+            // The canonical handoff completion is the receipt resolving legacy bookkeeping.
+            job.status = "done";
+            job.completed_at = job.completed_at ?? nowIso(now);
+            job.reason_code = undefined;
+            job.error = undefined;
+            releaseLocksForRecoveredJob(locks, job.job_id, "handoff_completed", now);
+        }
+        else if (job.status === "running" || job.status === "unknown_recovery" || hasActiveLockForJob(locks.locks, job.job_id)) {
+            // Do not infer worker death from a legacy synthetic job's kind.
+            job.status = "unknown_recovery";
+            job.reason_code = "handoff_execution_unverified";
+            job.error = "Legacy handoff execution requires a completion receipt; ownership and locks are preserved.";
+        }
+        else if (!TERMINAL_STATUSES.has(job.status)) {
+            job.status = "blocked";
+            job.reason_code = "handoff_metadata_only";
+            job.error = "Lifecycle metadata is synchronized by the handoff registry, not dispatched.";
+        }
+        await persistSchedulerState({ queue, locks, lease: readSchedulerLease() });
+        return {
+            ok: true,
+            enqueued,
+            path: getJobQueuePath(),
+            queue,
+            ack: { job_id: job.job_id, status: job.status },
+        };
+    });
+}
 export async function acknowledgeJob(input) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
+    const result = await withSchedulerTransaction(async () => {
         const queue = readJobQueue();
         const job = queue.jobs.find((row) => row.job_id === input.job_id);
         if (!job) {
@@ -984,20 +1070,23 @@ export async function acknowledgeJob(input) {
 }
 export async function dispatchJobs(input = {}) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
+    const result = await withSchedulerTransaction(async () => {
         const owner = deriveOwner(input.owner);
         const now = parseDate(input.now_iso) ?? new Date();
         const table = readJobLockTable();
         const leaseTtl = typeof input.lease_ttl_seconds === "number" && input.lease_ttl_seconds > 0
             ? Math.floor(input.lease_ttl_seconds)
             : defaultLeaseTtlSeconds();
-        const leaseResult = acquireLease(readSchedulerLease(), owner, leaseTtl, now);
+        const leaseResult = acquireLease(leaseForAcquisition(), owner, leaseTtl, now);
         if (!leaseResult.acquired) {
             const queue = readJobQueue();
             return {
                 ok: false,
+                reason_code: "scheduler_lease_held",
+                error: `Scheduler lease is held by ${leaseResult.lease.owner} until ${leaseResult.lease.expires_at}; dispatch requested by ${owner}.`,
                 owner,
                 lease_acquired: false,
+                lease_retained: true,
                 lease: leaseResult.lease,
                 queue_path: getJobQueuePath(),
                 lock_path: getJobLockTablePath(),
@@ -1006,7 +1095,7 @@ export async function dispatchJobs(input = {}) {
                 summary: {
                     total_jobs: queue.jobs.length,
                     blocked_jobs: queue.jobs.filter((job) => job.status === "blocked").length,
-                    ready_jobs: queue.jobs.filter((job) => job.status === "ready").length,
+                    ready_jobs: queue.jobs.filter((job) => job.status === "ready" && job.kind !== "handoff.lifecycle").length,
                     running_jobs: queue.jobs.filter((job) => job.status === "running").length,
                     started_jobs: 0,
                     recovered_jobs: 0,
@@ -1029,6 +1118,8 @@ export async function dispatchJobs(input = {}) {
         const reapedJobIds = reapStaleRunningJobs(queue, table, now, staleMs, buf);
         const reapedJobs = reapedJobIds.length;
         for (const job of queue.jobs) {
+            if (job.kind === "handoff.lifecycle")
+                continue;
             if (TERMINAL_STATUSES.has(job.status))
                 continue;
             if (job.status === "running" || job.status === "unknown_recovery")
@@ -1051,7 +1142,7 @@ export async function dispatchJobs(input = {}) {
         }
         const occupancy = buildOccupancy(table.locks);
         const readyJobs = queue.jobs
-            .filter((job) => job.status === "ready")
+            .filter((job) => job.status === "ready" && job.kind !== "handoff.lifecycle")
             .sort(compareJobs);
         let startedJobs = 0;
         for (const job of readyJobs) {
@@ -1080,7 +1171,7 @@ export async function dispatchJobs(input = {}) {
         const summary = {
             total_jobs: queue.jobs.length,
             blocked_jobs: queue.jobs.filter((job) => job.status === "blocked").length,
-            ready_jobs: queue.jobs.filter((job) => job.status === "ready").length,
+            ready_jobs: queue.jobs.filter((job) => job.status === "ready" && job.kind !== "handoff.lifecycle").length,
             running_jobs: queue.jobs.filter((job) => job.status === "running").length,
             started_jobs: startedJobs,
             recovered_jobs: recoveredJobs,
@@ -1093,6 +1184,7 @@ export async function dispatchJobs(input = {}) {
             payload: {
                 owner,
                 lease_acquired: true,
+                lease_retained: hasExecutionOwnership(queue, table),
                 lease_id: refreshedLease.lease_id,
                 recovery_mode: leaseResult.recovery_mode,
                 ...summary,
@@ -1107,6 +1199,7 @@ export async function dispatchJobs(input = {}) {
                 owner,
                 lease_id: refreshedLease.lease_id,
                 lease_acquired: true,
+                lease_retained: hasExecutionOwnership(queue, table),
                 recovery_mode: leaseResult.recovery_mode,
                 summary,
             },
@@ -1115,6 +1208,7 @@ export async function dispatchJobs(input = {}) {
             ok: true,
             owner,
             lease_acquired: true,
+            lease_retained: hasExecutionOwnership(queue, table),
             lease: refreshedLease,
             queue_path: getJobQueuePath(),
             lock_path: getJobLockTablePath(),
@@ -1128,7 +1222,7 @@ export async function dispatchJobs(input = {}) {
 }
 export async function dispatchJobNow(input) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
+    const result = await withSchedulerTransaction(async () => {
         const owner = deriveOwner(input.owner);
         const now = parseDate(input.now_iso) ?? new Date();
         const leaseResult = ensureLeaseForOwner(owner, now);
@@ -1155,6 +1249,16 @@ export async function dispatchJobNow(input) {
                 error: `Unknown job_id: ${input.job_id}`,
             };
         }
+        if (job.kind === "handoff.lifecycle") {
+            return {
+                ok: false,
+                queue_path: getJobQueuePath(),
+                lock_path: getJobLockTablePath(),
+                queue,
+                locks: table,
+                error: "Handoff lifecycle jobs are metadata; synchronize the handoff instead of dispatching it.",
+            };
+        }
         if (job.status === "unknown_recovery") {
             return {
                 ok: false,
@@ -1253,7 +1357,7 @@ export async function dispatchJobNow(input) {
 }
 export async function completeJob(input) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
+    const result = await withSchedulerTransaction(async () => {
         const owner = deriveOwner(input.owner);
         const now = parseDate(input.now_iso) ?? new Date();
         const leaseResult = ensureLeaseForOwner(owner, now);
@@ -1394,7 +1498,7 @@ export async function completeJob(input) {
  * heartbeat reliably signals a dead worker.
  */
 export async function heartbeatJob(input) {
-    return withFileLock(SCHEDULER_LOCK_REL, async () => {
+    return withSchedulerTransaction(async () => {
         const owner = deriveOwner(input.owner);
         const now = parseDate(input.now_iso) ?? new Date();
         const leaseTtl = typeof input.lease_ttl_seconds === "number" && input.lease_ttl_seconds > 0
@@ -1464,7 +1568,7 @@ export async function heartbeatJob(input) {
  */
 export async function reapStaleRunningJobsTick(input = {}) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
+    const result = await withSchedulerTransaction(async () => {
         const now = parseDate(input.now_iso) ?? new Date();
         const staleMs = resolveStaleMs(input.heartbeat_stale_seconds);
         const queue = readJobQueue();

package/dist/orchestrator-supervisor.d.ts

@@ -1,3 +1,4 @@
+import { type DispatchJobsResult } from "./job-scheduler.js";
 import type { BridgeResult } from "./model-bridge.js";
 import type { LocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
 export type TaskStepStatus = "planned" | "running" | "done" | "failed" | "skipped" | "blocked";
@@ -151,6 +152,8 @@ export declare function amendTaskPlanWithTransition(plan: TaskPlan, amendment: T
 export declare function promoteParallelGroupToScheduler(plan: TaskPlan, parallelGroup: string, owner?: string): Promise<{
     plan: TaskPlan;
     job_ids: string[];
+    dispatch?: DispatchJobsResult;
+    blocked_reason?: string;
 }>;
 export declare function superviseTaskPlan(inputPlan: TaskPlan, hooks: SupervisorHooks): Promise<SupervisorRunResult>;
 //# sourceMappingURL=orchestrator-supervisor.d.ts.map

package/dist/orchestrator-supervisor.js

@@ -281,7 +281,10 @@ export async function promoteParallelGroupToScheduler(plan, parallelGroup, owner
     const jobIds = [];
     const nextSteps = cloneSteps(plan.steps);
     for (const step of readySteps) {
+        // Stable identity also makes retrying the original plan safe after a refused tick.
+        const requestedJobId = step.job_id ?? `PLANJOB-${plan.plan_id}-${step.step_id}`;
         const enqueued = await enqueueJob({
+            job_id: requestedJobId,
             kind: step.role,
             payload: {
                 task: step.task,
@@ -295,7 +298,11 @@ export async function promoteParallelGroupToScheduler(plan, parallelGroup, owner
                 ref: dependency,
             })) ?? [],
         });
-        const jobId = enqueued.ack?.job_id;
+        const existingJob = enqueued.nack?.reason_code === "duplicate_job_id"
+            ? enqueued.queue.jobs.find((job) => job.job_id === requestedJobId &&
+                job.payload.plan_id === plan.plan_id && job.payload.step_id === step.step_id)
+            : undefined;
+        const jobId = enqueued.ack?.job_id ?? existingJob?.job_id;
         if (!jobId)
             continue;
         jobIds.push(jobId);
@@ -303,36 +310,70 @@ export async function promoteParallelGroupToScheduler(plan, parallelGroup, owner
         if (stepIndex >= 0) {
             nextSteps[stepIndex] = {
                 ...nextSteps[stepIndex],
-                status: "running",
                 job_id: jobId,
             };
         }
     }
+    let dispatch;
+    let blockedReason;
     if (jobIds.length > 0) {
         const refs = deriveWorkspaceVericifyRunRef({
             session_id: plan.plan_id,
             role: "orchestrator",
         });
-        await dispatchJobs({ owner });
+        dispatch = await dispatchJobs({ owner });
+        blockedReason = dispatch.error;
+        const promotedIds = new Set(jobIds);
+        for (const step of nextSteps) {
+            if (!step.job_id || !promotedIds.has(step.job_id))
+                continue;
+            const job = dispatch.queue.jobs.find((candidate) => candidate.job_id === step.job_id);
+            // A recorded assignment is not proof of dispatch. Keep queued steps retryable.
+            switch (job?.status) {
+                case "running":
+                    step.status = "running";
+                    break;
+                case "done":
+                    step.status = "done";
+                    break;
+                case "failed_terminal":
+                    step.status = "failed";
+                    break;
+                case "canceled":
+                    step.status = "skipped";
+                    break;
+                case "unknown_recovery":
+                    step.status = "blocked";
+                    break;
+                default: step.status = "planned";
+            }
+            step.blocked_reason = step.status === "planned" || step.status === "blocked"
+                ? dispatch.error ?? job?.error
+                : undefined;
+        }
         await appendVericifyProcessPostSafe({
             run_id: refs.run_id,
             branch_id: refs.branch_id,
             lane_id: refs.lane_id,
             agent_id: "agent-orchestrator",
-            kind: "progress",
-            summary: `Promoted parallel group '${parallelGroup}' to scheduler: ${jobIds.join(", ")}`,
+            kind: blockedReason ? "blocker" : "progress",
+            summary: blockedReason
+                ? `Parallel group '${parallelGroup}' queued; ${blockedReason}`
+                : `Promoted parallel group '${parallelGroup}' to scheduler: ${jobIds.join(", ")}; running=${nextSteps.filter((step) => step.job_id && promotedIds.has(step.job_id) && step.status === "running").length}`,
             tool_refs: ["enqueue_job", "dispatch_jobs"],
             evidence_refs: jobIds,
         });
     }
+    const promotedPlan = withDerivedStatus({
+        ...plan,
+        execution_mode: "scheduled",
+        steps: nextSteps,
+    });
     return {
-        plan: withDerivedStatus({
-            ...plan,
-            execution_mode: "scheduled",
-            steps: nextSteps,
-            status: "executing",
-        }),
+        plan: blockedReason ? { ...promotedPlan, status: "blocked" } : promotedPlan,
         job_ids: jobIds,
+        dispatch,
+        blocked_reason: blockedReason,
     };
 }
 export async function superviseTaskPlan(inputPlan, hooks) {
@@ -368,6 +409,17 @@ export async function superviseTaskPlan(inputPlan, hooks) {
                 const promoted = await promoteParallelGroupToScheduler(plan, readyGroup);
                 jobIds.push(...promoted.job_ids);
                 plan = promoted.plan;
+                if (promoted.blocked_reason) {
+                    await hooks.emitStatusEvent?.({ status: "blocked", summary: promoted.blocked_reason });
+                    await hooks.contextSnapshot?.(plan);
+                    return {
+                        plan,
+                        handoff_ids: handoffIds,
+                        job_ids: jobIds,
+                        circuit_opened: false,
+                        blocked_reason: promoted.blocked_reason,
+                    };
+                }
                 break;
             }
         }

package/dist/server.d.ts

@@ -11,9 +11,20 @@ export declare function createAceServer(options?: CreateAceServerOptions): McpSe
 export type AceHostProfile = "host-min" | "full";
 /**
  * Curated premium-host surface (report WS-G). ~15–25 high-value tools instead of the
- * full tool surface, cutting the per-session schema tax. Everything omitted here remains reachable
- * via `run_orchestrator` delegation or by starting with `--profile full`. Goal-engine
- * tools (start_goal/…) are intentionally absent until WS-F ships.
+ * full tool surface, cutting the per-session schema tax. `run_orchestrator` only reaches an
+ * omitted tool if the model-bridge child it spawns happens to have that tool in its own MCP
+ * session — it is a role/plan dispatcher, not a generic proxy for any omitted tool by name.
+ * The reliable way to reach anything below is to start with `--profile full`.
+ *
+ * Whole domains are intentionally absent, not just individual tools: goal-engine
+ * (start_goal/get_goal_status/resume_goal/stop_goal — until WS-F ships), git
+ * (git_status/git_diff/git_log/git_commit), scheduler (enqueue_job/dispatch_jobs/
+ * heartbeat_job/reap_stale_jobs/get_lock_table/…), drift/change-intelligence
+ * (snapshot_state/semantic_diff/drift_report/rewrite_targets/list_snapshots), discovery
+ * (scan_workspace_delta/web_research_packet/codemunch_snapshot/codemunch_index/
+ * mcp_ingestion_probe/refresh_astgrep_index), skills (skill_catalog_summary/skill_audit/
+ * problem_triage), and todo (get_todo/update_todo/get_run_ledger) all have zero
+ * representation below.
  */
 export declare const HOST_MIN_TOOL_PROFILE: readonly string[];
 export declare function resolveHostProfileAllowlist(profile: AceHostProfile): readonly string[] | undefined;

package/dist/server.js

@@ -94,9 +94,20 @@ async function verifyMcpStoreStartup(workspaceRoot, logStartup) {
 }
 /**
  * Curated premium-host surface (report WS-G). ~15–25 high-value tools instead of the
- * full tool surface, cutting the per-session schema tax. Everything omitted here remains reachable
- * via `run_orchestrator` delegation or by starting with `--profile full`. Goal-engine
- * tools (start_goal/…) are intentionally absent until WS-F ships.
+ * full tool surface, cutting the per-session schema tax. `run_orchestrator` only reaches an
+ * omitted tool if the model-bridge child it spawns happens to have that tool in its own MCP
+ * session — it is a role/plan dispatcher, not a generic proxy for any omitted tool by name.
+ * The reliable way to reach anything below is to start with `--profile full`.
+ *
+ * Whole domains are intentionally absent, not just individual tools: goal-engine
+ * (start_goal/get_goal_status/resume_goal/stop_goal — until WS-F ships), git
+ * (git_status/git_diff/git_log/git_commit), scheduler (enqueue_job/dispatch_jobs/
+ * heartbeat_job/reap_stale_jobs/get_lock_table/…), drift/change-intelligence
+ * (snapshot_state/semantic_diff/drift_report/rewrite_targets/list_snapshots), discovery
+ * (scan_workspace_delta/web_research_packet/codemunch_snapshot/codemunch_index/
+ * mcp_ingestion_probe/refresh_astgrep_index), skills (skill_catalog_summary/skill_audit/
+ * problem_triage), and todo (get_todo/update_todo/get_run_ledger) all have zero
+ * representation below.
  */
 export const HOST_MIN_TOOL_PROFILE = [
     "recall_context",

package/dist/tools-files.js

@@ -17,7 +17,8 @@ import { safeEditFile, diffContents, applyPatch } from "./safe-edit.js";
 import { detectAstgrepCommand, flattenMetaVariables, locateAstgrepMatches, runAstgrepQuery, } from "./astgrep-index.js";
 import { readRuntimeProfile, resolveEffectiveSurgicalReadBudget, validateRuntimeProfileContent, } from "./runtime-profile.js";
 import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
-import { listStoreKeysSync } from "./store/store-snapshot.js";
+import { getWorkspaceStorePath, listStoreKeysSync } from "./store/store-snapshot.js";
+import { listStoreEntries } from "./store/store-cli.js";
 function reasonCodeFromError(error) {
     return typeof error === "object" && error !== null && "reason_code" in error
         ? String(error.reason_code)
@@ -1092,7 +1093,7 @@ export function registerFileTools(server) {
             ],
         };
     });
-    server.tool("list_workspace", "List files/directories in a workspace path", {
+    server.tool("list_workspace", "List files/directories in a workspace path, plus any ACEPACK store-only artifacts under it (content the lifecycle sweep folded into the store and removed from disk). Store-only entries are flat logical paths, not directory entries; read them back with read_workspace_file.", {
         path: z
             .string()
             .optional()
@@ -1110,24 +1111,47 @@ export function registerFileTools(server) {
                 ],
             };
         }
+        const diskNames = new Set();
+        let diskSection;
+        let diskError;
         try {
-            const entries = readdirSync(dir, { withFileTypes: true })
+            const diskEntries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of diskEntries)
+                diskNames.add(entry.name);
+            diskSection = diskEntries
                 .map((entry) => `${entry.isDirectory() ? "[DIR]" : "[FILE]"} ${entry.name}`)
                 .join("\n");
-            return {
-                content: [{ type: "text", text: `# ${dir}\n\n${entries}` }],
-            };
         }
         catch (err) {
+            diskError = String(err);
+        }
+        const storePrefix = normalizeRelPath(rel);
+        let storeSection;
+        if (existsSync(getWorkspaceStorePath(WORKSPACE_ROOT))) {
+            const storeOnly = listStoreEntries(WORKSPACE_ROOT, storePrefix).filter((entry) => !diskNames.has(entry.path.slice(storePrefix.length).replace(/^\//, "").split("/")[0]));
+            if (storeOnly.length > 0) {
+                storeSection = storeOnly
+                    .map((entry) => `[STORE] ${entry.path}  (${entry.bytes}B)`)
+                    .join("\n");
+            }
+        }
+        if (diskError && !storeSection) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `❌ Could not list ${dir}\n${String(err)}`,
+                        text: `❌ Could not list ${dir}\n${diskError}`,
                     },
                 ],
             };
         }
+        const sections = [
+            diskError ? `(no such disk directory: ${diskError})` : diskSection || "(empty)",
+            storeSection ? `\nStore-only (not on disk):\n${storeSection}` : undefined,
+        ].filter(Boolean);
+        return {
+            content: [{ type: "text", text: `# ${dir}\n\n${sections.join("\n")}` }],
+        };
     });
     // ── Safe-edit (new P0 tool) ───────────────────────────────────────
     server.tool("safe_edit_file", "Edit a file using copy→validate→swap pattern. Automatically rolls back if validation or tests fail. Prefer apply_patch for small targeted edits. Cost: heavy for large files.", {

package/dist/tools-handoff.d.ts

@@ -3,13 +3,14 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { HandoffRecord } from "./handoff-registry.js";
-import { DispatchJobsResult } from "./job-scheduler.js";
 export interface HandoffSchedulerSyncResult {
     ok: boolean;
     job_id: string;
     enqueued: boolean;
     enqueue_reason?: string;
-    tick: DispatchJobsResult;
+    dispatch_performed: false;
+    reconciliation_required: boolean;
+    reconciliation_reason?: string;
 }
 export interface HandoffSchedulerBackfillResult {
     scanned: number;

package/dist/tools-handoff.js

@@ -10,9 +10,8 @@ import { validateHandoffPayload, validateSwarmHandoffPayload, lintHandoffPayload
 import { acknowledgeHandoffSafe, getHandoffRegistryPath, readHandoffRegistry, registerHandoffSafe, } from "./handoff-registry.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { refreshKanbanArtifacts } from "./kanban.js";
-import { dispatchJobs, enqueueJob } from "./job-scheduler.js";
+import { readJobQueue, syncHandoffLifecycleJob } from "./job-scheduler.js";
 import { appendStatusEventSafe } from "./status-events.js";
-const DEFAULT_SCHEDULER_OWNER = "capability-ops";
 function toSchedulerPriority(input) {
     if (input === "P0" || input === "P1" || input === "P2" || input === "P3") {
         return input;
@@ -62,9 +61,9 @@ async function recordHandoffSchedulerSyncEffects(record, sync) {
     }
 }
 export async function syncHandoffIntoScheduler(record, options = {}) {
-    const owner = options.owner?.trim() || DEFAULT_SCHEDULER_OWNER;
     const jobId = handoffSchedulerJobId(record.handoff_id);
-    const enqueue = await enqueueJob({
+    const enqueue = await syncHandoffLifecycleJob({
+        now_iso: options.now_iso,
         job_id: jobId,
         kind: "handoff.lifecycle",
         priority: toSchedulerPriority(record.priority),
@@ -85,28 +84,30 @@ export async function syncHandoffIntoScheduler(record, options = {}) {
         ],
         resource_requirements: buildHandoffResources(record),
     });
-    const enqueued = enqueue.ok;
+    const enqueued = enqueue.enqueued;
     const enqueueReason = enqueue.ok || !enqueue.nack
         ? undefined
         : `${enqueue.nack.reason_code}: ${enqueue.nack.reason}`;
-    const tick = await dispatchJobs({
-        owner,
-        ...(options.now_iso ? { now_iso: options.now_iso } : {}),
-    });
     const syncResult = {
-        ok: enqueue.ok || enqueue.nack?.reason_code === "duplicate_job_id",
+        ok: enqueue.ok,
         job_id: jobId,
         enqueued,
         enqueue_reason: enqueueReason,
-        tick,
+        dispatch_performed: false,
+        reconciliation_required: enqueue.ack?.status === "unknown_recovery",
+        reconciliation_reason: enqueue.ack?.status === "unknown_recovery"
+            ? enqueue.queue.jobs.find((job) => job.job_id === jobId)?.error
+            : undefined,
     };
     await recordHandoffSchedulerSyncEffects(record, syncResult);
     return syncResult;
 }
 export async function backfillHandoffsIntoScheduler(options = {}) {
     const registry = readHandoffRegistry();
+    const existing = new Set(readJobQueue().jobs.filter((job) => job.kind === "handoff.lifecycle")
+        .map((job) => job.payload.handoff_id));
     const active = Object.values(registry.handoffs)
-        .filter((record) => record.status !== "completed")
+        .filter((record) => record.status !== "completed" || existing.has(record.handoff_id))
         .sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
     const result = {
         scanned: active.length,
@@ -117,16 +118,15 @@ export async function backfillHandoffsIntoScheduler(options = {}) {
     for (const record of active) {
         try {
             const sync = await syncHandoffIntoScheduler(record, options);
+            if (sync.enqueued)
+                result.enqueued += 1;
             if (sync.ok) {
                 result.synced += 1;
-                if (sync.enqueued) {
-                    result.enqueued += 1;
-                }
             }
-            else {
+            if (!sync.ok || sync.reconciliation_required) {
                 result.failures.push({
                     handoff_id: record.handoff_id,
-                    error: sync.enqueue_reason ?? "scheduler sync returned not-ok",
+                    error: sync.reconciliation_reason ?? sync.enqueue_reason ?? "scheduler sync returned not-ok",
                 });
             }
         }
@@ -282,7 +282,10 @@ export function registerHandoffTools(server) {
                         `Handoff registry: ${registry.path}`,
                         `Run ledger: ${runLedger.path} (${runLedger.entry.id})`,
                         `Scheduler job: ${schedulerSync.job_id} (${schedulerSync.enqueued ? "enqueued" : "already_exists"})`,
-                        `Scheduler dispatch: lease_acquired=${schedulerSync.tick.lease_acquired}, started=${schedulerSync.tick.summary.started_jobs}, ready=${schedulerSync.tick.summary.ready_jobs}`,
+                        "Scheduler: handoff metadata synchronized; no execution dispatch",
+                        schedulerSync.reconciliation_required
+                            ? `Scheduler reconciliation required: ${schedulerSync.reconciliation_reason}`
+                            : "",
                         schedulerSync.enqueue_reason
                             ? `Scheduler enqueue detail: ${schedulerSync.enqueue_reason}`
                             : "",
@@ -466,7 +469,10 @@ export function registerHandoffTools(server) {
                             ? `scheduler-job: ${schedulerSync.job_id} (${schedulerSync.enqueued ? "enqueued" : "already_exists"})`
                             : "",
                         schedulerSync
-                            ? `scheduler-dispatch: lease_acquired=${schedulerSync.tick.lease_acquired}, started=${schedulerSync.tick.summary.started_jobs}, ready=${schedulerSync.tick.summary.ready_jobs}`
+                            ? "scheduler: handoff metadata synchronized; no execution dispatch"
+                            : "",
+                        schedulerSync?.reconciliation_required
+                            ? `scheduler-reconciliation-required: ${schedulerSync.reconciliation_reason}`
                             : "",
                         schedulerSync?.enqueue_reason
                             ? `scheduler-enqueue-detail: ${schedulerSync.enqueue_reason}`

package/dist/tools-scheduler.js

@@ -144,6 +144,7 @@ export function registerSchedulerTools(server) {
                         result.ok ? "✅ Scheduler dispatch completed" : "⚠️ Scheduler lease not acquired",
                         `Owner: ${result.owner}`,
                         `Lease acquired: ${result.lease_acquired}`,
+                        `Lease retained for execution: ${result.lease_retained}`,
                         `Queue: ${result.queue_path}`,
                         `Locks: ${result.lock_path}`,
                         asJsonBlock(result),

package/docs/mcp-tool-reference.md

@@ -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"],

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,6 +1,6 @@
 {
   "name": "@voybio/ace-swarm",
-  "version": "2.4.7",
+  "version": "2.4.9",
   "description": "ACE Framework MCP server and CLI — single-file ACEPACK state, local-model serving, agent orchestration, and host compliance enforcement.",
   "type": "module",
   "main": "dist/index.js",