hippo-memory 1.39.0 → 1.41.0

package/README.md

@@ -619,6 +619,16 @@ hippo watch "npm run build"
 | `hippo session latest` | Show latest task snapshot + events |
 | `hippo session resume` | Re-inject latest handoff as context |
 | `hippo current show` | Compact current state (task + session events) |
+| `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; 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 |
 | `hippo wm clear --scope <s>` | Clear working memory |
@@ -627,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

@@ -0,0 +1,47 @@
+/** A work-queue card's lifecycle state; CARD_TRANSITIONS lists the legal moves between them. */
+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 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;
+    status: CardStatus;
+    assigneeRuntime: string | null;
+    repo: string | null;
+    contract: string | null;
+    budget: number | null;
+    leaseUntil: string | null;
+    heartbeatAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    tenantId: string;
+    scope: string | null;
+}
+/** One claim-to-close attempt at a card by a runtime. */
+export interface CardRun {
+    id: number;
+    card: string;
+    runtime: string;
+    sessionId: string | null;
+    started: string;
+    ended: string | null;
+    outcome: string | null;
+}
+/** A comment left on a card. */
+export interface CardComment {
+    id: number;
+    cardId: string;
+    author: string;
+    body: string;
+    createdAt: string;
+}
+/** The legal next-statuses for each CardStatus. */
+export type CardTransitions = {
+    readonly [S in CardStatus]: readonly CardStatus[];
+};
+/** 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

@@ -0,0 +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,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

@@ -0,0 +1,19 @@
+const CARD_STATUSES = ['backlog', 'ready', 'running', 'blocked', 'review', 'done', 'shelved'];
+/** Narrows a raw string, such as a CLI flag value, to a CardStatus. */
+export function isCardStatus(v) {
+    return CARD_STATUSES.some((s) => s === v);
+}
+/** transitionCard checks every status write against this map. */
+export const CARD_TRANSITIONS = {
+    backlog: ['ready'],
+    ready: ['running'],
+    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

@@ -0,0 +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,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,6 +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|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;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA2BH,OAAO,EAWL,WAAW,EAEZ,MAAM,aAAa,CAAC;AA8GrB,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;AA+pGD,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,6 +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|heartbeat|block|review|complete|reclaim|comment>
  *   hippo current <show>
  *   hippo forget <id> [--archive --reason "<why>"]
  *   hippo reject <id>|--value "<text>" --reason "<why>"
@@ -37,10 +38,11 @@ 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, } 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';
+import { isCardStatus } from './card.js';
 import { passesScopeFilterForRecall } from './recall-scope.js';
 import { markRetrieved, hybridSearch, physicsSearch, explainMatch, textOverlap, tokenize as tokenizeQuery } from './search.js';
 import { compareEntryIdentity } from './compare.js';
@@ -253,8 +255,8 @@ export function parseArgs(argv) {
                 i++;
             }
             else {
-                // Check if it's a repeatable flag (tag, artifact, link, step, constraint)
-                if (key === 'tag' || key === 'artifact' || key === 'link' || key === 'step' || key === 'constraint') {
+                // Check if it's a repeatable flag (tag, artifact, link, step, constraint, depends-on)
+                if (key === 'tag' || key === 'artifact' || key === 'link' || key === 'step' || key === 'constraint' || key === 'depends-on') {
                     if (Array.isArray(flags[key])) {
                         flags[key].push(next);
                     }
@@ -4024,6 +4026,348 @@ function cmdHandoff(hippoRoot, args, flags) {
     console.error('Usage: hippo handoff <create|latest|show>');
     process.exit(1);
 }
+// Mirrors ARCHIVE_REASON_REQUIRED so the block message can't drift from its usage line.
+const CARD_BLOCK_REASON_REQUIRED = 'hippo card block <id> requires --reason "<why>" (recorded as a comment).';
+function printCard(hippoRoot, tenantId, card) {
+    console.log(`## Card ${card.id}\n`);
+    console.log(`- Title: ${card.title}`);
+    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)
+        console.log(`- Contract: ${card.contract}`);
+    if (card.budget !== null)
+        console.log(`- Budget: ${card.budget}`);
+    console.log(`- Updated: ${card.updatedAt}`);
+    const deps = loadCardDeps(hippoRoot, tenantId, card.id);
+    if (deps.parents.length > 0)
+        console.log(`- Parents: ${deps.parents.join(', ')}`);
+    if (deps.children.length > 0)
+        console.log(`- Children: ${deps.children.join(', ')}`);
+    const runs = loadCardRuns(hippoRoot, tenantId, card.id);
+    if (runs.length > 0) {
+        console.log('\n### Runs');
+        for (const run of runs) {
+            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);
+    if (comments.length > 0) {
+        console.log('\n### Comments');
+        for (const comment of comments) {
+            console.log(`- [${comment.createdAt}] ${comment.author}: ${comment.body}`);
+        }
+    }
+    const handoff = loadLatestHandoffForCard(hippoRoot, tenantId, card.id);
+    if (handoff) {
+        console.log('\n### Latest handoff');
+        console.log(`- Session: ${handoff.sessionId}, updated ${handoff.updatedAt}`);
+        console.log(handoff.summary);
+    }
+    console.log('');
+}
+// parseArgs turns a value-less flag into `true`; refuse rather than silently
+// stringifying it (String(true) === 'true'), mirroring cmdHandoff's guard.
+function cardStringFlag(flags, key) {
+    const v = flags[key];
+    if (v === undefined)
+        return undefined;
+    if (v === true || v === false || Array.isArray(v)) {
+        console.error(`--${key} requires a value`);
+        process.exit(1);
+    }
+    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'],
+    heartbeat: ['run'],
+    block: ['reason', 'run'],
+    review: ['run'],
+    complete: ['outcome', 'run'],
+    reclaim: new Array(),
+    comment: ['body', 'author'],
+};
+function cmdCard(hippoRoot, args, flags) {
+    requireInit(hippoRoot);
+    const tenantId = resolveTenantId({});
+    const subcommand = args[0] ?? '';
+    if (Object.hasOwn(CARD_SUBCOMMAND_FLAGS, subcommand)) {
+        // SAFETY: hasOwn, unlike `in`, skips inherited keys such as constructor, so subcommand is a real key.
+        const allowedFlags = CARD_SUBCOMMAND_FLAGS[subcommand];
+        for (const key of Object.keys(flags)) {
+            if (!allowedFlags.includes(key)) {
+                // --flag=value never splits on '=' (see parseArgs), so it lands here as one long key.
+                const hint = key.includes('=') ? ` Use --${key.slice(0, key.indexOf('='))} <value>, not --${key}.` : '';
+                const valid = allowedFlags.length > 0 ? allowedFlags.map((f) => `--${f}`).join(', ') : '(none)';
+                console.error(`Unknown flag --${key} for hippo card ${subcommand}.${hint} Valid flags: ${valid}`);
+                process.exit(1);
+            }
+        }
+    }
+    if (subcommand === 'create') {
+        const title = cardStringFlag(flags, 'title') ?? '';
+        if (!title) {
+            console.error('Usage: hippo card create --title "..." [--repo <name>] [--contract <text>] [--budget <n>] [--depends-on <id>...]');
+            process.exit(1);
+        }
+        const repo = cardStringFlag(flags, 'repo') || undefined;
+        const contract = cardStringFlag(flags, 'contract') || undefined;
+        const budgetRaw = cardStringFlag(flags, 'budget');
+        let budget;
+        if (budgetRaw !== undefined) {
+            if (!/^\d+$/.test(budgetRaw)) {
+                console.error(`Invalid budget: "${budgetRaw}" (expected a positive integer)`);
+                process.exit(1);
+            }
+            budget = Number(budgetRaw);
+        }
+        const dependsOnFlag = flags['depends-on'];
+        if (dependsOnFlag === true) {
+            console.error('--depends-on requires a value');
+            process.exit(1);
+        }
+        const dependsOn = Array.isArray(dependsOnFlag) ? dependsOnFlag : [];
+        let card;
+        try {
+            card = createCard(hippoRoot, tenantId, { title, repo, contract, budget, dependsOn });
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        console.log(`Created card ${card.id} (status: ${card.status})`);
+        return;
+    }
+    if (subcommand === 'show') {
+        const id = args[1];
+        if (!id) {
+            console.error('Usage: hippo card show <id> [--json]');
+            process.exit(1);
+        }
+        const card = loadCard(hippoRoot, tenantId, id);
+        if (!card) {
+            console.error(`No card found with id ${id}.`);
+            process.exit(1);
+        }
+        if (flags['json']) {
+            console.log(JSON.stringify({
+                card,
+                deps: loadCardDeps(hippoRoot, tenantId, id),
+                runs: loadCardRuns(hippoRoot, tenantId, id),
+                comments: loadCardComments(hippoRoot, tenantId, id),
+                handoff: loadLatestHandoffForCard(hippoRoot, tenantId, id),
+            }, null, 2));
+            return;
+        }
+        printCard(hippoRoot, tenantId, card);
+        return;
+    }
+    if (subcommand === 'list') {
+        const status = cardStringFlag(flags, 'status');
+        if (status !== undefined && !isCardStatus(status)) {
+            console.error(`Invalid status: "${status}".`);
+            process.exit(1);
+        }
+        const cards = listCards(hippoRoot, tenantId, { status });
+        if (flags['json']) {
+            console.log(JSON.stringify({ cards }, null, 2));
+            return;
+        }
+        if (cards.length === 0) {
+            console.log('No cards found.');
+            return;
+        }
+        for (const card of cards) {
+            console.log(`${card.id}\t${card.status}\t${card.title}${card.assigneeRuntime ? `\t(${card.assigneeRuntime})` : ''}`);
+        }
+        return;
+    }
+    if (subcommand === 'claim') {
+        const id = args[1];
+        const runtime = cardStringFlag(flags, 'runtime') ?? '';
+        if (!id || !runtime) {
+            console.error('Usage: hippo card claim <id> --runtime <name> [--session <id>]');
+            process.exit(1);
+        }
+        const sessionId = cardStringFlag(flags, 'session') || undefined;
+        let card;
+        try {
+            card = claimCard(hippoRoot, tenantId, id, runtime, sessionId);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        if (!card) {
+            console.error(`Could not claim card ${id} (not ready/blocked, or already claimed).`);
+            process.exit(1);
+        }
+        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') {
+        const id = args[1];
+        const reason = cardStringFlag(flags, 'reason') ?? '';
+        if (!id || !reason) {
+            console.error(CARD_BLOCK_REASON_REQUIRED);
+            process.exit(1);
+        }
+        const runId = cardRunFlag(flags);
+        let card;
+        try {
+            card = blockCard(hippoRoot, tenantId, id, reason, runId);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        if (!card) {
+            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}`);
+        return;
+    }
+    if (subcommand === 'review') {
+        const id = args[1];
+        if (!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, runId);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        if (!card) {
+            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`);
+        return;
+    }
+    if (subcommand === 'complete') {
+        const id = args[1];
+        const outcomeRaw = flags['outcome'];
+        if (!id || !isHandoffOutcome(outcomeRaw)) {
+            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, runId);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        if (!result) {
+            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})`);
+        if (result.promotedChildren.length > 0) {
+            console.log(`Promoted to ready: ${result.promotedChildren.join(', ')}`);
+        }
+        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/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}.`);
+            process.exit(1);
+        }
+        const body = cardStringFlag(flags, 'body') ?? '';
+        if (!body) {
+            console.error('Usage: hippo card comment <id> --body "..." [--author <name>]');
+            process.exit(1);
+        }
+        const author = cardStringFlag(flags, 'author') || 'cli';
+        const comment = addCardComment(hippoRoot, tenantId, id, author, body);
+        console.log(`Added comment ${comment.id} to card ${id}`);
+        return;
+    }
+    console.error('Usage: hippo card <create|show|list|claim|heartbeat|block|review|complete|reclaim|comment>');
+    process.exit(1);
+}
 // ---------------------------------------------------------------------------
 // E2 prediction first-class object (v0.31)
 // docs/plans/2026-05-26-e2-prediction-object.md
