@specship/specship-darwin-arm64 0.29.0 → 0.30.0

package/lib/dist/bin/specship.js

@@ -61,6 +61,7 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const directory_1 = require("../directory");
+const hook_output_1 = require("../activation/hook-output");
 const worktree_1 = require("../sync/worktree");
 const shimmer_progress_1 = require("../ui/shimmer-progress");
 const glyphs_1 = require("../ui/glyphs");
@@ -69,6 +70,7 @@ const updater_1 = require("../update/updater");
 const resolve_latest_1 = require("../update/resolve-latest");
 const run_installer_1 = require("../update/run-installer");
 const wasm_runtime_flags_1 = require("../extraction/wasm-runtime-flags");
+const parse_warnings_1 = require("../extraction/parse-warnings");
 // Lazy-load heavy modules (SpecShip, runInstaller) to keep CLI startup fast.
 async function loadSpecShip() {
     try {
@@ -118,133 +120,6 @@ async function loadServerPackage() {
  * The JSONL ingest watcher now ships inside `@specship/specship-server`
  * itself — `createServer({ ingest: true })` starts it. No separate package.
  */
-/**
- * Claude Code's slug encoding (every non-alphanumeric char → '-') is lossy,
- * so decoding by mapping '-' back to '/' mangles any path containing
- * hyphens/dots/underscores. Recover real paths from `~/.claude.json` (its
- * `projects` object is keyed by real absolute paths), then from a `"cwd"`
- * value in the slug's newest transcript, before falling back to the lossy
- * decode. Mirrors `server/src/ingest/project-paths.ts`
- * (REQ-SLUGRES-004) — the server package depends on this one, so the CLI
- * can't import it.
- */
-function buildClaudeSlugIndex() {
-    const bySlug = new Map();
-    try {
-        const raw = fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8');
-        const parsed = JSON.parse(raw);
-        for (const realPath of Object.keys(parsed.projects ?? {})) {
-            bySlug.set(realPath.replace(/[^A-Za-z0-9]/g, '-'), realPath);
-        }
-    }
-    catch { /* missing or malformed — sniff/fallback below still work */ }
-    return bySlug;
-}
-function sniffClaudeSlugCwd(claudeRoot, slug) {
-    const dir = path.join(claudeRoot, slug);
-    let newest = null;
-    try {
-        for (const f of fs.readdirSync(dir, { withFileTypes: true })) {
-            if (!f.isFile() || !f.name.toLowerCase().endsWith('.jsonl'))
-                continue;
-            const st = fs.statSync(path.join(dir, f.name));
-            if (!newest || st.mtimeMs > newest.mtimeMs)
-                newest = { file: f.name, mtimeMs: st.mtimeMs };
-        }
-    }
-    catch {
-        return null;
-    }
-    if (!newest)
-        return null;
-    try {
-        const fd = fs.openSync(path.join(dir, newest.file), 'r');
-        let chunk;
-        try {
-            const buf = Buffer.alloc(64 * 1024);
-            const read = fs.readSync(fd, buf, 0, buf.length, 0);
-            chunk = buf.toString('utf8', 0, read);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-        const m = /"cwd"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(chunk);
-        if (!m)
-            return null;
-        let cwd = JSON.parse(`"${m[1]}"`);
-        // Accept the cwd or an ancestor of it — sessions may record a subdir.
-        for (;;) {
-            if (cwd.replace(/[^A-Za-z0-9]/g, '-') === slug)
-                return cwd;
-            const parent = path.dirname(cwd);
-            if (parent === cwd)
-                return null;
-            cwd = parent;
-        }
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Auto-pick a default project for `specship desktop` when the user
- * didn't pass `-p` and the cwd isn't initialized either. Walks
- * `~/.claude/projects/*` (Claude Code's per-project transcript dirs),
- * resolves each slug back to a real path, and returns the most-recently-
- * touched one that's still on disk AND has been `specship init`'d.
- *
- * Returns null when nothing qualifies — the server boots projectless and
- * the desktop UI prompts the user to pick.
- */
-async function pickRecentInitializedProject() {
-    const claudeRoot = path.join(os.homedir(), '.claude', 'projects');
-    let entries;
-    try {
-        entries = fs.readdirSync(claudeRoot, { withFileTypes: true });
-    }
-    catch {
-        return null;
-    }
-    const slugIndex = buildClaudeSlugIndex();
-    const candidates = [];
-    for (const ent of entries) {
-        if (!ent.isDirectory())
-            continue;
-        const slug = ent.name;
-        const decoded = slugIndex.get(slug) ??
-            sniffClaudeSlugCwd(claudeRoot, slug) ??
-            (slug.startsWith('-') ? '/' + slug.slice(1).replace(/-/g, '/') : slug);
-        try {
-            const st = fs.statSync(decoded);
-            if (!st.isDirectory())
-                continue;
-        }
-        catch {
-            continue;
-        }
-        if (!(0, directory_1.isInitialized)(decoded))
-            continue;
-        // Use the newest .jsonl mtime in the slug dir as the activity signal.
-        let lastTouched = 0;
-        try {
-            const files = fs.readdirSync(path.join(claudeRoot, slug), { withFileTypes: true });
-            for (const f of files) {
-                if (!f.isFile() || !f.name.toLowerCase().endsWith('.jsonl'))
-                    continue;
-                try {
-                    const st = fs.statSync(path.join(claudeRoot, slug, f.name));
-                    if (st.mtimeMs > lastTouched)
-                        lastTouched = st.mtimeMs;
-                }
-                catch { /* ignore */ }
-            }
-        }
-        catch { /* ignore */ }
-        candidates.push({ decoded, lastTouched });
-    }
-    candidates.sort((a, b) => b.lastTouched - a.lastTouched);
-    return candidates[0]?.decoded ?? null;
-}
 // Dynamic import helper — tsc compiles import() to require() in CJS mode,
 // which fails for ESM-only packages. This bypasses the transformation.
 // eslint-disable-next-line @typescript-eslint/no-implied-eval
@@ -333,9 +208,79 @@ function main() {
         .name('specship')
         .description('Code intelligence and knowledge graph for any codebase')
         .version(packageJson.version);
+    /**
+     * Commands that run on every agent turn / tool call (the installed hooks, the
+     * status line) or as the long-lived MCP server. They must stay exactly as
+     * fast as before, so the installed-agents record is never checked on them.
+     */
+    const AGENT_RECORD_SKIP_COMMANDS = new Set([
+        'serve',
+        'cheatsheet',
+        'spec-nudge',
+        'steer-nudge',
+        'search-intercept',
+        'statusline',
+        'sync',
+        'sync-if-dirty',
+        'mark-dirty',
+        'auto-sync',
+        'hook',
+    ]);
+    // REQ-AGENTSWITCH-006.A2: any other command rebuilds a missing/unreadable
+    // installed-agents record from the agents' configs. A present record costs one
+    // file read and no write. Silent: the record never blocks or fails a command.
+    /**
+     * Commands that never auto-set-up a newly used agent (REQ-AGENTSWITCH-008):
+     * the install commands do it explicitly, and the MCP server detects its
+     * agent from the client name in its own session instead.
+     */
+    const AUTO_MIGRATE_SKIP_COMMANDS = new Set(['install', 'uninstall', 'serve', 'update']);
+    program.hook('preAction', (_root, actionCommand) => {
+        let top = actionCommand;
+        while (top.parent && top.parent !== program)
+            top = top.parent;
+        // REQ-AGENTSWITCH-008: a `specship` command in a supported agent's shell —
+        // typed by the user, run by a hook, or by the git hook a commit from that
+        // shell fires — sets SpecShip up for that agent if the record doesn't list
+        // it here. Unknown agent → no file access; recorded agent → one small read.
+        // The notice goes to stderr so hook stdout stays the host's JSON.
+        if (!AUTO_MIGRATE_SKIP_COMMANDS.has(top.name())) {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const { agentFromEnv } = require('../agents/detect');
+                const agent = agentFromEnv();
+                if (agent !== 'unknown') {
+                    // eslint-disable-next-line @typescript-eslint/no-require-imports
+                    const { maybeAutoMigrate, migrationLine } = require('../installer/auto-migrate');
+                    const line = migrationLine(maybeAutoMigrate(agent));
+                    if (line)
+                        process.stderr.write(line + '\n');
+                }
+            }
+            catch {
+                /* advisory — never blocks or fails a command */
+            }
+        }
+        if (AGENT_RECORD_SKIP_COMMANDS.has(top.name()))
+            return;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { ensureAgentRecord } = require('../installer/agent-record');
+            ensureAgentRecord(process.cwd());
+        }
+        catch {
+            /* advisory */
+        }
+    });
     // =============================================================================
     // Helper Functions
     // =============================================================================
+    /** Every supported agent's display name, from the target registry (REQ-AGENTSWITCH-012). */
+    function agentNames() {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { allTargets } = require('../installer/targets/registry');
+        return allTargets().map((t) => t.displayName).join(', ');
+    }
     /**
      * Resolve project path from argument or current directory
      * Walks up parent directories to find nearest initialized SpecShip project
@@ -496,7 +441,7 @@ function main() {
             if (!sp)
                 return;
             console.log();
-            console.log(chalk.bold('Try this first — ask Claude:'));
+            console.log(chalk.bold('Try this first — ask your coding agent:'));
             console.log('  ' + chalk.cyan(sp.prompt));
             console.log(chalk.dim("  (it'll explore the index instead of reading files)"));
         }
@@ -540,6 +485,10 @@ function main() {
         else {
             clack.log.warn('No files found to index');
         }
+        // Parse-error regions that may have swallowed declarations (REQ-HTMLLEX-003).
+        const parseWarning = (0, parse_warnings_1.formatParseWarningSummary)(result.filesWithParseWarnings);
+        if (parseWarning)
+            clack.log.warn(parseWarning);
         if (hasErrors) {
             const errorsByCode = new Map();
             for (const err of result.errors) {
@@ -854,10 +803,12 @@ function main() {
             // CLAUDE.md governance findings ride the same SessionStart line
             // (CLAUDEMD-DOC, REQ-CLAUDEMD-003) — silent at zero.
             try {
-                const { readClaudeMdAudit } = require('../claudemd/audit');
+                const { readClaudeMdAudit, auditMemoryFiles } = require('../claudemd/audit');
                 const audit = readClaudeMdAudit(projectPath);
                 if (audit && audit.findings.length > 0) {
-                    console.log(`⚠ ${audit.findings.length} CLAUDE.md finding(s) — review with /specship:check claudemd`);
+                    // Name the memory file(s) the findings are about (REQ-AGENTSWITCH-003).
+                    const files = auditMemoryFiles(audit).join(' and ');
+                    console.log(`⚠ ${audit.findings.length} ${files} finding(s) — review with /specship:check claudemd`);
                 }
             }
             catch {
@@ -997,6 +948,10 @@ function main() {
                     parts.push(`${specWarnings} warning${specWarnings === 1 ? '' : 's'}`);
                 clack.log.warn(`Spec parse: ${parts.join(', ')}`);
             }
+            // Parse-error regions that may have swallowed declarations (REQ-HTMLLEX-003).
+            const parseWarning = (0, parse_warnings_1.formatParseWarningSummary)(result.filesWithParseWarnings);
+            if (parseWarning)
+                clack.log.warn(parseWarning);
             pushDriftNotices(result);
             await pushJiraDriftComments(cg, result);
             await pushJiraAutoPublish(result);
@@ -1026,6 +981,10 @@ function main() {
         // working tree (e.g. a nested worktree borrowing the main checkout's index).
         const startPath = path.resolve(pathArg || process.cwd());
         const worktreeMismatch = (0, worktree_1.detectWorktreeIndexMismatch)(startPath, projectPath);
+        // The agent whose shell ran this command, from its launcher env vars
+        // (REQ-AGENTSWITCH-007). Report-only: detection never changes anything.
+        const { agentFromEnv, agentDisplayName } = await Promise.resolve().then(() => __importStar(require('../agents/detect')));
+        const currentAgent = agentFromEnv(process.env);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
                 if (options.json) {
@@ -1035,11 +994,13 @@ function main() {
                         projectPath,
                         indexPath: (0, directory_1.getSpecShipDir)(projectPath),
                         lastIndexed: null,
+                        currentAgent,
                     }));
                     return;
                 }
                 console.log(chalk.bold('\nSpecShip Status\n'));
                 info(`Project: ${projectPath}`);
+                info(`Agent: ${agentDisplayName(currentAgent)}`);
                 warn('Not initialized');
                 info('Run "specship init" to initialize');
                 return;
@@ -1050,6 +1011,9 @@ function main() {
             const changes = cg.getChangedFiles();
             const backend = cg.getBackend();
             const journalMode = cg.getJournalMode();
+            // Recorded index revision vs live HEAD (REQ-MULTIDEV-004). Report-only:
+            // nothing here syncs because HEAD moved.
+            const freshness = cg.getIndexFreshness();
             // JSON output mode
             if (options.json) {
                 const lastIndexedMs = cg.getLastIndexedAt();
@@ -1075,6 +1039,8 @@ function main() {
                     worktreeMismatch: worktreeMismatch
                         ? { worktreeRoot: worktreeMismatch.worktreeRoot, indexRoot: worktreeMismatch.indexRoot }
                         : null,
+                    ...(0, worktree_1.indexFreshnessJsonFields)(freshness),
+                    currentAgent,
                 }));
                 cg.destroy();
                 return;
@@ -1082,9 +1048,16 @@ function main() {
             console.log(chalk.bold('\nSpecShip Status\n'));
             // Project info
             console.log(chalk.cyan('Project:'), projectPath);
+            console.log(chalk.cyan('Agent:  '), agentDisplayName(currentAgent));
             if (worktreeMismatch) {
                 warn((0, worktree_1.worktreeMismatchWarning)(worktreeMismatch));
             }
+            if (freshness) {
+                console.log(chalk.cyan('Indexed:'), (0, worktree_1.formatRevision)(freshness.indexedBranch, freshness.indexedCommit));
+                console.log(chalk.cyan('HEAD:   '), (0, worktree_1.formatRevision)(freshness.headBranch, freshness.headCommit));
+                if (freshness.stale)
+                    warn((0, worktree_1.indexStaleNotice)(freshness));
+            }
             console.log();
             // Index stats
             console.log(chalk.bold('Index Statistics:'));
@@ -1163,7 +1136,7 @@ function main() {
      */
     program
         .command('statusline')
-        .description('Print a SpecShip status-line segment (reads Claude Code JSON on stdin)')
+        .description('Print a SpecShip status-line segment (Claude-only surface — reads the status-line JSON the agent pipes on stdin)')
         .action(async () => {
         const { buildSegment } = await Promise.resolve().then(() => __importStar(require('../statusline/index')));
         let raw = '';
@@ -1548,7 +1521,7 @@ function main() {
         .command('capture')
         .description('Capture a lesson/anti-pattern as a human-gated memory rule (lesson text on stdin).')
         .requiredOption('--title <title>', 'short title for the lesson')
-        .option('--target <target>', 'where apply would write it: "memory" (portable ~/.claude note, default) or "claude-md" (project CLAUDE.md)', 'memory')
+        .option('--target <target>', 'where apply would write it: "memory" (portable user memory, default) or "claude-md" (the project memory file of the active agent)', 'memory')
         .option('--path <projectRoot>', 'project root (default: cwd)')
         .option('-j, --json', 'output the created proposal as JSON')
         .action(async (options) => {
@@ -1578,7 +1551,7 @@ function main() {
             }
             else {
                 info(`Captured lesson as proposal ${p.contentHash.slice(0, 12)} (${p.state}): ${p.title}`);
-                info(`Target: ${p.targetKind === 'claude_md' ? 'project CLAUDE.md' : 'portable ~/.claude memory note'} — nothing written yet.`);
+                info(`Target: ${memoryTargetLabel(p, projectPath)} — nothing written yet.`);
                 info('Review with `specship reflect`; manage applied memory rules with `specship memory list`.');
             }
             cg.destroy();
@@ -1588,6 +1561,20 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * Where a memory_rule proposal writes, named from its own target path so each
+     * agent's memory file shows (REQ-AGENTSWITCH-003).
+     */
+    function memoryTargetLabel(p, projectRoot) {
+        if (p.targetKind !== 'claude_md') {
+            const dir = path.dirname(p.targetPath);
+            const home = os.homedir();
+            return `portable memory note in ${dir.startsWith(home) ? '~' + dir.slice(home.length) : dir}`;
+        }
+        const file = path.basename(p.targetPath);
+        const inProject = !path.relative(path.resolve(projectRoot), p.targetPath).startsWith('..');
+        return inProject ? `project ${file}` : `portable user ${file}`;
+    }
     // Body text of a memory_rule proposal's payload (the note or the CLAUDE.md block).
     function memoryRuleBody(p) {
         if (p.payload.kind === 'memory_note')
@@ -1623,7 +1610,7 @@ function main() {
                 return;
             }
             for (const p of items) {
-                const target = p.targetKind === 'claude_md' ? 'CLAUDE.md' : 'memory note';
+                const target = p.targetKind === 'claude_md' ? path.basename(p.targetPath) : 'memory note';
                 success(`${p.contentHash.slice(0, 12)}  [${target}]  ${p.title}`);
             }
             cg.destroy();
@@ -2260,7 +2247,7 @@ function main() {
         .option('-j, --json', 'Output as JSON')
         .option('--strict', 'Treat every check as gating for this run only (nothing read from or written to config)')
         .option('--enable-gate <checks...>', 'Persist gating for the named checks into specship.config.json, then run the gate')
-        .option('--since <ref>', 'Evaluate only requirements whose links or spec files touch files changed since <ref> (drift + behaviour; fitness and maintainability stay repo-global)')
+        .option('--since <ref>', 'Evaluate only requirements whose links or spec files touch files changed since <ref> (drift + behaviour; fitness and maintainability stay repo-global), and report links that resolved at <ref> but this branch broke (branchBroken)')
         .action(async (pathArg, options) => {
         const projectPath = resolveProjectPath(pathArg);
         try {
@@ -2300,6 +2287,8 @@ function main() {
             }
             const { default: SpecShip } = await loadSpecShip();
             const cg = await SpecShip.open(projectPath);
+            // The branch-broken check parses link targets at the ref (REQ-MULTIDEV-002).
+            await cg.prepareEnforce(scope);
             // --strict gates everything for this run only (REQ-ENFORCE-004.A2).
             const r = options.strict
                 ? cg.getEnforce(enforce.strictEnforceConfig(), scope)
@@ -2312,7 +2301,8 @@ function main() {
             console.log(chalk.bold('\nEnforcement gate\n'));
             if (scope) {
                 console.log(chalk.dim(`  scoped to ${scope.changedFiles.length} file(s) changed since ${scope.since}` +
-                    ' — drift and behaviour are link-scoped; fitness and maintainability are repo-global analyses and ran unscoped.\n'));
+                    ' — drift and behaviour are link-scoped; branchBroken compares against that ref;' +
+                    ' fitness, maintainability and undeclaredLinks are repo-global and ran unscoped.\n'));
             }
             for (const c of r.checks) {
                 const tag = c.gating ? chalk.dim('[gating]') : chalk.dim('[advisory]');
@@ -2390,7 +2380,7 @@ function main() {
                 root = process.cwd();
             }
             else {
-                root = await pickRecentInitializedProject();
+                root = await (await Promise.resolve().then(() => __importStar(require('../agents/recent-project')))).pickRecentInitializedProject();
             }
             const port = options.port ? parseInt(options.port, 10) : 4242;
             const host = options.host ?? '127.0.0.1';
@@ -2431,7 +2421,7 @@ function main() {
                 console.error(chalk.green((0, glyphs_1.getGlyphs)().ok) + ` Dashboard: ${handle.url}/`);
             }
             if (options.ingest !== false) {
-                console.error(chalk.dim('  Claude Code transcript ingest watcher active'));
+                console.error(chalk.dim(`  Transcript ingest watcher active (${agentNames()})`));
             }
             if (options.mcp) {
                 if (!root) {
@@ -2533,7 +2523,7 @@ function main() {
                 // Use stderr so stdout stays clean for any piped/stdio usage.
                 console.error(chalk.bold('\nSpecShip MCP Server\n'));
                 console.error(chalk.blue((0, glyphs_1.getGlyphs)().info) + ' Use --mcp flag to start the MCP server');
-                console.error('\nTo use with Claude Code, add to your MCP configuration:');
+                console.error('\nTo use it from your coding agent, add to its MCP configuration (or run `specship install --print-config --target <agent>`):');
                 console.error(chalk.dim(`
 {
   "mcpServers": {
@@ -2570,8 +2560,8 @@ function main() {
         .option('-p, --path <path>', 'Project path (default: cwd, else your most recent initialized project)')
         .option('--port <n>', 'HTTP port (default 4242)')
         .option('--host <h>', 'HTTP bind host (default 127.0.0.1)')
-        .option('--ingest', 'Enable the Claude Code JSONL transcript watcher', true)
-        .option('--no-ingest', 'Disable the Claude Code JSONL transcript watcher')
+        .option('--ingest', 'Enable the agent transcript watcher (every supported agent)', true)
+        .option('--no-ingest', 'Disable the agent transcript watcher')
         .option('--web-dir <path>', 'Path to a built desktop SPA (index.html lives here); auto-detected by default from the bundled ui/dist')
         .option('--no-web', 'Run headless (API only, no dashboard SPA)')
         .option('--no-watch', 'Disable the file watcher (no auto-sync; useful on slow filesystems like WSL2 /mnt drives)')
@@ -2975,7 +2965,7 @@ function main() {
      */
     program
         .command('install')
-        .description('Install specship MCP server into Claude Code')
+        .description('Install the specship MCP server into your coding agent (choose one with --target)')
         .option('-l, --location <where>', 'Install location: "global" or "local". Default: prompt (local)')
         .option('-y, --yes', 'Non-interactive: defaults to --location=local (the only question an interactive install asks)')
         .option('--no-permissions', 'Skip writing the auto-allow permissions list (written by default)')
@@ -2984,30 +2974,47 @@ function main() {
         .option('--path <repo>', 'Target repo to wire and initialize (default: current directory). Project-local files and the .specship index land there')
         .option('--with-jira', 'Enable the optional JIRA integration (talks to your Atlassian instance; off by default — the core install is 100% local)')
         .option('--with-designer', 'Enable the optional Designer integration (EXPERIMENTAL — drives claude.ai/design via a debug Chrome session and may break without notice; off by default)')
-        .option('--statusline', '(default) Wire the SpecShip status-line segment into Claude; never overwrites an existing status line')
+        .option('--statusline', '(default; Claude-only surface) Wire the SpecShip status-line segment; never overwrites an existing status line')
         .option('--skip-statusline', 'Do not add the status-line segment (it is added by default)')
         .option('--skip-index', 'Do not index the current project (it is indexed by default)')
-        .option('--print-config', 'Print the MCP config snippet and exit (no file writes). Claude Code by default; `--target gemini` prints the Gemini CLI settings snippet')
+        .option('--print-config', 'Print the target agent\'s MCP config snippet and exit (no file writes); pick the agent with --target')
         // -t/--target SELECTS the agents to wire (GEMINI-TARGET-DOC, REQ-GEMINI-002)
         // and also picks the snippet --print-config prints. The legacy spellings
         // ("claude" / "auto" / "all" / "none") keep their Claude-only meanings, so
         // existing invocations — including our own offline-install scripts — behave
         // exactly as before.
         .option('-t, --target <ids>', 'Agents to wire, comma-separated: "claude" (default) | "gemini" | "claude,gemini". Also selects the snippet `--print-config` prints. Legacy: "auto"/"all" = claude, "none" = skip')
-        .option('--trust', 'Gemini only (REQ-GEMINI-009): write ~/.gemini/policies/specship.toml auto-allowing SpecShip\'s read-only tools. Opt-in — an admin policy still wins and run_shell_command is unaffected')
+        .option('--trust', `Gemini only (REQ-GEMINI-009): write ~/${(0, hook_output_1.hostTraitsFor)('gemini').configDir}/policies/specship.toml auto-allowing SpecShip's read-only tools. Opt-in — an admin policy still wins and run_shell_command is unaffected`)
+        // REQ-AGENTSWITCH-006.A3: reinstall for every recorded agent. Run by
+        // `specship update` (through the new binary) and the bundle installer; exits
+        // 3 when nothing is recorded so the bundle installer can fall back.
+        .addOption(new commander_1.Option('--replay-recorded', 'Reinstall for every agent in the installed-agents record').hideHelp())
         .action(async (opts) => {
+        if (opts.replayRecorded) {
+            const { reinstallRecordedAgents } = await Promise.resolve().then(() => __importStar(require('../installer')));
+            const reports = reinstallRecordedAgents();
+            if (reports.length === 0) {
+                info('No agents recorded — nothing to reinstall.');
+                process.exit(3);
+            }
+            for (const r of reports) {
+                if (r.status === 'reinstalled')
+                    success(r.detail);
+                else
+                    warn(r.detail);
+            }
+            if (reports.some((r) => r.status === 'failed'))
+                process.exit(1);
+            return;
+        }
         if (opts.printConfig) {
             const loc = (opts.location === 'local' ? 'local' : 'global');
-            // Only `gemini` selects the non-default snippet; every other value
-            // (including the vestigial "auto" / "all" / "none") stays Claude, so
-            // existing invocations print exactly what they printed before.
-            if (opts.target === 'gemini') {
-                const { geminiTarget } = await Promise.resolve().then(() => __importStar(require('../installer/targets/gemini')));
-                process.stdout.write(geminiTarget.printConfig(loc));
-                return;
-            }
-            const { claudeTarget } = await Promise.resolve().then(() => __importStar(require('../installer/targets/claude')));
-            process.stdout.write(claudeTarget.printConfig(loc));
+            // A registered target id prints that target's snippet; any other value
+            // (including the vestigial "auto" / "all" / "none") prints the default
+            // host's, so existing invocations print exactly what they printed before.
+            const { getTarget } = await Promise.resolve().then(() => __importStar(require('../installer/targets/registry')));
+            const target = getTarget(String(opts.target ?? '')) ?? getTarget(hook_output_1.DEFAULT_HOST_TRAITS.id);
+            process.stdout.write(target.printConfig(loc));
             return;
         }
         // Target repo (INSTALL-SCOPE-DOC, REQ-SCOPE-002): the project-local
@@ -3260,7 +3267,12 @@ function main() {
             }
         }
         catch { /* store unavailable → omit the line */ }
-        const payload = buildCheatsheetPayload(process.env, { conventions, openProposals });
+        // SessionStart is sent by every host, so the launcher env identifies the
+        // agent; unknown → today's text (REQ-AGENTSWITCH-002).
+        const { agentFromEnv, UNKNOWN_AGENT } = await Promise.resolve().then(() => __importStar(require('../agents/detect')));
+        const agent = agentFromEnv(process.env);
+        const traits = agent === UNKNOWN_AGENT ? undefined : (0, hook_output_1.hostTraitsFor)(agent);
+        const payload = buildCheatsheetPayload(process.env, { conventions, openProposals }, traits);
         if (payload)
             process.stdout.write(JSON.stringify(payload) + '\n');
         process.exit(0);
@@ -3276,7 +3288,7 @@ function main() {
      */
     program
         .command('spec-nudge')
-        .description('Internal hook: nudge toward spec-author on feature/bug intent (UserPromptSubmit)')
+        .description(`Internal hook: nudge toward spec-author on feature/bug intent (${hook_output_1.DEFAULT_HOST_TRAITS.fallbackPromptEvent})`)
         .action(async () => {
         const shouldNudge = (prompt) => {
             const text = (prompt || '').trim();
@@ -3319,7 +3331,7 @@ function main() {
      */
     program
         .command('steer-nudge')
-        .description('Internal hook: steer flow/structure questions to specship_explore (UserPromptSubmit)')
+        .description(`Internal hook: steer flow/structure questions to specship_explore (${hook_output_1.DEFAULT_HOST_TRAITS.fallbackPromptEvent})`)
         .action(async () => {
         // Prefer the hook payload's cwd (Claude Code / Gemini CLI both send it
         // on stdin) so the check targets the project the prompt belongs to, not
@@ -3350,7 +3362,7 @@ function main() {
             catch { /* telemetry must never break the hook */ }
         }
         const { buildSteeringNudge } = await Promise.resolve().then(() => __importStar(require('../activation/steering')));
-        const additionalContext = buildSteeringNudge(cwd, process.env, undefined, traits.toolPrefix);
+        const additionalContext = buildSteeringNudge(cwd, traits, process.env);
         if (additionalContext) {
             process.stdout.write(buildHookAdditionalContext(additionalContext, payload.hookEventName, traits.fallbackPromptEvent));
         }
@@ -3394,10 +3406,6 @@ function main() {
                 }
             }
             catch { /* not JSON — strict path stays off, advisory still works via payload */ }
-            const DENY_TOOLS = new Set(traits.denyEligibleTools);
-            const shellCommand = traits.shellTool !== null && toolName === traits.shellTool && typeof toolInput.command === 'string'
-                ? toolInput.command
-                : null;
             const { resolveSetting } = await Promise.resolve().then(() => __importStar(require('../config/runtime-settings')));
             const strict = traits.supportsBeforeToolDeny &&
                 resolveSetting('SPECSHIP_GEMINI_STRICT', cwd, process.env, os.homedir()) === '1';
@@ -3409,11 +3417,10 @@ function main() {
                 cwd,
                 sessionId: payload.sessionId,
                 transcriptPath: payload.transcriptPath,
-                specshipToolMarkers: traits.specshipToolMarkers,
-                transcriptFormat: traits.transcriptFormat,
+                traits,
+                toolName,
+                toolInput,
                 strict,
-                denyEligible: DENY_TOOLS.has(toolName),
-                shellCommand,
                 searchPattern,
             });
             if (result) {
@@ -3443,12 +3450,28 @@ function main() {
         .description('Completely remove SpecShip (wiring, indexes, ~/.specship data, and the binary)')
         .option('-y, --yes', 'Skip the confirmation prompt (also: --force)')
         .option('-f, --force', 'Alias for --yes')
-        .option('--keep-data', 'Only unwire from Claude Code; keep the indexes, ~/.specship data, and the binary')
+        .option('--keep-data', 'Only unwire from the selected agent(s); keep the indexes, ~/.specship data, and the binary')
         .option('-l, --location <where>', 'With --keep-data: which wiring to remove ("global" or "local")')
-        // vestigial — kept so existing `--target claude` invocations keep working.
-        .option('-t, --target <ids>', '(vestigial) accepted: "claude" | "auto" | "all" | "none"')
+        .option('--local', 'Only unwire this project (same as --keep-data --location local); keeps indexes, data and the binary')
+        .option('--global', 'Only unwire the user-wide install (same as --keep-data --location global); keeps indexes, data and the binary')
+        .option('-t, --target <ids>', 'Agents to unwire: "claude" | "gemini" | "claude,gemini". With --keep-data/--local/--global the default is claude; a full purge with no --target unwires every agent')
         .action(async (opts) => {
         const { runUninstaller } = await Promise.resolve().then(() => __importStar(require('../installer')));
+        // `--local` / `--global` (REQ-AGENTSWITCH-008): the undo command an
+        // automatic agent setup prints — wiring-only, never the full purge.
+        if (opts.local && opts.global) {
+            error('Use only one of --local and --global.');
+            process.exit(1);
+        }
+        if (opts.local || opts.global) {
+            const where = opts.local ? 'local' : 'global';
+            if (opts.location && opts.location !== where) {
+                error(`--${where} conflicts with --location ${opts.location}.`);
+                process.exit(1);
+            }
+            opts.location = where;
+            opts.keepData = true;
+        }
         if (opts.location && opts.location !== 'global' && opts.location !== 'local') {
             error(`--location must be "global" or "local" (got "${opts.location}").`);
             process.exit(1);
@@ -4368,6 +4391,9 @@ function main() {
             detect: () => (0, updater_1.detectInstallMethod)(__dirname, installDir),
             resolveLatest: (method) => (0, resolve_latest_1.resolveLatestVersion)(method),
             runInstaller: (method) => (0, run_installer_1.runInstaller)(method, { installDir, binDir }),
+            // REQ-AGENTSWITCH-006.A3: the old code is still loaded in this
+            // process, so the reinstall runs through the NEW binary.
+            reinstallAgents: () => replayRecordedAgents((0, updater_1.detectInstallMethod)(__dirname, installDir), binDir),
             installDir,
             binDir,
         }, { check: options.check });
@@ -4380,6 +4406,25 @@ function main() {
         if (result.exitCode !== 0)
             process.exit(result.exitCode);
     });
+    /**
+     * Run `specship install --replay-recorded` on the freshly installed binary and
+     * return its output lines. Exit 3 means nothing was recorded.
+     */
+    function replayRecordedAgents(method, binDir) {
+        const bundleLink = path.join(binDir, 'specship');
+        const bin = method === 'bundle' && fs.existsSync(bundleLink) ? bundleLink : 'specship';
+        return new Promise((resolve, reject) => {
+            const { execFile } = require('child_process');
+            execFile(bin, ['install', '--replay-recorded'], { encoding: 'utf8', shell: process.platform === 'win32', windowsHide: true }, (err, stdout) => {
+                const lines = String(stdout ?? '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+                const code = err?.code;
+                if (!err || code === 3)
+                    resolve(lines);
+                else
+                    reject(new Error(lines.at(-1) ?? err.message));
+            });
+        });
+    }
     /**
      * specship jira — connect SpecShip to a JIRA instance (REQ-JIRA-001).
      *