cogmem 3.6.3 → 3.6.5

package/dist/bin/connect.js

@@ -90,22 +90,92 @@ function defaultSkillPath(agent, workspaceRoot) {
     return join(process.env.HOME || homedir(), '.hermes', 'skills', 'cogmem-memory', 'SKILL.md');
 }
 function nextCommands(agent) {
+    return nextSteps(agent)
+        .filter((step) => step.safeForAutomation && step.actor === 'agent')
+        .map((step) => step.command);
+}
+function nextSteps(agent) {
+    const project = agent === 'openclaw' ? 'openclaw' : 'hermes';
+    const importCommand = agent === 'openclaw' ? 'import-openclaw' : 'import-hermes';
+    const steps = [
+        {
+            id: 'doctor',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: './node_modules/.bin/cogmem doctor',
+            when: 'after installation or update',
+            purpose: 'verify package, config, and database access',
+        },
+        {
+            id: 'import_dry_run',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem ${importCommand} --workspace . --project ${project} --dry-run --json`,
+            when: 'before importing legacy memory',
+            purpose: 'preview source discovery and import counts',
+        },
+        {
+            id: 'import_apply',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem ${importCommand} --workspace . --project ${project} --json`,
+            when: 'after dry-run looks correct',
+            purpose: 'idempotently import legacy memory into Cogmem',
+        },
+        {
+            id: 'memory_plan',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem memory plan --project ${project} --json`,
+            when: 'after import, update, or user asks for governance progress',
+            purpose: 'read agent-safe next actions instead of guessing from raw counters',
+        },
+        {
+            id: 'memory_status',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: `./node_modules/.bin/cogmem memory status --project ${project} --json`,
+            when: 'for read-only health checks',
+            purpose: 'inspect raw ledger, vector fallback, dream backlog, and queue summary',
+        },
+        {
+            id: 'interactive_init',
+            actor: 'operator',
+            safeForAutomation: false,
+            command: `./node_modules/.bin/cogmem init --agent ${agent} --scope project`,
+            when: 'only if no Cogmem config exists and a human operator is present',
+            purpose: 'interactive first-time config wizard; agents must not run this unattended',
+        },
+    ];
     if (agent === 'openclaw') {
-        return [
-            './node_modules/.bin/cogmem-init --agent openclaw --scope project',
-            './node_modules/.bin/cogmem-doctor',
-            './node_modules/.bin/cogmem-import-openclaw --workspace . --project openclaw --dry-run',
-            './node_modules/.bin/cogmem-import-openclaw --workspace . --project openclaw',
-            './node_modules/.bin/cogmem-connect openclaw --workspace . --auto --force',
-        ];
+        steps.splice(1, 0, {
+            id: 'openclaw_diagnose',
+            actor: 'agent',
+            safeForAutomation: true,
+            command: './node_modules/.bin/cogmem openclaw diagnose --workspace . --json',
+            when: 'after connect --auto --force or before investigating injection failures',
+            purpose: 'verify generated plugin files, audit log, queue lock, and hook diagnostics',
+        });
+        steps.push({
+            id: 'restart_gateway',
+            actor: 'host',
+            safeForAutomation: false,
+            command: 'openclaw gateway restart',
+            when: 'after plugin files or OpenClaw config changed',
+            purpose: 'reload OpenClaw hooks so the refreshed Cogmem plugin is active',
+        });
     }
-    return [
-        './node_modules/.bin/cogmem-init --agent hermes',
-        './node_modules/.bin/cogmem-doctor',
-        './node_modules/.bin/cogmem-connect hermes --workspace . --auto --force',
-        './node_modules/.bin/cogmem-import-hermes --workspace . --project hermes --dry-run',
-        './node_modules/.bin/cogmem-import-hermes --workspace . --project hermes',
-    ];
+    else {
+        steps.push({
+            id: 'reload_hermes',
+            actor: 'host',
+            safeForAutomation: false,
+            command: 'restart or reload Hermes MCP server',
+            when: 'after Hermes MCP config changed',
+            purpose: 'reload the cogmem MCP server entry',
+        });
+    }
+    return steps;
 }
 function usage() {
     return [
@@ -138,33 +208,45 @@ function hostConfigSnippet(agent, workspaceRoot, auto) {
             '// Add host config only after installing a real OpenClaw plugin wrapper with a valid manifest/schema.',
         ].join('\n');
     }
-    const mcpBin = resolveCogmemMcpCommand(workspaceRoot);
+    const mcpServer = resolveCogmemMcpServer(workspaceRoot);
     return [
         'mcp_servers:',
         '  cogmem:',
-        `    command: "${mcpBin}"`,
-        '    args: []',
+        `    command: "${mcpServer.command}"`,
+        `    args: ${JSON.stringify(mcpServer.args)}`,
         '    enabled: true',
         '    tools:',
         '      include:',
         ...HERMES_COGMEM_TOOLS.map((tool) => `        - ${tool}`),
     ].join('\n');
 }
-function resolveCogmemMcpCommand(workspaceRoot) {
+function resolveCogmemMcpServer(workspaceRoot) {
     if (process.env.COGMEM_MCP_BIN)
-        return process.env.COGMEM_MCP_BIN;
-    const workspaceBin = join(workspaceRoot, 'node_modules', '.bin', 'cogmem-mcp');
-    if (existsSync(workspaceBin))
-        return workspaceBin;
+        return { command: process.env.COGMEM_MCP_BIN, args: [] };
+    if (process.env.COGMEM_BIN)
+        return { command: process.env.COGMEM_BIN, args: ['mcp'] };
+    const workspaceCli = join(workspaceRoot, 'node_modules', '.bin', 'cogmem');
+    if (existsSync(workspaceCli))
+        return { command: workspaceCli, args: ['mcp'] };
     const pathValue = process.env.PATH || '';
+    for (const segment of pathValue.split(':')) {
+        if (!segment)
+            continue;
+        const candidate = join(segment, 'cogmem');
+        if (existsSync(candidate))
+            return { command: candidate, args: ['mcp'] };
+    }
+    const workspaceMcp = join(workspaceRoot, 'node_modules', '.bin', 'cogmem-mcp');
+    if (existsSync(workspaceMcp))
+        return { command: workspaceMcp, args: [] };
     for (const segment of pathValue.split(':')) {
         if (!segment)
             continue;
         const candidate = join(segment, 'cogmem-mcp');
         if (existsSync(candidate))
-            return candidate;
+            return { command: candidate, args: [] };
     }
-    return 'cogmem-mcp';
+    return { command: 'cogmem', args: ['mcp'] };
 }
 function installSkill(args) {
     if (!args.agent)
@@ -227,6 +309,7 @@ function installSkill(args) {
         installed: !args.dryRun && !alreadyCurrent,
         alreadyCurrent,
         nextCommands: nextCommands(args.agent),
+        nextSteps: nextSteps(args.agent),
         hostConfigSnippet: hostConfigSnippet(args.agent, args.workspaceRoot, args.auto),
         autoMemory,
         hermesMcp,
@@ -237,9 +320,9 @@ function defaultHermesConfigPath(env = process.env) {
 }
 function installHermesMcpConfig(input) {
     const configPath = resolve(input.configPath || defaultHermesConfigPath());
-    const serverCommand = resolveCogmemMcpCommand(resolve(input.workspaceRoot));
+    const server = resolveCogmemMcpServer(resolve(input.workspaceRoot));
     const original = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
-    const patched = patchHermesMcpConfig(original, serverCommand);
+    const patched = patchHermesMcpConfig(original, server.command, server.args);
     const changed = patched !== original;
     let backupPath;
     if (!input.dryRun && (changed || input.force)) {
@@ -253,21 +336,22 @@ function installHermesMcpConfig(input) {
     return {
         enabled: true,
         configPath,
-        serverCommand,
+        serverCommand: server.command,
+        serverArgs: server.args,
         dryRun: input.dryRun,
         configUpdated: changed || input.force,
         backupPath,
     };
 }
-function patchHermesMcpConfig(original, serverCommand) {
-    if (/^\s+cogmem\s*:/m.test(original) && original.includes('cogmem-mcp')) {
+function patchHermesMcpConfig(original, serverCommand, serverArgs) {
+    if (/^\s+cogmem\s*:/m.test(original)) {
         return patchExistingHermesCogmemConfig(original);
     }
     const lines = original.replace(/\r\n/g, '\n').split('\n');
     const serverBlock = [
         '  cogmem:',
         `    command: "${serverCommand}"`,
-        '    args: []',
+        `    args: ${JSON.stringify(serverArgs)}`,
         '    enabled: true',
         '    tools:',
         '      include:',
@@ -366,7 +450,7 @@ function printHuman(result) {
         console.log('');
         console.log('Hermes MCP integration:');
         console.log(`  config: ${result.hermesMcp.configPath}`);
-        console.log(`  command: ${result.hermesMcp.serverCommand}`);
+        console.log(`  command: ${result.hermesMcp.serverCommand} ${result.hermesMcp.serverArgs.join(' ')}`.trimEnd());
         if (result.hermesMcp.backupPath)
             console.log(`  backup: ${result.hermesMcp.backupPath}`);
         console.log('  reload: /reload-mcp');

package/dist/bin/import-support.d.ts

@@ -22,6 +22,7 @@ export interface AgentImportResult {
     recordsIngested: number;
     skippedRecords: number;
     rawRecordsAnchored?: number;
+    emptyEpisodesSkipped?: number;
     reindexRaw?: boolean;
     processedSourceIds: string[];
     diagnostics: SourceAdapterDiagnostic[];

package/dist/bin/import-support.js

@@ -152,6 +152,7 @@ function previewSources(input) {
         recordsIngested: 0,
         skippedRecords: 0,
         rawRecordsAnchored: 0,
+        emptyEpisodesSkipped: 0,
         reindexRaw: false,
         processedSourceIds: [],
         diagnostics,
@@ -161,6 +162,7 @@ function previewSources(input) {
 async function importSources(input) {
     const opened = openKernel(input.args, input.workspaceRoot);
     const importedEpisodeIds = new Set();
+    let emptyEpisodesSkipped = 0;
     const processor = new InstalledBatchProcessor({
         cursorStore: opened.kernel.cursorStore,
         ingestBatch: async (items) => {
@@ -190,7 +192,7 @@ async function importSources(input) {
         for (const episodeId of importedEpisodeIds) {
             const episode = opened.kernel.getEpisode(episodeId);
             if (episode?.status !== 'sealed') {
-                opened.kernel.sealImportedEpisode(episodeId, { reason: `${input.agent}_import_batch_boundary` });
+                emptyEpisodesSkipped += sealImportedEpisodeIfReady(opened.kernel, episodeId, `${input.agent}_import_batch_boundary`) ? 0 : 1;
             }
         }
         return {
@@ -207,6 +209,7 @@ async function importSources(input) {
             recordsIngested: summary.recordsIngested,
             skippedRecords: summary.skippedRecords,
             rawRecordsAnchored: summary.recordsIngested,
+            emptyEpisodesSkipped,
             reindexRaw: false,
             processedSourceIds: summary.processedSourceIds,
             diagnostics: summary.adapterDiagnostics,
@@ -238,6 +241,7 @@ async function reindexRawSources(input) {
     let rawRecordsAnchored = 0;
     let skippedRecords = 0;
     const importedEpisodeIds = new Set();
+    let emptyEpisodesSkipped = 0;
     try {
         for (const source of input.sources) {
             const adapter = adapters.get(source.adapterKind);
@@ -279,7 +283,7 @@ async function reindexRawSources(input) {
         for (const episodeId of importedEpisodeIds) {
             const episode = opened.kernel.getEpisode(episodeId);
             if (episode?.status !== 'sealed') {
-                opened.kernel.sealImportedEpisode(episodeId, { reason: `${input.agent}_reindex_batch_boundary` });
+                emptyEpisodesSkipped += sealImportedEpisodeIfReady(opened.kernel, episodeId, `${input.agent}_reindex_batch_boundary`) ? 0 : 1;
             }
         }
         return {
@@ -297,6 +301,7 @@ async function reindexRawSources(input) {
             recordsIngested: rawRecordsAnchored,
             skippedRecords,
             rawRecordsAnchored,
+            emptyEpisodesSkipped,
             processedSourceIds,
             diagnostics,
             sourceResults,
@@ -307,6 +312,12 @@ async function reindexRawSources(input) {
         opened.kernel.close();
     }
 }
+function sealImportedEpisodeIfReady(kernel, episodeId, reason) {
+    if (kernel.listEpisodeEventLinks(episodeId).length === 0)
+        return false;
+    kernel.sealImportedEpisode(episodeId, { reason });
+    return true;
+}
 async function recordRawImportedEvidence(kernel, projectId, envelope) {
     const sourceRef = envelope.ingestInput.sourceRefs?.[0];
     const record = envelope.record;
@@ -483,6 +494,8 @@ function printHumanSummary(result) {
     console.log(`records ${action}: ${result.dryRun ? result.recordsWouldIngest : result.recordsIngested}`);
     if (result.rawRecordsAnchored !== undefined)
         console.log(`raw ledger anchors: ${result.rawRecordsAnchored}`);
+    if (result.emptyEpisodesSkipped)
+        console.log(`empty episodes skipped: ${result.emptyEpisodesSkipped}`);
     console.log(`records skipped: ${result.skippedRecords}`);
     if (result.diagnostics.length > 0) {
         console.log('diagnostics:');

package/dist/bin/mcp.js

@@ -29,7 +29,8 @@ function stringArg(values, key) {
 }
 function usage() {
     return [
-        'Usage: cogmem-mcp [--db <memory.db>|--config <config.toml>] [--cwd <dir>]',
+        'Usage: cogmem mcp [--db <memory.db>|--config <config.toml>] [--cwd <dir>]',
+        '       cogmem-mcp [--db <memory.db>|--config <config.toml>] [--cwd <dir>]',
         '',
         'Starts a stdio MCP server exposing recall, strategy, episode append/import/status/seal, conditional dream tick/status, memory map, maintenance, and prospective-memory tools.',
     ].join('\n');

package/dist/bin/memory.js

@@ -55,6 +55,8 @@ function readArgs(argv) {
         before: numberArg(values, 'before'),
         after: numberArg(values, 'after'),
         sinceGlobalSeq: numberArg(values, 'since') ?? numberArg(values, 'since-global-seq'),
+        untilGlobalSeq: numberArg(values, 'until') ?? numberArg(values, 'until-global-seq'),
+        order: orderArg(values, 'order'),
         intervalMs: numberArg(values, 'interval-ms'),
         maxRuns: numberArg(values, 'max-runs'),
         promoteLimit: numberArg(values, 'promote-limit'),
@@ -75,6 +77,7 @@ function usage() {
         '',
         'Commands:',
         '  status               summarize raw ledger, vector, and dream backlog state',
+        '  plan                 summarize status as agent-safe next actions',
         '  list                 list raw ledger events with source anchors',
         '  search --query <q>   search raw ledger text without requiring hot vectors',
         '  recall --query <q>   run agent-facing governed recall with source context',
@@ -101,7 +104,9 @@ function usage() {
         '  --thread <id>        scope to one thread',
         '  --session <id>       scope to one session',
         '  --limit <n>          result limit, default 20',
-        '  --since <globalSeq>  for bind, scan raw events at or after a global sequence',
+        '  --since <globalSeq>  list/bind events at or after a global sequence',
+        '  --until <globalSeq>  list events at or before a global sequence',
+        '  --order <asc|desc>   list raw ledger order, default desc',
         '  --status <status>    candidate queue status, default candidate',
         '  --id <candidate>     candidate id for review',
         '  --action <action>    review action: approve, reject, defer, supersede, or relink',
@@ -117,7 +122,7 @@ function usage() {
         '  --interval-ms <n>    watch sleep interval, default 300000',
         '  --max-runs <n>       stop watch after n iterations; omit for long-running worker',
         '  --agent <id>         agent id for governed recall, default openclaw',
-        '  --intent <intent>    memory_recall, previous_session_summary, or forensic_quote',
+        '  --intent <intent>    memory_recall, previous_session_summary, forensic_quote, or historical_discussion',
         '  --db <memory.db>     open an explicit database path',
         '  --config <toml>      open a cogmem TOML config',
         '  --include-evidence   include bounded raw excerpts; event ids are always returned',
@@ -135,6 +140,7 @@ function usage() {
 }
 function isMemoryCommand(value) {
     return value === 'status'
+        || value === 'plan'
         || value === 'list'
         || value === 'search'
         || value === 'recall'
@@ -166,9 +172,17 @@ function recallIntentArg(values, key) {
     const raw = stringArg(values, key);
     if (!raw)
         return undefined;
-    if (raw === 'memory_recall' || raw === 'previous_session_summary' || raw === 'forensic_quote')
+    if (raw === 'memory_recall' || raw === 'previous_session_summary' || raw === 'forensic_quote' || raw === 'historical_discussion')
         return raw;
-    throw new Error(`--${key} must be one of memory_recall, previous_session_summary, forensic_quote`);
+    throw new Error(`--${key} must be one of memory_recall, previous_session_summary, forensic_quote, historical_discussion`);
+}
+function orderArg(values, key) {
+    const raw = stringArg(values, key);
+    if (!raw)
+        return undefined;
+    if (raw === 'asc' || raw === 'desc')
+        return raw;
+    throw new Error(`--${key} must be one of asc, desc`);
 }
 function stringArg(values, key) {
     const value = values[key];
@@ -219,30 +233,32 @@ function inspectionDbPath(args) {
 function runReadOnlyInspection(args) {
     const inspection = new MemoryInspectionStore(inspectionDbPath(args));
     try {
-        if (args.command === 'status') {
+        if (args.command === 'status' || args.command === 'plan') {
             const payload = inspection.status({
                 projectId: args.projectId, workspaceId: args.workspaceId,
                 threadId: args.threadId, sessionId: args.sessionId,
             });
+            const queueSummary = buildCandidateQueueSummary(inspection, args.projectId, args.limit || 5000);
+            const plan = buildMemoryPlan(payload, queueSummary, args.projectId);
+            const enrichedPayload = args.command === 'plan'
+                ? plan
+                : { ...payload, queueSummary, nextActions: plan.nextActions, blocking: plan.blocking, nonBlocking: plan.nonBlocking };
             if (args.json) {
-                printCliJson('memory.status', payload, {
+                printCliJson(`memory.${args.command}`, enrichedPayload, {
                     queue: payload.dreamCandidateQueue,
                     beliefs: payload.activeBeliefs,
                 });
             }
             else
-                printHuman('status', payload);
+                printHuman(args.command, enrichedPayload);
             return;
         }
-        const status = args.status || 'candidate';
-        const candidates = inspection.listCandidates({
-            projectId: args.projectId,
-            status,
-            limit: args.limit || 50,
-        });
-        const payload = { total: candidates.length, status, candidates: candidates.map(candidateToJson) };
+        const queueSummary = buildCandidateQueueSummary(inspection, args.projectId, args.limit || 50);
+        const payload = args.status
+            ? buildSpecificCandidatePayload(inspection, args.projectId, args.status, args.limit || 50, queueSummary)
+            : buildGroupedCandidatePayload(queueSummary);
         if (args.json)
-            printCliJson('memory.candidates', payload);
+            printCliJson('memory.candidates', payload, { queue: queueSummary });
         else
             printHuman('candidates', payload);
     }
@@ -262,6 +278,7 @@ function eventText(event) {
 }
 function eventToJson(event) {
     const text = eventText(event);
+    const locator = eventSourceLocator(event, 2, 2);
     return {
         eventId: event.eventId,
         label: memoryEventLabel(event),
@@ -294,6 +311,21 @@ function eventToJson(event) {
             causalityType: event.causalityType,
             orderingConfidence: event.orderingConfidence,
         },
+        sourceLocator: locator,
+    };
+}
+function eventSourceLocator(event, before, after) {
+    const projectArg = event.projectId ? ` --project ${cliArg(event.projectId)}` : '';
+    const base = `cogmem memory show --event ${cliArg(event.eventId)}${projectArg}`;
+    return {
+        eventId: event.eventId,
+        globalSeq: event.globalSeq,
+        projectId: event.projectId,
+        threadId: event.threadId,
+        sessionId: event.sessionId,
+        localDate: event.localDate,
+        command: `${base} --before ${before} --after ${after} --json`,
+        contextCommand: `${base} --before 3 --after 3 --json`,
     };
 }
 function candidateToJson(candidate) {
@@ -313,6 +345,141 @@ function candidateToJson(candidate) {
         updatedAt: candidate.updatedAt,
     };
 }
+function buildCandidateQueueSummary(inspection, projectId, limit) {
+    const status = inspection.status({ projectId });
+    const queue = status.dreamCandidateQueue;
+    const candidateRows = inspection.listCandidates({ projectId, status: 'candidate', limit });
+    const needsRows = inspection.listCandidates({ projectId, status: 'needs_confirmation', limit: Math.max(limit, 5000) });
+    const now = Date.now();
+    const deferredRows = needsRows.filter((candidate) => candidate.reviewAfter !== undefined && candidate.reviewAfter > now);
+    const activeNeedsRows = needsRows.filter((candidate) => !(candidate.reviewAfter !== undefined && candidate.reviewAfter > now));
+    return {
+        candidate: queue.candidate,
+        needs_confirmation: queue.needsConfirmation,
+        activeNeedsConfirmation: Math.max(0, queue.needsConfirmation - deferredRows.length),
+        deferredNeedsConfirmation: deferredRows.length,
+        promoted: queue.promoted,
+        rejected: queue.rejected,
+        superseded: queue.superseded,
+        shadow: queue.shadow,
+        groups: {
+            candidate: candidateRows.slice(0, limit).map(candidateToJson),
+            needs_confirmation: activeNeedsRows.slice(0, limit).map(candidateToJson),
+            deferred: deferredRows.slice(0, limit).map(candidateToJson),
+        },
+    };
+}
+function buildSpecificCandidatePayload(inspection, projectId, status, limit, queueSummary) {
+    const candidates = inspection.listCandidates({ projectId, status, limit });
+    const payload = {
+        total: candidates.length,
+        status,
+        candidates: candidates.map(candidateToJson),
+        queueSummary,
+    };
+    if (status === 'candidate') {
+        payload.warning = 'This lists only status=candidate. Use memory candidates without --status for grouped candidate and needs_confirmation queues.';
+    }
+    else if (status === 'needs_confirmation') {
+        payload.warning = 'memory govern does not process needs_confirmation. Use memory review with explicit user evidence, or defer with review_after.';
+    }
+    return payload;
+}
+function buildGroupedCandidatePayload(queueSummary) {
+    return {
+        total: queueSummary.groups.candidate.length + queueSummary.groups.needs_confirmation.length + queueSummary.groups.deferred.length,
+        status: 'grouped',
+        queueSummary,
+        groups: queueSummary.groups,
+        nextActions: candidateNextActions(queueSummary, undefined),
+    };
+}
+function buildMemoryPlan(status, queueSummary, projectId) {
+    const nextActions = [];
+    const blocking = [];
+    const nonBlocking = [];
+    const projectArg = projectId ? ` --project ${cliArg(projectId)}` : '';
+    const episodeDream = status.episodeDream;
+    const pendingEpisodes = asCount(episodeDream.pending) + asCount(episodeDream.retryScheduled);
+    const undreamedRawCount = asCount(status.undreamedRawCount);
+    if (pendingEpisodes > 0) {
+        nextActions.push({
+            priority: 'high',
+            type: 'dream_tick',
+            safeForAutomation: true,
+            reason: `${pendingEpisodes} sealed episode Dream jobs can be processed`,
+            command: `cogmem dream tick${projectArg} --mode auto --max-episodes 20 --json`,
+        });
+    }
+    if (undreamedRawCount > 0) {
+        nonBlocking.push({
+            type: 'raw_dream_ledger_lag',
+            count: undreamedRawCount,
+            episodeDreamPending: pendingEpisodes,
+            resolvableByDreamTick: false,
+            safeForAutomation: false,
+            reason: pendingEpisodes > 0
+                ? 'Raw ledger dream coverage is tracked separately from sealed episode Dream jobs; dream tick may process episodes but does not guarantee this counter will clear.'
+                : 'Raw ledger dream coverage is behind, but there are no sealed episode Dream jobs. Do not run dream tick for this signal alone.',
+            command: `cogmem memory list${projectArg} --order asc --limit 20 --json`,
+        });
+    }
+    nextActions.push(...candidateNextActions(queueSummary, projectId));
+    if (queueSummary.activeNeedsConfirmation > 0) {
+        blocking.push({
+            type: 'needs_confirmation',
+            count: queueSummary.activeNeedsConfirmation,
+            reason: 'Manual review requires explicit user evidence; memory govern will not process these candidates.',
+            command: `cogmem memory candidates${projectArg} --status needs_confirmation --json`,
+        });
+    }
+    if (queueSummary.deferredNeedsConfirmation > 0) {
+        nonBlocking.push({
+            type: 'deferred_confirmation',
+            count: queueSummary.deferredNeedsConfirmation,
+            reason: 'Deferred needs_confirmation remains in the review queue until review_after.',
+            command: `cogmem memory candidates${projectArg} --json`,
+        });
+    }
+    return {
+        healthy: nextActions.length === 0 && blocking.length === 0,
+        projectId,
+        queueSummary,
+        dreamBacklog: status.dreamBacklog,
+        episodeDream: status.episodeDream,
+        vectorState: status.vectorState,
+        nextActions,
+        blocking,
+        nonBlocking,
+    };
+}
+function candidateNextActions(queueSummary, projectId) {
+    const projectArg = projectId ? ` --project ${cliArg(projectId)}` : '';
+    const actions = [];
+    if (queueSummary.candidate > 0) {
+        actions.push({
+            priority: 'high',
+            type: 'govern',
+            safeForAutomation: true,
+            reason: `${queueSummary.candidate} ordinary candidates are ready for deterministic governance`,
+            command: `cogmem memory govern${projectArg} --limit 100 --json`,
+        });
+    }
+    if (queueSummary.activeNeedsConfirmation > 0) {
+        actions.push({
+            priority: 'medium',
+            type: 'review_needs_confirmation',
+            safeForAutomation: false,
+            reason: `${queueSummary.activeNeedsConfirmation} candidates need explicit operator/user confirmation`,
+            command: `cogmem memory candidates${projectArg} --status needs_confirmation --json`,
+            reviewCommand: `cogmem memory review${projectArg} --id <candidate-id> --action <approve|reject|defer|supersede|relink> --actor <operator> --reason <reason> --json`,
+        });
+    }
+    return actions;
+}
+function asCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
 function runStatus(kernel, args) {
     const page = kernel.eventStore.queryEvents(1, 1, {
         projectId: args.projectId ? [args.projectId] : undefined,
@@ -344,9 +511,15 @@ function runList(kernel, args) {
         workspaceId: args.workspaceId ? [args.workspaceId] : undefined,
         threadId: args.threadId ? [args.threadId] : undefined,
         sessionId: args.sessionId ? [args.sessionId] : undefined,
+        sinceGlobalSeq: args.sinceGlobalSeq,
+        untilGlobalSeq: args.untilGlobalSeq,
+        order: args.order,
     });
     return {
         total: page.total,
+        sinceGlobalSeq: args.sinceGlobalSeq,
+        untilGlobalSeq: args.untilGlobalSeq,
+        order: args.order || 'desc',
         events: page.records.map(eventToJson),
     };
 }
@@ -607,12 +780,24 @@ function runCandidates(kernel, args) {
     };
 }
 function printHuman(command, payload) {
-    if (command === 'status') {
+    if (command === 'status' || command === 'plan') {
+        if (command === 'plan') {
+            console.log(`healthy: ${payload.healthy}`);
+            console.log(`queueSummary: ${JSON.stringify(payload.queueSummary)}`);
+            console.log(`nextActions: ${JSON.stringify(payload.nextActions)}`);
+            console.log(`blocking: ${JSON.stringify(payload.blocking)}`);
+            console.log(`nonBlocking: ${JSON.stringify(payload.nonBlocking)}`);
+            return;
+        }
         console.log(`rawEvents: ${payload.rawEventCount}`);
         console.log(`vectors: ${payload.vectorCount}`);
         console.log(`dreamBacklog: ${JSON.stringify(payload.dreamBacklog)}`);
         console.log(`episodeDream: ${JSON.stringify(payload.episodeDream)}`);
         console.log(`dreamCandidateQueue: ${JSON.stringify(payload.dreamCandidateQueue)}`);
+        if (payload.queueSummary)
+            console.log(`queueSummary: ${JSON.stringify(payload.queueSummary)}`);
+        if (payload.nextActions)
+            console.log(`nextActions: ${JSON.stringify(payload.nextActions)}`);
         return;
     }
     if (command === 'dream') {
@@ -646,6 +831,18 @@ function printHuman(command, payload) {
         return;
     }
     if (command === 'candidates') {
+        if (payload.queueSummary)
+            console.log(`queueSummary: ${JSON.stringify(payload.queueSummary)}`);
+        const groups = payload.groups;
+        if (groups) {
+            for (const [group, values] of Object.entries(groups)) {
+                console.log(`${group}: ${values.length}`);
+                for (const candidate of values) {
+                    console.log(`- ${candidate.candidateId} ${candidate.candidateType} ${candidate.status} confidence=${candidate.confidence}`);
+                }
+            }
+            return;
+        }
         const candidates = Array.isArray(payload.candidates) ? payload.candidates : [];
         for (const candidate of candidates) {
             console.log(`- ${candidate.candidateId} ${candidate.candidateType} ${candidate.status} confidence=${candidate.confidence}`);
@@ -741,7 +938,7 @@ async function main() {
         console.log(usage());
         return;
     }
-    if (args.command === 'status' || args.command === 'candidates') {
+    if (args.command === 'status' || args.command === 'plan' || args.command === 'candidates') {
         runReadOnlyInspection(args);
         return;
     }
@@ -801,3 +998,6 @@ main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
 });
+function cliArg(value) {
+    return /^[A-Za-z0-9._:/=@+-]+$/u.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}