brainclaw 0.28.0 → 1.5.3

package/dist/cli.js

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import { runInit } from './commands/init.js';
 import { runSetup } from './commands/setup.js';
 import { runUpgrade } from './commands/upgrade.js';
+import { patchAllMcpConfigs } from './core/agent-files.js';
 import { runReconcile } from './commands/reconcile.js';
 import { getMemoryLog, rollbackMemory, hasMemoryRepo } from './core/memory-git.js';
 import { buildMachineProfile, saveMachineProfile, loadMachineProfile, renderMachineProfileSummary } from './core/machine-profile.js';
@@ -18,7 +19,10 @@ import { runListPlans } from './commands/list-plans.js';
 import { runUpdatePlan } from './commands/update-plan.js';
 import { runDeletePlan } from './commands/delete-plan.js';
 import { runPlanResource } from './commands/plan-resource.js';
+import { runSequenceResource } from './commands/sequence.js';
 import { runAddStep } from './commands/add-step.js';
+import { runDeleteStep } from './commands/delete-step.js';
+import { runUpdateStep } from './commands/update-step.js';
 import { runEstimationReport } from './commands/estimation-report.js';
 import { runCompleteStep } from './commands/complete-step.js';
 import { runUpdateHandoff } from './commands/update-handoff.js';
@@ -27,6 +31,8 @@ import { runListAgents } from './commands/list-agents.js';
 import { runSurfaceTaskResource } from './commands/surface-task-resource.js';
 import { runListInstructions } from './commands/list-instructions.js';
 import { runDoctor } from './commands/doctor.js';
+import { runRepair } from './commands/repair.js';
+import { runStale } from './commands/stale.js';
 import { runRebuild } from './commands/rebuild.js';
 import { runReflect } from './commands/reflect.js';
 import { runReflectRuntimeNote } from './commands/reflect-runtime-note.js';
@@ -37,6 +43,7 @@ import { runUseCandidate } from './commands/use-candidate.js';
 import { runAccept } from './commands/accept.js';
 import { runReject } from './commands/reject.js';
 import { runPruneCandidates } from './commands/prune-candidates.js';
+import { cleanupStaleCandidates } from './core/candidates.js';
 import { runListClaims } from './commands/list-claims.js';
 import { runReleaseClaim } from './commands/release-claim.js';
 import { runClaimResource } from './commands/claim-resource.js';
@@ -52,9 +59,13 @@ import { runEnv } from './commands/env.js';
 import { runAdapterOpenclawImport } from './commands/adapter-openclaw-import.js';
 import { runInstallHooks } from './commands/install-hooks.js';
 import { runCheckConstraints } from './commands/check-constraints.js';
+import { runCheckPolicy } from './commands/check-policy.js';
+import { runCheckSecurity } from './commands/check-security.js';
+import { runSetupSecurity } from './commands/setup-security.js';
 import { runRegisterAgent } from './commands/register-agent.js';
 import { runEnableAgent } from './commands/enable-agent.js';
 import { runVersion } from './commands/version.js';
+import { runReleaseNotes } from './commands/release-notes.js';
 import { runDiff } from './commands/changes.js';
 import { runPrune } from './commands/prune.js';
 import { runMcp } from './commands/mcp.js';
@@ -62,10 +73,13 @@ import { runSetTrust } from './commands/set-trust.js';
 import { runSessionStart } from './commands/session-start.js';
 import { runSessionEnd } from './commands/session-end.js';
 import { runWhoami } from './commands/whoami.js';
+import { runUsage } from './commands/usage.js';
 import { runSearch } from './commands/search.js';
-import { runExport } from './commands/export.js';
+import { runExport, runRefresh } from './commands/export.js';
 import { runHooks } from './commands/hooks.js';
 import { runWatch } from './commands/watch.js';
+import { runDispatchAnalysis, runDispatch, runDispatchReview } from './commands/dispatch.js';
+import { runInboxList, runInboxAck, runInboxArchive, runInboxSend, runInboxThread } from './commands/inbox.js';
 import { runMetrics } from './commands/metrics.js';
 import { runRollback } from './commands/rollback.js';
 import { runPull } from './commands/pull.js';
@@ -74,20 +88,30 @@ import { runAuditCommand } from './commands/audit.js';
 import { runHistory } from './commands/history.js';
 import { runContextDiff } from './commands/context-diff.js';
 import { runCapability } from './commands/capability.js';
+import { runLink } from './commands/link.js';
 import { runTool } from './commands/tool.js';
 import { runExplore } from './commands/explore.js';
 import { getInstalledBrainclawVersion } from './core/brainclaw-version.js';
-import { cleanOrphanFiles, memoryDir } from './core/io.js';
+import { cleanOrphanFiles, memoryDir, memoryExists } from './core/io.js';
 import { initLogLevel, logger } from './core/logger.js';
 import { resolveEffectiveCwd } from './core/store-resolution.js';
+import { resolveProjectCwd } from './core/cross-project.js';
 import { runSwitch } from './commands/switch.js';
+import { runWorktreeCreate, runWorktreeList, runWorktreeRemove, runWorktreePrune, runWorktreeClean, runWorktreeMerge } from './commands/worktree.js';
 import { runCheckEvents } from './commands/check-events.js';
 import { runDiscover } from './commands/discover.js';
 import { runMigrate } from './commands/migrate.js';
+import { runRunProfile } from './commands/run-profile.js';
+import { runCompact } from './commands/compact.js';
+import { runHarvestCandidates } from './commands/harvest.js';
+import { requireRegisteredAgentIdentity } from './core/agent-registry.js';
 const program = new Command();
 function collect(value, previous) {
     return [...previous, value];
 }
+function isCodevEnabled() {
+    return process.env.BRAINCLAW_ENABLE_CODEV === '1';
+}
 program
     .name('brainclaw')
     .description('Shared project memory for humans and coding agents.')
