hippo-memory 1.40.0 → 1.41.0

package/README.md

@@ -622,10 +622,12 @@ hippo watch "npm run build"
 | `hippo card create --title "..."` | Create a work-queue card (`--repo`, `--contract`, `--budget`, repeatable `--depends-on <id>`) |
 | `hippo card show <id>` | Show a card, its deps, runs, comments and latest handoff |
 | `hippo card list [--status <status>]` | List cards, newest-updated first |
-| `hippo card claim <id> --runtime <name>` | Claim a ready or blocked card |
-| `hippo card block <id> --reason "<why>"` | Block a running card; the reason is recorded as a comment |
-| `hippo card review <id>` | Move a running card to review |
-| `hippo card complete <id> --outcome <success\|failure\|partial>` | Complete a card in review: `success` marks it done and promotes children whose parents are all done; `failure` or `partial` shelves it |
+| `hippo card claim <id> --runtime <name>` | Claim a ready or blocked card; prints its run id and the time its 4-hour lease expires |
+| `hippo card heartbeat <id> --run <n>` | Extend a claimed card's lease |
+| `hippo card block <id> --reason "<why>" [--run <n>]` | Block a running card; the reason is recorded as a comment |
+| `hippo card review <id> [--run <n>]` | Move a running card to review |
+| `hippo card complete <id> --outcome <success\|failure\|partial> [--run <n>]` | Complete a card in review: `success` marks it done and promotes children whose parents are all done; `failure` or `partial` shelves it |
+| `hippo card reclaim` | Sweep every card whose lease has passed and return it to ready |
 | `hippo card comment <id> --body "..."` | Add a comment to a card |
 | `hippo wm push --scope <s> --content "..."` | Push to working memory |
 | `hippo wm read --scope <s>` | Read working memory entries |
@@ -635,6 +637,8 @@ hippo watch "npm run build"
 | `hippo dashboard --port <n>` | Use custom port |
 | `hippo mcp` | Start MCP server (stdio transport) |
 
+On `heartbeat`, `block`, `review` and `complete`, a given `--run` is checked against the card's live run and the command is refused, unchanged, if the two do not match.
+
 ---
 
 ## Framework Integrations

package/dist/card.d.ts

@@ -2,7 +2,7 @@
 export type CardStatus = 'backlog' | 'ready' | 'running' | 'blocked' | 'review' | 'done' | 'shelved';
 /** Narrows a raw string, such as a CLI flag value, to a CardStatus. */
 export declare function isCardStatus(v: string): v is CardStatus;
