@skyf0xx/hedgehog 4.0.15 → 4.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Turn AI from a code generator into a reliable software engineer ⭐
 
-[![Total downloads](https://img.shields.io/npm/dt/%40skyf0xx%2Fhedgehog?style=for-the-badge)](https://www.npmjs.com/package/@skyf0xx/hedgehog)
+[![Total downloads](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/badges/npm-downloads.svg)](https://www.npmjs.com/package/@skyf0xx/hedgehog)
 
 AI can write code in seconds.
 

package/bin/cli.mjs

@@ -653,6 +653,20 @@ async function resolveCorePath() {
   return null;
 }
 
+// The active core's `id` (e.g. `full-stack-app`), or null when no core has
+// landed yet or it fails to parse — packet rendering degrades gracefully
+// either way (see next.mjs's layerShapeLines), so a caller only asking for
+// the id doesn't need its own try/catch.
+async function resolveCoreId() {
+  const corePath = await resolveCorePath();
+  if (!corePath) return null;
+  try {
+    return (await loadCore(corePath)).id;
+  } catch {
+    return null;
+  }
+}
+
 // `hedgehog plan --recompile` — the reconciliation path for a core.yaml
 // edited after `plan` already compiled it.
 //
@@ -933,10 +947,10 @@ async function nextCommand() {
 
   const db = openDb();
   let packet;
-  let stalled = [];
+  let stalled;
   try {
     packet = nextTask(db);
-    if (!packet) stalled = stalledTasks(db);
+    stalled = stalledTasks(db);
   } finally {
     db.close();
   }
@@ -947,10 +961,7 @@ async function nextCommand() {
     // a failed verification.
     if (stalled.length > 0) {
       console.error(`${red(bold('No ready task, but the graph is blocked.'))}\n`);
-      for (const task of stalled) {
-        const reason = BLOCKED_REASON_LABELS[task.blocked_reason] ?? task.blocked_reason;
-        console.error(`  ${red('✗')} ${bold(task.id)}   ${task.layer}   ${dim(reason)}`);
-      }
+      printStalledTasks(stalled);
       // `verify` refuses anything that isn't `building` and leased to
       // the caller, so a blocked task has to go back through the queue
       // — retry, claim, then verify — rather than straight to verify.
@@ -964,7 +975,26 @@ async function nextCommand() {
     return;
   }
 
-  console.log(formatNext(packet));
+  // A blocked task elsewhere in the graph doesn't stop this ready task
+  // from being handed out — leases are scoped to disjoint work, so an
+  // unrelated block is no reason to halt everything else. But it's easy
+  // to miss otherwise: the queue keeps producing ready tasks right up
+  // until it doesn't, and a block can sit unnoticed the whole time. This
+  // warns without withholding the packet.
+  if (stalled.length > 0) {
+    console.error(`${yellow(bold(`${stalled.length} task(s) blocked elsewhere in the graph:`))}`);
+    printStalledTasks(stalled);
+    console.error('');
+  }
+
+  console.log(formatNext(packet, await resolveCoreId()));
+}
+
+function printStalledTasks(stalled) {
+  for (const task of stalled) {
+    const reason = BLOCKED_REASON_LABELS[task.blocked_reason] ?? task.blocked_reason;
+    console.error(`  ${red('✗')} ${bold(task.id)}   ${task.layer}   ${dim(reason)}`);
+  }
 }
 
 // Mirrors, read-only, the condition verifyTask's own Phase 0
@@ -1027,6 +1057,49 @@ async function missingBinariesForTask(db, taskId, owner) {
   return missing.length === 0 ? null : { layer: layer.id, missing };
 }
 
+// What an out-of-scope path most likely is, and what to do about it.
+// "Outside allowed scope" is true of every offending path and tells the
+// reader nothing about which of three quite different situations they're
+// in: a package shell the layer itself had to create (widen this one
+// task), shared config a source-level fix touched (commit it separately),
+// or a genuine stray. Each wants a different next move, and working out
+// which costs a beat every time.
+//
+// Evidence-only, like core.mjs's lint: an unrecognised path gets no
+// annotation rather than a guessed one.
+const SCOPE_HINTS = [
+  {
+    // A package root's own scaffolding — package.json, tsconfig*.json,
+    // vitest.config.mts, src/index.ts directly under packages/<pkg>/ or
+    // libs/<a>/<b>/. No {module}-bearing scope glob can cover these, so
+    // the first module through a layer that creates its package always
+    // lands here.
+    test: (p) =>
+      /^(packages\/[^/]+|libs\/[^/]+\/[^/]+)\/(package\.json|tsconfig[^/]*\.json|vitest\.config\.[cm]?ts|project\.json|eslint\.config\.[cm]?js|src\/index\.ts)$/.test(
+        p,
+      ),
+    hint: 'package shell — if this layer is the first to create this package, widen just this task with `hedgehog override add` (see hedgehog-loop, "First arrival in a package") and retry',
+  },
+  {
+    test: (p) =>
+      p === 'pnpm-workspace.yaml' ||
+      p === 'pnpm-lock.yaml' ||
+      p === 'tsconfig.json' ||
+      p === 'nx.json' ||
+      p === 'package.json' ||
+      p.startsWith('packages/config/'),
+    hint: 'shared workspace config — no layer owns it; commit it separately as its own `chore(workspace): …` before retrying',
+  },
+  {
+    test: (p) => p.startsWith('.hedgehog/'),
+    hint: 'build-graph state — intents, overrides and friction are committed by the command that writes them, not by a layer',
+  },
+];
+
+function scopeHintFor(path) {
+  return SCOPE_HINTS.find((h) => h.test(path))?.hint ?? null;
+}
+
 async function verifyCommand(args) {
   await ensureDb();
 
@@ -1077,7 +1150,11 @@ async function verifyCommand(args) {
   if (result.outcome === 'scope_violation') {
     console.error(`${red(bold('Scope violation.'))} Task ${bold(taskId)} is now ${bold('blocked')}.\n`);
     console.error('Touched paths outside allowed scope:');
-    for (const path of result.offending) console.error(`  ${red('✗')} ${path}`);
+    for (const path of result.offending) {
+      console.error(`  ${red('✗')} ${path}`);
+      const hint = scopeHintFor(path);
+      if (hint) console.error(`      ${dim(hint)}`);
+    }
     console.error();
     process.exitCode = 1;
     return;
@@ -1129,14 +1206,15 @@ async function verifyCommand(args) {
 // doesn't print the packet here, the STATUS/ALLOWED SCOPE/VERIFICATION an
 // agent is supposed to be dispatched with is no longer reachable from any
 // command. (`hedgehog show <task-id>` reprints it later.)
-function printPackets(tasks) {
+async function printPackets(tasks) {
+  const coreId = await resolveCoreId();
   const db = openDb();
   try {
     for (const task of tasks) {
       const packet = taskPacket(db, task.id);
       if (!packet) continue;
       console.log();
-      console.log(formatPacket(packet, taskStatusLine(packet.task)));
+      console.log(formatPacket(packet, taskStatusLine(packet.task), coreId));
     }
   } finally {
     db.close();
@@ -1185,13 +1263,30 @@ async function claimCommand(args) {
   }
 
   const db = openDb();
-  let claimed;
+  let claimed, blocked;
   try {
-    claimed = claimTasks(db, { owner, count });
+    ({ claimed, blocked } = claimTasks(db, { owner, count }));
   } finally {
     db.close();
   }
 
+  // Stop-the-line: claimTasks refuses the whole batch, in any module,
+  // while any task anywhere is blocked — see its own comment in
+  // claim.mjs. A targeted `hedgehog claim <task-id>` is unaffected, which
+  // is how the blocked task itself gets reclaimed after `hedgehog retry`.
+  if (blocked.length > 0) {
+    console.error(`${red(bold('Claim refused.'))} ${blocked.length} task(s) blocked:\n`);
+    for (const task of blocked) {
+      const reason = BLOCKED_REASON_LABELS[task.blocked_reason] ?? task.blocked_reason;
+      console.error(`  ${red('✗')} ${bold(task.id)}   ${task.layer}   ${dim(reason)}`);
+    }
+    console.error(
+      `\nFix the work, then ${bold('hedgehog retry <task-id>')} before claiming more.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   if (claimed.length === 0) {
     console.log(`${dim('No claimable task.')} Nothing is ready with no lease held.\n`);
     return;
@@ -1206,7 +1301,7 @@ async function claimCommand(args) {
     if (claimed.length > 1) console.log(`  ${bold(task.id)}`);
     console.log(`  ${dim('expires')}  ${task.lease_expires_at}`);
   }
-  printPackets(claimed);
+  await printPackets(claimed);
 }
 
 // The targeted half of `claim`: one named task, or a non-zero exit
@@ -1225,7 +1320,7 @@ async function claimOneCommand(taskId, owner) {
   if (result.claimed) {
     console.log(`${green(bold('Claimed.'))} Task ${bold(taskId)} leased to ${bold(owner)}.`);
     console.log(`  ${dim('expires')}  ${result.task.lease_expires_at}`);
-    printPackets([result.task]);
+    await printPackets([result.task]);
     return;
   }
 
@@ -1349,7 +1444,7 @@ async function showCommand(args) {
     return;
   }
 
-  console.log(formatPacket(packet, taskStatusLine(packet.task)));
+  console.log(formatPacket(packet, taskStatusLine(packet.task), await resolveCoreId()));
 }
 
 // `hedgehog release <task-id> --owner <owner>` — hands a claimed task
@@ -1506,7 +1601,27 @@ async function statusCommand() {
     }
   }
 
-  const overrides = core ? await loadOverrides() : new Map();
+  // Loaded whether or not a core resolved: drift is the only consumer
+  // that needs `core` composed against these, and graphStatus already
+  // gates that on `core` itself. The orphan check reads task ids out of
+  // the database, so it is answerable — and worth answering — on a
+  // project whose core.yaml is missing or unparseable. A missing
+  // overrides directory reads as an empty Map (loadOverrides), so this
+  // costs nothing on a project that has never written one.
+  //
+  // A malformed override file throws, and for the same reason an
+  // unparseable core.yaml doesn't take `status` down, neither may this:
+  // status is the command every session starts with, and the report of
+  // the broken file is more useful than an aborted overview.
+  let overrides = new Map();
+  try {
+    overrides = await loadOverrides();
+  } catch (err) {
+    console.error(
+      `${yellow('Override file unreadable:')} ${err.message}\n${dim('Scope overrides are ignored until it parses.')}\n`,
+    );
+  }
+
   const db = openDb();
   let result;
   try {
@@ -1678,7 +1793,13 @@ function openInBrowser(url) {
 // either fails silently or blocks on a text browser. Printing the URL is
 // the useful behaviour in that case — a person on the other end of a
 // port-forward can still open it.
+//
+// HEDGEHOG_FORCE_HEADLESS bypasses the platform check entirely — the
+// repro suite's only way to exercise the no-display branch on macOS/
+// Windows, where DISPLAY/WAYLAND_DISPLAY are never consulted for real
+// users. Not a documented user-facing flag.
 function hasDisplay() {
+  if (process.env.HEDGEHOG_FORCE_HEADLESS) return false;
   if (process.platform === 'darwin' || process.platform === 'win32') return true;
   return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "4.0.15",
+  "version": "4.2.0",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {
@@ -44,4 +44,4 @@
     "hedgehog"
   ],
   "license": "MIT"
-}
+}

package/src/agents/backend-eng.md

@@ -34,31 +34,54 @@ build exactly what its ALLOWED SCOPE names, one layer at a time, gated by
 Use `nx-run-tasks` (build/lint/test/typecheck), `nx-workspace` (inspecting
 project/target config), `nx-generate` (scaffolding a new library/app), and
 `link-workspace-packages` (wiring a new package into a consumer) as
-needed.
+needed. A layer's first-arrival package shell (`contract`, `repository`,
+`service`) is a generator call, not a hand-copy of a sibling package —
+`hedgehog-loop`'s "First arrival in a package" section names the exact
+command and tags for each.
 
 ## Core Responsibilities
 
 - **`schema`**: define the table in `packages/db` (Drizzle). One domain
   module = one table. Cross-module references are FK-by-ID columns
-  only — never a foreign schema import.
+  only — never a foreign schema import. Add one re-export line for the
+  module to `packages/db/src/schema/index.ts` (in scope for this
+  layer) so the table is importable outside `packages/db` — the
+  package's own `src/index.ts` re-exports that barrel and never
+  changes after bootstrap.
 - **`contract`**: derive the Zod schema from Drizzle (`drizzle-zod`) and
-  wire the ts-rest contract in `packages/contracts`.
+  wire the ts-rest contract in `packages/contracts`. A `date`-mode
+  `timestamp` column reflected through `createSelectSchema` is overridden
+  to a union of `z.date()` and an ISO datetime string, never left as the
+  derived `z.date()` alone and never narrowed to a string-only schema —
+  the same field is checked server-side against a real `Date` and
+  client-side against JSON's string, and no `.transform()` can satisfy
+  both.
 - **`repository`**: a port (interface) plus a Drizzle adapter in
   `libs/<module>/repository`. A `findById`-shaped miss returns
   `undefined` — plain absence, not a thrown error; the service decides
-  what absence means.
-- **`service`**: domain logic in `libs/<module>/service`, importing only
-  its own ports (`type:port`, `type:util` — the Nx boundary rule). Throws
-  typed, domain-named errors (`OrderNotFoundError`, not a bare `Error` or
-  an HTTP exception). No logging, no HTTP, no queue mechanics inside a
-  service method. Multi-write operations wrap in one Drizzle transaction,
-  passed through the port.
+  what absence means. The concrete adapter's file name ends in
+  `.adapter.ts` and the lib's entry point exports the port interface and
+  its DI token; `packages/config/eslint-base.js` keys its port-discipline
+  rule on that suffix, so an adapter named anything else silently opts
+  out of the check.
+- **`service`**: domain logic in `libs/<module>/service`, importing its
+  own module's port interface from the repository lib's entry point —
+  never a `*.adapter` file, never `drizzle-orm` or `packages/db`
+  (`no-restricted-imports` in `eslint-base.js` fails lint on either).
+  Throws typed, domain-named errors (`OrderNotFoundError`, not a bare
+  `Error` or an HTTP exception). No logging, no HTTP, no queue mechanics
+  inside a service method. Multi-write operations wrap in one Drizzle
+  transaction, passed through the port.
 - **`controller`**: thin HTTP in `apps/api`, wiring the contract to the
   service. The only layer that maps domain errors to status codes.
   Validation happens once, at this boundary, via the Zod contract — past
-  it, types are trusted. Bundles queue infra (port + BullMQ adapter in
-  `apps/worker`, same shape as the repository) when the Queue add-on is
-  on and this operation needs it.
+  it, types are trusted. `apps/api` is the composition root: the module's
+  `*.module.ts` is the one file that constructs the concrete adapter and
+  binds it to the port's DI token, and the only file in `apps/api`
+  allowed to import a `*.adapter`. A controller takes the service, or the
+  bound token — never the adapter. Bundles queue infra (port + BullMQ
+  adapter in `apps/worker`, same shape as the repository) when the Queue
+  add-on is on and this operation needs it.
 
 ## Workflow
 
@@ -77,7 +100,16 @@ needed.
    dependencies guarantee this); check before writing the FK column.
 2. Build exactly one layer, matching the packet's ALLOWED SCOPE. Run
    typecheck, lint, and test yourself as a sanity check before reporting
-   back — necessary, not sufficient.
+   back — necessary, not sufficient. If this layer also has to create the
+   package it lands in (the first module through `contract` creates
+   `packages/contracts`), its shell files sit outside the packet's ALLOWED
+   SCOPE and `hedgehog verify` will leave them uncommitted — stop and say
+   so before building, so the scope can be widened for this one task
+   (`hedgehog-loop`, "First arrival in a package"). Don't build against a
+   scope you already know won't commit your work. That section also owns
+   the workspace wiring a new package needs (`pnpm install`, `pnpm nx
+   sync`, and its own `chore(workspace):` commit) — follow it rather than
+   leaving the package unlinked for a later layer to trip over.
 3. **Report the work as done; do not commit it yourself.** Per the build
    graph's design, an agent reporting success never moves a task — only
    `hedgehog verify <task-id>`'s passing exit code does. It checks your

package/src/agents/front-end-eng.md

@@ -32,7 +32,9 @@ before the next starts.
 Use `nx-run-tasks` (build/lint/test/typecheck), `nx-workspace` (inspecting
 project/target config), `nx-generate` (scaffolding a new library/app), and
 `link-workspace-packages` (wiring a new package into a consumer) as
-needed.
+needed. The `hook` layer's first-arrival package shell is a generator
+call, not a hand-copy of a sibling package — `hedgehog-loop`'s "First
+arrival in a package" section names the exact command and tags.
 
 If the screen step calls for animation or motion — entrances, sequencing,
 scroll-driven effects, drag, SVG/morph effects — use GSAP, loading the
@@ -46,17 +48,26 @@ don't reach for a second one.
 
 - **`hook`**: build the TanStack Query hook in `packages/hooks`, wrapping
   the ts-rest contract client. One hook per contract operation, typed end
-  to end from the Zod contract. The client's base URL comes from a
-  `NEXT_PUBLIC_`-prefixed env var (add to `packages/config/env.schema.ts`
-  if missing) — never a hardcoded `http://localhost:<port>` fallback,
-  which silently drifts out of sync with `apps/api`'s dev port (`3333`,
-  per `hedgehog-bootstrap-full-stack-app-core` — chosen to not collide
-  with `apps/web`'s `next dev` default of `3000`) and produces a 404 that
-  looks like a routing bug, not a config bug.
-- **`screen`**: build the screen/component in `apps/web` and/or
-  `apps/mobile`, consuming the hook and `ux-planner`'s rationale for that
-  module (screen inventory, interaction pattern, information hierarchy).
-  No direct data-fetching in the screen — the hook owns that.
+  to end from the Zod contract. The client's base URL is
+  `process.env.NEXT_PUBLIC_API_BASE_URL`, scaffolded in
+  `apps/web/.env.example` and already carrying `apps/api`'s `/api` global
+  prefix. Read it as-is: don't append or strip a path segment (the prefix
+  is in the value), don't add it to `packages/config/env.schema.ts` (that
+  schema is `apps/api`'s server env, and a `NEXT_PUBLIC_` var is inlined
+  into the browser bundle by Next, never parsed at runtime by `loadEnv()`),
+  and never fall back to a hardcoded `http://localhost:<port>`. A wrong or
+  absent base URL 404s against Next's own dev server — a config bug wearing
+  a routing bug's clothes, and one unit tests never see, because they mock
+  the client.
+- **`screen`**: build the screen/component in `apps/web` (plus
+  `apps/mobile` when the Mobile add-on is on), consuming the hook and
+  `ux-planner`'s rationale for that module (screen inventory, interaction
+  pattern, information hierarchy). No direct data-fetching in the
+  screen — the hook owns that. If this module's screen is the first one
+  built, wire `apps/web/src/app/page.tsx`'s primary CTA (ShadCN's
+  `asChild` + `next/link`, per `button.tsx`'s existing `asChild` prop)
+  to this module's own route — a compiling, lint-clean button with no
+  `href` or `onClick` still ships silent and unclickable.
 - Translate design specs into components. If a design tool is wired into
   this project's MCP config, use it for tokens/spacing/typography;
   otherwise match existing ShadCN/Tailwind patterns in the repo.
@@ -83,7 +94,13 @@ don't reach for a second one.
    early.
 2. Build the hook against the contract client, matching the packet's
    ALLOWED SCOPE. Run typecheck, lint, and test yourself as a sanity
-   check before reporting back — necessary, not sufficient.
+   check before reporting back — necessary, not sufficient. On the first
+   module through this layer, the hook also creates `packages/hooks`, and
+   that package's shell sits outside the packet's ALLOWED SCOPE —
+   `hedgehog verify` would leave it uncommitted. Stop and say so before
+   building, so the scope can be widened for this one task
+   (`hedgehog-loop`, "First arrival in a package") — that section also
+   owns the workspace wiring the new package needs.
 3. **Report the work as done; do not commit it yourself.** Only
    `hedgehog verify <task-id>`'s passing exit code moves the task to
    `complete` and writes the commit (the packet's exact Conventional

package/src/agents/reviewer.md

@@ -32,10 +32,15 @@ Everything lefthook already enforces (typecheck, lint, unit test
 pass/fail) is out of scope — don't re-report a green gate. Check what the
 gate structurally cannot:
 
-- **Port discipline**: does the service import only `type:port` /
-  `type:util`, per the Nx boundary rule — read the actual imports, don't
-  just trust `nx lint` ran. A boundary violation tagged wrong slips past
-  the rule. Use `nx show project <name> --json` (per nrwl's
+- **Port discipline**: a module's port interface and its Drizzle adapter
+  share one lib, so the tag graph has to allow `type:service →
+  type:adapter` and the real check is at the import level: does the
+  service import the port from the repository lib's entry point, or the
+  concrete `*.adapter`? Does anything in `apps/api` outside a
+  `*.module.ts` construct an adapter? `eslint-base.js`'s
+  `no-restricted-imports` rules catch the named cases — read the actual
+  imports anyway, since an adapter file not named `*.adapter.ts` opts
+  itself out of the rule. Use `nx show project <name> --json` (per nrwl's
   [nx-workspace](https://github.com/nrwl/nx-ai-agents-config/tree/main/skills/nx-workspace) skill) to check a project's resolved tags and
   dependencies rather than reading `project.json` directly — it only
   holds partial configuration, not tags inferred by plugins.

package/src/agents/ux-planner.md

@@ -127,8 +127,8 @@ conclusion.
 8. Hand off to `front-end-eng` for the screen step. The file isn't a step in
    the Domain Module Pattern and isn't committed on its own — it lands in
    the same commit as the screen step it informs
-   (`feat(<module>): screen-web` / `screen-mobile`), same as any other
-   file `front-end-eng` touches while building that step.
+   (`feat(<module>): screen-web`), same as any other file
+   `front-end-eng` touches while building that step.
 
 ## Constraints
 

package/src/db/claim.mjs

@@ -180,16 +180,25 @@ function loadTask(db, taskId) {
 // concurrent `claim` call in the interim would otherwise reach `verify`
 // with a technically-expired lease that still matches status/lease_owner
 // and sail through unreaped.
+//
+// Returns the ids it just flipped, as a Set — claimTasks's stop-the-line
+// check uses this to tell a block this very call produced from one that
+// was already sitting there, so a dead agent's lease lapsing doesn't
+// itself become the reason every other module's fan-out refuses.
 export function reapExpiredLeases(db) {
-  db.prepare(
-    `
+  const rows = db
+    .prepare(
+      `
     UPDATE tasks
     SET status = 'blocked', blocked_reason = 'lease_expired',
         lease_owner = NULL, lease_expires_at = NULL, leased_at = NULL,
         claim_snapshot = NULL
     WHERE status IN ('building', 'verifying') AND lease_expires_at < datetime('now')
+    RETURNING id
   `,
-  ).run();
+    )
+    .all();
+  return new Set(rows.map((r) => r.id));
 }
 
 // The atomic claim primitive: the WHERE clause re-checks status and
@@ -204,8 +213,38 @@ const claimOne = (db) =>
     RETURNING id
   `);
 
-// Claims up to `count` ready tasks for `owner`. `count` is a maximum, not
-// a promise — returns however many were actually claimed, possibly zero.
+// Every `blocked` task in the graph, regardless of module or reason —
+// the fan-out claim's stop-the-line check. Ordered the same as the
+// NEEDS ATTENTION list in status.mjs, so the two never disagree about
+// which tasks are outstanding.
+function findBlockedTasks(db) {
+  return db.prepare(`SELECT * FROM tasks WHERE status = 'blocked' ORDER BY priority, id`).all();
+}
+
+// Claims up to `count` ready tasks for `owner`, returning
+// `{ claimed, blocked }`. `count` is a maximum, not a promise — `claimed`
+// may hold fewer tasks than `count`, or none. `blocked` is non-empty only
+// on the stop-the-line refusal below, in which case `claimed` is always
+// empty.
+//
+// Stop-the-line: if any task anywhere in the graph was already `blocked`
+// before this call, the fan-out refuses to claim anything at all, in any
+// module — a blocked task needs a human/agent decision (retry after a
+// fix, or leave it), and handing out fresh work around it makes that easy
+// to ignore indefinitely. Deliberately stricter than dependency-based
+// blocking: an unrelated module isn't literally stuck on the blocked
+// task, but the fan-out stops anyway until it's retried. A targeted
+// `hedgehog claim <task-id>` (claimTask, below) is exempt — that's how
+// the blocked task itself gets reclaimed after `hedgehog retry`.
+//
+// "Already blocked" excludes a lease this same call's reapExpiredLeases
+// just flipped: a dead agent's lease can lapse on an unrelated module,
+// and the first `claim` call after that lapse is whichever one happens to
+// discover it. That call still claims normally; the reaped task still
+// lands in `blocked`/`lease_expired` and still needs `hedgehog retry`
+// before it's claimable — only this one call's refusal is skipped. Every
+// `claim` call after it sees the same task still blocked and stops as
+// usual.
 //
 // Fan-out keeps the batch mutually non-conflicting, and non-conflicting
 // with every task already in flight, per conflict.mjs's
@@ -229,7 +268,12 @@ export function claimTasks(db, { owner, count = 1, leaseMinutes = 45 }) {
   const claimSnapshot = snapshotWorkingTree();
 
   return inTransaction(db, () => {
-    reapExpiredLeases(db);
+    const justReaped = reapExpiredLeases(db);
+
+    const blocked = findBlockedTasks(db).filter((task) => !justReaped.has(task.id));
+    if (blocked.length > 0) {
+      return { claimed: [], blocked };
+    }
 
     const candidates = findClaimableTasks(db);
     const inFlight = findInFlightTasks(db);
@@ -245,7 +289,7 @@ export function claimTasks(db, { owner, count = 1, leaseMinutes = 45 }) {
       claimed.push(loadTask(db, candidate.id));
     }
 
-    return claimed;
+    return { claimed, blocked: [] };
   });
 }