brainclaw 0.29.2 → 1.5.3

package/dist/commands/session-start.js

@@ -1,35 +1,66 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { memoryExists, resolveEntityDir } from '../core/io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from '../core/migration.js';
-import { buildOperationalIdentity, saveCurrentSession } from '../core/identity.js';
-import { requireMinimumTrustLevel, requireRegisteredAgentIdentity, resolveCurrentModel } from '../core/agent-registry.js';
-import { buildContext } from '../core/context.js';
+import { buildOperationalIdentity, loadAllSessions, saveCurrentSession } from '../core/identity.js';
+import { requireMinimumTrustLevel, resolveCurrentModel, resolveOrAutoRegisterAgentIdentity } from '../core/agent-registry.js';
+import { buildContext, renderContextPromptTemplate } from '../core/context.js';
+import { writeContextMarker } from '../core/freshness.js';
 import { saveRuntimeNote, generateRuntimeNoteId } from '../core/runtime.js';
-import { nowISO, generateId } from '../core/ids.js';
+import { nowISO, generateId, generateIdWithLabel } from '../core/ids.js';
 import { appendAuditEntry } from '../core/audit.js';
-import { SessionSnapshotSchema } from '../core/schema.js';
+import { releaseStaleClaimsFromOtherAgents } from '../core/claims.js';
+import { SessionSnapshotSchema, CandidateSchema, HandoffSchema, RuntimeNoteSchema } from '../core/schema.js';
 import { auditLocalAgentWorkspaceFiles } from '../core/agent-files.js';
 import { buildAgentInventory, loadAgentInventory, saveAgentInventory, diffInventory } from '../core/agent-inventory.js';
+import { checkMemoryPressure } from '../core/gc-semantic.js';
+import { pullSignalsFromLinkedProjects, markSignalProcessed } from '../core/federation-transport.js';
+import { saveCandidate, generateCandidateIdWithLabel } from '../core/candidates.js';
+import { mutateState } from '../core/state.js';
 function sessionsDir(cwd) {
     return resolveEntityDir('sessions', cwd ?? process.cwd(), 'read');
 }
 function sessionSnapshotPath(sessionId, cwd) {
     return path.join(sessionsDir(cwd), `${sessionId}.json`);
 }
