@voybio/ace-swarm 2.4.9 → 2.4.10

package/dist/job-scheduler.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { readHandoffRegistry } from "./handoff-registry.js";
-import { resolveWorkspaceRoot, safeRead, safeWrite, withFileLock, wsPath } from "./helpers.js";
+import { resolveWorkspaceRoot, withWorkspaceRoot, safeRead, safeWrite, withFileLock, wsPath } from "./helpers.js";
 import { isReadError } from "./shared.js";
 import { appendStatusEventSafe, readStatusEvents } from "./status-events.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
@@ -10,6 +10,7 @@ import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { SchedulerRepository } from "./store/repositories/scheduler-repository.js";
 import { getWorkspaceStorePath, readStoreJsonSync, storeExistsSync, } from "./store/store-snapshot.js";
 import { withStoreWriteCoordinator } from "./store/write-coordinator.js";
+import { probeProcess, readProcessIdentity } from "./process-identity.js";
 // ── Buffered transition-event infrastructure ────────────────────────
 // Events are collected during the scheduler lock and flushed after
 // the lock is released.  Emission is failure-tolerant: a broken
@@ -204,6 +205,8 @@ function parseQueueFile(raw) {
                 evidence_ref: typeof job.evidence_ref === "string" ? job.evidence_ref : undefined,
                 error: typeof job.error === "string" ? job.error : undefined,
                 reason_code: typeof job.reason_code === "string" ? job.reason_code : undefined,
+                execution: job.execution && typeof job.execution === "object" ? { ...job.execution } : undefined,
+                execution_children: Array.isArray(job.execution_children) ? job.execution_children.map(identity => ({ ...identity })) : undefined,
             });
         }
         return {
@@ -289,16 +292,28 @@ function parseLease(raw) {
         return undefined;
     }
 }
-export function getJobQueuePath() {
+export function getJobQueuePath(workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => getJobQueuePathInWorkspace());
+}
+function getJobQueuePathInWorkspace() {
     return wsPath(JOB_QUEUE_REL);
 }
-export function getJobLockTablePath() {
+export function getJobLockTablePath(workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => getJobLockTablePathInWorkspace());
+}
+function getJobLockTablePathInWorkspace() {
     return wsPath(JOB_LOCK_TABLE_REL);
 }
-export function getSchedulerLeasePath() {
+export function getSchedulerLeasePath(workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => getSchedulerLeasePathInWorkspace());
+}
+function getSchedulerLeasePathInWorkspace() {
     return wsPath(SCHEDULER_LEASE_REL);
 }