-/** A card row; leaseUntil and heartbeatAt are reserved for W2b's lease and heartbeat, W2a never writes them and they stay null. */
+/** A card row; leaseUntil and heartbeatAt are null unless the card is running, and a card claimed under 1.40.0 runs with both null until a heartbeat sets them. */
 export interface Card {
     id: string;
     title: string;
@@ -42,4 +42,6 @@ export type CardTransitions = {
 };
 /** transitionCard checks every status write against this map. */
 export declare const CARD_TRANSITIONS: CardTransitions;
+/** How long a claim or a heartbeat keeps a running card's lease before reclaimExpiredCards may return it to ready. */
+export declare const CARD_LEASE_MS: number;
 //# sourceMappingURL=card.d.ts.map

package/dist/card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../src/card.ts"],"names":[],"mappings":"AACA,gGAAgG;AAChG,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAIrG,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,UAAU,CAEvD;AAED,mIAAmI;AACnI,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mDAAmD;AACnD,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,UAAU,GAAG,SAAS,UAAU,EAAE;CAAE,CAAC;AAEpF,iEAAiE;AACjE,eAAO,MAAM,gBAAgB,EAAE,eAQ9B,CAAC"}
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../src/card.ts"],"names":[],"mappings":"AACA,gGAAgG;AAChG,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAIrG,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,UAAU,CAEvD;AAED,mKAAmK;AACnK,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mDAAmD;AACnD,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,UAAU,GAAG,SAAS,UAAU,EAAE;CAAE,CAAC;AAEpF,iEAAiE;AACjE,eAAO,MAAM,gBAAgB,EAAE,eAQ9B,CAAC;AAGF,sHAAsH;AACtH,eAAO,MAAM,aAAa,QAAqB,CAAC"}

package/dist/card.js

@@ -7,10 +7,13 @@ export function isCardStatus(v) {
 export const CARD_TRANSITIONS = {
     backlog: ['ready'],
     ready: ['running'],
-    running: ['blocked', 'review'],
+    running: ['blocked', 'review', 'ready'],
     blocked: ['running'],
     review: ['done', 'shelved'],
     done: [],
     shelved: [],
 };
+// SHORTCUT: one fixed lease for every claim; add a per-claim lease when the W3 dispatcher heartbeats on a timer.
+/** How long a claim or a heartbeat keeps a running card's lease before reclaimExpiredCards may return it to ready. */
+export const CARD_LEASE_MS = 4 * 60 * 60 * 1000;
 //# sourceMappingURL=card.js.map

package/dist/card.js.map

@@ -1 +1 @@
-{"version":3,"file":"card.js","sourceRoot":"","sources":["../src/card.ts"],"names":[],"mappings":"AAIA,MAAM,aAAa,GAA0B,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;AAErH,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5C,CAAC;AA0CD,iEAAiE;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C,OAAO,EAAE,CAAC,OAAO,CAAC;IAClB,KAAK,EAAE,CAAC,SAAS,CAAC;IAClB,OAAO,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC9B,OAAO,EAAE,CAAC,SAAS,CAAC;IACpB,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,EAAE;CACZ,CAAC"}
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../src/card.ts"],"names":[],"mappings":"AAIA,MAAM,aAAa,GAA0B,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;AAErH,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5C,CAAC;AA0CD,iEAAiE;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C,OAAO,EAAE,CAAC,OAAO,CAAC;IAClB,KAAK,EAAE,CAAC,SAAS,CAAC;IAClB,OAAO,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC;IACvC,OAAO,EAAE,CAAC,SAAS,CAAC;IACpB,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,EAAE;CACZ,CAAC;AAEF,iHAAiH;AACjH,sHAAsH;AACtH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC"}

package/dist/cli.d.ts

@@ -13,7 +13,7 @@
  *   hippo snapshot <save|show|clear>
  *   hippo session <log|show|latest|resume|complete>
  *   hippo handoff <create|latest|show>
- *   hippo card <create|show|list|claim|block|review|complete|comment>
+ *   hippo card <create|show|list|claim|heartbeat|block|review|complete|reclaim|comment>
  *   hippo current <show>
  *   hippo forget <id> [--archive --reason "<why>"]
  *   hippo reject <id>|--value "<text>" --reason "<why>"

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA2BH,OAAO,EAWL,WAAW,EAEZ,MAAM,aAAa,CAAC;AA2HrB,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AA4ChC,kFAAkF;AAClF,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAsJD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAA;CAAE,CAwCjI;AAqxED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,MAAqB,GAAG,MAAM,CAyF3F;AAyGD;;;GAGG;AACH,oHAAoH;AACpH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAuD/D;AA87GD,oHAAoH;AACpH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,EACtF,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAAkB,GAC1B,IAAI,CA8BN"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA2BH,OAAO,EAWL,WAAW,EAEZ,MAAM,aAAa,CAAC;AA6HrB,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AA4ChC,kFAAkF;AAClF,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAsJD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAA;CAAE,CAwCjI;AAqxED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,MAAqB,GAAG,MAAM,CAyF3F;AAyGD;;;GAGG;AACH,oHAAoH;AACpH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAuD/D;AAigHD,oHAAoH;AACpH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,EACtF,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAAkB,GAC1B,IAAI,CA8BN"}

package/dist/cli.js

@@ -13,7 +13,7 @@
  *   hippo snapshot <save|show|clear>
  *   hippo session <log|show|latest|resume|complete>
  *   hippo handoff <create|latest|show>
- *   hippo card <create|show|list|claim|block|review|complete|comment>
+ *   hippo card <create|show|list|claim|heartbeat|block|review|complete|reclaim|comment>
  *   hippo current <show>
  *   hippo forget <id> [--archive --reason "<why>"]
  *   hippo reject <id>|--value "<text>" --reason "<why>"
@@ -38,7 +38,7 @@ import { execFileSync, execSync, spawn } from 'child_process';
 import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths, detectInstalledTools, defaultSleepLogPath, ensureCodexWrapperInstalled, installCodexWrapper, isCodexWrapperInstalled, repairCodexWrapperIfInstalled, uninstallCodexWrapper, resolveCodexSessionTranscript, resolveCodexWrapperPaths, installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPath, } from './hooks.js';
 import { createMemory, calculateStrength, calculateRewardFactor, deriveHalfLife, resolveConfidence, confidenceFacets, confidenceLabel, computeSchemaFit, Layer, } from './memory.js';
 import { detectSecret } from './secret-detect.js';