-function createHash(data) {
-    let hash = 0;
-    for (let i = 0; i < data.length; i++) {
-        const chr = data.charCodeAt(i);
-        hash = ((hash << 5) - hash) + chr;
-        hash |= 0;
-    }
-    return (hash >>> 0).toString(16).padStart(8, '0');
-}
 export function runSessionStart(options = {}) {
     try {
-        const snapshot = startSession(options);
+        const snapshot = startSession({
+            ...options,
+            maintenanceMode: options.maintenanceMode ?? 'full',
+        });
+        // --include-context: output full project context (replaces separate `brainclaw context` call)
+        if (options.includeContext) {
+            try {
+                const cwd = options.cwd ?? process.cwd();
+                // Find the previous session for the same agent to auto-surface a context diff on resume.
+                // We exclude the session just created so we always point at the prior one.
+                const previousSession = loadAllSessions(cwd)
+                    .find((s) => s.agent === snapshot.agent && s.session_id !== snapshot.session_id);
+                const contextResult = buildContext({
+                    target: options.context,
+                    agent: snapshot.agent,
+                    cwd,
+                    sinceSession: previousSession?.session_id,
+                });
+                console.log(renderContextPromptTemplate(contextResult, false));
+                writeContextMarker({
+                    read_at: nowISO(),
+                    memory_version: contextResult.memory_version,
+                    host_id: contextResult.current_host,
+                    target: options.context,
+                    project: contextResult.project,
+                    all_hosts: false,
+                }, cwd);
+            }
+            catch (ctxErr) {
+                // Context build failure should not block session start output
+                console.error(`⚠ Context build failed: ${ctxErr instanceof Error ? ctxErr.message : String(ctxErr)}`);
+            }
+            return;
+        }
         if (options.json) {
             console.log(JSON.stringify(snapshot, null, 2));
             return;
@@ -53,6 +84,12 @@ export function runSessionStart(options = {}) {
                 console.warn(`⚠ ${line}`);
             }
         }
+        if (snapshot.stale_claims_released) {
+            console.warn(`⚠ Auto-released ${snapshot.stale_claims_released.length} stale claim(s):`);
+            for (const c of snapshot.stale_claims_released) {
+                console.warn(`  ${c.agent} → ${c.scope}`);
+            }
+        }
     }
     catch (e) {
         console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
@@ -63,7 +100,7 @@ export function startSession(options = {}) {
     if (!memoryExists(options.cwd)) {
         throw new Error('.brainclaw/ not found. Run `brainclaw init` first.');
     }
-    const registered = requireRegisteredAgentIdentity({
+    const { identity: registered, auto_registered: autoRegistered } = resolveOrAutoRegisterAgentIdentity({
         agentName: options.agent,
         agentId: options.agentId,
         cwd: options.cwd,
@@ -72,13 +109,7 @@ export function startSession(options = {}) {
     });
     requireMinimumTrustLevel(registered, 'contributor');
     const actor = buildOperationalIdentity(registered.agent_name, options.cwd, { agentId: registered.agent_id });
-    // Capture initial context snapshot
-    let initialContextHash;
-    try {
-        const ctx = buildContext({ target: options.context, agent: actor.agent, cwd: options.cwd });
-        initialContextHash = createHash(JSON.stringify(ctx.selected));
-    }
-    catch { /* non-fatal */ }
+    const maintenanceMode = options.maintenanceMode ?? 'fast';
     // Capture git HEAD SHA for later handoff generation
     let gitSha;
     try {
@@ -93,7 +124,6 @@ export function startSession(options = {}) {
         agent_id: actor.agent_id,
         started_at: nowISO(),
         context_target: options.context,
-        initial_context_hash: initialContextHash,
         git_sha: gitSha,
         ...(model ? { model } : {}),
     };
@@ -102,6 +132,14 @@ export function startSession(options = {}) {
     if (!fs.existsSync(dir))
         fs.mkdirSync(dir, { recursive: true });
     saveVersionedJsonFile('session_snapshot', sessionSnapshotPath(snapshot.session_id, options.cwd), SessionSnapshotSchema.parse(snapshot));
+    // Resolve git branch and worktree for session tracking
+    let currentBranch;
+    let currentWorktreePath;
+    try {
+        currentBranch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8', cwd: options.cwd ?? process.cwd() }).trim();
+        currentWorktreePath = execSync('git rev-parse --show-toplevel', { encoding: 'utf-8', cwd: options.cwd ?? process.cwd() }).trim();
+    }
+    catch { /* non-fatal — not a git repo */ }
     saveCurrentSession({
         schema_version: 2,
         session_id: snapshot.session_id,
@@ -110,6 +148,12 @@ export function startSession(options = {}) {
         agent: actor.agent,
         agent_id: actor.agent_id,
         host_id: actor.host_id,
+        user: process.env.USER || process.env.USERNAME || os.userInfo().username || undefined,
+        pid: process.pid,
+        model: model ?? undefined,
+        branch: currentBranch,
+        worktree_path: currentWorktreePath,
+        isolation_mode: 'shared-checkout',
     }, options.cwd);
     // Write session_start runtime note
     const noteId = generateRuntimeNoteId();
@@ -125,27 +169,143 @@ export function startSession(options = {}) {
         visibility: 'shared',
         note_type: 'session_start',
     }, options.cwd);
-    appendAuditEntry({ action: 'session_start', actor: actor.agent, actor_id: actor.agent_id, item_id: snapshot.session_id, item_type: 'session' }, options.cwd);
+    appendAuditEntry({ action: 'session_start', actor: actor.agent, actor_id: actor.agent_id, item_id: snapshot.session_id, item_type: 'session', session_id: snapshot.session_id, host_id: actor.host_id }, options.cwd);
     const agentGitHygiene = auditLocalAgentWorkspaceFiles(options.cwd ?? process.cwd());
-    // Inventory reconciliation — detect new/disappeared agents on this machine
+    // Non-critical maintenance work lives behind the full mode only.
     let inventoryAdvisory;
-    try {
-        const previousInventory = loadAgentInventory();
-        const currentInventory = buildAgentInventory();
-        const diff = diffInventory(previousInventory, currentInventory);
-        saveAgentInventory(currentInventory);
-        const lines = [];
-        if (diff.appeared.length > 0)
-            lines.push(`New agents detected: ${diff.appeared.join(', ')}`);
-        if (diff.disappeared.length > 0)
-            lines.push(`Agents no longer detected: ${diff.disappeared.join(', ')}`);
-        for (const vc of diff.version_changed) {
-            lines.push(`${vc.name} version changed: ${vc.from ?? '?'} → ${vc.to ?? '?'}`);
+    if (maintenanceMode === 'full') {
+        try {
+            const previousInventory = loadAgentInventory();
+            const currentInventory = buildAgentInventory();
+            const diff = diffInventory(previousInventory, currentInventory);
+            saveAgentInventory(currentInventory);
+            const lines = [];
+            if (diff.appeared.length > 0)
+                lines.push(`New agents detected: ${diff.appeared.join(', ')}`);
+            if (diff.disappeared.length > 0)
+                lines.push(`Agents no longer detected: ${diff.disappeared.join(', ')}`);
+            for (const vc of diff.version_changed) {
+                lines.push(`${vc.name} version changed: ${vc.from ?? '?'} → ${vc.to ?? '?'}`);
+            }
+            if (lines.length > 0)
+                inventoryAdvisory = lines;
         }
-        if (lines.length > 0)
-            inventoryAdvisory = lines;
+        catch { /* non-fatal — inventory scan failure should not block session start */ }
+    }
+    // Shared checkout detection: warn if other active sessions share the same worktree
+    let sharedCheckoutWarning;
+    if (currentWorktreePath) {
+        try {
+            const allSessions = loadAllSessions(options.cwd);
+            const ttlMs = 4 * 60 * 60 * 1000; // 4h
+            const now = Date.now();
+            const otherSessions = allSessions.filter(s => s.session_id !== snapshot.session_id
+                && s.worktree_path === currentWorktreePath
+                && (now - Date.parse(s.last_seen_at)) <= ttlMs
+                && (!s.pid || isPidAlive(s.pid)));
+            if (otherSessions.length > 0) {
+                sharedCheckoutWarning = {
+                    worktree_path: currentWorktreePath,
+                    other_sessions: otherSessions.map(s => ({
+                        session_id: s.session_id,
+                        agent: s.agent,
+                        user: s.user,
+                        branch: s.branch,
+                        pid: s.pid,
+                    })),
+                };
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    // Stale claim auto-release. Phase 4 slice pln#388 stp_e2b10ab4: pass
+    // the new session_id so same-agent prior-session claims can be swept
+    // too — without it, a crash-recovered agent would keep its own orphaned
+    // claims hanging until 24h.
+    let staleClaimsReleased;
+    if (maintenanceMode === 'full') {
+        try {
+            const staleResult = releaseStaleClaimsFromOtherAgents(actor.agent, options.cwd, snapshot.session_id);
+            if (staleResult.released.length > 0) {
+                staleClaimsReleased = staleResult.released.map(c => ({ id: c.id, agent: c.agent, scope: c.scope }));
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    // Memory pressure check: hint agent to run bclaw_compact if store is large
+    let memoryPressure;
+    if (maintenanceMode === 'full') {
+        try {
+            const pressure = checkMemoryPressure(options.cwd);
+            if (pressure.memory_pressure) {
+                memoryPressure = pressure;
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    // Materialize incoming federation signals from linked projects
+    if (maintenanceMode === 'full') {
+        try {
+            const federationSignals = pullSignalsFromLinkedProjects(options.cwd);
+            let materialized = 0;
+            for (const signal of federationSignals) {
+                try {
+                    const origin = `remote:${signal.from.project_name}:${signal.from.agent_name}`;
+                    if (signal.type === 'candidate') {
+                        const parsed = CandidateSchema.safeParse(signal.payload);
+                        if (parsed.success) {
+                            const { id, short_label } = generateCandidateIdWithLabel(options.cwd);
+                            saveCandidate({
+                                ...parsed.data,
+                                id,
+                                short_label,
+                                created_at: nowISO(),
+                                source: undefined, // remote federation signal — treated as 'human' (legacy default)
+                                star_count: 0,
+                                starred_by: [],
+                                usage_count: 0,
+                                usage_events: [],
+                                status: 'pending',
+                            }, options.cwd);
+                        }
+                    }
+                    else if (signal.type === 'handoff') {
+                        const parsed = HandoffSchema.safeParse(signal.payload);
+                        if (parsed.success) {
+                            const { id, short_label } = generateIdWithLabel('open_handoffs', options.cwd);
+                            mutateState((state) => {
+                                state.open_handoffs.push({
+                                    ...parsed.data,
+                                    id,
+                                    short_label,
+                                    created_at: nowISO(),
+                                    tags: [...(parsed.data.tags ?? []), origin],
+                                });
+                            }, options.cwd);
+                        }
+                    }
+                    else if (signal.type === 'runtime_note') {
+                        const parsed = RuntimeNoteSchema.safeParse(signal.payload);
+                        if (parsed.success) {
+                            saveRuntimeNote({
+                                ...parsed.data,
+                                id: generateRuntimeNoteId(),
+                                created_at: nowISO(),
+                                tags: [...(parsed.data.tags ?? []), origin],
+                            }, options.cwd);
+                        }
+                    }
+                    markSignalProcessed(signal.from.project_path, signal.id);
+                    materialized++;
+                }
+                catch { /* skip this signal — do not block session start */ }
+            }
+            if (materialized > 0) {
+                console.log(`✔ Materialized ${materialized} federation signal(s) from linked projects`);
+            }
+        }
+        catch { /* Non-fatal — federation pull failure should not block session start */ }
     }
-    catch { /* non-fatal — inventory scan failure should not block session start */ }
     return {
         ...snapshot,
         ...(agentGitHygiene.isGitRepo && (agentGitHygiene.missingGitignorePaths.length > 0 || agentGitHygiene.trackedPaths.length > 0)
@@ -157,8 +317,21 @@ export function startSession(options = {}) {
             }
             : {}),
         ...(inventoryAdvisory ? { inventory_advisory: inventoryAdvisory } : {}),
+        ...(sharedCheckoutWarning ? { shared_checkout_warning: sharedCheckoutWarning } : {}),
+        ...(staleClaimsReleased ? { stale_claims_released: staleClaimsReleased } : {}),
+        ...(memoryPressure ? { memory_pressure: memoryPressure } : {}),
+        ...(autoRegistered ? { auto_registered: true } : {}),
     };
 }
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export function loadSessionSnapshot(sessionId, cwd) {
     const p = sessionSnapshotPath(sessionId, cwd);
     if (!fs.existsSync(p))

package/dist/commands/setup-security.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryExists, memoryPath, ensureMemoryDir } from '../core/io.js';
+import { loadConfig, saveConfig } from '../core/config.js';
+import { generateBashGuard, generatePowerShellGuard, generatePipBashGuard } from '../core/security-guard.js';
+export function runSetupSecurity(options = {}) {
+    const cwd = options.cwd;
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const config = loadConfig(cwd);
+    const mode = options.mode ?? 'advisory';
+    // Enable preinstall in config
+    if (!config.security) {
+        config.security = { mode: 'warn', strict_redaction: false, block_sensitive_paths: true };
+    }
+    config.security.preinstall = {
+        enabled: true,
+        mode,
+        thresholds: {
+            composite_pass: 70,
+            composite_warn: 50,
+            supply_chain_block: 30,
+            vulnerability_block: 20,
+        },
+        weights: {
+            supply_chain: 0.35,
+            vulnerability: 0.30,
+            quality: 0.15,
+            maintenance: 0.15,
+            license: 0.05,
+        },
+        cache_ttl_hours: 24,
+        fallback_on_error: 'warn',
+        allowlist: [],
+        denylist: [],
+        socket_endpoint: 'https://mcp.socket.dev/',
+    };
+    saveConfig(config, cwd);
+    // Resolve brainclaw binary path
+    const brainclawBin = resolveBrainclawBin(cwd);
+    // Generate wrapper scripts
+    const guardDir = memoryPath('security/bin', cwd);
+    ensureMemoryDir(cwd);
+    if (!fs.existsSync(guardDir)) {
+        fs.mkdirSync(guardDir, { recursive: true });
+    }
+    // npm guard (bash)
+    const npmBashPath = path.join(guardDir, 'npm');
+    fs.writeFileSync(npmBashPath, generateBashGuard(brainclawBin), { mode: 0o755 });
+    // npm guard (PowerShell)
+    const npmPs1Path = path.join(guardDir, 'npm.ps1');
+    fs.writeFileSync(npmPs1Path, generatePowerShellGuard(brainclawBin));
+    // pip guard (bash)
+    const pipBashPath = path.join(guardDir, 'pip');
+    fs.writeFileSync(pipBashPath, generatePipBashGuard(brainclawBin), { mode: 0o755 });
+    // pip guard (PowerShell)
+    const pipPs1Path = path.join(guardDir, 'pip.ps1');
+    fs.writeFileSync(pipPs1Path, generatePowerShellGuard(brainclawBin).replace('} else { "npm" }', '} else { "pip" }'));
+    console.log(`\u2705 Security gate enabled (mode: ${mode})`);
+    console.log('');
+    console.log('Generated wrapper scripts:');
+    console.log(`  ${npmBashPath}`);
+    console.log(`  ${npmPs1Path}`);
+    console.log(`  ${pipBashPath}`);
+    console.log(`  ${pipPs1Path}`);
+    console.log('');
+    console.log('To activate, prepend the guard directory to your PATH:');
+    console.log(`  export PATH="${guardDir}:$PATH"    # bash/zsh`);
+    console.log(`  $env:PATH = "${guardDir};$env:PATH"  # PowerShell`);
+    console.log('');
+    console.log('Or add it to your shell profile for persistent activation.');
+    console.log('');
+    console.log(`Mode: ${mode}`);
+    if (mode === 'advisory') {
+        console.log('  Advisory mode: warnings and traps are created but installs are not blocked.');
+        console.log('  Switch to enforced mode: brainclaw setup --security --mode enforced');
+    }
+    else {
+        console.log('  Enforced mode: risky installs will be blocked (exit code 1).');
+    }
+}
+function resolveBrainclawBin(cwd) {
+    // Try to find brainclaw in common locations
+    const candidates = [
+        'brainclaw',
+        path.resolve(cwd ?? process.cwd(), 'node_modules/.bin/brainclaw'),
+        path.resolve(cwd ?? process.cwd(), 'dist/cli.js'),
+    ];
+    for (const c of candidates) {
+        try {
+            if (fs.existsSync(c))
+                return c;
+        }
+        catch {
+            // continue
+        }
+    }
+    // Default to just 'brainclaw' and hope it's in PATH
+    return 'brainclaw';
+}
+//# sourceMappingURL=setup-security.js.map

package/dist/commands/setup.js

@@ -7,7 +7,7 @@ import { detectAiAgent } from '../core/ai-agent-detection.js';
 import { buildAiSurfaceInventory, renderAiSurfaceUsageHints } from '../core/ai-surface-inventory.js';
 import { buildMachineProfile, saveMachineProfile, loadMachineProfile } from '../core/machine-profile.js';
 import { buildAgentInventory, saveAgentInventory, loadAgentInventory } from '../core/agent-inventory.js';
-import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursorMcpConfig, ensureWindsurfMcpConfig, ensureAntigravityMcpConfig, ensureContinueUserMcpConfig, ensureCodexMcpConfig, writeDetectedAgentAutoConfig, describeAutoConfigWrite, ensureGitignoreEntries, collectWorkspaceGitignoreEntries, } from '../core/agent-files.js';
+import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursorMcpConfig, ensureWindsurfMcpConfig, ensureAntigravityMcpConfig, ensureContinueUserMcpConfig, ensureContinueUserPermissions, ensureCodexMcpConfig, writeDetectedAgentAutoConfig, describeAutoConfigWrite, ensureGitignoreEntries, collectWorkspaceGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
 import { MEMORY_DIR, memoryExists, ensureMemoryDir } from '../core/io.js';
 import { saveConfig, defaultConfig } from '../core/config.js';
 import { readSetupState, resolveHomeDir, writeSetupState } from '../core/setup-state.js';
@@ -26,6 +26,10 @@ export const ALL_KNOWN_AGENTS = [
     'continue',
     'roo',
     'openclaw',
+    'nanoclaw',
+    'nemoclaw',
+    'picoclaw',
+    'zeroclaw',
 ];
 const BRAINCLAW_ASCII = [
     '',
@@ -224,6 +228,9 @@ export function runGlobalInstall(selectedAgents, env = process.env) {
         const r = ensureContinueUserMcpConfig(home);
         if (r && (r.created || r.updated))
             written.push(r.filePath);
+        const perms = ensureContinueUserPermissions(home);
+        if (perms && (perms.created || perms.updated))
+            written.push(perms.filePath);
     }
     if (selectedAgents.includes('codex')) {
         const r = ensureCodexMcpConfig(home, env);
@@ -272,7 +279,7 @@ export async function initReposAndConfigureAgents(selectedRepos, selectedAgents,
             }
         }
         if (gitignoreEntries.size > 0) {
-            ensureGitignoreEntries(repo.path, [...gitignoreEntries]);
+            ensureGitignoreEntries(repo.path, [...gitignoreEntries, ...BRAINCLAW_EXCLUSIVE_DIRECTORIES]);
             console.log(`  ✔ Updated .gitignore with generated agent files (${[...gitignoreEntries].join(', ')})`);
         }
     }
@@ -390,7 +397,8 @@ export async function runSetup(options = {}) {
     // Step 4: Agent detection & selection
     const detectedAi = detectAiAgent(env);
     const detectedName = detectedAi?.name;
-    const detectedSurfaces = buildAiSurfaceInventory();
+    const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
+    const detectedSurfaces = testMode ? [] : buildAiSurfaceInventory();
     console.log('');
     if (detectedName) {
         console.log(`Detected AI agent: ${detectedName}`);
@@ -452,6 +460,8 @@ export async function runSetup(options = {}) {
     // Step 6: Init repos + configure agents
     console.log('\n→ Initialising repositories and configuring agents...');
     const { initialisedRepos, configActions } = await initReposAndConfigureAgents(selectedRepos, selectedAgents, env);
+    // Step 7: VS Code extension
+    installVscodeExtension();
     // Save state
     writeSetupState({
         completed_at: new Date().toISOString(),
@@ -459,8 +469,36 @@ export async function runSetup(options = {}) {
         initialised_repos: initialisedRepos,
         global_configs_written: selectedAgents,
     }, env);
-    // Step 7: Reload reminder
+    // Step 8: Reload reminder
     printReloadReminder(detectedName);
     void configActions;
 }
+// ─── VS Code extension auto-install ──────────────────────────────────────────
+function installVscodeExtension() {
+    // Find the bundled vsix
+    const vsixPath = resolveVsixPath();
+    if (!vsixPath)
+        return;
+    // Check if `code` CLI is available
+    const codeAvailable = spawnSync('code', ['--version'], { stdio: 'ignore', timeout: 5000 });
+    if (codeAvailable.status !== 0)
+        return; // VS Code not installed or not in PATH — skip silently
+    // Install the extension
+    const result = spawnSync('code', ['--install-extension', vsixPath, '--force'], { stdio: 'pipe', timeout: 30000 });
+    if (result.status === 0) {
+        console.log('  ✔ Installed Brainclaw VS Code extension');
+    }
+}
+function resolveVsixPath() {
+    const thisDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/i, '$1'));
+    // 1. Bundled in dist/ (npm install) — dist/commands/setup.js → dist/brainclaw-vscode.vsix
+    const distVsix = path.join(thisDir, '..', 'brainclaw-vscode.vsix');
+    if (fs.existsSync(distVsix))
+        return distVsix;
+    // 2. Dev mode: vscode-extension/ directory
+    const devVsix = path.join(thisDir, '..', '..', 'vscode-extension', 'brainclaw-vscode-0.1.0.vsix');
+    if (fs.existsSync(devVsix))
+        return devVsix;
+    return undefined;
+}
 //# sourceMappingURL=setup.js.map

package/dist/commands/stale.js

@@ -0,0 +1,109 @@
+/**
+ * `brainclaw stale` — minimal operator flow over the staleness detector.
+ *
+ * Phase 4 Sprint 1 Lane A step 4 (pln#390 / stp_18d6bc03). Lets operators
+ * list stale items and apply the canonical v1.0 action without having to
+ * remember per-entity syntax.
+ *
+ * Subcommands:
+ *   list                — print the stale report (same as doctor + board)
+ *   resolve <id>        — apply the canonical action for the entity type:
+ *                           plan        → transition status 'dropped'
+ *                           handoff     → transition status 'closed'
+ *                           candidate   → transition status 'rejected'
+ *                           trap        → transition status 'resolved'
+ *                           runtime_note → remove (archive via entity-operations)
+ */
+import { listCandidates } from '../core/candidates.js';
+import { removeEntity, transitionEntity, } from '../core/entity-operations.js';
+import { listRuntimeNotes } from '../core/runtime.js';
+import { loadState } from '../core/state.js';
+import { detectStaleness, staleSummary, } from '../core/staleness.js';
+/** Resolve the canonical transition target (or removal) per entity kind. */
+const RESOLVE_ACTIONS = {
+    plan: { kind: 'transition', entity: 'plan', to: 'dropped' },
+    handoff: { kind: 'transition', entity: 'handoff', to: 'closed' },
+    candidate: { kind: 'transition', entity: 'candidate', to: 'rejected' },
+    trap: { kind: 'transition', entity: 'trap', to: 'resolved' },
+    runtime_note: { kind: 'remove', entity: 'runtime_note' },
+};
+function buildReport(cwd) {
+    const state = loadState(cwd);
+    const pending = listCandidates('pending', cwd);
+    const notes = listRuntimeNotes(undefined, cwd);
+    return detectStaleness(state.plan_items, state.known_traps, state.open_handoffs, pending, Date.now(), notes);
+}
+export function runStaleList(options = {}) {
+    const report = buildReport(options.cwd);
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    if (report.warnings.length === 0) {
+        console.log('✔ No stale items detected.');
+        return;
+    }
+    console.log(`⚠ ${staleSummary(report)}`);
+    console.log('');
+    for (const w of report.warnings) {
+        console.log(`  [${w.entity} ${w.id}] ${w.reason}`);
+        console.log(`    → brainclaw stale resolve ${w.id}   # or: ${w.suggested_action}`);
+    }
+}
+export function runStaleResolve(id, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const report = buildReport(cwd);
+    const warning = report.warnings.find((w) => w.id === id);
+    if (!warning) {
+        console.error(`Error: ${id} is not currently flagged stale.`);
+        console.error('Run `brainclaw stale list` to see the current warnings.');
+        process.exit(1);
+    }
+    const action = RESOLVE_ACTIONS[warning.entity];
+    try {
+        if (action.kind === 'transition') {
+            const result = transitionEntity(action.entity, id, action.to, cwd, 'resolved via brainclaw stale resolve');
+            if (options.json) {
+                console.log(JSON.stringify({ resolved: id, ...result }, null, 2));
+            }
+            else {
+                console.log(`✔ ${warning.entity} ${id}: ${result.from} → ${action.to}`);
+            }
+        }
+        else {
+            const result = removeEntity(action.entity, id, cwd);
+            if (options.json) {
+                console.log(JSON.stringify({ resolved: id, ...result }, null, 2));
+            }
+            else {
+                const verb = result.purged ? 'purged' : 'archived';
+                console.log(`✔ ${warning.entity} ${id}: ${verb}`);
+            }
+        }
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`Error: could not resolve ${id} — ${msg}`);
+        process.exit(1);
+    }
+}
+export function runStale(subcommand, arg, options = {}) {
+    const effective = subcommand ?? 'list';
+    switch (effective) {
+        case 'list':
+            runStaleList(options);
+            return;
+        case 'resolve': {
+            if (!arg) {
+                console.error('Error: `brainclaw stale resolve <id>` requires an entity id.');
+                process.exit(1);
+            }
+            runStaleResolve(arg, options);
+            return;
+        }
+        default:
+            console.error(`Error: unknown subcommand '${effective}'. Use: list | resolve <id>.`);
+            process.exit(1);
+    }
+}
+//# sourceMappingURL=stale.js.map