brainclaw 1.7.5 → 1.9.0

package/README.md

@@ -65,17 +65,17 @@ brainclaw is designed to sit alongside the coding agents teams are already using
 | Logo | Agent | Tier | What brainclaw configures |
 |---|---|---|---|
 | [![Claude Code](https://img.shields.io/badge/Claude_Code-111111?logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code) | **[Claude Code](https://github.com/anthropics/claude-code)** | A | MCP + CLAUDE.md + hooks + auto-approve + permissions + /brainclaw skill |
-| [![Codex](https://img.shields.io/badge/Codex-111111?logo=openai&logoColor=white)](https://openai.com/codex/) | **[Codex](https://openai.com/codex/)** | A | MCP + AGENTS.md + hooks + skills |
+| [![Codex](https://img.shields.io/badge/Codex-111111?logo=openai&logoColor=white)](https://openai.com/codex/) | **[Codex](https://openai.com/codex/)** | A | MCP + AGENTS.md + skills |
 | [![Cursor](https://img.shields.io/badge/Cursor-1F2430?logo=cursor&logoColor=white)](https://cursor.com/en-US) | **[Cursor](https://cursor.com/en-US)** | A | MCP (machine) + .cursor/rules/ + hooks + skills |
-| [![Windsurf](https://img.shields.io/badge/Windsurf-0B1220?logo=codeium&logoColor=white)](https://windsurf.com/) | **[Windsurf](https://windsurf.com/)** | A | MCP (machine) + .windsurfrules + hooks + skills |
-| [![Cline](https://img.shields.io/badge/Cline-0F766E?logoColor=white)](https://github.com/cline/cline) | **[Cline](https://github.com/cline/cline)** | A | MCP + auto-approve + .clinerules/ + hooks + skills |
+| [![Windsurf](https://img.shields.io/badge/Windsurf-0B1220?logo=codeium&logoColor=white)](https://windsurf.com/) | **[Windsurf](https://windsurf.com/)** | A | MCP (machine) + .windsurfrules + .windsurf/rules/ |
+| [![Cline](https://img.shields.io/badge/Cline-0F766E?logoColor=white)](https://github.com/cline/cline) | **[Cline](https://github.com/cline/cline)** | A | MCP + auto-approve + .clinerules/ |
 | [![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-181717?logo=githubcopilot&logoColor=white)](https://github.com/features/copilot) | **[GitHub Copilot](https://github.com/features/copilot)** | A | MCP + copilot-instructions.md + hooks + skills |
 | [![Roo](https://img.shields.io/badge/Roo-7C3AED?logoColor=white)](https://github.com/RooCodeInc/Roo-Code) | **[Roo](https://github.com/RooCodeInc/Roo-Code)** | B | MCP + auto-approve + .roo/rules/ |
 | [![Continue](https://img.shields.io/badge/Continue-2563EB?logoColor=white)](https://github.com/continuedev/continue) | **[Continue](https://github.com/continuedev/continue)** | B | MCP + .continue/rules/ |
 | [![OpenCode](https://img.shields.io/badge/OpenCode-0F172A?logoColor=white)](https://github.com/opencode-ai/opencode) | **[OpenCode](https://github.com/opencode-ai/opencode)** | B | MCP + AGENTS.md |
 | [![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-1A73E8?logo=googlegemini&logoColor=white)](https://github.com/google-gemini/gemini-cli) | **[Antigravity / Gemini CLI](https://github.com/google-gemini/gemini-cli)** | B | MCP + GEMINI.md |
 
-**Tier A** = MCP + hooks + skills (context injected dynamically, lightweight instruction files). **Tier B** = MCP only, no hooks (richer static instruction files with architecture + top traps). Tier can degrade at runtime if integration surfaces are missing.
+**Tier A** = strongest supported integration for that agent family (usually MCP plus native files, and hooks/skills where the agent exposes them). **Tier B** = MCP/native-file integration with fewer automation surfaces. Tier can degrade at runtime if integration surfaces are missing.
 
 ### Autonomous Agents
 
@@ -96,11 +96,11 @@ brainclaw is most effective today when one agent works at a time in a given chec
 
 ## Platform Support
 
-brainclaw declares support for Node.js 20+ in `package.json`, and CI actively exercises Node 20, 22, and 24 across the main Linux path (Windows runs on Node 24). Real-world support is still not perfectly even yet.
+brainclaw declares support for Node.js 20+ in `package.json` (`engines.node = ">=20.0.0"`). CI actively exercises Node 22 (Active LTS) and Node 24 (current LTS) on Linux; Windows runs on Node 24. Node 20 still works as a minimum runtime but is no longer CI-verified — it reached EOL in April 2026 and was removed from GitHub-hosted runners. The recommended runtime is Node 22 LTS or Node 24 LTS. Real-world support is still not perfectly even yet.
 
 | Logo | Platform | Status today | Notes |
 |---|---|---|---|
-| [![Linux](https://img.shields.io/badge/Linux-111111?logo=linux&logoColor=white)](https://www.kernel.org/) | **[Linux](https://www.kernel.org/)** | Recommended | best-supported environment today; GitHub CI runs on Ubuntu with Node 20, 22, and 24 |
+| [![Linux](https://img.shields.io/badge/Linux-111111?logo=linux&logoColor=white)](https://www.kernel.org/) | **[Linux](https://www.kernel.org/)** | Recommended | best-supported environment today; GitHub CI runs on Ubuntu with Node 22 and 24 |
 | [![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white)](https://www.apple.com/macos/) | **[macOS](https://www.apple.com/macos/)** | Likely supported | Unix-like path and shell model should map well, but it is less exercised than Linux |
 | [![Windows](https://img.shields.io/badge/Windows-0078D4?logo=windows&logoColor=white)](https://www.microsoft.com/windows/) | **[Windows](https://www.microsoft.com/windows/)** | Supported with caveats | native support exists, but PATH, npm, SSH, and PowerShell quoting still create more friction than on Unix systems |
 | [![Windows + WSL2](https://img.shields.io/badge/Windows%20%2B%20WSL2-0078D4?logo=windows&logoColor=white)](https://learn.microsoft.com/windows/wsl/) | **[Windows + WSL2](https://learn.microsoft.com/windows/wsl/)** | Important, still maturing | Brainclaw detects this setup explicitly, but setup/install/store parity across Windows and WSL is not fully seamless yet |
@@ -232,7 +232,7 @@ Still sharp:
 1. **Same-checkout concurrent edits** — running two agents in the *same* working tree (no per-claim worktree) is still the wrong answer. Use the dispatch path (auto-worktree per claim) instead of raw concurrent CLI sessions.
 2. **Cross-machine sync** — federation across machines is on the roadmap, not in v1.x. Today brainclaw's store is local and one-machine-per-project.
 3. **Spawn-and-forget assumptions** — spawned workers don't always commit their work cleanly. The brief-ack file confirms the spawn started; in the worst case the coordinator harvests open changes.
-4. **Live state for hook-less agents** — Tier B/C agents without lifecycle hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe, Hermes) get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
+4. **Live state for hook-less agents** — supported hook-less file surfaces such as Cline, Windsurf, Continue, Antigravity/Gemini CLI, and Mistral Vibe can get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
 
 Recommended use today:
 
@@ -334,9 +334,10 @@ If you are integrating Brainclaw into an agent workflow, start with the agent-fa
 Contributor note: the commands below are for developing Brainclaw itself, not for normal agent usage inside a target repo.
 
 ```bash
-npm test                   # unit + smoke (fast path)
-npm run test:e2e           # full suite
-npm run test:coverage      # with coverage report
+npm test                   # unit + smoke (fast path)
+npm run test:e2e           # end-to-end suite
+npm run test:all           # full suite
+npm run test:coverage      # with coverage report
 ```
 
 ---
@@ -345,6 +346,22 @@ npm run test:coverage      # with coverage report
 
 For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
 
+### v1.8.0
+
+- **Multi-agent dispatch convergence — "worktree-as-contract"** (from a real
+  cross-project field session where a sandboxed worker could neither commit nor
+  reach MCP). The worker's contract shrinks to "edit files in this worktree +
+  drop `LANE-RESULT.json`": `brainclaw harvest --integrate` commits the worktree
+  diff on behalf of a worker that can't self-commit (hard-guarded to the linked
+  worktree, never the main repo), then completes the assignment and releases the
+  claim with plan cascade. A `LANE-RESULT.json` is now the #1 verdict signal in
+  `bclaw_dispatch_status` (worker FINISHED, even without self-update); the
+  dispatcher refuses to spawn without an isolated worktree; `open_loop` reviews
+  pre-flight each reviewer agent with a trivial validation spawn (clear
+  boot-failure reason instead of a generic loop timeout); and decisions/traps
+  gain `verified_at`/`verify_cmd` so perishable facts can be flagged stale.
+  Additive + opt-in throughout. (pln#530, pln#531, pln#532, pln#533, pln#534, trp#468)
+
 ### v1.7.5
 
 - **Security patch (recommended upgrade)** — fixes a git command-injection / RCE
@@ -443,7 +460,7 @@ For older releases (v0.x and the early v1.0 launch series), `git log` on `master
 
 ### v1.1.0
 
-- **Node 20+ baseline** (pln#485) — `engines.node` is now `>=20.0.0` (Node 18 reached EOL in April 2025). CI matrix runs Node 20, 22, and 24 on Linux; Windows on Node 24.
+- **Node 20+ baseline** (pln#485) — `engines.node` is now `>=20.0.0` (Node 18 reached EOL in April 2025). CI matrix runs Node 22 and 24 on Linux; Windows on Node 24. Node 20 remains the minimum installable runtime but is no longer CI-verified.
 - **commander 13 → 14** (requires Node 20+).
 - **@types/node 22 → 24** (LTS-aligned).
 

package/dist/cli.js

@@ -63,7 +63,7 @@ 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 { runRegisterAgent, runRemoveAgent } 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';
@@ -80,6 +80,7 @@ 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 { runDispatchWatch } from './commands/dispatch-watch.js';
 import { runInboxList, runInboxAck, runInboxArchive, runInboxSend, runInboxThread } from './commands/inbox.js';
 import { runMetrics } from './commands/metrics.js';
 import { runRollback } from './commands/rollback.js';
@@ -98,7 +99,7 @@ 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 { runWorktreeCreate, runWorktreeList, runWorktreeRemove, runWorktreePrune, runWorktreeClean, runWorktreeMerge, runWorktreeCheck } from './commands/worktree.js';
 import { runCheckEvents } from './commands/check-events.js';
 import { runDiscover } from './commands/discover.js';
 import { runMigrate } from './commands/migrate.js';
@@ -148,11 +149,72 @@ function parseLeadingGlobalOptions(argv) {
     }
     return result;
 }
+function trailingGlobalOptionError(argv, actionCommand) {
+    let firstCommandIndex = -1;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--')
+            break;
+        if (!token.startsWith('-')) {
+            firstCommandIndex = i;
+            break;
+        }
+        if (token === '--cwd' || token === '--project')
+            i++;
+    }
+    if (firstCommandIndex < 0)
+        return undefined;
+    for (let i = firstCommandIndex + 1; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--')
+            break;
+        const long = token.includes('=') ? token.slice(0, token.indexOf('=')) : token;
+        if (!['--cwd', '--project', '--verbose', '--debug'].includes(long))
+            continue;
+        const isLocalOption = actionCommand.options.some((option) => option.long === long);
+        if (!isLocalOption) {
+            const valueHint = token === long && (long === '--cwd' || long === '--project') ? ' <value>' : '';
+            return `Global option ${long} must appear before the subcommand. Use: brainclaw ${long}${valueHint} <command> ...`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the (possibly nested) subcommand named in argv without parsing.
+ * Used to run the trailing-global-option guard BEFORE Commander parses:
+ * with positional options enabled, Commander would otherwise reject a
+ * trailing --cwd/--project as "unknown option" before any hook runs.
+ */
+function findCommandFromArgv(argv) {
+    let current = program;
+    let found;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--')
+            break;
+        if (token.startsWith('-')) {
+            if (!found && (token === '--cwd' || token === '--project'))
+                i++;
+            continue;
+        }
+        const sub = current.commands.find((c) => c.name() === token || c.aliases().includes(token));
+        if (!sub)
+            break;
+        found = sub;
+        current = sub;
+    }
+    return found;
+}
 function isCodevEnabled() {
     return process.env.BRAINCLAW_ENABLE_CODEV === '1';
 }
 program
     .name('brainclaw')
+    // Stop the program-level parser from consuming options that appear AFTER the
+    // subcommand: `instruction … --project auth` must reach the subcommand's own
+    // --project, not the global routing flag (which is leading-only by contract —
+    // see parseLeadingGlobalOptions + trailingGlobalOptionError).
+    .enablePositionalOptions()
     .description('Shared project memory for humans and coding agents.')
     .version(getInstalledBrainclawVersion())
     .option('--verbose', 'Show info-level log messages on stderr')
@@ -570,8 +632,10 @@ program
     .command('add-step <planId> <text>')
     .description('Add an optional step to a plan item')
     .option('--assign <assignee>', 'Assign this step to an agent or person')
+    .option('--estimate <minutes>', 'Step-level estimate (minutes, or a duration like "2h"/"30m")')
+    .option('--actual-effort <effort>', 'Step-level actual effort (e.g. "45m", "2h")')
     .action((planId, text, options) => {
-    runAddStep(planId, text, { assignee: options.assign });
+    runAddStep(planId, text, { assignee: options.assign, estimatedEffort: options.estimate, actualEffort: options.actualEffort });
 });
 // --- complete-step ---
 program
@@ -583,10 +647,12 @@ program
 // --- update-step ---
 program
     .command('update-step <planId> <stepId>')
-    .description('Update a plan step (status, text, assignee)')
+    .description('Update a plan step (status, text, assignee, effort)')
     .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)')
+    .option('--estimate <minutes>', 'Step-level estimate (minutes, or a duration like "2h"/"30m")')
+    .option('--actual-effort <effort>', 'Step-level actual effort (e.g. "45m", "2h")')
     .action((planId, stepId, options) => {
     runUpdateStep(planId, stepId, options);
 });
@@ -603,8 +669,13 @@ program
     .description('Show estimation accuracy report for completed plans')
     .option('--agent <name>', 'Filter by agent/author name')
     .option('--json', 'Output as JSON')
+    .option('--outlier-threshold <minutes>', 'Drop plan-wallclock actuals over N minutes from the stats (default 1440 = 24h; 0 disables)')
     .action((options) => {
-    runEstimationReport(options);
+    runEstimationReport({
+        agent: options.agent,
+        json: options.json,
+        outlierThresholdMinutes: options.outlierThreshold !== undefined ? Number(options.outlierThreshold) : undefined,
+    });
 });
 // --- update-plan ---
 program
@@ -681,6 +752,7 @@ program
     .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)')
+    .option('--verify-journal', 'Phase-2 cutover gate (pln#565): rebuild state from the event journal and diff vs live projections; exits non-zero on any drift')
     .option('--spawn-check', 'Real spawn round-trip per installed agent before dispatch (pln#520 step 2): validates delivery + handshake on this host, exits non-zero on any installed-agent failure')
     .option('--spawn-check-timeout <ms>', 'Per-agent timeout for --spawn-check (default 15000)', parseInt)
     .action(async (options) => {
@@ -688,7 +760,7 @@ program
         await runDoctorSpawnCheck({ cwd: options.cwd, json: options.json, timeoutMs: options.spawnCheckTimeout });
         return;
     }
-    runDoctor({ ...options, afterMigration: options.afterMigration, dispatch: options.dispatch });
+    runDoctor({ ...options, afterMigration: options.afterMigration, dispatch: options.dispatch, verifyJournal: options.verifyJournal });
 });
 // --- repair (Phase 4 Sprint 2 Lane C / pln#397) ---
 program
@@ -901,8 +973,14 @@ program
     .option('--generate-fingerprint', 'Generate or rotate a local public identity fingerprint for this agent')
     .option('--set-current', 'Set this identity as the current agent in config')
     .option('--curator', 'Register this agent as a curator (project owner with direct-write access)')
+    .option('--remove', 'Remove this identity instead of registering (guarded: debris identities only unless --force)')
+    .option('--force', 'With --remove: allow removing a non-debris identity')
     .option('--json', 'Output as JSON')
     .action((name, options) => {
+    if (options.remove) {
+        runRemoveAgent(name, { force: options.force, json: options.json });
+        return;
+    }
     runRegisterAgent(name, options);
 });
 // --- enable-agent ---
@@ -1014,6 +1092,9 @@ program
     .command('harvest [assignment_id]')
     .description('Harvest a worker LANE-RESULT.json from its worktree into the project (pass an assignment id, or --all)')
     .option('--all', 'Harvest every lane result found across worktrees')
+    .option('--integrate', 'Worktree-as-contract (pln#534): commit the worktree diff on behalf of a sandboxed worker, lifecycle the assignment, and release the claim')
+    .option('--orphaned', 'Recover a dead worker that left NO lane-result (pln#554): typecheck + commit the worktree on behalf, lifecycle, release. Never deletes or resets anything')
+    .option('--base <ref>', 'Base ref for --orphaned commits-ahead comparison (default: master)')
     .option('--dry-run', 'Preview without writing events/markers')
     .option('--worktree <path>', 'Explicit worktree path to scan (repeatable)', collect, [])
     .option('--json', 'Output as JSON')
@@ -1236,13 +1317,19 @@ program
 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('--packages <names>', 'Comma-separated package names (e.g. "axios,express" or "axios@1.14.1")')
+    .option('--requirements <file>', 'Path to a pip-style requirements.txt to scan')
+    .option('--lockfile <file>', 'Path to a package-lock.json (npm) to scan top-level deps')
     .option('--ecosystem <type>', 'Package ecosystem: npm or pypi', 'npm')
+    .option('--mode <mode>', 'Override security mode: advisory or enforced (defaults to config)')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
     await runCheckSecurity({
         packages: options.packages,
+        requirements: options.requirements,
+        lockfile: options.lockfile,
         ecosystem: options.ecosystem,
+        mode: options.mode,
         json: options.json,
     });
 });
@@ -1338,7 +1425,7 @@ program
     .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('--no-reflect', 'Suppress the dogfooding reflection prompt (project + your surfaces/skills/tools), shown by default')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
     await runSessionEnd({
@@ -1387,7 +1474,7 @@ program
 program
     .command('export')
     .description('Export memory as instructions for IDE/AI tools')
-    .option('--format <format>', 'Format: copilot-instructions, cursor-rules, agents-md, claude-md, gemini-md, windsurf, cline, roo, continue')
+    .option('--format <format>', 'Format: copilot-instructions, cursor-rules, agents-md, claude-md, gemini-md, windsurf, cline, roo, continue, openclaw, nanoclaw, nemoclaw, picoclaw, zeroclaw')
     .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')
@@ -1465,8 +1552,8 @@ dispatchCmd
     .option('--spawn', 'Autonomously launch CLI agents with invoke templates')
     .option('--agent <name>', 'Dispatcher agent name')
     .option('--json', 'Output as JSON')
-    .action((options) => {
-    runDispatch({
+    .action(async (options) => {
+    await runDispatch({
         agents: options.agents,
         lanes: options.lanes,
         max: options.max,
@@ -1478,6 +1565,21 @@ dispatchCmd
         json: options.json,
     });
 });
+dispatchCmd
+    .command('watch <target>')
+    .description('Block until a dispatched worker reaches a terminal state (asgn_/clm_/run_ id) — sentinels, lane-result, committed-clean and worker-process-gone heuristics')
+    .option('--interval <seconds>', 'Poll interval in seconds (default 60)', parseInt)
+    .option('--timeout <minutes>', 'Give up after N minutes (default 90, exit code 2)', parseInt)
+    .option('--base <ref>', 'Base ref for commits-ahead evidence (default master)')
+    .option('--json', 'One JSON object per poll line')
+    .action(async (target, options) => {
+    await runDispatchWatch(target, {
+        intervalSeconds: options.interval,
+        timeoutMinutes: options.timeout,
+        base: options.base,
+        json: options.json,
+    });
+});
 dispatchCmd
     .command('review')
     .description('Dispatch code reviews for completed handoffs')
@@ -1697,9 +1799,10 @@ program
     .command('migrate')
     .description('Migrate memory items between stores (e.g. promote machine-scoped items to user store)')
     .option('--promote-machine-items', 'Move items with scope:machine from project store to user store (~/.brainclaw/)')
-    .option('--dry-run', 'Show what would be moved without actually moving')
+    .option('--enable-journal', 'Turn on the event journal (mode=dual) for this existing store and backfill it (pln#567)')
+    .option('--dry-run', 'Show what would be done without writing')
     .action((options) => {
-    runMigrate({ promoteMachineItems: options.promoteMachineItems, dryRun: options.dryRun });
+    runMigrate({ promoteMachineItems: options.promoteMachineItems, enableJournal: options.enableJournal, dryRun: options.dryRun });
 });
 program
     .command('switch [project]')
@@ -1780,6 +1883,15 @@ worktreeCmd
     const globalOpts = program.opts();
     runWorktreeMerge({ branch, message: options.message, dryRun: options.dryRun, cwd: globalOpts.cwd });
 });
+worktreeCmd
+    .command('check')
+    .description('Pre-merge conflict detection: which parallel lanes touch overlapping files, and who owns them (exit 3 if overlaps found)')
+    .option('--base <ref>', 'Base ref each lane is diffed against (default: current branch)')
+    .option('--json', 'Emit the full risk report as JSON')
+    .action((options) => {
+    const globalOpts = program.opts();
+    runWorktreeCheck({ baseRef: options.base, json: options.json, cwd: globalOpts.cwd });
+});
 // --- federation cloud ---
 const federationCmd = program
     .command('federation')
@@ -2022,6 +2134,20 @@ program
     const globalOpts = program.opts();
     runRunProfile(profileName, { ...options, cwd: globalOpts.cwd });
 });
+{
+    // Friendly trailing-global-option error must run before Commander parses:
+    // with positional options enabled, Commander itself would reject a trailing
+    // --cwd/--project as a bare "unknown option" otherwise.
+    const argvTail = process.argv.slice(2);
+    const guardCommand = findCommandFromArgv(argvTail);
+    if (guardCommand) {
+        const trailingError = trailingGlobalOptionError(argvTail, guardCommand);
+        if (trailingError) {
+            console.error(`Error: ${trailingError}`);
+            process.exit(1);
+        }
+    }
+}
 program.parseAsync(process.argv).catch((err) => {
     console.error(err);
     process.exit(1);

package/dist/commands/add-step.js

@@ -5,7 +5,7 @@ export function runAddStep(planId, text, options = {}) {
     requireInitialized(process.cwd());
     validateCliInput(text);
     try {
-        const result = addStep({ planId, text, assignee: options.assignee });
+        const result = addStep({ planId, text, assignee: options.assignee, estimatedEffort: options.estimatedEffort, actualEffort: options.actualEffort });
         console.log(`✔ Step added: [${result.stepId}] ${text}`);
         console.log(`  Plan [${result.planId}] progress: ${result.doneSteps}/${result.totalSteps} steps done`);
     }

package/dist/commands/bootstrap.js

@@ -1,9 +1,8 @@
 import fs from 'node:fs';
-import readline from 'node:readline/promises';
-import { stdin as input, stdout as output } from 'node:process';
 import { memoryExists } from '../core/io.js';
 import { applyBootstrapImport, renderBootstrapInterview, renderBootstrapSummary, runBootstrapProfile, uninstallBootstrapImport, } from '../core/bootstrap.js';
 import { BootstrapInterviewAnswerSchema } from '../core/schema.js';
+import { confirmAction } from './confirm.js';
 export async function runBootstrap(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (!memoryExists(cwd)) {
@@ -92,28 +91,5 @@ function loadBootstrapInterviewAnswers(filepath) {
     }
     return parsed.map((entry) => BootstrapInterviewAnswerSchema.parse(entry));
 }
-async function confirmBootstrapAction(question, yes) {
-    if (yes) {
-        return;
-    }
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        console.error(`Error: ${question} Re-run with --yes in non-interactive mode.`);
-        process.exit(1);
-    }
-    const rl = readline.createInterface({ input, output });
-    try {
-        const answer = await rl.question(`${question} [y/N] `);
-        if (answer.trim().toLowerCase() !== 'y') {
-            console.error('Cancelled.');
-            process.exit(1);
-        }
-    }
-    catch (error) {
-        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
-        process.exit(1);
-    }
-    finally {
-        rl.close();
-    }
-}
+const confirmBootstrapAction = confirmAction;
 //# sourceMappingURL=bootstrap.js.map

package/dist/commands/check-security-mcp.js

@@ -2,7 +2,9 @@ import { memoryExists, memoryPath } from '../core/io.js';
 import { loadConfig } from '../core/config.js';
 import { SecurityCache } from '../core/security-cache.js';
 import { querySocketScores } from '../core/socket-client.js';
-import { evaluateBatch, worstDecision } from '../core/security-scoring.js';
+import { applyMode, evaluateBatch, worstDecision, } from '../core/security-scoring.js';
+import { parsePackageSpec } from '../core/security-packages.js';
+import { collectPackages } from '../core/security-extract.js';
 import { createTrap } from '../core/operations/memory-write.js';
 export async function handleCheckSecurity(args, cwd) {
     if (!memoryExists(cwd)) {
@@ -13,20 +15,35 @@ export async function handleCheckSecurity(args, cwd) {
     if (!preinstall?.enabled) {
         return { content: [{ type: 'text', text: 'Security preinstall checks are not enabled. Set security.preinstall.enabled: true in config.yaml.' }] };
     }
-    const packagesStr = String(args.packages ?? '').trim();
-    if (!packagesStr) {
-        return { content: [{ type: 'text', text: 'Error: missing required argument: packages' }] };
-    }
     const ecosystem = (String(args.ecosystem ?? 'npm').trim());
-    const packageNames = packagesStr.split(',').map(p => p.trim()).filter(Boolean);
+    const modeArg = args.mode ? String(args.mode).trim() : undefined;
+    const effectiveMode = (modeArg === 'enforced' || modeArg === 'advisory')
+        ? modeArg
+        : (preinstall.mode ?? 'advisory');
+    let packageSpecs;
+    try {
+        packageSpecs = collectPackages({
+            packages: args.packages ? String(args.packages) : undefined,
+            requirements: args.requirements ? String(args.requirements) : undefined,
+            lockfile: args.lockfile ? String(args.lockfile) : undefined,
+            defaultEcosystem: ecosystem,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: `Error: ${msg}` }] };
+    }
+    if (packageSpecs.length === 0) {
+        return { content: [{ type: 'text', text: 'Error: no packages specified (pass --packages, --requirements, or --lockfile).' }] };
+    }
     // Build cache
     const cachePath = memoryPath('security/cache.json', cwd);
     const cache = new SecurityCache(cachePath, preinstall.cache_ttl_hours);
     // Separate cached vs uncached
     const queries = [];
     const cachedScores = [];
-    for (const name of packageNames) {
-        const [depname, version] = parsePackageName(name);
+    for (const spec of packageSpecs) {
+        const { depname, version } = parsePackageSpec(spec);
         const cached = cache.get(ecosystem, depname, version);
         if (cached) {
             cachedScores.push(cached);
@@ -55,25 +72,34 @@ export async function handleCheckSecurity(args, cwd) {
     const allScores = [...cachedScores, ...fetchedScores];
     if (allScores.length === 0 && fetchError) {
         const fallback = preinstall.fallback_on_error;
+        const fallbackVerdict = fallback === 'block' ? 'block' : fallback === 'warn' ? 'warn' : 'pass';
+        const effective = applyMode(fallbackVerdict, effectiveMode);
         return {
-            content: [{ type: 'text', text: `Socket MCP error: ${fetchError}\nFallback policy: ${fallback}` }],
-            structuredContent: { error: fetchError, fallback, decision: fallback === 'block' ? 'block' : fallback === 'warn' ? 'warn' : 'pass' },
+            content: [{ type: 'text', text: `Socket MCP error: ${fetchError}\nFallback policy: ${fallback} (mode=${effectiveMode}) → ${effective.toUpperCase()}` }],
+            structuredContent: {
+                error: fetchError,
+                fallback,
+                mode: effectiveMode,
+                decision: fallbackVerdict,
+                effective_decision: effective,
+            },
         };
     }
     const verdicts = evaluateBatch(allScores, preinstall);
-    const worst = worstDecision(verdicts);
+    const intrinsic = worstDecision(verdicts);
+    const effective = applyMode(intrinsic, effectiveMode);
     // Build text output
     const lines = [];
     if (fetchError) {
-        lines.push(`\u26A0 Socket MCP partial error: ${fetchError} (${cachedScores.length} results from cache)`);
+        lines.push(`⚠ Socket MCP partial error: ${fetchError} (${cachedScores.length} results from cache)`);
         lines.push('');
     }
     for (const v of verdicts) {
-        const icon = v.decision === 'pass' ? '\u2705' : v.decision === 'warn' ? '\u26A0\uFE0F' : '\uD83D\uDED1';
-        lines.push(`${icon} ${v.ecosystem}/${v.package}@${v.version} \u2014 composite=${v.composite} [${v.decision.toUpperCase()}]`);
+        const icon = v.decision === 'pass' ? '✅' : v.decision === 'warn' ? '⚠️' : '🛑';
+        lines.push(`${icon} ${v.ecosystem}/${v.package}@${v.version} — composite=${v.composite} [${v.decision.toUpperCase()}]`);
         lines.push(`   SC=${v.scores.supplyChain} vuln=${v.scores.vulnerability} qual=${v.scores.quality} maint=${v.scores.maintenance} lic=${v.scores.license}`);
         for (const r of v.reasons) {
-            lines.push(`   \u2192 ${r}`);
+            lines.push(`   → ${r}`);
         }
     }
     // Auto-create traps for WARN and BLOCK verdicts
@@ -102,7 +128,12 @@ export async function handleCheckSecurity(args, cwd) {
         lines.push(`Created ${trapsCreated.length} security trap(s): ${trapsCreated.join(', ')}`);
     }
     lines.push('');
-    lines.push(`Overall decision: ${worst.toUpperCase()}`);
+    if (intrinsic !== effective) {
+        lines.push(`Verdict: ${intrinsic.toUpperCase()} — downgraded to ${effective.toUpperCase()} by mode=${effectiveMode}.`);
+    }
+    else {
+        lines.push(`Verdict: ${intrinsic.toUpperCase()} (mode=${effectiveMode})`);
+    }
     return {
         content: [{ type: 'text', text: lines.join('\n') }],
         structuredContent: {
@@ -121,25 +152,11 @@ export async function handleCheckSecurity(args, cwd) {
                     license: v.scores.license,
                 },
             })),
-            decision: worst,
+            decision: intrinsic,
+            effective_decision: effective,
+            mode: effectiveMode,
             ...(fetchError ? { fetch_error: fetchError } : {}),
         },
     };
 }
-function parsePackageName(name) {
-    // Handle scoped packages: @scope/pkg@version
-    if (name.startsWith('@')) {
-        const lastAt = name.lastIndexOf('@', name.length - 1);
-        if (lastAt > 0) {
-            return [name.slice(0, lastAt), name.slice(lastAt + 1)];
-        }
-        return [name, 'latest'];
-    }
-    // Regular: pkg@version
-    if (name.includes('@')) {
-        const [depname, version] = name.split('@');
-        return [depname, version || 'latest'];
-    }
-    return [name, 'latest'];
-}
 //# sourceMappingURL=check-security-mcp.js.map