-export function readJobQueue() {
+export function readJobQueue(workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => readJobQueueInWorkspace());
+}
+function readJobQueueInWorkspace() {
     const root = resolveWorkspaceRoot();
     if (storeExistsSync(root)) {
         const stored = readStoreJsonSync(root, "state/scheduler/queue");
@@ -311,7 +326,10 @@ export function readJobQueue() {
         return defaultQueueFile();
     return parseQueueFile(raw) ?? defaultQueueFile();
 }
-export function readJobLockTable() {
+export function readJobLockTable(workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => readJobLockTableInWorkspace());
+}
+function readJobLockTableInWorkspace() {
     const root = resolveWorkspaceRoot();
     if (storeExistsSync(root)) {
         const stored = readStoreJsonSync(root, "state/scheduler/locks");
@@ -324,7 +342,10 @@ export function readJobLockTable() {
         return defaultJobLockFile();
     return parseJobLockFile(raw) ?? defaultJobLockFile();
 }
-export function readSchedulerLease() {
+export function readSchedulerLease(workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => readSchedulerLeaseInWorkspace());
+}
+function readSchedulerLeaseInWorkspace() {
     const root = resolveWorkspaceRoot();
     if (storeExistsSync(root)) {
         const stored = readStoreJsonSync(root, "state/scheduler/lease");
@@ -341,9 +362,17 @@ async function withSchedulerTransaction(fn) {
     const storePath = getWorkspaceStorePath(resolveWorkspaceRoot());
     return withFileLock(SCHEDULER_LOCK_REL, () => withStoreWriteCoordinator(storePath, fn, { operation_label: "scheduler_transaction" }));
 }
+function probeJobExecution(job) {
+    const identities = [...(job.execution ? [job.execution] : []), ...(job.execution_children ?? [])];
+    const states = identities.map(probeProcess);
+    if (states.includes("alive"))
+        return "alive";
+    return states.includes("unknown") ? "unknown" : "dead";
+}
 function hasExecutionOwnership(queue, locks) {
     return queue.jobs.some((job) => job.status === "running" ||
-        (job.status === "unknown_recovery" && job.reason_code === "handoff_execution_unverified")) ||
+        (job.status === "unknown_recovery" && (job.reason_code === "handoff_execution_unverified" ||
+            probeJobExecution(job) !== "dead"))) ||
         locks.locks.some((lock) => isJobLockActive(lock));
 }
 function leaseForAcquisition() {
@@ -601,6 +630,11 @@ function acquireLease(existing, owner, ttlSeconds, now) {
     }
     const existingExpiry = parseDate(existing.expires_at);
     const expired = !existingExpiry || existingExpiry.getTime() <= now.getTime();
+    // A missed heartbeat is not evidence that an executing process has exited.
+    // Do not steal its owner lease while its identity is live or uncertain.
+    if (expired && existing.owner !== owner && readJobQueue().jobs.some((job) => (job.status === "running" || job.status === "unknown_recovery") &&
+        probeJobExecution(job) !== "dead"))
+        return { acquired: false, lease: existing, recovery_mode: false };
     if (expired || existing.owner === owner) {
         const lease = {
             version: 1,
@@ -718,11 +752,18 @@ function startJobNow(job, table, lease, now, buf, sourceTool) {
     });
     return { acquired_at: acquiredAt, resources };
 }
-function reconcileRecoveryState(queue, table, now, recoveryMode, buf) {
+function reconcileRecoveryState(queue, table, now, recoveryMode, buf, selected) {
     let recovered = 0;
     for (const job of queue.jobs) {
+        if (selected && !selected.has(job.job_id))
+            continue;
         if (job.kind === "handoff.lifecycle")
             continue;
+        if ((job.status === "running" || job.status === "unknown_recovery") && probeJobExecution(job) !== "dead") {
+            // Preserve ownership even during lease recovery or missing lock metadata.
+            // A retained uncertain execution must never be dispatched a second time.
+            continue;
+        }
         if (job.status === "unknown_recovery") {
             releaseLocksForRecoveredJob(table, job.job_id, "recovery_hold", now);
             continue;
@@ -769,11 +810,13 @@ function reconcileRecoveryState(queue, table, now, recoveryMode, buf) {
  * Missing-lock jobs are intentionally left to `reconcileRecoveryState`, which
  * runs first; this pass only inspects jobs that still hold active locks.
  */
-function reapStaleRunningJobs(queue, table, now, staleMs, buf) {
+function reapStaleRunningJobs(queue, table, now, staleMs, buf, selected) {
     if (staleMs <= 0)
         return [];
     const reaped = [];
     for (const job of queue.jobs) {
+        if (selected && !selected.has(job.job_id))
+            continue;
         if (job.kind === "handoff.lifecycle")
             continue;
         if (job.status !== "running")
@@ -787,6 +830,14 @@ function reapStaleRunningJobs(queue, table, now, staleMs, buf) {
         const ageMs = now.getTime() - lastBeat;
         if (ageMs <= staleMs)
             continue;
+        if (job.execution || job.execution_children?.length) {
+            const processState = probeJobExecution(job);
+            if (processState !== "dead") {
+                job.reason_code = `heartbeat_stale_process_${processState}`;
+                job.error = `Worker heartbeat is stale, but execution process is ${processState}; execution and resource locks are retained pending recovery.`;
+                continue;
+            }
+        }
         const previousStatus = job.status;
         job.status = "unknown_recovery";
         job.reason_code = "heartbeat_stale";
@@ -821,7 +872,10 @@ function reapStaleRunningJobs(queue, table, now, staleMs, buf) {
     }
     return reaped;
 }
-export async function enqueueJob(input) {
+export async function enqueueJob(input, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => enqueueJobInWorkspace(input));
+}
+async function enqueueJobInWorkspace(input) {
     const buf = newEventBuffer();
     const result = await withSchedulerTransaction(async () => {
         if (!input.kind || input.kind.trim().length === 0) {
@@ -923,7 +977,10 @@ export async function enqueueJob(input) {
     return result;
 }
 /** Mirror handoff lifecycle without admitting or executing a job. */
-export async function syncHandoffLifecycleJob(input) {
+export async function syncHandoffLifecycleJob(input, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => syncHandoffLifecycleJobInWorkspace(input));
+}
+async function syncHandoffLifecycleJobInWorkspace(input) {
     return withSchedulerTransaction(async () => {
         const queue = readJobQueue();
         const locks = readJobLockTable();
@@ -986,7 +1043,10 @@ export async function syncHandoffLifecycleJob(input) {
         };
     });
 }
-export async function acknowledgeJob(input) {
+export async function acknowledgeJob(input, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => acknowledgeJobInWorkspace(input));
+}
+async function acknowledgeJobInWorkspace(input) {
     const buf = newEventBuffer();
     const result = await withSchedulerTransaction(async () => {
         const queue = readJobQueue();
@@ -1068,8 +1128,12 @@ export async function acknowledgeJob(input) {
     await flushTransitionEvents(buf);
     return result;
 }
-export async function dispatchJobs(input = {}) {
+export async function dispatchJobs(input = {}, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => dispatchJobsInWorkspace(input));
+}
+async function dispatchJobsInWorkspace(input = {}) {
     const buf = newEventBuffer();
+    const selected = input.job_ids === undefined ? undefined : new Set(input.job_ids);
     const result = await withSchedulerTransaction(async () => {
         const owner = deriveOwner(input.owner);
         const now = parseDate(input.now_iso) ?? new Date();
@@ -1109,15 +1173,17 @@ export async function dispatchJobs(input = {}) {
             handoffState: readHandoffRegistry(),
             statusEvents: readStatusEvents(500),
         };
-        const recoveredJobs = reconcileRecoveryState(queue, table, now, leaseResult.recovery_mode, buf);
+        const recoveredJobs = reconcileRecoveryState(queue, table, now, leaseResult.recovery_mode, buf, selected);
         // Heartbeat watchdog: reap running jobs whose worker heartbeat is stale.
         // NOTE: dispatch deliberately does NOT re-stamp running-job heartbeats here.
         // Only a live worker (heartbeatJob) or a fresh start proves liveness; if the
         // dispatcher renewed heartbeats it would mask worker death (root cause of D3).
         const staleMs = resolveStaleMs(input.heartbeat_stale_seconds);
-        const reapedJobIds = reapStaleRunningJobs(queue, table, now, staleMs, buf);
+        const reapedJobIds = reapStaleRunningJobs(queue, table, now, staleMs, buf, selected);
         const reapedJobs = reapedJobIds.length;
         for (const job of queue.jobs) {
+            if (selected && !selected.has(job.job_id))
+                continue;
             if (job.kind === "handoff.lifecycle")
                 continue;
             if (TERMINAL_STATUSES.has(job.status))
@@ -1142,7 +1208,7 @@ export async function dispatchJobs(input = {}) {
         }
         const occupancy = buildOccupancy(table.locks);
         const readyJobs = queue.jobs
-            .filter((job) => job.status === "ready" && job.kind !== "handoff.lifecycle")
+            .filter((job) => job.status === "ready" && job.kind !== "handoff.lifecycle" && (!selected || selected.has(job.job_id)))
             .sort(compareJobs);
         let startedJobs = 0;
         for (const job of readyJobs) {
@@ -1220,7 +1286,10 @@ export async function dispatchJobs(input = {}) {
     await flushTransitionEvents(buf);
     return result;
 }
-export async function dispatchJobNow(input) {
+export async function dispatchJobNow(input, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => dispatchJobNowInWorkspace(input));
+}
+async function dispatchJobNowInWorkspace(input) {
     const buf = newEventBuffer();
     const result = await withSchedulerTransaction(async () => {
         const owner = deriveOwner(input.owner);
@@ -1355,7 +1424,70 @@ export async function dispatchJobNow(input) {
     await flushTransitionEvents(buf);
     return result;
 }
-export async function completeJob(input) {
+/** Atomically claim the side-effecting handler, independently of scheduler owner. */
+export async function claimJobExecution(input, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => withSchedulerTransaction(async () => {
+        const now = parseDate(input.now_iso) ?? new Date();
+        const owner = deriveOwner(input.owner);
+        const lease = ensureLeaseForOwner(owner, now);
+        if (!lease.acquired)
+            return { ok: false, reason_code: "scheduler_lease_held", error: "Execution owner does not hold the scheduler lease." };
+        const queue = readJobQueue();
+        const locks = readJobLockTable();
+        const job = queue.jobs.find(row => row.job_id === input.job_id);
+        if (!job || job.status !== "running")
+            return { ok: false, reason_code: "job_not_running", job };
+        if (job.execution || job.execution_children?.length) {
+            const state = probeJobExecution(job);
+            if (state === "dead") {
+                // The prior process may have performed side effects before it exited.
+                // Preserve uncertainty instead of replaying the handler automatically.
+                job.status = "unknown_recovery";
+                job.reason_code = "execution_process_exited";
+                job.error = "Claimed execution process exited; inspect retained outcomes before retrying.";
+                job.next_attempt_at = undefined;
+                releaseLocksForRecoveredJob(locks, job.job_id, "execution_process_exited", now);
+                await persistSchedulerState({ queue, locks, lease: lease.lease });
+            }
+            return { ok: false, reason_code: state === "alive" ? "execution_claimed" : state === "unknown" ? "execution_uncertain" : "execution_dead", job };
+        }
+        if (!hasActiveLockForJob(locks.locks, job.job_id))
+            return { ok: false, reason_code: "execution_missing_locks", job };
+        const identity = readProcessIdentity(process.pid);
+        if (!identity)
+            return { ok: false, reason_code: "identity_unavailable", error: "Cannot safely identify the worker process; handler was not invoked.", job };
+        const token = randomUUID();
+        job.execution = { ...identity, token };
+        job.execution_children = undefined;
+        await persistSchedulerState({ queue, locks, lease: lease.lease });
+        return { ok: true, token, job };
+    }));
+}
+/** Register a command before waiting on it; only its claimed attempt may do so. */
+export async function recordJobExecutionChild(input, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => withSchedulerTransaction(async () => {
+        const queue = readJobQueue();
+        const job = queue.jobs.find(row => row.job_id === input.job_id);
+        if (!job || job.status !== "running")
+            return { ok: false, reason_code: "job_not_running" };
+        if (!input.token || job.execution?.token !== input.token)
+            return { ok: false, reason_code: "execution_token_mismatch" };
+        const identity = input.identity;
+        if (!Number.isSafeInteger(identity.pid) || identity.pid <= 1 || !identity.started_at || !identity.hostname) {
+            return { ok: false, reason_code: "execution_identity_invalid" };
+        }
+        job.execution_children ??= [];
+        if (!job.execution_children.some(child => child.pid === identity.pid && child.started_at === identity.started_at && child.hostname === identity.hostname)) {
+            job.execution_children.push({ ...identity });
+            await persistSchedulerState({ queue, locks: readJobLockTable(), lease: readSchedulerLease() });
+        }
+        return { ok: true };
+    }));
+}
+export async function completeJob(input, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => completeJobInWorkspace(input));
+}
+async function completeJobInWorkspace(input) {
     const buf = newEventBuffer();
     const result = await withSchedulerTransaction(async () => {
         const owner = deriveOwner(input.owner);
@@ -1406,6 +1538,9 @@ export async function completeJob(input) {
             };
         }
         const success = input.success !== false;
+        // The claim belongs to this attempt only. A deliberate retry gets a new one.
+        job.execution = undefined;
+        job.execution_children = undefined;
         for (const lock of table.locks) {
             if (lock.job_id !== input.job_id)
                 continue;
@@ -1497,7 +1632,10 @@ export async function completeJob(input) {
  * job's heartbeat — the dispatcher deliberately does not, so a missing
  * heartbeat reliably signals a dead worker.
  */
-export async function heartbeatJob(input) {
+export async function heartbeatJob(input, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => heartbeatJobInWorkspace(input));
+}
+async function heartbeatJobInWorkspace(input) {
     return withSchedulerTransaction(async () => {
         const owner = deriveOwner(input.owner);
         const now = parseDate(input.now_iso) ?? new Date();
@@ -1542,6 +1680,10 @@ export async function heartbeatJob(input) {
             };
         }
         const beatAt = nowIso(now);
+        if (job.reason_code?.startsWith("heartbeat_stale_process_")) {
+            job.reason_code = undefined;
+            job.error = undefined;
+        }
         for (const lock of activeLocks) {
             lock.heartbeat_at = beatAt;
             lock.lease_id = leaseResult.lease.lease_id;
@@ -1566,21 +1708,25 @@ export async function heartbeatJob(input) {
  * watchdog cadence separate from dispatch. Does not require lease ownership —
  * reaping a dead worker's job must not depend on holding the lease.
  */
-export async function reapStaleRunningJobsTick(input = {}) {
+export async function reapStaleRunningJobsTick(input = {}, workspaceRoot = resolveWorkspaceRoot()) {
+    return withWorkspaceRoot(workspaceRoot, () => reapStaleRunningJobsTickInWorkspace(input));
+}
+async function reapStaleRunningJobsTickInWorkspace(input = {}) {
     const buf = newEventBuffer();
     const result = await withSchedulerTransaction(async () => {
         const now = parseDate(input.now_iso) ?? new Date();
         const staleMs = resolveStaleMs(input.heartbeat_stale_seconds);
         const queue = readJobQueue();
         const table = readJobLockTable();
+        const priorJobs = JSON.stringify(queue.jobs);
         const reapedJobIds = reapStaleRunningJobs(queue, table, now, staleMs, buf);
-        if (reapedJobIds.length > 0) {
+        // Retained live/unknown claims also carry a persisted diagnostic.
+        if (priorJobs !== JSON.stringify(queue.jobs))
             await persistSchedulerState({
                 queue,
                 locks: table,
                 lease: readSchedulerLease(),
             });
-        }
         return {
             ok: true,
             queue_path: getJobQueuePath(),

package/dist/job-worker.d.ts

@@ -35,6 +35,8 @@ export declare function listJobHandlerKinds(): string[];
 export declare function hasJobHandler(kind: string): boolean;
 export interface RunJobWorkerInput {
     owner?: string;
+    /** Execute only these jobs; unrelated jobs are not admitted by this tick. */
+    job_ids?: string[];
     /** Deterministic clock override; threaded through every scheduler call. */
     now_iso?: string;
     lease_ttl_seconds?: number;
@@ -60,7 +62,7 @@ export interface WorkerJobOutcome {
 export interface WorkerSkippedJob {
     job_id: string;
     kind: string;
-    reason: "no_handler" | "max_jobs";
+    reason: "no_handler" | "max_jobs" | "execution_claimed" | "execution_uncertain";
 }
 export interface RunJobWorkerResult {
     owner: string;

package/dist/job-worker.js

@@ -17,7 +17,7 @@
  * across a handler invocation, so a slow or hung handler cannot wedge the
  * scheduler for other owners.
  */
-import { completeJob, dispatchJobs, heartbeatJob, readJobQueue, readSchedulerLease, } from "./job-scheduler.js";
+import { completeJob, claimJobExecution, dispatchJobs, heartbeatJob, readJobQueue, readSchedulerLease, } from "./job-scheduler.js";
 import { resolveWorkspaceRoot } from "./helpers.js";
 const handlers = new Map();
 export function registerJobHandler(kind, handler) {
@@ -66,6 +66,7 @@ export async function runJobWorkerOnce(input = {}) {
         now_iso: input.now_iso,
         lease_ttl_seconds: input.lease_ttl_seconds,
         heartbeat_stale_seconds: input.heartbeat_stale_seconds,
+        job_ids: input.job_ids,
     });
     const executed = [];
     const skipped = [];
@@ -83,7 +84,8 @@ export async function runJobWorkerOnce(input = {}) {
         };
     }
     const queue = readJobQueue();
-    const runningJobs = queue.jobs.filter((job) => job.status === "running");
+    const selected = input.job_ids === undefined ? undefined : new Set(input.job_ids);
+    const runningJobs = queue.jobs.filter((job) => job.status === "running" && (!selected || selected.has(job.job_id)));
     const maxJobs = typeof input.max_jobs === "number" && input.max_jobs > 0
         ? Math.floor(input.max_jobs)
         : Number.POSITIVE_INFINITY;
@@ -98,6 +100,11 @@ export async function runJobWorkerOnce(input = {}) {
             skipped.push({ job_id: job.job_id, kind: job.kind, reason: "max_jobs" });
             continue;
         }
+        const claim = await claimJobExecution({ job_id: job.job_id, owner, now_iso: input.now_iso });
+        if (!claim.ok) {
+            skipped.push({ job_id: job.job_id, kind: job.kind, reason: claim.reason_code === "execution_claimed" ? "execution_claimed" : "execution_uncertain" });
+            continue;
+        }
         executedCount += 1;
         // Prove liveness immediately, then keep beating while the handler runs.
         await heartbeatJob({ job_id: job.job_id, owner, now_iso: input.now_iso });
@@ -113,7 +120,7 @@ export async function runJobWorkerOnce(input = {}) {
         }
         let handlerResult;
         try {
-            handlerResult = await handler({ job, owner });
+            handlerResult = await handler({ job: claim.job ?? job, owner });
         }
         catch (err) {
             handlerResult = { success: false, error: errorMessage(err) };

package/dist/kanban.d.ts

@@ -1,4 +1,4 @@
-export type KanbanColumn = "backlog" | "blocked" | "in_progress" | "gated" | "done";
+export type KanbanColumn = "backlog" | "blocked" | "in_progress" | "gated" | "done" | "cancelled";
 export interface AceKanbanCard {
     id: string;
     title: string;
@@ -10,8 +10,10 @@ export interface AceKanbanBoard {
     in_progress: AceKanbanCard[];
     gated: AceKanbanCard[];
     done: AceKanbanCard[];
+    cancelled: AceKanbanCard[];
 }
 export interface AceKanbanSnapshot {
+    refresh_scheduled?: boolean;
     version: number;
     generated_at: string;
     trigger: string;
@@ -21,6 +23,7 @@ export interface AceKanbanSnapshot {
     json_path: string;
 }
 export declare function renderKanbanHtml(snapshot: AceKanbanSnapshot): string;
+export declare function formatKanbanRefresh(snapshot: AceKanbanSnapshot): string;
 export declare function refreshKanbanArtifacts(trigger: string): AceKanbanSnapshot;
 export declare function getOrRefreshKanbanSnapshot(trigger: string): AceKanbanSnapshot;
 export declare function shouldAutoRefreshKanbanForPath(path: string): boolean;

package/dist/kanban.js

@@ -1,13 +1,13 @@
-import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, safeRead, safeWrite, wsPath } from "./helpers.js";
+import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, safeRead, safeWrite, wsPath, resolveWorkspaceRoot, withWorkspaceRoot } from "./helpers.js";
 import { isReadError, slugify } from "./shared.js";
 import { readHandoffRegistry } from "./handoff-registry.js";
 import { readTodoState } from "./todo-state.js";
 /** Debounce threshold in milliseconds. Skip re-render if within this window. */
 const KANBAN_DEBOUNCE_MS = 2000;
-let lastKanbanRenderTimestamp = 0;
+const renderState = new Map();
 const KANBAN_JSON_REL = "agent-state/kanban.json";
 const KANBAN_HTML_REL = "agent-state/kanban.html";
-const COLUMNS = ["backlog", "blocked", "in_progress", "gated", "done"];
+const COLUMNS = ["backlog", "blocked", "in_progress", "gated", "done", "cancelled"];
 function nowIso() {
     return new Date().toISOString();
 }
@@ -18,6 +18,7 @@ function emptyBoard() {
         in_progress: [],
         gated: [],
         done: [],
+        cancelled: [],
     };
 }
 function escapeHtml(input) {
@@ -236,7 +237,7 @@ export function renderKanbanHtml(snapshot) {
         "@keyframes spin{to{transform:rotate(360deg)}}",
         "h1{margin:0;font-family:'Space Grotesk','Avenir Next',sans-serif;font-size:24px}",
         ".stamp{margin:0;font-size:12px;opacity:.75}",
-        ".grid{display:grid;grid-template-columns:repeat(5,minmax(220px,1fr));gap:12px}",
+        ".grid{display:grid;grid-template-columns:repeat(6,minmax(220px,1fr));gap:12px}",
         ".column{background:rgba(255,255,255,.62);border:1px solid var(--line);border-radius:12px;min-height:220px}",
         ".column>header{display:flex;justify-content:space-between;align-items:center;padding:10px 12px;border-bottom:1px solid var(--line)}",
         ".column h2{margin:0;font-size:14px;text-transform:capitalize}",
@@ -265,16 +266,38 @@ export function renderKanbanHtml(snapshot) {
         "</html>",
     ].join("");
 }
+export function formatKanbanRefresh(snapshot) {
+    return snapshot.refresh_scheduled
+        ? `Kanban refresh scheduled: ${snapshot.html_path} (last generated ${snapshot.generated_at})`
+        : `Kanban updated: ${snapshot.html_path}`;
+}
 export function refreshKanbanArtifacts(trigger) {
-    // Debounce: skip expensive re-render if within threshold
-    const now = Date.now();
-    if (now - lastKanbanRenderTimestamp < KANBAN_DEBOUNCE_MS) {
-        // Return cached snapshot if available
-        const cached = getOrRefreshKanbanSnapshot(trigger);
-        if (cached.generated_at)
-            return cached;
+    const root = resolveWorkspaceRoot();
+    const state = renderState.get(root) ?? { last: 0 };
+    const delay = KANBAN_DEBOUNCE_MS - (Date.now() - state.last);
+    const cached = readKanbanSnapshot();
+    if (delay > 0 && cached) {
+        if (state.timer)
+            clearTimeout(state.timer);
+        state.timer = setTimeout(() => withWorkspaceRoot(root, () => {
+            state.timer = undefined;
+            try {
+                renderKanbanNow(trigger);
+            }
+            catch (error) {
+                state.last = 0;
+                console.error(`Kanban refresh failed for ${root}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }), delay);
+        state.timer.unref();
+        renderState.set(root, state);
+        return { ...cached, refresh_scheduled: true };
     }
-    lastKanbanRenderTimestamp = now;
+    if (state.timer)
+        clearTimeout(state.timer);
+    return renderKanbanNow(trigger);
+}
+function renderKanbanNow(trigger) {
     const board = emptyBoard();
     addTodoCards(board);
     addStatusCard(board);
@@ -292,15 +315,17 @@ export function refreshKanbanArtifacts(trigger) {
             in_progress: board.in_progress.length,
             gated: board.gated.length,
             done: board.done.length,
+            cancelled: board.cancelled.length,
         },
         html_path: wsPath(KANBAN_HTML_REL),
         json_path: wsPath(KANBAN_JSON_REL),
     };
     safeWrite(KANBAN_HTML_REL, renderKanbanHtml(snapshot));
     safeWrite(KANBAN_JSON_REL, JSON.stringify(snapshot, null, 2));
+    renderState.set(resolveWorkspaceRoot(), { last: Date.now() });
     return snapshot;
 }
-export function getOrRefreshKanbanSnapshot(trigger) {
+function readKanbanSnapshot() {
     const raw = safeRead(KANBAN_JSON_REL);
     if (!isReadError(raw)) {
         const parsed = tryParseJson(raw);
@@ -316,14 +341,17 @@ export function getOrRefreshKanbanSnapshot(trigger) {
                 version,
                 generated_at: generated,
                 trigger: savedTrigger,
-                board,
-                counts,
+                board: { ...emptyBoard(), ...board },
+                counts: { ...Object.fromEntries(COLUMNS.map((key) => [key, 0])), ...counts },
                 html_path: htmlPath,
                 json_path: jsonPath,
             };
         }
     }
-    return refreshKanbanArtifacts(trigger);
+    return undefined;
+}
+export function getOrRefreshKanbanSnapshot(trigger) {
+    return readKanbanSnapshot() ?? refreshKanbanArtifacts(trigger);
 }
 export function shouldAutoRefreshKanbanForPath(path) {
     const normalized = path.replace(/\\/g, "/").replace(/^\.?\//, "");

package/dist/learned-artifacts.d.ts

@@ -0,0 +1,64 @@
+import { type LearnedArtifact } from './learning-records.js';
+export { decodeLearned, type LearnedArtifact } from './learning-records.js';
+import { type PlaybookScope, type PlaybookSection } from './store/repositories/playbook-repository.js';
+import { type IAcePackedStore } from './store/types.js';
+import type { GoalEngineDeps } from './goal-engine.js';
+export interface LearnedPayload {
+    lessons?: Array<{
+        op: 'add' | 'edit' | 'retire';
+        bullet_id?: string;
+        section: PlaybookSection;
+        content: string;
+        scope: PlaybookScope;
+        episodes: string[];
+        retired_episodes?: string[];
+    }>;
+    skill?: {
+        op: 'add' | 'edit';
+        slug: string;
+        skill_md: string;
+        references?: Record<string, string>;
+        episodes: string[];
+        retired_episodes?: string[];
+    };
+    instruction?: {
+        role: string;
+        text: string;
+        episodes: string[];
+    };
+}
+export interface LearningAcceptance {
+    ok: boolean;
+    ids: string[];
+    errors: string[];
+    reason_code?: string;
+    options?: Array<{
+        tool: string;
+        args: Record<string, unknown>;
+        why: string;
+    }>;
+}
+export declare function listLearnedArtifacts(root: string): LearnedArtifact[];
+export declare function withLearnedStore<T>(root: string, apply: (store: IAcePackedStore) => Promise<T>): Promise<T>;
+export declare function saveLearnedArtifact(root: string, item: LearnedArtifact): Promise<void>;
+export declare function updateLearnedArtifact(root: string, key: string, update: (item: LearnedArtifact) => LearnedArtifact | undefined): Promise<void>;
+export declare function prepareLearned(root: string, payload: LearnedPayload, context: {
+    goal_id: string;
+    step_id: string;
+    attempt: number;
+}, deps?: GoalEngineDeps): Promise<{
+    result: LearningAcceptance;
+    publish: () => Promise<void>;
+}>;
+export declare function acceptLearned(root: string, payload: LearnedPayload, context: {
+    goal_id: string;
+    step_id: string;
+    attempt: number;
+}, deps?: GoalEngineDeps): Promise<LearningAcceptance>;
+export declare function regenerateLearnedProjection(root: string): Promise<void>;
+export declare function ensureLearningStep(root: string, force?: {
+    scope: PlaybookScope;
+    reason: string;
+}): Promise<void>;
+export declare function reopenLearningCorrection(root: string, errors: string[]): Promise<void>;
+//# sourceMappingURL=learned-artifacts.d.ts.map