@@ -7936,6 +8280,34 @@ Commands:
       --session <id>       Filter by session
       --json               Output as JSON
     handoff show <id>      Show a specific handoff by ID
+  card <sub>                Manage claimable work-queue cards
+    card create             Create a new card
+      --title <text>        Card title (required)
+      --repo <name>         Associated repo
+      --contract <text>     Associated contract
+      --budget <n>           Token/step budget
+      --depends-on <id>     Parent card id (repeatable)
+    card show <id>          Show a card, its deps, runs, comments and latest handoff
+      --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; 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)
   current <sub>            Show compact current state for agent injection
     current show           Active task + recent session events (default)
       --json               Output as JSON
@@ -8161,6 +8533,11 @@ Examples:
   hippo snapshot save --task "Ship feature" --summary "Tests are green" --next-step "Open the PR" --session sess_123
   hippo handoff create --summary "PR is open, tests green" --next "Merge after review" --session sess_123 --artifact src/foo.ts
   hippo handoff create --summary s --constraint a --constraint b --outcome partial --target-runtime codex --card-id c1 --tests pass
+  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
@@ -8548,6 +8925,9 @@ async function main() {
         case 'handoff':
             cmdHandoff(hippoRoot, args, flags);
             break;
+        case 'card':
+            cmdCard(hippoRoot, args, flags);
+            break;
         case 'predict':
             cmdPredict(hippoRoot, args, flags);
             break;