@@ -95,15 +119,33 @@ program
     .option('--verbose', 'Show info-level log messages on stderr')
     .option('--debug', 'Show debug-level log messages on stderr')
     .option('--cwd <path>', 'Override working directory for this invocation')
+    .option('--project <name>', 'Run the command against a linked project (cross_project_links or workspace store-chain child). Resolves via resolveProjectCwd; mutually exclusive with --cwd.')
     .hook('preAction', (_thisCommand, actionCommand) => {
     const root = actionCommand.optsWithGlobals();
     initLogLevel({ verbose: root.verbose, debug: root.debug });
     // Skip effective cwd resolution for commands that create the store
     const cmdName = actionCommand.name();
     const skipResolution = cmdName === 'init' || cmdName === 'setup';
+    // pln#359 phase 1c — `--project <name>` resolves a linked project to an
+    // absolute path via resolveProjectCwd, then feeds the same chdir flow
+    // as --cwd. Mutually exclusive with --cwd to avoid ambiguity.
+    let explicitCwd = root.cwd;
+    if (root.project) {
+        if (root.cwd) {
+            console.error('Error: --project and --cwd are mutually exclusive. Use one.');
+            process.exit(1);
+        }
+        try {
+            explicitCwd = resolveProjectCwd(root.project, process.cwd());
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+    }
     if (!skipResolution) {
-        // Resolve effective cwd (--cwd > BRAINCLAW_PROJECT > active-project > process.cwd)
-        const effectiveCwd = resolveEffectiveCwd({ explicitCwd: root.cwd });
+        // Resolve effective cwd (explicit > BRAINCLAW_PROJECT > active-project > process.cwd)
+        const effectiveCwd = resolveEffectiveCwd({ explicitCwd });
         if (effectiveCwd !== process.cwd()) {
             // Change process.cwd() so all commands resolve the correct store
             // without needing individual --cwd plumbing
@@ -115,9 +157,9 @@ program
             logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir()}`);
         }
     }
-    else if (root.cwd) {
-        // For init/setup, still respect explicit --cwd but nothing else
-        process.chdir(path.resolve(root.cwd));
+    else if (explicitCwd) {
+        // For init/setup, still respect explicit --cwd / --project but nothing else
+        process.chdir(path.resolve(explicitCwd));
     }
 });
 // --- init ---
@@ -131,6 +173,7 @@ program
     .option('--project-mode <mode>', 'Project mode: single-project, multi-project, auto')
     .option('--project-strategy <strategy>', 'Project strategy for multi-project mode: manual, folder')
     .option('--no-analyze-repo', 'Skip repository analysis when suggesting a project mode')
+    .option('--no-ai-scan', 'Skip AI surface scan during init')
     .option('--scan', 'Scan subdirectories for service boundaries and suggest init targets')
     .action(async (options) => {
     await runInit(options);
@@ -165,15 +208,34 @@ program
 // --- memory-rollback ---
 program
     .command('memory-rollback <ref>')
-    .description('Rollback entire memory to a previous git snapshot (use memory-log to find refs)')
-    .action((ref) => {
+    .description('Restore live project memory from a previous git snapshot without deleting audit or archive artifacts')
+    .option('--actor <name>', 'Registered human identity required to authorize the rollback')
+    .action((ref, options) => {
+    const cwd = process.cwd();
     if (!hasMemoryRepo()) {
         console.error('Error: no memory git repo. Run `brainclaw init --force` to enable.');
         process.exit(1);
     }
-    const success = rollbackMemory(ref);
+    let actor;
+    try {
+        actor = requireRegisteredAgentIdentity({
+            agentName: options.actor,
+            allowCurrent: true,
+            allowEnv: true,
+            cwd,
+        });
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    if (actor.kind !== 'human') {
+        console.error(`Error: memory-rollback is reserved to registered human identities. Resolved actor '${actor.agent_name}' is kind='${actor.kind}'.`);
+        process.exit(1);
+    }
+    const success = rollbackMemory(ref, cwd);
     if (success) {
-        console.log(`✔ Memory rolled back to ${ref}`);
+        console.log(`✔ Live project memory restored to ${ref} (audit, archives, backups preserved)`);
     }
     else {
         console.error(`Error: failed to rollback to '${ref}'. Check memory-log for valid refs.`);
@@ -186,12 +248,45 @@ program
     .description('Upgrade project memory structure and refresh managed workspace agent files without losing data')
     .option('--json', 'Output as JSON')
     .option('--dry-run', 'Show what would be done without making changes')
+    .option('--self-update', 'Check for a newer brainclaw package version and install it before upgrading memory')
+    .option('--to <version>', 'One-shot target schema version (e.g. --to=1.0). Real runs require a backup.')
+    .option('--backup', 'Create a timestamped backup of .brainclaw/ before any write (always on for --to runs)')
+    .option('--no-backup', 'Disable the automatic backup for housekeeping-only upgrade runs')
+    .option('--rollback', 'Restore the most recent backup, park the current live store, exit')
+    .option('--yes', 'Skip interactive confirmations (reserved for later prompt additions)')
     .action((options) => {
     runUpgrade({
         json: options.json,
         dryRun: options.dryRun,
+        selfUpdate: options.selfUpdate,
+        to: options.to,
+        backup: options.backup,
+        rollback: options.rollback,
+        yes: options.yes,
     });
 });
+// --- patch-configs ---
+program
+    .command('patch-configs')
+    .description('Patch all MCP config files to use the current brainclaw binary path')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    const cwd = process.env.BRAINCLAW_CWD ?? process.cwd();
+    const results = patchAllMcpConfigs(cwd);
+    if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+    }
+    else if (results.length === 0) {
+        console.log('✔ All MCP configs are already up to date.');
+    }
+    else {
+        for (const r of results) {
+            const tag = r.created ? 'created' : 'updated';
+            console.log(`✔ ${r.filePath} (${tag}) — ${r.label}`);
+        }
+        console.log(`\n${results.length} MCP config(s) patched.`);
+    }
+});
 // --- machine-profile ---
 program
     .command('machine-profile')
@@ -346,6 +441,11 @@ program
     .option('--plan <id>', 'Optional linked plan item ID')
     .option('--author <author>', 'Author name')
     .option('--capture-diff', 'Capture current git diff into the handoff snapshot')
+    .option('--files <files...>', 'Files touched in this handoff')
+    .option('--pre-condition <conditions...>', 'Pre-conditions for the receiving agent')
+    .option('--post-condition <conditions...>', 'Post-conditions the receiving agent must satisfy')
+    .option('--test <tests...>', 'Tests the receiving agent should verify')
+    .option('--linked-plan <plans...>', 'Linked plan IDs')
     .action((text, options) => {
     runHandoff(text, options);
 });
@@ -376,8 +476,10 @@ program
     .option('--estimate <minutes>', 'Estimated effort in minutes (positive integer, e.g. --estimate 30)')
     .option('--actual-effort <effort>', 'Actual effort spent (e.g. "20min", "1h30m")')
     .option('--store <target>', 'Target store level: local (default), repo, workspace, user')
+    .option('--recursive', 'Include plans from descendant brainclaw projects (for list)')
+    .option('--local-only', 'Read from local store only for list (skip parent stores in chain)')
     .action((subcommand, args, options) => {
-    runPlanResource(subcommand, args, { ...options, actualEffort: options.actualEffort });
+    runPlanResource(subcommand, args, { ...options, actualEffort: options.actualEffort, localOnly: options.localOnly });
 });
 // --- list-plans ---
 program
@@ -389,8 +491,24 @@ program
     .option('--assignee <assignee>', 'Filter by assignee')
     .option('--project <project>', 'Filter by project namespace')
     .option('--all', 'Include done and dropped plan items')
+    .option('--recursive', 'Include plans from descendant brainclaw projects')
+    .option('--local-only', 'Read from local store only (skip parent stores in chain)')
     .action((options) => {
-    runListPlans(options);
+    runListPlans({ ...options, localOnly: options.localOnly });
+});
+program
+    .command('sequence <subcommand> [args...]')
+    .description('Manage coordination sequences (create, list, show, update)')
+    .option('--json', 'Output as JSON')
+    .option('--description <text>', 'Optional sequence description')
+    .option('--status <status>', 'Sequence status: draft, active, archived')
+    .option('--owner <owner>', 'Optional sequence owner')
+    .option('--items <json>', 'Sequence items JSON array')
+    .option('--name <name>', 'Optional sequence name for update')
+    .option('--tag <tags...>', 'Tags for this sequence')
+    .option('--author <author>', 'Author name')
+    .action((subcommand, args, options) => {
+    runSequenceResource(subcommand, args, options);
 });
 // --- add-step ---
 program
@@ -407,6 +525,23 @@ program
     .action((planId, stepId) => {
     runCompleteStep(planId, stepId);
 });
+// --- update-step ---
+program
+    .command('update-step <planId> <stepId>')
+    .description('Update a plan step (status, text, assignee)')
+    .option('--status <status>', 'New status: todo, in_progress, testing, done, blocked')
+    .option('--text <text>', 'Replace step description')
+    .option('--assign <assignee>', 'Assign the step (empty string to unassign)')
+    .action((planId, stepId, options) => {
+    runUpdateStep(planId, stepId, options);
+});
+// --- delete-step ---
+program
+    .command('delete-step <planId> <stepId>')
+    .description('Remove a step from a plan')
+    .action((planId, stepId) => {
+    runDeleteStep(planId, stepId);
+});
 // --- estimation-report ---
 program
     .command('estimation-report')
@@ -460,11 +595,25 @@ program
 // --- update-handoff ---
 program
     .command('update-handoff <id>')
-    .description('Update the status of a handoff')
+    .description('Update the status, recipient, or review state of a handoff')
     .option('--status <status>', 'Status: open, accepted, closed')
     .option('--to <agent>', 'Change the receiving agent')
+    .option('--narrative <text>', 'Update the narrative attached to the handoff')
+    .option('--reviewer <agent>', 'Set or override the assigned reviewer')
+    .option('--review-verdict <verdict>', 'Set review verdict: approve or request_changes')
+    .option('--reviewed-by <agent>', 'Set the reviewer identity that produced the verdict')
+    .option('--review-summary <text>', 'Attach a short review summary')
+    .option('--blocking-issue <text>', 'Add a blocking review issue (repeatable)', collect, [])
+    .option('--suggestion <text>', 'Add a non-blocking review suggestion (repeatable)', collect, [])
     .action((id, options) => {
-    runUpdateHandoff(id, options);
+    runUpdateHandoff(id, {
+        ...options,
+        review_verdict: options.reviewVerdict,
+        reviewed_by: options.reviewedBy,
+        review_summary: options.reviewSummary,
+        blocking_issues: options.blockingIssue,
+        suggestions: options.suggestion,
+    });
 });
 // --- doctor ---
 program
@@ -473,8 +622,34 @@ program
     .option('--json', 'Output as JSON dashboard')
     .option('--migration-check', 'Report versioned documents that need schema migration')
     .option('--fix-agent-ignore', 'Add missing .gitignore entries for generated local Brainclaw agent files')
+    .option('--fix', 'Fix auto-resolvable issues (e.g. drifting MCP configs)')
+    .option('--repair', 'Rebuild dist/ when the MCP runtime is missing or stale')
+    .option('--after-migration', 'Run the v1.0 post-migration health check only (exits non-zero on any failure)')
+    .option('--dispatch', 'Run dispatch-health diagnostic only: reconcile open agent_runs and report stuck/unverified/silent failures (pln#496 step stp_8c072d75)')
+    .action((options) => {
+    runDoctor({ ...options, afterMigration: options.afterMigration, dispatch: options.dispatch });
+});
+// --- repair (Phase 4 Sprint 2 Lane C / pln#397) ---
+program
+    .command('repair')
+    .description('Apply safe, non-destructive fixes for the repair candidates surfaced by doctor')
+    .option('--dry-run', 'Print the plan without executing anything')
+    .option('--include-unsafe', 'Also apply candidates flagged unsafe (preserves data but requires confirmation)')
+    .option('--json', 'Output as JSON')
     .action((options) => {
-    runDoctor(options);
+    runRepair({
+        dryRun: options.dryRun,
+        includeUnsafe: options.includeUnsafe,
+        json: options.json,
+    });
+});
+// --- stale (Phase 4 Sprint 1 Lane A / pln#390) ---
+program
+    .command('stale [subcommand] [id]')
+    .description('List or resolve stale memory items (plans, traps, handoffs, candidates, runtime notes). Subcommands: list (default), resolve <id>.')
+    .option('--json', 'Output as JSON')
+    .action((subcommand, id, options) => {
+    runStale(subcommand, id, { json: options.json });
 });
 // --- version ---
 program
@@ -482,11 +657,23 @@ program
     .description('Show the installed brainclaw version and the project version policy')
     .option('--check', 'Check the configured installable update source')
     .option('--publish-local', 'Create/update the local installable .releases channel via npm pack')
-    .option('--release-notes <text>', 'Attach release notes to the generated local-pack manifest')
+    .option('--release-notes <text>', 'Attach plain-text release notes to the generated local-pack manifest')
+    .option('--agent-release-notes <json>', 'Attach structured agent-first release notes (JSON) to the generated local-pack manifest')
+    .option('--auto-release-notes', 'Auto-generate agent-first release notes from git log (use with --publish-local)')
     .option('--json', 'Output as JSON')
     .action((options) => {
     runVersion(options);
 });
+// --- release-notes ---
+program
+    .command('release-notes')
+    .description('Show or generate agent-first release notes')
+    .option('--generate', 'Generate release notes from git log instead of showing configured ones')
+    .option('--since <ref>', 'Git ref to generate from (default: last version tag)')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    runReleaseNotes(options);
+});
 // --- uninstall ---
 import { runUninstall } from './commands/uninstall.js';
 program
@@ -662,6 +849,7 @@ program
     .command('enable-agent <name>')
     .description('Activate a supported coding agent on an already initialized project')
     .option('--kind <kind>', 'Identity kind: agent, human, unknown', 'agent')
+    .option('--context-profile <profile>', 'Default context profile: dev, dense, compact, copilot, quick, openclaw, ops, research')
     .option('--capability <value>', 'Declare a capability on the agent profile (repeatable)', collect, [])
     .option('--replace-capabilities', 'Replace existing capabilities instead of merging')
     .option('--generate-fingerprint', 'Generate or rotate a local public identity fingerprint for this agent')
@@ -749,6 +937,17 @@ program
     .action((id, options) => {
     runReject(id, options.reason, options.by);
 });
+// --- harvest-candidates ---
+program
+    .command('harvest-candidates')
+    .description('Harvest candidates from worktree inboxes into the main project store (codex sandbox bridge)')
+    .option('--dry-run', 'Preview what would be imported without writing anything')
+    .option('--worktree <path>', 'Explicit worktree path to scan (repeatable)', collect, [])
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    const globalOpts = program.opts();
+    runHarvestCandidates({ ...options, cwd: globalOpts.cwd });
+});
 // --- prune-candidates ---
 program
     .command('prune-candidates')
@@ -758,6 +957,35 @@ program
     .action((options) => {
     runPruneCandidates(options);
 });
+// --- cleanup-candidates ---
+program
+    .command('cleanup-candidates')
+    .description('Remove stale auto-generated pending candidates')
+    .option('--max-age <days>', 'Max age in days before cleanup', parseInt)
+    .option('--dry-run', 'Preview without deleting')
+    .action((options) => {
+    if (!memoryExists()) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const maxAgeDays = options.maxAge ?? 30;
+    const result = cleanupStaleCandidates({
+        maxAgeDays,
+        dryRun: options.dryRun,
+    });
+    if (result.matched === 0) {
+        console.log(`No stale auto-generated candidates older than ${maxAgeDays} days found.`);
+        return;
+    }
+    if (options.dryRun) {
+        console.log(`Would remove ${result.matched} stale auto-generated candidate(s):`);
+        for (const candidate of result.candidates) {
+            console.log(`  [${candidate.id}] ${candidate.text}`);
+        }
+        return;
+    }
+    console.log(`✔ Removed ${result.deleted} stale auto-generated candidate(s) older than ${maxAgeDays} days.`);
+});
 // --- claim ---
 program
     .command('claim <subcommand> [args...]')
@@ -771,8 +999,9 @@ program
     .option('--json', 'Output as JSON for list')
     .option('--plan-status <status>', 'Optional linked plan status when releasing: todo, in_progress, blocked, done, dropped')
     .option('--store <target>', 'Target store level: local (default), repo, workspace')
+    .option('--local-only', 'Read from local store only for list (skip parent stores in chain)')
     .action((subcommand, args, options) => {
-    runClaimResource(subcommand, args, { ...options, planStatus: options.planStatus });
+    runClaimResource(subcommand, args, { ...options, planStatus: options.planStatus, localOnly: options.localOnly });
 });
 // --- list-claims ---
 program
@@ -783,8 +1012,9 @@ program
     .option('--project <project>', 'Filter by project namespace')
     .option('--plan <id>', 'Filter by linked plan item')
     .option('--agent <agent>', 'Filter by agent name')
+    .option('--local-only', 'Read from local store only (skip parent stores in chain)')
     .action((options) => {
-    runListClaims(options);
+    runListClaims({ ...options, localOnly: options.localOnly });
 });
 // --- release-claim ---
 program
@@ -818,6 +1048,7 @@ program
     .option('--capabilities', 'List all registered agents with their declared capabilities')
     .option('--suggest <query>', 'Suggest agents whose capabilities match a query string')
     .option('--include-session-meta', 'Include session_start/session_end runtime notes (hidden by default)')
+    .option('--all-agents', 'Show unfiltered board (supervisor mode — all claims, all agents)')
     .action((options) => {
     runAgentBoard(options);
 });
@@ -836,6 +1067,24 @@ program
     .action((text, options) => {
     runRuntimeNote(text, { ...options, autoReflect: options.autoReflect });
 });
+// --- note create ---
+const noteCommand = program
+    .command('note')
+    .description('Manage runtime notes');
+noteCommand
+    .command('create <text>')
+    .description('Alias for runtime-note')
+    .option('--agent <agent>', 'Agent name; defaults to the configured current agent')
+    .option('--project <project>', 'Optional project namespace')
+    .option('--plan <id>', 'Optional linked plan item ID')
+    .option('--visibility <visibility>', 'Visibility: shared, machine, private', 'shared')
+    .option('--host <host>', 'Optional host identifier override for machine/private runtime notes')
+    .option('--tag <tags...>', 'Tags')
+    .option('--ttl <duration>', 'Time-to-live: 30m, 2h, 7d (note auto-expires after this duration)')
+    .option('--auto-reflect', 'Attempt to turn this runtime note into durable memory immediately')
+    .action((text, options) => {
+    runRuntimeNote(text, { ...options, autoReflect: options.autoReflect });
+});
 // --- runtime-status ---
 program
     .command('runtime-status')
@@ -872,6 +1121,46 @@ program
     .action((options) => {
     runCheckConstraints({ staged: options.staged, files: options.files, json: options.json });
 });
+// --- check-policy ---
+program
+    .command('check-policy')
+    .description('Pre-execution policy check: verify claims, constraints, traps and instructions for a scope')
+    .requiredOption('--scope <path>', 'File or directory scope to check')
+    .option('--agent <name>', 'Agent name to check claims for')
+    .option('--agent-id <id>', 'Agent id to check claims for')
+    .option('--action <action>', 'Intended action: edit, create, delete')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    runCheckPolicy({
+        scope: options.scope,
+        agent: options.agent,
+        agentId: options.agentId,
+        action: options.action,
+        json: options.json,
+    });
+});
+// --- check-security ---
+program
+    .command('check-security')
+    .description('Check supply chain security scores for packages via Socket.dev')
+    .requiredOption('--packages <names>', 'Comma-separated package names (e.g. "axios,express" or "axios@1.14.1")')
+    .option('--ecosystem <type>', 'Package ecosystem: npm or pypi', 'npm')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    await runCheckSecurity({
+        packages: options.packages,
+        ecosystem: options.ecosystem,
+        json: options.json,
+    });
+});
+// --- setup-security ---
+program
+    .command('setup-security')
+    .description('Enable supply chain security gate: generate wrapper scripts and configure preinstall checks')
+    .option('--mode <mode>', 'Security mode: advisory (default) or enforced', 'advisory')
+    .action((options) => {
+    runSetupSecurity({ mode: options.mode });
+});
 // --- install-hooks ---
 program
     .command('install-hooks')
@@ -894,9 +1183,26 @@ program
     .command('prune')
     .description('Prune expired constraints and stale memory')
     .option('--expired', 'Also prune expired runtime notes and traps')
+    .option('--archive', 'Archive done plans and closed handoffs (>30 days) to cold storage JSONL')
+    .option('--semantic', 'Detect near-duplicate clusters and stale items via semantic analysis')
+    .option('--dry-run', 'Preview compaction without applying (use with --semantic)')
     .action((options) => {
     runPrune(options);
 });
+// --- compact ---
+program
+    .command('compact')
+    .description('LLM-driven semantic memory compaction — archive old items and get a summary template')
+    .option('--assess', 'Show pressure assessment and compaction template without archiving')
+    .option('--dry-run', 'Preview eligible items without archiving')
+    .option('--max-items <n>', 'Maximum items to compact (default: 20)', parseInt)
+    .option('--min-age <days>', 'Minimum age in days for eligibility (default: 7)', parseInt)
+    .option('--no-dedup-handoffs', 'Skip deduplication of auto-generated session-end handoffs')
+    .option('--no-purge-claims', 'Skip archival of released claims')
+    .option('--no-purge-session-notes', 'Skip archival of session-lifecycle runtime_notes')
+    .action((options) => {
+    runCompact(options);
+});
 // --- mcp ---
 program
     .command('mcp')
@@ -921,6 +1227,8 @@ program
     .option('--agent <agent>', 'Agent name (defaults to current configured agent)')
     .option('--context <path>', 'Context target path for initial hash capture')
     .option('--model <id>', 'Model identifier (e.g. claude-sonnet-4-6)')
+    .option('--maintenance-mode <mode>', 'Maintenance mode: full (default) or fast')
+    .option('--include-context', 'Output full project context after starting session (replaces separate context call)')
     .option('--json', 'Output as JSON')
     .action((options) => {
     runSessionStart(options);
@@ -934,10 +1242,21 @@ program
     .option('--summary <text>', 'Session summary text')
     .option('--auto-reflect', 'Auto-reflect session notes as pending candidates')
     .option('--auto-release', 'Auto-release any active claims at session end')
-    .option('--reflect-handoff', 'Generate a handoff candidate from git commits since session start')
+    .option('--reflect-handoff', 'Materialize an open handoff from git commits since session start')
+    .option('--dispatch-review', 'When used with --reflect-handoff, auto-dispatch a code review if the handoff is reviewable')
+    .option('--reviewer <name>', 'Explicit reviewer to route the reflected handoff review to')
+    .option('--reflect', 'Include structured reflection questions for the agent to answer')
     .option('--json', 'Output as JSON')
     .action((options) => {
-    runSessionEnd({ ...options, autoReflect: options.autoReflect, autoRelease: options.autoRelease, reflectHandoff: options.reflectHandoff });
+    runSessionEnd({
+        ...options,
+        autoReflect: options.autoReflect,
+        autoRelease: options.autoRelease,
+        reflectHandoff: options.reflectHandoff,
+        dispatchReview: options.dispatchReview,
+        reviewer: options.reviewer,
+        reflect: options.reflect,
+    });
 });
 // --- whoami ---
 program
@@ -947,6 +1266,17 @@ program
     .action((options) => {
     runWhoami(options);
 });
+// --- usage ---
+program
+    .command('usage')
+    .description('Show brainclaw context volume stats (tokens injected per agent/tool)')
+    .option('--agent <name>', 'Filter by agent name')
+    .option('--tool <name>', 'Filter by tool name')
+    .option('--days <n>', 'Limit to last N days', parseInt)
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    runUsage(options);
+});
 // --- search ---
 program
     .command('search <query>')
@@ -968,6 +1298,7 @@ program
     .option('--detect', 'Auto-detect agent environment and write to its native file')
     .option('--all', 'Write all known agent instruction files at once (claude-md, agents-md, copilot-instructions, cursor-rules, etc.)')
     .option('--write', 'Write to canonical file path instead of stdout (when --format is given); local files are gitignored by default')
+    .option('--include-live', 'Also write the native live companion file when the target agent supports one')
     .option('--shared', 'Keep the main exported instruction file versionable instead of auto-ignoring it (companions remain local)')
     .option('--output <file>', 'Write to a specific file path instead of stdout')
     .option('--project <project>', 'Project namespace filter')
@@ -975,6 +1306,12 @@ program
     .action((options) => {
     runExport(options);
 });
+program
+    .command('refresh')
+    .description('Refresh live companion files with current state (plans, claims, traps, sequences). Gitignored, safe to run frequently.')
+    .action(() => {
+    runRefresh();
+});
 program
     .command('reconcile')
     .description('Refresh machine and workspace bootstrap state after updates or onboarding on complex installs')
@@ -1012,6 +1349,110 @@ program
     .action((options) => {
     runWatch({ ...options, autoClaim: options.autoClaim });
 });
+// --- dispatch ---
+const dispatchCmd = program
+    .command('dispatch')
+    .description('Local agent dispatcher — analyze lanes and assign work');
+dispatchCmd
+    .command('analysis')
+    .description('Analyze the active sequence: show ready, active, blocked, and done lanes')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    runDispatchAnalysis({ json: options.json });
+});
+dispatchCmd
+    .command('run')
+    .description('Run a dispatch cycle: assign ready lanes to available agents')
+    .option('--agents <names>', 'Comma-separated list of agents to dispatch to')
+    .option('--lanes <names>', 'Comma-separated list of lanes to dispatch')
+    .option('--max <n>', 'Maximum assignments', parseInt)
+    .option('--dry', 'Preview assignments without sending messages')
+    .option('--spawn', 'Autonomously launch CLI agents with invoke templates')
+    .option('--agent <name>', 'Dispatcher agent name')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    runDispatch({
+        agents: options.agents,
+        lanes: options.lanes,
+        max: options.max,
+        dry: options.dry,
+        spawn: options.spawn,
+        agent: options.agent,
+        json: options.json,
+    });
+});
+dispatchCmd
+    .command('review')
+    .description('Dispatch code reviews for completed handoffs')
+    .option('--handoff <id>', 'Specific handoff ID to review')
+    .option('--reviewer <name>', 'Specific reviewer agent')
+    .option('--spawn', 'Launch the reviewer CLI agent')
+    .option('--dry', 'Preview without sending')
+    .option('--agent <name>', 'Dispatcher agent name')
+    .option('--json', 'Output as JSON')
+    .action((options) => {
+    runDispatchReview({
+        handoff: options.handoff,
+        reviewer: options.reviewer,
+        spawn: options.spawn,
+        dry: options.dry,
+        agent: options.agent,
+        json: options.json,
+    });
+});
+// --- inbox ---
+const inboxCmd = program
+    .command('inbox')
+    .description('Inter-agent messaging inbox');
+inboxCmd
+    .command('list')
+    .description('List inbox messages (default: pending only)')
+    .option('--agent <name>', 'Agent name')
+    .option('--status <status>', 'Filter by status: pending, read, acknowledged, archived')
+    .option('--type <type>', 'Filter by type: assign, review, rfc, info, reply')
+    .option('--thread <id>', 'Filter by thread ID')
+    .option('--all', 'Show all messages, not just pending')
+    .option('--json', 'Output as JSON')
+    .option('--local-only', 'Read from local store only (skip parent stores in chain)')
+    .action((options) => {
+    runInboxList({ ...options, localOnly: options.localOnly });
+});
+inboxCmd
+    .command('ack <id>')
+    .description('Acknowledge a message')
+    .option('--agent <name>', 'Agent name')
+    .option('--json', 'Output as JSON')
+    .action((id, options) => {
+    runInboxAck(id, options);
+});
+inboxCmd
+    .command('archive <id>')
+    .description('Archive a message')
+    .option('--agent <name>', 'Agent name')
+    .option('--json', 'Output as JSON')
+    .action((id, options) => {
+    runInboxArchive(id, options);
+});
+inboxCmd
+    .command('send <to> <text>')
+    .description('Send a message to another agent')
+    .option('--type <type>', 'Message type: assign, review, rfc, info, reply (default: info)')
+    .option('--ref <id>', 'Reference to a plan, sequence, or other entity')
+    .option('--scope <path>', 'File scope')
+    .option('--thread <id>', 'Thread ID for conversations')
+    .option('--ack', 'Require acknowledgment')
+    .option('--agent <name>', 'Sender agent name')
+    .option('--json', 'Output as JSON')
+    .action((to, text, options) => {
+    runInboxSend(to, text, options);
+});
+inboxCmd
+    .command('thread <id>')
+    .description('Show all messages in a thread')
+    .option('--json', 'Output as JSON')
+    .action((id, options) => {
+    runInboxThread(id, options);
+});
 // --- check-events ---
 program
     .command('check-events')
@@ -1063,14 +1504,16 @@ program
 // --- audit ---
 program
     .command('audit')
-    .description('View the append-only audit log of all memory mutations')
+    .description('View the append-only audit log, or generate a governance posture report with --governance')
     .option('--since <date>', 'Show entries since this ISO date')
     .option('--actor <agent>', 'Filter by actor name or agent ID')
     .option('--action <action>', 'Filter by action type (create, accept, reject, etc.)')
     .option('--limit <n>', 'Show last N entries', parseInt)
     .option('--json', 'Output as JSON')
+    .option('--governance', 'Generate a governance posture report (aggregated view of claims, constraints, traps, instructions)')
+    .option('--scope <path>', 'Filter governance report by scope (used with --governance)')
     .action((options) => {
-    runAuditCommand({ since: options.since, actor: options.actor, action: options.action, limit: options.limit, json: options.json });
+    runAuditCommand({ since: options.since, actor: options.actor, action: options.action, limit: options.limit, json: options.json, governance: options.governance, scope: options.scope });
 });
 // --- history ---
 program
@@ -1102,6 +1545,25 @@ program
         store: options.store,
     });
 });
+program
+    .command('link <subcommand> [args...]')
+    .description('Manage cross-project federation links (add, list, remove)')
+    .option('--name <slug>', 'Override the auto-derived link name')
+    .option('--role <role>', 'Link role: publisher (push signals out) or subscriber (default)')
+    .option('--channels <list>', 'Comma-separated allow-list of channels: candidate,handoff,runtime_note', (val) => val.split(',').map((s) => s.trim()).filter(Boolean))
+    .option('--force', 'Replace an existing link of the same name/path')
+    .option('--json', 'Output as JSON')
+    .option('--store <target>', 'Store level: local (default), repo, workspace, user')
+    .action((subcommand, args, options) => {
+    runLink(subcommand, args, {
+        name: options.name,
+        role: options.role,
+        channels: options.channels,
+        force: options.force,
+        json: options.json,
+        store: options.store,
+    });
+});
 program
     .command('tool <subcommand> [args...]')
     .description('Manage project tools (list, add, describe, search)')
@@ -1157,6 +1619,204 @@ program
         cwd: globalOpts.cwd,
     });
 });
+program
+    .command('who')
+    .description('Show active agent sessions on this workspace')
+    .option('--json', 'Output as JSON')
+    .option('--all', 'Include stale sessions')
+    .option('--gc', 'Remove stale sessions')
+    .option('--local-only', 'Read claims from local store only (skip parent stores in chain)')
+    .action(async (options) => {
+    const globalOpts = program.opts();
+    const { runWho } = await import('./commands/who.js');
+    runWho({ json: options.json, all: options.all, gc: options.gc, cwd: globalOpts.cwd, localOnly: options.localOnly });
+});
+const worktreeCmd = program
+    .command('worktree')
+    .description('Manage git worktrees for parallel agent isolation');
+worktreeCmd
+    .command('create <branch>')
+    .description('Create a linked git worktree for a given branch')
+    .option('--session-id <id>', 'Associate this worktree with a brainclaw session')
+    .option('--agent <name>', 'Associate this worktree with an agent name')
+    .action((branch, options) => {
+    const globalOpts = program.opts();
+    runWorktreeCreate({ branch, sessionId: options.sessionId, agent: options.agent, cwd: globalOpts.cwd });
+});
+worktreeCmd
+    .command('list')
+    .description('List all git worktrees for this project')
+    .action(() => {
+    const globalOpts = program.opts();
+    runWorktreeList({ cwd: globalOpts.cwd });
+});
+worktreeCmd
+    .command('remove <path>')
+    .description('Remove a linked git worktree')
+    .option('--force', 'Force removal even with uncommitted changes')
+    .action((worktreePath, options) => {
+    const globalOpts = program.opts();
+    runWorktreeRemove({ path: worktreePath, force: options.force, cwd: globalOpts.cwd });
+});
+worktreeCmd
+    .command('prune')
+    .description('Prune stale worktree administrative files')
+    .action(() => {
+    const globalOpts = program.opts();
+    runWorktreePrune({ cwd: globalOpts.cwd });
+});
+worktreeCmd
+    .command('clean')
+    .description('Remove worktrees whose branch is fully merged and orphan worktree directories')
+    .option('--force', 'Force removal even with uncommitted changes')
+    .option('--dry-run', 'Show what would be removed without actually removing')
+    .action((options) => {
+    const globalOpts = program.opts();
+    runWorktreeClean({ force: options.force, dryRun: options.dryRun, cwd: globalOpts.cwd });
+});
+worktreeCmd
+    .command('merge <branch>')
+    .description('Merge a worktree branch with auto-restoration of parasitic deletions')
+    .option('-m, --message <message>', 'Merge commit message')
+    .option('--dry-run', 'Show what would be merged without committing')
+    .action((branch, options) => {
+    const globalOpts = program.opts();
+    runWorktreeMerge({ branch, message: options.message, dryRun: options.dryRun, cwd: globalOpts.cwd });
+});
+// --- federation cloud ---
+const federationCmd = program
+    .command('federation')
+    .description('Cloud federation — sync signals with app.brainclaw.dev');
+federationCmd
+    .command('push <message>')
+    .description('Push a test signal to the cloud')
+    .option('--type <type>', 'Signal type', 'runtime_note')
+    .option('--to-project <project>', 'Target project name')
+    .option('--to-agent <agent>', 'Target agent name')
+    .action(async (message, options) => {
+    const { pushSignalToCloud, isCloudConfigured } = await import('./core/federation-cloud.js');
+    const { createFederationMessage } = await import('./core/federation-message.js');
+    const { loadConfig } = await import('./core/config.js');
+    const { resolveCurrentAgentName } = await import('./core/agent-registry.js');
+    if (!isCloudConfigured()) {
+        console.error('Error: cloud not configured. Set BRAINCLAW_CLOUD_API_KEY env var.');
+        process.exit(1);
+    }
+    const config = loadConfig();
+    const agent = resolveCurrentAgentName() ?? 'unknown';
+    const msg = createFederationMessage({
+        version: 1,
+        from: { project_name: config.project_name, project_path: process.cwd(), agent_name: agent },
+        to: { project_name: options.toProject ?? 'broadcast', project_path: '' },
+        type: options.type,
+        payload: { text: message },
+    });
+    const ok = await pushSignalToCloud(msg);
+    if (ok) {
+        console.log(`✔ Signal pushed to cloud: [${msg.id}] ${message}`);
+    }
+    else {
+        console.error('Error: failed to push signal to cloud.');
+        process.exit(1);
+    }
+});
+federationCmd
+    .command('pull')
+    .description('Pull signals from the cloud inbox')
+    .option('--agent <name>', 'Agent name to pull for')
+    .option('--since <date>', 'Only pull signals after this ISO date')
+    .option('--limit <n>', 'Max signals to pull', '20')
+    .action(async (options) => {
+    const { pullSignalsFromCloud, isCloudConfigured } = await import('./core/federation-cloud.js');
+    const { resolveCurrentAgentName } = await import('./core/agent-registry.js');
+    if (!isCloudConfigured()) {
+        console.error('Error: cloud not configured. Set BRAINCLAW_CLOUD_API_KEY env var.');
+        process.exit(1);
+    }
+    const agent = options.agent ?? resolveCurrentAgentName() ?? 'unknown';
+    const signals = await pullSignalsFromCloud(agent, {
+        since: options.since,
+        limit: parseInt(options.limit, 10),
+    });
+    if (signals.length === 0) {
+        console.log('No signals in cloud inbox.');
+        return;
+    }
+    console.log(`${signals.length} signal(s) from cloud:\n`);
+    for (const s of signals) {
+        const payload = typeof s.payload === 'object' && s.payload !== null ? s.payload.text ?? JSON.stringify(s.payload) : String(s.payload);
+        console.log(`  [${s.id}] ${s.type} from ${s.from.project_name}/${s.from.agent_name}`);
+        console.log(`    ${String(payload).slice(0, 120)}`);
+        console.log(`    ${s.created_at}\n`);
+    }
+});
+federationCmd
+    .command('status')
+    .description('Check cloud federation configuration')
+    .action(async () => {
+    const { isCloudConfigured } = await import('./core/federation-cloud.js');
+    const url = process.env.BRAINCLAW_CLOUD_URL ?? 'https://app.brainclaw.dev';
+    console.log(`Cloud URL: ${url}`);
+    console.log(`API Key: ${process.env.BRAINCLAW_CLOUD_API_KEY ? '***configured***' : 'NOT SET'}`);
+    console.log(`Configured: ${isCloudConfigured() ? 'yes' : 'no'}`);
+    if (isCloudConfigured()) {
+        try {
+            const res = await fetch(`${url}/api/v1/health`);
+            const data = await res.json();
+            console.log(`Cloud status: ${data.status} (v${data.version})`);
+        }
+        catch (e) {
+            console.error(`Cloud unreachable: ${e.message}`);
+        }
+    }
+});
+// --- codev (legacy experimental) ---
+if (isCodevEnabled()) {
+    program
+        .command('codev [topic]')
+        .description('Experimental legacy ideation session using persona-based consultation')
+        .option('--personas <tier>', 'Persona tier: tier1 (default), tier2, or list', 'tier1')
+        .option('--checkpoint', 'Pause after clarification for human input')
+        .option('--spawn', 'Spawn each consultant as an agent CLI instance')
+        .option('--fresh', 'Clear cached responses before starting a new run')
+        .option('--agents <list>', 'Comma-separated agent names for spawn (e.g. claude-code,codex,antigravity). Default: auto-detect')
+        .option('--rounds <N>', 'Number of discussion rounds in spawn mode (default 3, min 2)', '3')
+        .option('--target-duration <seconds>', 'Target duration per round indicated to agents (default 120)', '120')
+        .option('--quorum <N>', 'Advance to next round after N agent responses (default: all)')
+        .option('--model-map <map>', 'Per-persona model overrides, e.g. simplificateur:sonnet,stratege:opus')
+        .option('--metrics', 'Display response timing metrics at end of session')
+        .option('--json', 'Output as JSON')
+        .action(async (topic, options) => {
+        const globalOpts = program.opts();
+        const { runCodev } = await import('./commands/codev.js');
+        runCodev(topic, {
+            ...options,
+            rounds: parseInt(options.rounds, 10),
+            targetDuration: parseInt(options.targetDuration, 10),
+            quorum: options.quorum != null ? parseInt(options.quorum, 10) : undefined,
+            cwd: globalOpts.cwd,
+        });
+    });
+    program
+        .command('codev-metrics <thread>')
+        .description('Show per-agent avg/p95 response metrics for an experimental CoDev thread')
+        .option('--json', 'Output as JSON')
+        .action(async (thread, options) => {
+        const globalOpts = program.opts();
+        const { runCodevMetrics } = await import('./commands/codev.js');
+        runCodevMetrics(thread, { ...options, cwd: globalOpts.cwd });
+    });
+}
+// --- run (agent profiles) ---
+program
+    .command('run [profile-name]')
+    .description('Run an agent profile (list profiles if no name given)')
+    .option('--dry', 'Print the resolved command without executing')
+    .option('--agent <agent>', 'Override the invoke template with a known agent')
+    .action((profileName, options) => {
+    const globalOpts = program.opts();
+    runRunProfile(profileName, { ...options, cwd: globalOpts.cwd });
+});
 program.parseAsync(process.argv).catch((err) => {
     console.error(err);
     process.exit(1);