hippo-memory 1.38.10 → 1.40.0

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|block|review|complete|comment>
  *   hippo current <show>
  *   hippo forget <id> [--archive --reason "<why>"]
  *   hippo reject <id>|--value "<text>" --reason "<why>"
@@ -37,9 +38,12 @@ 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, RECALL_DEFAULT_DENY_SCOPES, } 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, blockCard, reviewCard, completeCard, 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';
 import { renderTraceContent, parseSteps } from './trace.js';
@@ -251,8 +255,8 @@ export function parseArgs(argv) {
                 i++;
             }
             else {
-                // Check if it's a repeatable flag (tag, artifact, link, step)
-                if (key === 'tag' || key === 'artifact' || key === 'link' || key === 'step') {
+                // 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);
                     }
@@ -1544,37 +1548,16 @@ async function cmdRecall(hippoRoot, query, flags) {
         const rawEvents = sessionId
             ? listSessionEvents(hippoRoot, tenantId, { session_id: sessionId, limit: 5 })
             : [];
-        // Mirror the api.recall default-deny rule for forward compat: when v1.2.0
-        // continuity writers start setting scope, a no-scope caller must not see
-        // private-channel-derived rows. Today scope is NULL on all continuity
-        // rows so this is a no-op. Caller-supplied --scope bypasses the gate
-        // (matches existing memory recall behavior).
-        // Scope filter mirrors api.recall: exact match when scope is set, default-deny
-        // on ANY `<source>:private:*` and 'unknown:legacy' otherwise. recallActiveScope
-        // merges --scope flag and detectScope() so auto-detected source contexts get
-        // matched. v1.2.1: generalized from slack-only to source-agnostic via
-        // api.isPrivateScope so v1.3 GitHub (and future sources) cannot leak.
-        const effectiveScope = recallActiveScope ?? '';
-        const passesScopeFilter = (s) => {
-            if (effectiveScope) {
-                return s === effectiveScope;
-            }
-            if (s === null)
-                return true;
-            if (api.isPrivateScope(s))
-                return false;
-            // v1.7.2: read from RECALL_DEFAULT_DENY_SCOPES (single source of truth
-            // shared with SQL + api.passesScopeFilterForRecall).
-            if (RECALL_DEFAULT_DENY_SCOPES.includes(s))
-                return false;
-            return true;
-        };
+        // W1: was its own copy of passesScopeFilterForRecall (cloned 3x);
+        // calls the shared helper directly now (recallActiveScope merges
+        // --scope and detectScope()).
+        const effectiveScope = recallActiveScope || undefined;
         const rowScope = (r) => r?.scope ?? null;
         activeSnapshot =
-            rawSnapshot && passesScopeFilter(rowScope(rawSnapshot)) ? rawSnapshot : null;
+            rawSnapshot && passesScopeFilterForRecall(rowScope(rawSnapshot), effectiveScope) ? rawSnapshot : null;
         sessionHandoff =
-            rawHandoff && passesScopeFilter(rowScope(rawHandoff)) ? rawHandoff : null;
-        recentSessionEvents = rawEvents.filter((e) => passesScopeFilter(rowScope(e)));
+            rawHandoff && passesScopeFilterForRecall(rowScope(rawHandoff), effectiveScope) ? rawHandoff : null;
+        recentSessionEvents = rawEvents.filter((e) => passesScopeFilterForRecall(rowScope(e), effectiveScope));
         const tokenize = (s) => s ? Math.ceil(s.length / 4) : 0;
         continuityTokens =
             tokenize(activeSnapshot?.task) +
@@ -1583,6 +1566,11 @@ async function cmdRecall(hippoRoot, query, flags) {
                 tokenize(sessionHandoff?.summary) +
                 tokenize(sessionHandoff?.nextAction) +
                 (sessionHandoff?.artifacts ?? []).reduce((acc, a) => acc + tokenize(a), 0) +
+                (sessionHandoff?.constraints ?? []).reduce((acc, c) => acc + tokenize(c), 0) +
+                tokenize(sessionHandoff?.evidence ? formatHandoffEvidenceLine(sessionHandoff.evidence) : null) +
+                tokenize(sessionHandoff?.outcome) +
+                tokenize(sessionHandoff?.targetRuntime) +
+                tokenize(sessionHandoff?.cardId) +
                 recentSessionEvents.reduce((acc, e) => acc + tokenize(e.content), 0);
     }
     const hasContinuity = activeSnapshot !== null
@@ -2936,6 +2924,30 @@ async function cmdSessionEnd(hippoRoot, flags) {
  * `__session-end-worker` subcommand (not user-facing). Failures in one stage
  * do not block the other.
  */
+// Best-effort git state; a missing git, non-repo cwd, or the timeout all
+// yield null fields rather than throw (autolearn.ts execFileSync shape).
+function collectHandoffEvidence(cwd, testStatus) {
+    let gitRef = null;
+    try {
+        gitRef = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd, encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim() || null;
+    }
+    catch {
+        gitRef = null;
+    }
+    let dirtyTree = null;
+    try {
+        const status = execFileSync('git', ['status', '--porcelain'], {
+            cwd, encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        dirtyTree = status.trim().length > 0;
+    }
+    catch {
+        dirtyTree = null;
+    }
+    return { gitRef, dirtyTree, testStatus };
+}
 async function cmdSessionEndWorker(hippoRoot, flags) {
     try {
         await cmdSleep(hippoRoot, flags);
@@ -2972,6 +2984,25 @@ async function cmdSessionEndWorker(hippoRoot, flags) {
     // in loadFreshActiveTaskSnapshot is the backstop layer, not this close.
     const closeLogFile = typeof flags['log-file'] === 'string' ? flags['log-file'] : null;
     const closeSessionId = typeof flags['session-id'] === 'string' ? flags['session-id'] : null;
+    // Handoff write happens BEFORE the snapshot close below, while the
+    // snapshot writeSessionEndHandoff reads is still active.
+    if (closeSessionId) {
+        try {
+            const activeForHandoff = loadActiveTaskSnapshot(hippoRoot, resolveTenantId({}));
+            if (!activeForHandoff || activeForHandoff.session_id !== closeSessionId) {
+                appendSessionEndCloseLog(closeLogFile, 'skip: no active snapshot for session');
+            }
+            else {
+                const evidence = collectHandoffEvidence(process.cwd(), 'unknown');
+                const handoff = writeSessionEndHandoff(hippoRoot, resolveTenantId({}), closeSessionId, evidence);
+                appendSessionEndCloseLog(closeLogFile, handoff ? `wrote handoff for session ${closeSessionId}` : 'skip: handoff newer than snapshot');
+            }
+        }
+        catch (err) {
+            // SAFETY: catch clauses bind unknown, but Node/V8 always throws an Error here.
+            appendSessionEndCloseLog(closeLogFile, `handoff write failed: ${err.message}`);
+        }
+    }
     try {
         if (closeSessionId) {
             const closed = closeTaskSnapshotsForSession(hippoRoot, resolveTenantId({}), closeSessionId);
@@ -3753,17 +3784,17 @@ function cmdSession(hippoRoot, args, flags) {
         return;
     }
     if (subcommand === 'complete') {
-        const outcome = String(flags['outcome'] ?? '').trim();
+        const outcomeRaw = String(flags['outcome'] ?? '').trim();
         const summary = String(flags['summary'] ?? '').trim();
-        const validOutcomes = ['success', 'failure', 'partial'];
         if (!sessionId) {
             console.error('Usage: hippo session complete --session <session-id> --outcome <success|failure|partial> [--summary "..."]');
             process.exit(1);
         }
-        if (!validOutcomes.includes(outcome)) {
-            console.error(`Invalid outcome: "${outcome}". Must be one of: ${validOutcomes.join(', ')}.`);
+        if (!isHandoffOutcome(outcomeRaw)) {
+            console.error(`Invalid outcome: "${outcomeRaw}". Must be one of: success, failure, partial.`);
             process.exit(1);
         }
+        const outcome = outcomeRaw;
         const metadata = { ended_at: new Date().toISOString() };
         if (summary)
             metadata.summary = summary;
@@ -3776,6 +3807,10 @@ function cmdSession(hippoRoot, args, flags) {
             metadata,
         });
         console.log(`Completed session ${event.session_id} with outcome=${outcome} (event #${event.id})`);
+        const stamped = stampHandoffOutcome(hippoRoot, resolveTenantId({}), sessionId, outcome);
+        if (stamped > 0) {
+            console.log(`Stamped outcome on handoff for session ${sessionId}`);
+        }
         return;
     }
     if (subcommand === 'resume') {
@@ -3794,6 +3829,12 @@ function cmdSession(hippoRoot, args, flags) {
             lines.push(`- Task: ${handoff.taskId}`);
         if (handoff.repoRoot)
             lines.push(`- Repo: ${handoff.repoRoot}`);
+        if (handoff.outcome)
+            lines.push(`- Outcome: ${handoff.outcome}`);
+        if (handoff.targetRuntime)
+            lines.push(`- Target runtime: ${handoff.targetRuntime}`);
+        if (handoff.cardId)
+            lines.push(`- Card: ${handoff.cardId}`);
         lines.push('', '### Summary', handoff.summary);
         if (handoff.nextAction) {
             lines.push('', '### Next action', handoff.nextAction);
@@ -3804,6 +3845,15 @@ function cmdSession(hippoRoot, args, flags) {
                 lines.push(`- ${artifact}`);
             }
         }
+        if (handoff.constraints && handoff.constraints.length > 0) {
+            lines.push('', '### Constraints');
+            for (const constraint of handoff.constraints) {
+                lines.push(`- ${constraint}`);
+            }
+        }
+        if (handoff.evidence) {
+            lines.push('', '### Evidence', formatHandoffEvidenceLine(handoff.evidence));
+        }
         lines.push('');
         console.log(lines.join('\n'));
         return;
@@ -3819,6 +3869,12 @@ function printHandoff(handoff) {
         console.log(`- Task: ${handoff.taskId}`);
     if (handoff.repoRoot)
         console.log(`- Repo: ${handoff.repoRoot}`);
+    if (handoff.outcome)
+        console.log(`- Outcome: ${handoff.outcome}`);
+    if (handoff.targetRuntime)
+        console.log(`- Target runtime: ${handoff.targetRuntime}`);
+    if (handoff.cardId)
+        console.log(`- Card: ${handoff.cardId}`);
     console.log('');
     console.log('### Summary');
     console.log(handoff.summary);
@@ -3834,6 +3890,18 @@ function printHandoff(handoff) {
             console.log(`- ${artifact}`);
         }
     }
+    if (handoff.constraints && handoff.constraints.length > 0) {
+        console.log('');
+        console.log('### Constraints');
+        for (const constraint of handoff.constraints) {
+            console.log(`- ${constraint}`);
+        }
+    }
+    if (handoff.evidence) {
+        console.log('');
+        console.log('### Evidence');
+        console.log(formatHandoffEvidenceLine(handoff.evidence));
+    }
     console.log('');
 }
 function cmdHandoff(hippoRoot, args, flags) {
@@ -3842,7 +3910,12 @@ function cmdHandoff(hippoRoot, args, flags) {
     if (subcommand === 'create') {
         const summary = String(flags['summary'] ?? '').trim();
         if (!summary) {
-            console.error('Usage: hippo handoff create --summary "..." [--next "..."] [--session <id>] [--task <id>] [--artifact <path>...]');
+            console.error('Usage: hippo handoff create --summary "..." [--next "..."] [--session <id>] [--task <id>] [--artifact <path>...] [--constraint <text>...] [--outcome <success|failure|partial>] [--target-runtime <name>] [--card-id <id>] [--tests <pass|fail|unknown>]');
+            process.exit(1);
+        }
+        const outcomeRaw = flags['outcome'];
+        if (outcomeRaw !== undefined && !isHandoffOutcome(outcomeRaw)) {
+            console.error(`Invalid outcome: "${String(outcomeRaw)}". Must be one of: success, failure, partial.`);
             process.exit(1);
         }
         const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim() || `fallback-${Date.now()}-${process.pid}`;
@@ -3852,6 +3925,22 @@ function cmdHandoff(hippoRoot, args, flags) {
         const artifacts = Array.isArray(artifactFlag)
             ? artifactFlag
             : (typeof artifactFlag === 'string' ? [artifactFlag] : []);
+        const constraintFlag = flags['constraint'];
+        const isFlagString = (v) => typeof v === 'string';
+        const constraints = Array.isArray(constraintFlag)
+            ? constraintFlag
+            : (isFlagString(constraintFlag) ? [constraintFlag] : []);
+        for (const name of ['target-runtime', 'card-id']) {
+            // parseArgs turns a value-less flag into `true`; refuse rather than store "true".
+            if (flags[name] === true) {
+                console.error(`--${name} needs a value`);
+                process.exit(1);
+            }
+        }
+        const targetRuntime = String(flags['target-runtime'] ?? '').trim() || undefined;
+        const cardId = String(flags['card-id'] ?? '').trim() || undefined;
+        const testStatus = String(flags['tests'] ?? '').trim();
+        const evidence = collectHandoffEvidence(process.cwd(), testStatus === 'pass' || testStatus === 'fail' ? testStatus : 'unknown');
         const handoff = saveSessionHandoff(hippoRoot, resolveTenantId({}), {
             version: 1,
             sessionId,
@@ -3860,6 +3949,12 @@ function cmdHandoff(hippoRoot, args, flags) {
             summary,
             nextAction,
             artifacts,
+            constraints,
+            evidence,
+            // SAFETY: isHandoffOutcome above already refused any non-matching value.
+            outcome: outcomeRaw,
+            targetRuntime,
+            cardId,
         });
         console.log(`Created session handoff for session ${handoff.sessionId}`);
         console.log(`   Summary: ${handoff.summary}`);
@@ -3868,6 +3963,17 @@ function cmdHandoff(hippoRoot, args, flags) {
         if (handoff.artifacts && handoff.artifacts.length > 0) {
             console.log(`   Artifacts: ${handoff.artifacts.join(', ')}`);
         }
+        if (handoff.constraints && handoff.constraints.length > 0) {
+            console.log(`   Constraints: ${handoff.constraints.join(', ')}`);
+        }
+        if (handoff.outcome)
+            console.log(`   Outcome: ${handoff.outcome}`);
+        if (handoff.targetRuntime)
+            console.log(`   Target runtime: ${handoff.targetRuntime}`);
+        if (handoff.cardId)
+            console.log(`   Card: ${handoff.cardId}`);
+        if (handoff.evidence)
+            console.log(`   Evidence: ${formatHandoffEvidenceLine(handoff.evidence)}`);
         return;
     }
     if (subcommand === 'latest') {
@@ -3920,6 +4026,281 @@ 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.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.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();
+}
+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'],
+    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}`);
+        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);
+        }
+        let card;
+        try {
+            card = blockCard(hippoRoot, tenantId, id, reason);
+        }
+        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).`);
+            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>');
+            process.exit(1);
+        }
+        let card;
+        try {
+            card = reviewCard(hippoRoot, tenantId, id);
+        }
+        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).`);
+            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>');
+            process.exit(1);
+        }
+        let result;
+        try {
+            result = completeCard(hippoRoot, tenantId, id, outcomeRaw);
+        }
+        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).`);
+            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 === '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.
+        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|block|review|complete|comment>');
+    process.exit(1);
+}
 // ---------------------------------------------------------------------------
 // E2 prediction first-class object (v0.31)
 // docs/plans/2026-05-26-e2-prediction-object.md
@@ -7823,10 +8204,37 @@ Commands:
       --session <id>       Session ID (auto-generated if omitted)
       --task <id>          Associated task ID
       --artifact <path>    Related file path (repeatable)
+      --constraint <text>  Constraint for the successor to respect (repeatable)
+      --outcome <o>        success | failure | partial
+      --target-runtime <n> Name of the runtime the successor will run in
+      --card-id <id>       Associated card/ticket ID
+      --tests <status>     pass | fail | unknown (default: unknown)
     handoff latest         Show the most recent handoff
       --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
+      --runtime <name>       Claiming runtime (required)
+      --session <id>         Session ID
+    card block <id>           Block a running card
+      --reason "<why>"       Reason recorded as a card comment (required)
+    card review <id>          Move a running card to review
+    card complete <id>       Complete a card in review
+      --outcome <o>          success | failure | partial (required)
+    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
@@ -8051,6 +8459,10 @@ Examples:
   hippo session resume
   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 embed --status
   hippo watch "npm run build"
   hippo learn --git --days 30
@@ -8438,6 +8850,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;