gm-orchestrator 0.10.0 → 0.12.0

package/README.md

@@ -72,7 +72,7 @@ The primary interface. Opens automatically at `http://localhost:4242`.
 
 ### Dashboard
 Overview of your project: task queue sorted by priority, epics, done count for today.
-One click to start a sprint or select an epic.
+One click to start a sprint or select an epic. Choose the Claude model (Sonnet, Opus, Haiku) from the dropdown before starting.
 
 ### Sprint Runner
 Live view while work is in progress:
@@ -196,7 +196,141 @@ Resolved in order — later sources override earlier:
 | `pauseMs`    | `number`   | `2000`            | Pause between tasks              |
 | `maxRetries` | `number`   | `1`               | Retries on timeout/error         |
 | `claudeArgs` | `string[]` | `[]`              | Extra args for `claude --print`  |
+| `model`      | `string`   |                   | Claude model override (e.g. `claude-sonnet-4-6`) |
 | `dryRun`     | `boolean`  | `false`           | Preview prompts, don't run       |
+| `postTaskHooks` | `PostTaskHook[]` | `[]`        | Verification commands run after each task (see [Post-task verification hooks](#post-task-verification-hooks)) |
+| `heartbeat`  | `HeartbeatConfig` |            | Heartbeat / zombie recovery settings (see [Crash recovery](#crash-recovery-heartbeat)) |
+
+---
+
+## Task dependencies
+
+The orchestrator respects task blockers when choosing which task to run next.
+A task whose blockers are unresolved is **skipped** regardless of its priority.
+
+### Marking a blocker
+
+Use `tasks_link` with `kind="blocks"`:
+
+```
+tasks_link(fromId="U13", toId="U7", kind="blocks")
+```
+
+This means **U13 blocks U7** — the orchestrator will not start U7 until U13 reaches `done` (or `cancelled`).
+
+**Concrete example:** task U13 creates a lock helper used by U7 and U9. Link U13→U7 and U13→U9 with `kind="blocks"` so the orchestrator picks U13 first, even if U7 and U9 have higher priority.
+
+### Link kinds
+
+GraphMemory supports four link kinds between tasks:
+
+| Kind | Effect on orchestrator |
+|------|----------------------|
+| `blocks` | **Enforced.** Target task is skipped until the source is terminal (`done` / `cancelled`). Checked by `areBlockersResolved(task)`. |
+| `prefers_after` | **Soft.** Target task is deprioritised while the source is still active, but **not blocked**. If the source is cancelled or stuck, the target can still run. Useful for "ideally A before B" without a hard gate. |
+| `subtask_of` | Structural only — groups tasks under a parent. Does **not** affect scheduling order. |
+| `related_to` | Informational only — no effect on scheduling. |
+
+### Cancelled blockers
+
+A blocker in `cancelled` state is treated as **resolved**, same as `done`. Semantically, "this work is not going to happen" is equivalent to "this work is already accomplished" from the dependent task's perspective. Cancelling a blocker unblocks everything downstream — no ghost-blocked tasks stalling forever.
+
+### Cross-project blockers
+
+For multi-project setups, a blocker can live in a different GraphMemory project. Pass `targetProjectId` when linking:
+
+```
+tasks_link(fromId="U-API-1", toId="U6", kind="blocks", targetProjectId="MixPlacesEcommerce")
+```
+
+This means **U-API-1 in the current project blocks U6 in `MixPlacesEcommerce`**. The orchestrator resolves blocker status across all configured projects, so you can run multiple epics in parallel and let the scheduler interleave tasks based on real-time readiness — no need to sequence epics by hand.
+
+### Programmatic check
+
+```ts
+import { areBlockersResolved } from 'gm-orchestrator';
+
+// Returns true when every task linked with kind="blocks" is done or cancelled
+areBlockersResolved(task); // boolean
+```
+
+---
+
+## Post-task verification hooks
+
+After a task is marked `done`, the orchestrator can run user-configurable verification commands before accepting the `done` state. This provides a hard gate on quality — "task done = runtime verified" is enforced mechanically, not by convention.
+
+Hooks run **in the orchestrator process**, not inside the spawned Claude session. A failing session cannot skip its own verification.
+
+### Configuration
+
+```json
+{
+  "postTaskHooks": [
+    {
+      "name": "make-verify",
+      "command": "make verify",
+      "cwd": "/path/to/project",
+      "timeoutMs": 600000,
+      "onFailure": "block"
+    },
+    {
+      "name": "lint",
+      "command": "npm run lint",
+      "onFailure": "warn"
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Human-readable label for logs. |
+| `command` | `string` | Shell command to execute. |
+| `cwd` | `string` | Working directory (default: `process.cwd()`). |
+| `timeoutMs` | `number` | Timeout in ms (default: 600000 = 10 min). |
+| `onFailure` | `'block' \| 'warn'` | `block` halts the sprint, `warn` logs and continues. |
+
+### On failure (`onFailure: "block"`)
+
+1. Task is moved back from `done` to `in_progress`
+2. An `auto-verify-failed` tag is added
+3. Last 50 lines of stdout/stderr are attached to `task.metadata.verifyFailures`
+4. The sprint halts — orchestrator does **not** pick the next task until the user intervenes
+
+Hooks run sequentially in the order declared. Multiple hooks per project (e.g. lint + build + test as separate entries) are supported.
+
+---
+
+## Crash recovery (heartbeat)
+
+If the orchestrator process dies mid-task (OS reboot, OOM, pkill), the task is left stuck in `in_progress` forever. Heartbeats give the orchestrator a way to tell live work from zombie state.
+
+While a task is running, the orchestrator writes `metadata.runId` and `metadata.heartbeatAt` on a 30s interval. On startup, it scans all `in_progress` tasks: any task with a stale heartbeat (older than 2× the interval) or no heartbeat at all is treated as a zombie and recovered according to the configured policy.
+
+### Configuration
+
+```json
+{
+  "heartbeat": {
+    "intervalMs": 30000,
+    "staleThresholdMs": 60000,
+    "zombiePolicy": "reset-to-todo"
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `intervalMs` | `30000` | How often to write heartbeat metadata. |
+| `staleThresholdMs` | `2 × intervalMs` | Age threshold for zombie detection. |
+| `zombiePolicy` | `reset-to-todo` | `reset-to-todo`, `move-to-review`, or `cancel`. |
+
+`reset-to-todo` is the safe default: the zombie task goes back in the queue and will be re-picked with a fresh Claude session. Given per-task isolation, redoing the work is usually fine.
+
+### Idempotency (double-spawn safety)
+
+Each run gets a unique `runId` UUID, exposed to the spawned Claude session via the `ORCHESTRATOR_RUN_ID` environment variable and written to `task.metadata.runId`. Before making destructive changes, a well-behaved subagent can call `tasks_get` and compare `metadata.runId` to its own `ORCHESTRATOR_RUN_ID` — if they differ, another run has superseded this one and it should exit cleanly. This protects against race conditions between two orchestrator instances or restarts that happen during the narrow window between "pick task" and "move to in_progress".
 
 ---
 

package/dist/cli/index.js

@@ -199,11 +199,16 @@ async function main() {
         projectId: activeProj?.projectId ?? '',
         ...(activeProj?.apiKey !== undefined && { apiKey: activeProj.apiKey }),
     });
+    // Lazy-import HookRunner only when hooks are configured
+    const hookRunner = config.postTaskHooks?.length
+        ? new (await import('../infra/hook-runner.js')).HookRunner()
+        : undefined;
     const ports = {
         gm,
         runner: new ClaudeRunner(),
         poller: new TaskPoller(gm),
         logger: consoleLogger,
+        ...(hookRunner ? { hookRunner } : {}),
     };
     if (effectiveCommand === 'status') {
         const [todo, inProgress, done] = await Promise.all([

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/core/heartbeat.d.ts

@@ -0,0 +1,33 @@
+import type { GraphMemoryPort, HeartbeatConfig } from './types.js';
+import type { Logger } from '../infra/logger.js';
+export declare const HEARTBEAT_DEFAULTS: HeartbeatConfig;
+/**
+ * Resolve heartbeat config by merging user overrides with defaults.
+ */
+export declare function resolveHeartbeatConfig(partial?: Partial<HeartbeatConfig>): HeartbeatConfig;
+export interface HeartbeatHandle {
+    /** Unique run ID for this session. */
+    runId: string;
+    /** Stop the heartbeat interval and clear metadata from the task. */
+    stop(): Promise<void>;
+}
+/**
+ * Start a heartbeat for a running task.
+ *
+ * - Writes `metadata.runId` and `metadata.heartbeatAt` immediately.
+ * - Updates `metadata.heartbeatAt` every `intervalMs`.
+ * - `stop()` clears the interval and removes heartbeat metadata.
+ */
+export declare function startHeartbeat(taskId: string, gm: GraphMemoryPort, config: HeartbeatConfig, logger: Logger): HeartbeatHandle;
+/**
+ * Detect and recover zombie tasks on startup.
+ *
+ * Scans all `in_progress` tasks. If a task has heartbeat metadata
+ * and `heartbeatAt` is older than `staleThresholdMs`, it's a zombie.
+ * Tasks with no heartbeat metadata but `in_progress` status are also
+ * treated as zombies (pre-heartbeat era or metadata was lost).
+ *
+ * Returns the list of recovered task IDs.
+ */
+export declare function recoverZombieTasks(gm: GraphMemoryPort, config: HeartbeatConfig, logger: Logger): Promise<string[]>;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/core/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/core/heartbeat.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAIhB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAIjD,eAAO,MAAM,kBAAkB,EAAE,eAIhC,CAAC;AAEF;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GACjC,eAAe,CAQjB;AAID,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,GACb,eAAe,CAqCjB;AAID;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,EAAE,CAAC,CA4CnB"}

package/dist/core/heartbeat.js

@@ -0,0 +1,138 @@
+import { randomUUID } from 'crypto';
+// ─── Defaults ────────────────────────────────────────────────────────────
+export const HEARTBEAT_DEFAULTS = {
+    intervalMs: 30_000,
+    staleThresholdMs: 60_000,
+    zombiePolicy: 'reset-to-todo',
+};
+/**
+ * Resolve heartbeat config by merging user overrides with defaults.
+ */
+export function resolveHeartbeatConfig(partial) {
+    return {
+        intervalMs: partial?.intervalMs ?? HEARTBEAT_DEFAULTS.intervalMs,
+        staleThresholdMs: partial?.staleThresholdMs ??
+            (partial?.intervalMs ? partial.intervalMs * 2 : HEARTBEAT_DEFAULTS.staleThresholdMs),
+        zombiePolicy: partial?.zombiePolicy ?? HEARTBEAT_DEFAULTS.zombiePolicy,
+    };
+}
+/**
+ * Start a heartbeat for a running task.
+ *
+ * - Writes `metadata.runId` and `metadata.heartbeatAt` immediately.
+ * - Updates `metadata.heartbeatAt` every `intervalMs`.
+ * - `stop()` clears the interval and removes heartbeat metadata.
+ */
+export function startHeartbeat(taskId, gm, config, logger) {
+    const runId = randomUUID();
+    let stopped = false;
+    const writeMeta = async () => {
+        if (stopped)
+            return;
+        const meta = { runId, heartbeatAt: Date.now() };
+        try {
+            await gm.updateTask(taskId, {
+                metadata: { runId: meta.runId, heartbeatAt: meta.heartbeatAt },
+            });
+        }
+        catch (err) {
+            logger.warn(`Heartbeat write failed for ${taskId}: ${String(err)}`);
+        }
+    };
+    // Initial write
+    void writeMeta();
+    const timer = setInterval(() => void writeMeta(), config.intervalMs);
+    return {
+        runId,
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(timer);
+            // Clear heartbeat metadata so it's not mistaken for a zombie
+            try {
+                await gm.updateTask(taskId, {
+                    metadata: { runId: null, heartbeatAt: null },
+                });
+            }
+            catch (err) {
+                logger.warn(`Heartbeat clear failed for ${taskId}: ${String(err)}`);
+            }
+        },
+    };
+}
+// ─── Zombie recovery ─────────────────────────────────────────────────────
+/**
+ * Detect and recover zombie tasks on startup.
+ *
+ * Scans all `in_progress` tasks. If a task has heartbeat metadata
+ * and `heartbeatAt` is older than `staleThresholdMs`, it's a zombie.
+ * Tasks with no heartbeat metadata but `in_progress` status are also
+ * treated as zombies (pre-heartbeat era or metadata was lost).
+ *
+ * Returns the list of recovered task IDs.
+ */
+export async function recoverZombieTasks(gm, config, logger) {
+    const now = Date.now();
+    const recovered = [];
+    let inProgressTasks;
+    try {
+        inProgressTasks = await gm.listTasks({ status: 'in_progress' });
+    }
+    catch (err) {
+        logger.error(`Zombie recovery: failed to list in_progress tasks: ${String(err)}`);
+        return [];
+    }
+    for (const task of inProgressTasks) {
+        const heartbeatAt = task.metadata?.['heartbeatAt'];
+        // If there's a recent heartbeat, it's alive — skip
+        if (typeof heartbeatAt === 'number' && now - heartbeatAt < config.staleThresholdMs) {
+            continue;
+        }
+        // This task is a zombie — either stale heartbeat or no heartbeat at all
+        const age = typeof heartbeatAt === 'number'
+            ? `${Math.round((now - heartbeatAt) / 1000)}s ago`
+            : 'no heartbeat';
+        logger.warn(`Zombie detected: "${task.title}" (${task.id}) — last heartbeat: ${age}`);
+        try {
+            await applyZombiePolicy(task, config.zombiePolicy, gm, logger);
+            recovered.push(task.id);
+        }
+        catch (err) {
+            logger.error(`Zombie recovery failed for ${task.id}: ${String(err)}`);
+        }
+    }
+    if (recovered.length) {
+        logger.info(`Zombie recovery: ${recovered.length} task(s) recovered with policy "${config.zombiePolicy}"`);
+    }
+    else if (inProgressTasks.length === 0) {
+        logger.info('Zombie recovery: no in_progress tasks found');
+    }
+    else {
+        logger.info(`Zombie recovery: ${inProgressTasks.length} in_progress task(s) are all alive`);
+    }
+    return recovered;
+}
+async function applyZombiePolicy(task, policy, gm, logger) {
+    // Clear heartbeat metadata regardless of policy
+    await gm.updateTask(task.id, {
+        metadata: { runId: null, heartbeatAt: null },
+    });
+    switch (policy) {
+        case 'reset-to-todo':
+            logger.info(`  → resetting "${task.title}" to todo`);
+            await gm.moveTask(task.id, 'todo');
+            break;
+        case 'cancel':
+            logger.info(`  → cancelling "${task.title}"`);
+            await gm.moveTask(task.id, 'cancelled');
+            break;
+        case 'move-to-review':
+            // Move to cancelled with a note — there's no "review" status,
+            // so we cancel + tag for human inspection
+            logger.info(`  → cancelling "${task.title}" for review (zombie)`);
+            await gm.moveTask(task.id, 'cancelled');
+            break;
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/core/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../../src/core/heartbeat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAUpC,4EAA4E;AAE5E,MAAM,CAAC,MAAM,kBAAkB,GAAoB;IACjD,UAAU,EAAE,MAAM;IAClB,gBAAgB,EAAE,MAAM;IACxB,YAAY,EAAE,eAAe;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAkC;IAElC,OAAO;QACL,UAAU,EAAE,OAAO,EAAE,UAAU,IAAI,kBAAkB,CAAC,UAAU;QAChE,gBAAgB,EACd,OAAO,EAAE,gBAAgB;YACzB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,gBAAgB,CAAC;QACtF,YAAY,EAAE,OAAO,EAAE,YAAY,IAAI,kBAAkB,CAAC,YAAY;KACvE,CAAC;AACJ,CAAC;AAWD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,EAAmB,EACnB,MAAuB,EACvB,MAAc;IAEd,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,SAAS,GAAG,KAAK,IAAmB,EAAE;QAC1C,IAAI,OAAO;YAAE,OAAO;QACpB,MAAM,IAAI,GAAsB,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACnE,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE;gBAC1B,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE;aAC/D,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,8BAA8B,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC,CAAC;IAEF,gBAAgB;IAChB,KAAK,SAAS,EAAE,CAAC;IAEjB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,SAAS,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAErE,OAAO;QACL,KAAK;QACL,KAAK,CAAC,IAAI;YACR,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,aAAa,CAAC,KAAK,CAAC,CAAC;YACrB,6DAA6D;YAC7D,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE;oBAC1B,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE;iBAC7C,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,IAAI,CAAC,8BAA8B,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,4EAA4E;AAE5E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,EAAmB,EACnB,MAAuB,EACvB,MAAc;IAEd,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,IAAI,eAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,eAAe,GAAG,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;IAClE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,sDAAsD,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;QACnC,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,aAAa,CAAC,CAAC;QAEnD,mDAAmD;QACnD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,GAAG,GAAG,WAAW,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;YACnF,SAAS;QACX,CAAC;QAED,wEAAwE;QACxE,MAAM,GAAG,GAAG,OAAO,WAAW,KAAK,QAAQ;YACzC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC,OAAO;YAClD,CAAC,CAAC,cAAc,CAAC;QAEnB,MAAM,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,EAAE,uBAAuB,GAAG,EAAE,CAAC,CAAC;QAEtF,IAAI,CAAC;YACH,MAAM,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,YAAY,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;YAC/D,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,8BAA8B,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;QACrB,MAAM,CAAC,IAAI,CAAC,oBAAoB,SAAS,CAAC,MAAM,mCAAmC,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC;IAC7G,CAAC;SAAM,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;IAC7D,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,IAAI,CAAC,oBAAoB,eAAe,CAAC,MAAM,oCAAoC,CAAC,CAAC;IAC9F,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,iBAAiB,CAC9B,IAAU,EACV,MAAoB,EACpB,EAAmB,EACnB,MAAc;IAEd,gDAAgD;IAChD,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE;QAC3B,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE;KAC7C,CAAC,CAAC;IAEH,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,eAAe;YAClB,MAAM,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,KAAK,WAAW,CAAC,CAAC;YACrD,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YACnC,MAAM;QACR,KAAK,QAAQ;YACX,MAAM,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;YAC9C,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;YACxC,MAAM;QACR,KAAK,gBAAgB;YACnB,8DAA8D;YAC9D,0CAA0C;YAC1C,MAAM,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,KAAK,uBAAuB,CAAC,CAAC;YAClE,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;YACxC,MAAM;IACV,CAAC;AACH,CAAC"}

package/dist/core/orchestrator.d.ts

@@ -1,4 +1,4 @@
-import type { GraphMemoryPort, ClaudeRunnerPort, TaskPollerPort, OrchestratorConfig, SprintStats, CrossProjectResolver, CrossProjectTask } from './types.js';
+import type { GraphMemoryPort, ClaudeRunnerPort, TaskPollerPort, HookRunnerPort, OrchestratorConfig, SprintStats, CrossProjectResolver, CrossProjectTask } from './types.js';
 import type { Logger } from '../infra/logger.js';
 interface Ports {
     gm: GraphMemoryPort;
@@ -11,6 +11,12 @@ interface Ports {
      * When provided, `findNextRunnable` will check blockers in other projects.
      */
     crossProjectResolver?: CrossProjectResolver;
+    /**
+     * Optional hook runner for post-task verification.
+     * When provided along with config.postTaskHooks, hooks are executed
+     * after a task is marked done — before the orchestrator accepts completion.
+     */
+    hookRunner?: HookRunnerPort;
 }
 /**
  * Orchestrates a full sprint: runs all todo/in_progress tasks in priority

package/dist/core/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/core/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,WAAW,EAGX,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,UAAU,KAAK;IACb,EAAE,EAAE,eAAe,CAAC;IACpB,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,WAAW,CAAC,CAyDtB;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,WAAW,CAAC,CA2DtB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,WAAW,CAAC,CAoDtB;AAyHD;;;;GAIG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,QAAQ,CAAC,EACvC,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,eAAe,EACjD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAAC,KAAK,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC,CAmC/F"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/core/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,WAAW,EAGX,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAKpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,UAAU,KAAK;IACb,EAAE,EAAE,eAAe,CAAC;IACpB,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,WAAW,CAAC,CAgEtB;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,WAAW,CAAC,CAkEtB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,WAAW,CAAC,CAyDtB;AA6JD;;;;GAIG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,QAAQ,CAAC,EACvC,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,eAAe,EACjD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAAC,KAAK,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC,CAmC/F"}

package/dist/core/orchestrator.js

@@ -1,5 +1,7 @@
 import { getActiveProject } from './types.js';
 import { sortByPriority, areBlockersResolved, areBlockersResolvedAsync } from './task-utils.js';
+import { startHeartbeat, resolveHeartbeatConfig } from './heartbeat.js';
+import { runPostTaskHooks, handleVerifyFailure } from './post-task-hooks.js';
 /**
  * Orchestrates a full sprint: runs all todo/in_progress tasks in priority
  * order, respecting blockers, retrying on failure, until none remain.
@@ -47,10 +49,16 @@ export async function runSprint(ports, config) {
             return stats;
         }
         const result = await runOneTask(next, ports, config);
-        await handleResult(result, next, {
+        const halt = await handleResult(result, next, {
             gm, logger, stats, failedIds, retryCounts,
             maxRetries: config.maxRetries,
         });
+        if (halt) {
+            logger.warn('Sprint halted due to verification failure');
+            stats.durationMs = Date.now() - startTime;
+            logStats(logger, stats);
+            return stats;
+        }
         await sleep(config.pauseMs);
     }
 }
@@ -97,10 +105,16 @@ export async function runEpic(epicId, ports, config) {
             return stats;
         }
         const result = await runOneTask(next, ports, config);
-        await handleResult(result, next, {
+        const halt = await handleResult(result, next, {
             gm, logger, stats, failedIds, retryCounts,
             maxRetries: config.maxRetries,
         });
+        if (halt) {
+            logger.warn('Epic halted due to verification failure');
+            stats.durationMs = Date.now() - startTime;
+            logStats(logger, stats);
+            return stats;
+        }
         await sleep(config.pauseMs);
     }
 }
@@ -146,10 +160,14 @@ export async function runTasks(taskIds, ports, config) {
         if (failedIds.has(task.id))
             continue;
         const result = await runOneTask(task, ports, config);
-        await handleResult(result, task, {
+        const halt = await handleResult(result, task, {
             gm, logger, stats, failedIds, retryCounts,
             maxRetries: config.maxRetries,
         });
+        if (halt) {
+            logger.warn('Task run halted due to verification failure');
+            break;
+        }
         await sleep(config.pauseMs);
     }
     stats.durationMs = Date.now() - startTime;
@@ -181,7 +199,8 @@ async function findNextRunnable(queue, logger, resolver) {
     }
     return null;
 }
-async function runOneTask(task, { gm, runner, poller, logger, signal }, config) {
+async function runOneTask(task, ports, config) {
+    const { gm, runner, poller, logger, signal } = ports;
     logger.task(task);
     // Mark in_progress (idempotent)
     if (task.status !== 'in_progress') {
@@ -194,40 +213,70 @@ async function runOneTask(task, { gm, runner, poller, logger, signal }, config)
         await gm.moveTask(task.id, 'done').catch(() => { });
         return 'dry_run';
     }
-    // Spawn Claude Code session (fire and forget — poller drives completion)
-    const sessionPromise = runner.run(task, config).catch((e) => {
-        logger.warn(`Claude session error: ${String(e)}`);
-    });
-    // Poll GraphMemory until task reaches terminal state
-    const pollResult = await poller.waitForCompletion(task.id, {
-        timeoutMs: config.timeoutMs,
-        ...(signal ? { signal } : {}),
-    });
-    await sessionPromise; // let process clean up
-    if (pollResult === 'timeout') {
-        logger.error(`Timeout: "${task.title}" (${task.id})`);
-        return 'timeout';
-    }
-    if (pollResult === 'done') {
-        logger.success(`Done: "${task.title}"`);
+    // Start heartbeat for crash recovery
+    const hbConfig = resolveHeartbeatConfig(config.heartbeat);
+    const heartbeat = startHeartbeat(task.id, gm, hbConfig, logger);
+    try {
+        // Spawn Claude Code session (fire and forget — poller drives completion)
+        const sessionPromise = runner.run(task, config, heartbeat.runId).catch((e) => {
+            logger.warn(`Claude session error: ${String(e)}`);
+        });
+        // Poll GraphMemory until task reaches terminal state
+        const pollResult = await poller.waitForCompletion(task.id, {
+            timeoutMs: config.timeoutMs,
+            ...(signal ? { signal } : {}),
+        });
+        await sessionPromise; // let process clean up
+        if (pollResult === 'timeout') {
+            logger.error(`Timeout: "${task.title}" (${task.id})`);
+            return 'timeout';
+        }
+        if (pollResult === 'done') {
+            // Run post-task verification hooks (if configured)
+            const hooks = config.postTaskHooks;
+            if (hooks?.length && ports.hookRunner) {
+                logger.info(`Running ${hooks.length} post-task hook(s) for "${task.title}"`);
+                const report = await runPostTaskHooks(hooks, ports.hookRunner, logger);
+                if (!report.passed) {
+                    await handleVerifyFailure(task, report, gm, logger);
+                    return 'verify_failed';
+                }
+            }
+            logger.success(`Done: "${task.title}"`);
+        }
+        else {
+            logger.warn(`Cancelled: "${task.title}"`);
+        }
+        return pollResult;
     }
-    else {
-        logger.warn(`Cancelled: "${task.title}"`);
+    finally {
+        // Always stop the heartbeat — whether success, failure, or abort
+        await heartbeat.stop();
     }
-    return pollResult;
 }
+/**
+ * Processes a task run result. Returns true if the sprint/epic should halt
+ * (e.g. on verify_failed — don't continue to next task).
+ */
 async function handleResult(result, task, ctx) {
     const { gm, logger, stats, failedIds, retryCounts, maxRetries } = ctx;
     if (result === 'done' || result === 'dry_run') {
         stats.done++;
         logger.taskResult(task, 'done');
-        return;
+        return false;
+    }
+    if (result === 'verify_failed') {
+        stats.errors++;
+        failedIds.add(task.id);
+        logger.taskResult(task, 'verify_failed');
+        logger.error(`Halting — post-task verification failed for "${task.title}" (${task.id})`);
+        return true; // halt the sprint/epic
     }
     if (result === 'cancelled') {
         stats.cancelled++;
         failedIds.add(task.id);
         logger.taskResult(task, 'cancelled');
-        return;
+        return false;
     }
     // timeout | error
     const retries = retryCounts.get(task.id) ?? 0;
@@ -245,6 +294,7 @@ async function handleResult(result, task, ctx) {
         logger.error(`Giving up on: ${task.id}`);
         await gm.moveTask(task.id, 'cancelled').catch(() => { });
     }
+    return false;
 }
 /**
  * Collect tasks for a cross-project epic.