-import { getHippoRoot, isInitialized, initStore, writeEntry, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, blockCard, reviewCard, completeCard, addCardComment, loadLatestHandoffForCard, } from './store.js';
+import { getHippoRoot, isInitialized, initStore, writeEntry, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { RejectedValueError } from './rejection.js';
 import { isHandoffOutcome, formatHandoffEvidenceLine } from './handoff.js';
@@ -4034,6 +4034,10 @@ function printCard(hippoRoot, tenantId, card) {
     console.log(`- Status: ${card.status}`);
     if (card.assigneeRuntime)
         console.log(`- Assignee: ${card.assigneeRuntime}`);
+    if (card.leaseUntil)
+        console.log(`- Lease until: ${card.leaseUntil}`);
+    if (card.heartbeatAt)
+        console.log(`- Heartbeat: ${card.heartbeatAt}`);
     if (card.repo)
         console.log(`- Repo: ${card.repo}`);
     if (card.contract)
@@ -4050,7 +4054,7 @@ function printCard(hippoRoot, tenantId, card) {
     if (runs.length > 0) {
         console.log('\n### Runs');
         for (const run of runs) {
-            console.log(`- ${run.runtime} started ${run.started}${run.ended ? ` ended ${run.ended} (${run.outcome})` : ' (open)'}`);
+            console.log(`- run ${run.id}: ${run.runtime} started ${run.started}${run.ended ? ` ended ${run.ended} (${run.outcome})` : ' (open)'}`);
         }
     }
     const comments = loadCardComments(hippoRoot, tenantId, card.id);
@@ -4080,14 +4084,34 @@ function cardStringFlag(flags, key) {
     }
     return v.trim();
 }
+// A too-large --run would silently round to a different id (mirrors parsePositiveIncidentId).
+function cardRunFlag(flags) {
+    const raw = cardStringFlag(flags, 'run');
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!/^\d+$/.test(raw) || !Number.isSafeInteger(n) || n <= 0) {
+        console.error(`Invalid --run: "${raw}" (expected a positive integer).`);
+        process.exit(1);
+    }
+    return n;
+}
+// Reads after the store already refused, so this only explains the refusal, never changes it.
+function cardRefusal(hippoRoot, tenantId, id) {
+    const card = loadCard(hippoRoot, tenantId, id);
+    const liveRun = loadCardRuns(hippoRoot, tenantId, id).find((r) => !r.ended);
+    return `status ${card?.status ?? 'unknown'}, live run ${liveRun?.id ?? 'none'}`;
+}
 const CARD_SUBCOMMAND_FLAGS = {
     create: ['title', 'repo', 'contract', 'budget', 'depends-on'],
     show: ['json'],
     list: ['status', 'json'],
     claim: ['runtime', 'session'],
-    block: ['reason'],
-    review: new Array(),
-    complete: ['outcome'],
+    heartbeat: ['run'],
+    block: ['reason', 'run'],
+    review: ['run'],
+    complete: ['outcome', 'run'],
+    reclaim: new Array(),
     comment: ['body', 'author'],
 };
 function cmdCard(hippoRoot, args, flags) {
@@ -4205,7 +4229,29 @@ function cmdCard(hippoRoot, args, flags) {
             console.error(`Could not claim card ${id} (not ready/blocked, or already claimed).`);
             process.exit(1);
         }
-        console.log(`Claimed card ${card.id} for ${runtime}`);
+        console.log(`Claimed card ${card.id} for ${runtime} (run ${card.runId}, lease until ${card.leaseUntil})`);
+        return;
+    }
+    if (subcommand === 'heartbeat') {
+        const id = args[1];
+        const runId = cardRunFlag(flags);
+        if (!id || runId === undefined) {
+            console.error('Usage: hippo card heartbeat <id> --run <n>');
+            process.exit(1);
+        }
+        let card;
+        try {
+            card = heartbeatCard(hippoRoot, tenantId, id, runId);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        if (!card) {
+            console.error(`Could not heartbeat card ${id} (${cardRefusal(hippoRoot, tenantId, id)}).`);
+            process.exit(1);
+        }
+        console.log(`Heartbeat card ${card.id}: lease until ${card.leaseUntil}`);
         return;
     }
     if (subcommand === 'block') {
@@ -4215,16 +4261,18 @@ function cmdCard(hippoRoot, args, flags) {
             console.error(CARD_BLOCK_REASON_REQUIRED);
             process.exit(1);
         }
+        const runId = cardRunFlag(flags);
         let card;
         try {
-            card = blockCard(hippoRoot, tenantId, id, reason);
+            card = blockCard(hippoRoot, tenantId, id, reason, runId);
         }
         catch (error) {
             console.error(error instanceof Error ? error.message : String(error));
             process.exit(1);
         }
         if (!card) {
-            console.error(`Could not block card ${id} (not running).`);
+            const why = runId === undefined ? 'not running' : cardRefusal(hippoRoot, tenantId, id);
+            console.error(`Could not block card ${id} (${why}).`);
             process.exit(1);
         }
         console.log(`Blocked card ${card.id}`);
@@ -4233,19 +4281,21 @@ function cmdCard(hippoRoot, args, flags) {
     if (subcommand === 'review') {
         const id = args[1];
         if (!id) {
-            console.error('Usage: hippo card review <id>');
+            console.error('Usage: hippo card review <id> [--run <n>]');
             process.exit(1);
         }
+        const runId = cardRunFlag(flags);
         let card;
         try {
-            card = reviewCard(hippoRoot, tenantId, id);
+            card = reviewCard(hippoRoot, tenantId, id, runId);
         }
         catch (error) {
             console.error(error instanceof Error ? error.message : String(error));
             process.exit(1);
         }
         if (!card) {
-            console.error(`Could not move card ${id} to review (not running).`);
+            const why = runId === undefined ? 'not running' : cardRefusal(hippoRoot, tenantId, id);
+            console.error(`Could not move card ${id} to review (${why}).`);
             process.exit(1);
         }
         console.log(`Card ${card.id} moved to review`);
@@ -4255,19 +4305,21 @@ function cmdCard(hippoRoot, args, flags) {
         const id = args[1];
         const outcomeRaw = flags['outcome'];
         if (!id || !isHandoffOutcome(outcomeRaw)) {
-            console.error('Usage: hippo card complete <id> --outcome <success|failure|partial>');
+            console.error('Usage: hippo card complete <id> --outcome <success|failure|partial> [--run <n>]');
             process.exit(1);
         }
+        const runId = cardRunFlag(flags);
         let result;
         try {
-            result = completeCard(hippoRoot, tenantId, id, outcomeRaw);
+            result = completeCard(hippoRoot, tenantId, id, outcomeRaw, runId);
         }
         catch (error) {
             console.error(error instanceof Error ? error.message : String(error));
             process.exit(1);
         }
         if (!result) {
-            console.error(`Could not complete card ${id} (not in review).`);
+            const why = runId === undefined ? 'not in review' : cardRefusal(hippoRoot, tenantId, id);
+            console.error(`Could not complete card ${id} (${why}).`);
             process.exit(1);
         }
         console.log(`Completed card ${result.card.id} (status: ${result.card.status})`);
@@ -4276,13 +4328,28 @@ function cmdCard(hippoRoot, args, flags) {
         }
         return;
     }
+    if (subcommand === 'reclaim') {
+        if (args.length > 1) {
+            console.error('Usage: hippo card reclaim (sweeps every expired lease; use hippo card block <id> for one card)');
+            process.exit(1);
+        }
+        const ids = reclaimExpiredCards(hippoRoot, tenantId);
+        if (ids.length === 0) {
+            console.log('No expired leases.');
+            return;
+        }
+        for (const id of ids) {
+            console.log(`Reclaimed card ${id} (now ready)`);
+        }
+        return;
+    }
     if (subcommand === 'comment') {
         const id = args[1];
         if (!id) {
             console.error('Usage: hippo card comment <id> --body "..." [--author <name>]');
             process.exit(1);
         }
-        // Only show and comment look the card up directly; claim/block/review/complete throw from the store instead.
+        // Only show and comment look the card up directly; claim/heartbeat/block/review/complete throw from the store instead.
         const card = loadCard(hippoRoot, tenantId, id);
         if (!card) {
             console.error(`No card found with id ${id}.`);
@@ -4298,7 +4365,7 @@ function cmdCard(hippoRoot, args, flags) {
         console.log(`Added comment ${comment.id} to card ${id}`);
         return;
     }
-    console.error('Usage: hippo card <create|show|list|claim|block|review|complete|comment>');
+    console.error('Usage: hippo card <create|show|list|claim|heartbeat|block|review|complete|reclaim|comment>');
     process.exit(1);
 }
 // ---------------------------------------------------------------------------
@@ -8224,14 +8291,20 @@ Commands:
       --json                 Output as JSON
     card list                List cards, newest-updated first
       --status <status>     Filter by status
-    card claim <id>          Claim a ready or blocked card
+    card claim <id>          Claim a ready or blocked card; prints its run id and lease
       --runtime <name>       Claiming runtime (required)
       --session <id>         Session ID
+    card heartbeat <id>       Extend a running card's lease
+      --run <n>              Your run id, as card claim printed it (required)
     card block <id>           Block a running card
       --reason "<why>"       Reason recorded as a card comment (required)
+      --run <n>              Refuse unless <n> is the card's live run
     card review <id>          Move a running card to review
+      --run <n>              Refuse unless <n> is the card's live run
     card complete <id>       Complete a card in review
       --outcome <o>          success | failure | partial (required)
+      --run <n>              Refuse unless <n> is the card's live run
+    card reclaim              Return every running card whose lease has expired to ready
     card comment <id>         Add a comment to a card
       --body <text>          Comment body (required)
       --author <name>       Comment author (default: cli)
@@ -8463,6 +8536,8 @@ Examples:
   hippo card create --title "Add cards table" --repo hippo --depends-on card_abc
   hippo card claim card_abc --runtime codex
   hippo card complete card_abc --outcome success
+  hippo card heartbeat card_abc --run 7
+  hippo card reclaim
   hippo embed --status
   hippo watch "npm run build"
   hippo learn --git --days 30