@voybio/ace-swarm 2.4.8 → 2.4.9

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/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.8",
+  "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",