ccnav 1.0.0 → 1.1.1

package/README.md

@@ -6,15 +6,24 @@ Works on Windows, macOS and Linux with Node 20 or later. Everything that differs
 
 ## Install
 
-From a checkout (any OS):
+```sh
+npm install -g ccnav    # the -g matters
+ccnav --install-shell   # optional: leave your shell in the session's directory afterwards
+```
+
+Without `-g`, npm treats the current folder as a project and puts the command in
+`./node_modules/.bin`, which is not on PATH — the install succeeds and `ccnav` still
+reports `command not found`. If that happens after a `-g` install, npm's global bin
+folder is missing from PATH; `npm prefix -g` prints the folder whose `bin` belongs there.
+
+From a checkout instead:
 
 ```sh
 npm install
 npm link                # puts `ccnav` on PATH
-ccnav --install-shell   # optional: leave your shell in the session's directory afterwards
 ```
 
-Or build a tarball once and install it anywhere, e.g. on a Mac:
+Or build a tarball once and install it anywhere:
 
 ```sh
 npm pack                        # -> ccnav-1.0.0.tgz
@@ -23,7 +32,23 @@ npm install -g ./ccnav-1.0.0.tgz
 
 `--install-shell` writes a function to the right file for your shell: the PowerShell `$PROFILE` on Windows, `~/.zshrc` for zsh (macOS default), `~/.bash_profile` (macOS) or `~/.bashrc` (Linux) for bash, and `~/.config/fish/functions/ccnav.fish` for fish. Running it again replaces the block rather than adding a second one.
 
-New tabs (`t`) use Windows Terminal, iTerm2, WezTerm, kitty, GNOME Terminal or Konsole. Terminal.app gets a new window, because real tabs need Accessibility permission.
+New tabs (`t`) use Windows Terminal, iTerm2, WezTerm, kitty, GNOME Terminal or Konsole. Terminal.app gets a new window, because real tabs need Accessibility permission. On macOS the first new tab asks for permission to control the terminal; if it is refused, allow it again under System Settings → Privacy & Security → Automation.
+
+On Windows, PowerShell 7 preserves forwarded arguments including quotes and shell characters. With the built-in Windows PowerShell 5.1 fallback, arguments containing quotes, shell characters or line breaks are rejected because its npm command shim cannot pass them safely.
+
+## Agents
+
+Sessions are listed whether or not the agent that wrote them is still installed, so an
+old machine's transcripts stay visible. Resuming one whose agent is missing offers to
+install it:
+
+```
+codex is not installed. Install it now with "npm install -g @openai/codex"? (y/N)
+```
+
+Answer `y` and ccnav runs that install, then launches the agent so you can sign in and
+finish its own setup. Answer `n` and nothing is installed. `claude` maps to
+`@anthropic-ai/claude-code` and `codex` to `@openai/codex`.
 
 ## Use
 
@@ -34,7 +59,38 @@ ccnav --codex          only Codex sessions
 ccnav --list           print sessions and exit
 ccnav --json           print sessions as JSON and exit
 ccnav --model opus     any other arguments are passed to the agent
+ccnav here             new session in the current directory, running unattended
+ccnav here --codex     the same, without being asked which agent
+```
+
+## Start one here
+
+`ccnav here` ignores the session list entirely. It asks which agent, then starts a
+**new** session in the current directory with that agent's permission prompts turned
+off, so it runs unattended:
+
 ```
+New session in /Users/you/project
+
+  1) ◆ claude  claude --dangerously-skip-permissions
+  2) ● codex   codex --dangerously-bypass-approvals-and-sandbox
+
+Which agent? [1]
+```
+
+Pressing enter takes the first agent; `1`/`2` or a name (`codex`, `cl`) picks one.
+`ccnav here --claude` or `--codex` skips the question, and any other arguments go to
+the agent (`ccnav here --claude --model opus`). The exact command is printed before it
+runs, and ctrl-D at the prompt starts nothing.
+
+What those flags mean is worth being clear about. Claude's
+`--dangerously-skip-permissions` bypasses every permission check. Codex's
+`--dangerously-bypass-approvals-and-sandbox` skips approvals *and* runs without a
+sandbox — its own help calls it EXTREMELY DANGEROUS and intends it for environments
+that are already sandboxed. Neither confines the agent to the directory you started in.
+Codex removed `--full-auto` in 0.156, so the sandboxed middle ground is now spelled
+`--ask-for-approval never --sandbox workspace-write` if you would rather edit
+`src/providers/codex.mjs` to use that instead.
 
 | Key | Action |
 |---|---|
@@ -66,7 +122,7 @@ ccnav --model opus     any other arguments are passed to the agent
 | Resume / fork | `claude --resume <id>` / `--fork-session` | `codex resume <id>` / `codex fork <id>` |
 | Hidden | subagent sidechain folders, Desktop scratch workspaces | subagent threads spawned by other sessions |
 
-Only the first and last 256 KB of each transcript are read when listing, so a 21 MB session costs the same as a small one. Full-text search reads whole files.
+Only the first and last 256 KB of each transcript are read when listing, so a 21 MB session costs the same as a small one. Full-text search streams each file in full and can be cancelled while it runs.
 
 Archived sessions move to `~/.claude/ccnav-archive/` or `~/.codex/ccnav-archive/`, keeping the folders they had underneath (`<project>/` for Claude, `YYYY/MM/DD/` for Codex). Moving a file back restores it. Sessions used in the last 10 minutes are never archived, because they may still be open. Archiving a Codex session leaves its line in `session_index.jsonl`; that is harmless but not cleaned up.
 

package/bin/ccnav.mjs

@@ -2,8 +2,8 @@
 import React from 'react';
 import { render } from 'ink';
 import { App } from '../src/app.mjs';
-import { ago, humanSize, listSessions, providerOf, shortPath } from '../src/sessions.mjs';
-import { installShellFunction, launchAgent, reportCwd } from '../src/actions.mjs';
+import { AGENTS, PROVIDERS, ago, humanSize, listSessions, providerOf, shortPath } from '../src/sessions.mjs';
+import { askUser, ensureAgent, installShellFunction, launchAgent, reportCwd } from '../src/actions.mjs';
 
 const args = process.argv.slice(2);
 
@@ -17,6 +17,9 @@ usage:
   ccnav --codex          only Codex sessions
   ccnav --list           print sessions as a table and exit
   ccnav --json           print sessions as JSON and exit
+  ccnav here             skip the picker: start a NEW session in the current
+                         directory, running unattended with no permission prompts
+                         (ccnav here --claude / --codex picks the agent outright)
   ccnav --install-shell  add a shell function (PowerShell, zsh, bash or fish) so
                          your shell is left in the session's directory afterwards
 
@@ -24,6 +27,40 @@ Any other arguments are passed to the agent (e.g. ccnav --model opus).`);
   process.exit(0);
 }
 
+// `ccnav here` never touches the session list: it starts a new one in this directory.
+async function chooseAgent() {
+  if (!process.stdin.isTTY) {
+    console.error('ccnav here needs an interactive terminal, or name the agent: ccnav here --claude');
+    process.exit(1);
+  }
+  console.log(`\nNew session in ${process.cwd()}\n`);
+  AGENTS.forEach((a, i) => {
+    const p = PROVIDERS[a];
+    console.log(`  ${i + 1}) ${p.glyph} ${a.padEnd(7)} ${p.command} ${p.AUTO_ARGS.join(' ')}`);
+  });
+  const answer = await askUser(`\nWhich agent? [1] `);
+  // EOF is not a choice: never start an unattended agent nobody actually asked for.
+  if (answer === null) { console.error('\nNo answer given, nothing started.'); process.exit(1); }
+  if (!answer) return AGENTS[0];
+  const byNumber = AGENTS[Number(answer) - 1];
+  if (byNumber) return byNumber;
+  const byName = AGENTS.find(a => a.startsWith(answer.toLowerCase()));
+  if (byName) return byName;
+  console.error(`Not an agent: ${answer}`);
+  process.exit(1);
+}
+
+if (args[0] === 'here') {
+  const rest = args.slice(1);
+  const named = AGENTS.find(a => rest.includes(`--${a}`));
+  const extra = rest.filter(a => a !== '--' && !AGENTS.some(x => a === `--${x}`));
+  const provider = PROVIDERS[named || await chooseAgent()];
+  if (!await ensureAgent(provider.command)) process.exit(127);
+  const argv = [...provider.AUTO_ARGS, ...extra];
+  console.log(`\n\u2192 ${process.cwd()}\n\u2192 ${provider.command} ${argv.join(' ')}\n`);
+  process.exit(await launchAgent(provider.command, process.cwd(), argv));
+}
+
 if (args.includes('--install-shell')) {
   const { shell, file, reload } = installShellFunction();
   console.log(`ccnav ${shell} function written to ${file}\nto use it now: ${reload}`);
@@ -64,6 +101,9 @@ const { action, session } = choice;
 const provider = providerOf(session);
 const agentArgs = provider.launchArgs(action, session, passthrough);
 
+// The agent may not be installed yet; offer to install it rather than just failing.
+if (!await ensureAgent(provider.command)) process.exit(127);
+
 reportCwd(session.cwd);
 console.log(`\n→ ${session.cwd}\n→ ${provider.command} ${agentArgs.join(' ')}\n`);
 process.exit(await launchAgent(provider.command, session.cwd, agentArgs));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccnav",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Claude Codex Navigator - pick a Claude Code or Codex session and resume it in its directory",
   "scripts": {
     "test": "node --test"
@@ -19,6 +19,7 @@
     "ccnav": "bin/ccnav.mjs"
   },
   "dependencies": {
+    "cross-spawn": "^7.0.6",
     "ink": "^7.1.1",
     "react": "^19.3.0"
   },

package/src/actions.mjs

@@ -1,31 +1,40 @@
 import fs from 'node:fs';
 import path from 'node:path';
-export { copyToClipboard, installShellFunction, launchAgent, openFolder, openInNewTab } from './platform.mjs';
+import readline from 'node:readline';
+import { setImmediate as yieldToUi } from 'node:timers/promises';
+export { askUser, copyToClipboard, ensureAgent, hasCommand, installShellFunction, launchAgent, openFolder, openInNewTab } from './platform.mjs';
 
 // Sessions touched this recently may be open in another terminal.
 export const LIVE_WINDOW_MS = 10 * 60 * 1000;
 export const isMaybeLive = s => Date.now() - s.lastUsed < LIVE_WINDOW_MS;
 
-// Case-insensitive search through the whole transcript; returns a short snippet or null.
-export function searchTranscript(session, query) {
+// Stream the transcript so a search does not block the picker or load whole files into memory.
+export async function searchTranscript(session, query, signal) {
+  if (!query || signal?.aborted) return null;
   const q = query.toLowerCase();
-  let text;
-  try { text = fs.readFileSync(session.file, 'utf8'); } catch { return null; }
-  const lower = text.toLowerCase();
-  const idx = lower.indexOf(q);
-  if (idx < 0) return null;
-  // Prefer the matching string value from the parsed record over raw JSON.
-  const lineStart = text.lastIndexOf('\n', idx) + 1;
-  const lineEnd = text.indexOf('\n', idx);
-  let hay = text.slice(Math.max(0, idx - 60), idx + q.length + 80);
+  const stream = fs.createReadStream(session.file, { encoding: 'utf8', signal });
+  const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
   try {
-    const found = findString(JSON.parse(text.slice(lineStart, lineEnd < 0 ? undefined : lineEnd)), q);
-    if (found) {
-      const i = found.toLowerCase().indexOf(q);
-      hay = found.slice(Math.max(0, i - 60), i + q.length + 80);
+    let count = 0;
+    for await (const line of lines) {
+      if (signal?.aborted) return null;
+      if (++count % 256 === 0) await yieldToUi();
+      const idx = line.toLowerCase().indexOf(q);
+      if (idx < 0) continue;
+      // Prefer the matching string value from the parsed record over raw JSON.
+      let hay = line.slice(Math.max(0, idx - 60), idx + q.length + 80);
+      try {
+        const found = findString(JSON.parse(line), q);
+        if (found) {
+          const i = found.toLowerCase().indexOf(q);
+          hay = found.slice(Math.max(0, i - 60), i + q.length + 80);
+        }
+      } catch { /* fall back to the raw line */ }
+      return hay.replace(/\\[nrt]/g, ' ').replace(/\s+/g, ' ').trim();
     }
-  } catch { /* fall back to raw slice */ }
-  return hay.replace(/\\[nrt]/g, ' ').replace(/\s+/g, ' ').trim();
+  } catch { /* unreadable or cancelled transcript */ }
+  finally { lines.close(); stream.destroy(); }
+  return null;
 }
 
 function findString(v, q) {

package/src/app.mjs

@@ -1,7 +1,7 @@
 import React, { useEffect, useMemo, useState } from 'react';
 import { Box, Text, useApp, useInput, useStdout } from 'ink';
 import { AGENTS, ago, humanSize, providerOf } from './sessions.mjs';
-import { archiveSession, copyToClipboard, isMaybeLive, openFolder, openInNewTab, searchTranscript } from './actions.mjs';
+import { archiveSession, copyToClipboard, hasCommand, isMaybeLive, openFolder, openInNewTab, searchTranscript } from './actions.mjs';
 
 const h = React.createElement;
 
@@ -34,27 +34,33 @@ export function App({ sessions: initialSessions, onChoose, passthrough = [] }) {
   const [mode, setMode] = useState('list');
   const [deep, setDeep] = useState(false);
   const [deepHits, setDeepHits] = useState(null); // Map id -> snippet, for the last deep query
-  const [searching, setSearching] = useState(false);
+  const [searchQuery, setSearchQuery] = useState(null);
   const [showScratch, setShowScratch] = useState(false);
   const [agentIdx, setAgentIdx] = useState(0); // 0 = all agents, then one per agent
   const [message, setMessage] = useState(null); // { text, color }
   const [days, setDays] = useState('30');
 
-  // Deep search reads whole transcripts, so it runs once per submitted query rather than per keystroke.
+  // Search once per submitted query, cancelling when the query or session list changes.
   useEffect(() => {
-    if (!searching) return;
-    const t = setTimeout(() => {
+    if (searchQuery === null) return;
+    const controller = new AbortController();
+    const search = async () => {
       const hits = new Map();
       for (const s of sessions) {
-        const snip = searchTranscript(s, filter);
+        if (controller.signal.aborted) return;
+        const snip = await searchTranscript(s, searchQuery, controller.signal);
         if (snip) hits.set(keyOf(s), snip);
       }
+      if (controller.signal.aborted) return;
       setDeepHits(hits);
-      setSearching(false);
+      setSearchQuery(null);
       setCursor(0);
-    }, 10);
-    return () => clearTimeout(t);
-  }, [searching]);
+    };
+    search();
+    return () => controller.abort();
+  }, [searchQuery, sessions]);
+
+  const searching = searchQuery !== null;
 
   const sorted = useMemo(() => {
     const q = filter.toLowerCase();
@@ -162,11 +168,11 @@ export function App({ sessions: initialSessions, onChoose, passthrough = [] }) {
     setMessage(null);
 
     if (mode === 'filter') {
-      if (key.escape) { setMode('list'); setFilter(''); setDeepHits(null); return; }
-      if (key.tab) { setDeep(d => !d); setDeepHits(null); return; }
-      if (key.return) { setMode('list'); if (deep && filter) setSearching(true); return; }
-      if (key.backspace || key.delete) { setFilter(f => f.slice(0, -1)); setDeepHits(null); setCursor(0); return; }
-      if (input && !key.ctrl && !key.meta) { setFilter(f => f + input); setDeepHits(null); setCursor(0); }
+      if (key.escape) { setMode('list'); setFilter(''); setDeepHits(null); setSearchQuery(null); return; }
+      if (key.tab) { setDeep(d => !d); setDeepHits(null); setSearchQuery(null); return; }
+      if (key.return) { setMode('list'); if (deep && filter) { setDeepHits(null); setSearchQuery(filter); } return; }
+      if (key.backspace || key.delete) { setFilter(f => f.slice(0, -1)); setDeepHits(null); setSearchQuery(null); setCursor(0); return; }
+      if (input && !key.ctrl && !key.meta) { setFilter(f => f + input); setDeepHits(null); setSearchQuery(null); setCursor(0); }
       return;
     }
 
@@ -212,6 +218,11 @@ export function App({ sessions: initialSessions, onChoose, passthrough = [] }) {
     else if (input === 't' && sel && requireDir()) {
       try {
         const p = providerOf(sel);
+        // A new tab has nowhere to report an install prompt, so send them to enter instead.
+        if (!hasCommand(p.command)) {
+          flash(`${p.command} is not installed — press enter to resume and ccnav will offer to install it.`, 'yellow');
+          return;
+        }
         const where = openInNewTab(p.command, sel.cwd, p.launchArgs('resume', sel, passthrough), oneLine(sel.title) || sel.id);
         flash(`Opened "${oneLine(sel.title) || sel.id}" in a new ${where}`);
       } catch (e) { flash(`Could not open a new tab: ${e.message}`, 'red'); }
@@ -229,7 +240,7 @@ export function App({ sessions: initialSessions, onChoose, passthrough = [] }) {
     else if (input === 's') { setSortIdx(i => (i + 1) % SORTS.length); setCursor(0); }
     else if (key.tab) { setAgentIdx(i => (i + 1) % (AGENTS.length + 1)); setCursor(0); }
     else if (input === 'a') { setShowScratch(v => !v); setCursor(0); }
-    else if (key.escape && filter) { setFilter(''); setDeepHits(null); setCursor(0); }
+    else if (key.escape && filter) { setFilter(''); setDeepHits(null); setSearchQuery(null); setCursor(0); }
     else if (input === 'q' || key.escape) exit();
   });
 

package/src/jsonl.mjs

@@ -25,14 +25,17 @@ export function parseLines(text, { dropFirst = false, dropLast = false } = {}) {
 // Returns { stat, head, tail }; tail === head when the file fits in one read.
 export function readEnds(file) {
   const stat = fs.statSync(file);
+  if (!stat.isFile()) throw new Error('not a regular file');
   const fd = fs.openSync(file, 'r');
   try {
     const headLen = Math.min(HEAD_BYTES, stat.size);
     const head = parseLines(readSlice(fd, 0, headLen), { dropLast: headLen < stat.size });
     const tailStart = Math.max(0, stat.size - TAIL_BYTES);
-    const tail = tailStart > headLen
-      ? parseLines(readSlice(fd, tailStart, stat.size - tailStart), { dropFirst: true })
+    const tail = stat.size > HEAD_BYTES
+      ? parseLines(readSlice(fd, tailStart, stat.size - tailStart),
+        { dropFirst: tailStart > 0 && readSlice(fd, tailStart - 1, 1) !== '\n' })
       : head;
+    if (stat.size && !head.length && !tail.length) throw new Error('no readable JSONL records');
     return { stat, head, tail };
   } finally {
     fs.closeSync(fd);

package/src/platform.mjs

@@ -2,7 +2,10 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import readline from 'node:readline';
 import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import crossSpawn from 'cross-spawn';
 
 export const IS_WIN = process.platform === 'win32';
 export const IS_MAC = process.platform === 'darwin';
@@ -11,46 +14,156 @@ const has = cmd => IS_WIN
   ? spawnSync('where', [cmd], { stdio: 'ignore' }).status === 0
   : spawnSync('sh', ['-c', `command -v ${cmd}`], { stdio: 'ignore' }).status === 0;
 
+// Exported so the picker can warn before opening a tab that would only fail.
+export const hasCommand = has;
+
 // POSIX single-quote escaping for building `sh -c` / AppleScript command lines.
 const shq = s => `'${String(s).replace(/'/g, `'\\''`)}'`;
-// Windows command lines: quote args with spaces, strip embedded quotes (args are UUIDs and flags).
-const winq = s => /[\s"]/.test(s) ? `"${String(s).replace(/"/g, '')}"` : s;
 const osaString = s => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+// Encode the command and argv as data before handing them to PowerShell.
+function windowsCommand(cmd, args, { keepOpen = false } = {}) {
+  const spec = Buffer.from(JSON.stringify({ command: cmd, args }), 'utf8').toString('base64');
+  const run = `$ErrorActionPreference = 'Stop'; $spec = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${spec}')) | ConvertFrom-Json; $arguments = [string[]]$spec.args; $global:LASTEXITCODE = 0; try { & $spec.command @arguments } catch { [Console]::Error.WriteLine($_.Exception.Message); exit 127 }`;
+  const script = keepOpen ? run : `${run}; exit $LASTEXITCODE`;
+  const encoded = Buffer.from(script, 'utf16le').toString('base64');
+  const shell = has('pwsh') ? 'pwsh' : 'powershell.exe';
+  return [shell, ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', ...(keepOpen ? ['-NoExit'] : []), '-EncodedCommand', encoded]];
+}
+
+// PowerShell 5 changes quoted arguments when its npm .ps1 shim forwards them to Node.
+// For that fallback, use the .cmd shim and reject values it can reinterpret.
+function legacyWindowsArgs(cmd, args) {
+  if (args.some(arg => /\0/.test(String(arg)))) return null;
+  const extension = path.extname(cmd).toLowerCase();
+  const where = spawnSync('where', [cmd], { encoding: 'utf8' });
+  const found = String(where.stdout || '').split(/\r?\n/);
+  const cmdShim = extension === '.cmd' || extension === '.bat'
+    || (extension !== '.exe' && found.some(p => /\.(cmd|bat)$/i.test(p)));
+  if (cmdShim && args.some(arg => /[\r\n"%!^&|<>]/.test(String(arg)))) return null;
+  return args;
+}
 
-const INSTALL_HINT = {
-  claude: 'npm install -g @anthropic-ai/claude-code',
-  codex: 'npm install -g @openai/codex',
+export const INSTALL_PKG = {
+  claude: '@anthropic-ai/claude-code',
+  codex: '@openai/codex',
 };
+const hint = cmd => INSTALL_PKG[cmd] ? ` Install it: npm install -g ${INSTALL_PKG[cmd]}` : '';
 
 // Runs the agent in the foreground with the session's directory as cwd; resolves with its exit code.
 export function launchAgent(cmd, cwd, args) {
   return new Promise(resolve => {
-    // On Windows these are npm .cmd shims, which need a shell; elsewhere spawn them directly.
-    const child = IS_WIN
-      ? spawn([cmd, ...args.map(winq)].join(' '), { cwd, stdio: 'inherit', shell: true })
-      : spawn(cmd, args, { cwd, stdio: 'inherit' });
-    child.on('error', e => {
+    const legacy = IS_WIN && !has('pwsh');
+    const passedArgs = legacy ? legacyWindowsArgs(cmd, args) : args;
+    if (passedArgs === null) {
+      console.error('could not start agent: Windows PowerShell 5 cannot safely pass these arguments through a command shim; use PowerShell 7');
+      resolve(127);
+      return;
+    }
+    const [shell, shellArgs] = IS_WIN && !legacy ? windowsCommand(cmd, args) : [cmd, passedArgs];
+    const fail = e => {
       console.error(e.code === 'ENOENT'
-        ? `${cmd} was not found on PATH.${INSTALL_HINT[cmd] ? ` Install it: ${INSTALL_HINT[cmd]}` : ''}`
+        ? `${shell} was not found on PATH.${shell === cmd ? hint(cmd) : ''}`
         : `could not start ${cmd}: ${e.message}`);
       resolve(127);
-    });
+    };
+    let child;
+    try { child = legacy ? crossSpawn(shell, shellArgs, { cwd, stdio: 'inherit' }) : spawn(shell, shellArgs, { cwd, stdio: 'inherit' }); }
+    catch (error) { fail(error); return; }
+    child.on('error', fail);
     child.on('exit', code => resolve(code ?? 0));
   });
 }
 
+// ---- installing a missing agent ----
+
+// Resolves the trimmed answer, or null when stdin closed without one (ctrl-D, a closed pipe).
+// Resolving on 'close' rather than only in the callback keeps the promise from hanging on EOF.
+export function askUser(question) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let answer = null;
+    rl.question(question, a => { answer = String(a).trim().toLowerCase(); rl.close(); });
+    rl.on('close', () => resolve(answer));
+  });
+}
+
+// Offers to install the agent when it is missing. Resolves true if it is on PATH afterwards.
+// The agent's own first-run login/setup then runs as usual when it launches.
+export async function ensureAgent(cmd) {
+  if (has(cmd)) return true;
+
+  const pkg = INSTALL_PKG[cmd];
+  if (!pkg) {
+    console.error(`${cmd} was not found on PATH.`);
+    return false;
+  }
+  // Without a terminal there is nobody to answer the prompt (e.g. piped output).
+  if (!process.stdin.isTTY) {
+    console.error(`${cmd} is not installed.${hint(cmd)}`);
+    return false;
+  }
+  if (!has('npm')) {
+    console.error(`${cmd} is not installed, and npm is not available to install it.`);
+    console.error(`Install Node.js 20 or later, then run: npm install -g ${pkg}`);
+    return false;
+  }
+
+  const answer = await askUser(`\n${cmd} is not installed. Install it now with "npm install -g ${pkg}"? (y/N) `);
+  if (answer !== 'y' && answer !== 'yes') {
+    console.log(`Skipped. You can install it later: npm install -g ${pkg}`);
+    return false;
+  }
+
+  console.log(`\nnpm install -g ${pkg}\n`);
+  const [installer, installArgs] = IS_WIN
+    ? windowsCommand('npm', ['install', '-g', pkg])
+    : ['npm', ['install', '-g', pkg]];
+  const r = spawnSync(installer, installArgs, { stdio: 'inherit' });
+  if (r.error || r.status !== 0) {
+    console.error(`\nInstall failed${r.error ? `: ${r.error.message}` : ` (npm exited with ${r.status})`}.`);
+    console.error(`If it was a permissions error, npm's global folder is not writable by you.`);
+    console.error(`Check where it points with: npm prefix -g`);
+    return false;
+  }
+  if (!has(cmd)) {
+    console.error(`\n${pkg} installed, but "${cmd}" is still not on PATH.`);
+    console.error(`npm's global bin folder is probably not in PATH. Find it with: npm prefix -g`);
+    return false;
+  }
+  console.log(`\n${cmd} installed.\n`);
+  return true;
+}
+
+// ---- new terminal tabs ----
+
+const run = (cmd, argv) => {
+  const r = spawnSync(cmd, argv, { encoding: 'utf8' });
+  if (r.error) throw new Error(r.error.message);
+  if (r.status !== 0) {
+    // Keep the tool's own message: AppleScript errors are the only clue to a denied permission.
+    const detail = String(r.stderr || '').trim().split('\n').find(Boolean);
+    throw new Error(detail || `${cmd} exited with ${r.status}`);
+  }
+};
+
+// macOS asks for Automation permission the first time; a denial comes back as -1743.
+function macAutomationError(e, app) {
+  const msg = e?.message || String(e);
+  return /-1743|not authoriz/i.test(msg)
+    ? `macOS blocked ccnav from controlling ${app}. Allow your terminal under System Settings → Privacy & Security → Automation, then try again.`
+    : msg;
+}
+
 // Opens a new terminal tab (or window) in `cwd` running `cmd` with `args`. Throws if nothing worked.
 export function openInNewTab(cmd, cwd, args, title = cmd) {
-  const run = (cmd, argv) => {
-    const r = spawnSync(cmd, argv, { stdio: 'ignore' });
-    if (r.error || r.status !== 0) throw new Error(`${cmd} failed${r.error ? `: ${r.error.message}` : ` (exit ${r.status})`}`);
-  };
-
   if (IS_WIN) {
-    const argv = ['-w', '0', 'new-tab', '--title', title.replace(/[;"]/g, ' ').slice(0, 40), '-d', cwd,
-      'pwsh', '-NoExit', '-Command', cmd, ...args];
-    // wt.exe is an app execution alias, which needs a shell to launch reliably; it returns immediately.
-    const r = spawnSync(['wt.exe', ...argv.map(winq)].join(' '), { shell: true, stdio: 'ignore', windowsHide: true });
+    const spec = Buffer.from(JSON.stringify({ cmd, cwd, args }), 'utf8').toString('base64');
+    const helper = fileURLToPath(new URL('./windows-tab.mjs', import.meta.url));
+    const [agentShell, agentArgs] = windowsCommand(process.execPath, [helper, spec], { keepOpen: true });
+    const argv = ['-w', '0', 'new-tab', '--title', title.replace(/[\r\n;"]/g, ' ').slice(0, 40), '-d', cwd,
+      agentShell, ...agentArgs];
+    const [terminalShell, terminalArgs] = windowsCommand('wt.exe', argv);
+    const r = spawnSync(terminalShell, terminalArgs, { stdio: 'ignore', windowsHide: true });
     if (r.error || r.status !== 0) throw new Error(r.error?.message || `wt.exe exited with ${r.status}`);
     return 'Windows Terminal tab';
   }
@@ -68,15 +181,27 @@ export function openInNewTab(cmd, cwd, args, title = cmd) {
   }
   if (IS_MAC) {
     if (term === 'iTerm.app') {
-      run('osascript', [
-        '-e', 'tell application "iTerm" to tell current window to create tab with default profile',
-        '-e', `tell application "iTerm" to tell current session of current window to write text ${osaString(shellCmd)}`,
-      ]);
+      try {
+        // A tab needs a window to live in: iTerm can be running with none open.
+        run('osascript', ['-e', [
+          'tell application "iTerm"',
+          '  activate',
+          '  if (count of windows) = 0 then',
+          '    create window with default profile',
+          '  else',
+          '    tell current window to create tab with default profile',
+          '  end if',
+          `  tell current session of current window to write text ${osaString(shellCmd)}`,
+          'end tell',
+        ].join('\n')]);
+      } catch (e) { throw new Error(macAutomationError(e, 'iTerm')); }
       return 'iTerm tab';
     }
     // Terminal.app (and anything else): a new Terminal window. Real tabs would need Accessibility permission.
-    run('osascript', ['-e', `tell application "Terminal" to do script ${osaString(shellCmd)}`,
-      '-e', 'tell application "Terminal" to activate']);
+    try {
+      run('osascript', ['-e', `tell application "Terminal" to do script ${osaString(shellCmd)}`,
+        '-e', 'tell application "Terminal" to activate']);
+    } catch (e) { throw new Error(macAutomationError(e, 'Terminal')); }
     return 'Terminal window';
   }
   if (has('gnome-terminal')) {

package/src/providers/claude.mjs

@@ -8,6 +8,8 @@ export const agent = 'claude';
 export const command = 'claude';
 export const glyph = '◆';
 export const color = 'cyan';
+// `ccnav here`: a fresh session that never stops to ask for permission.
+export const AUTO_ARGS = ['--dangerously-skip-permissions'];
 
 export const HOME_DIR = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 export const SESSIONS_ROOT = path.join(HOME_DIR, 'projects');
@@ -66,18 +68,22 @@ export function readSession(file) {
 }
 
 // Top-level *.jsonl only: <sessionId>/ subdirectories hold subagent sidechains.
-export function listSessions() {
+export function listSessions({ onError = (file, error) => console.error(`ccnav: could not read Claude session at ${file}: ${error.message}`) } = {}) {
   if (!fs.existsSync(SESSIONS_ROOT)) return [];
   const out = [];
   for (const dir of fs.readdirSync(SESSIONS_ROOT, { withFileTypes: true })) {
     if (!dir.isDirectory()) continue;
     const projectDir = path.join(SESSIONS_ROOT, dir.name);
-    for (const f of fs.readdirSync(projectDir)) {
+    let files;
+    try { files = fs.readdirSync(projectDir); }
+    catch (error) { onError(projectDir, error); continue; }
+    for (const f of files) {
       if (!f.endsWith('.jsonl')) continue;
+      const file = path.join(projectDir, f);
       try {
-        const s = readSession(path.join(projectDir, f));
+        const s = readSession(file);
         if (s) out.push(s);
-      } catch { /* unreadable file */ }
+      } catch (error) { onError(file, error); }
     }
   }
   return out;

package/src/providers/codex.mjs

@@ -8,6 +8,9 @@ export const agent = 'codex';
 export const command = 'codex';
 export const glyph = '●';
 export const color = 'green';
+// `ccnav here`: codex removed --full-auto in 0.156, so the policy is named directly.
+// This is the counterpart to Claude's --dangerously-skip-permissions: no approvals, no sandbox.
+export const AUTO_ARGS = ['--dangerously-bypass-approvals-and-sandbox'];
 
 export const HOME_DIR = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
 export const SESSIONS_ROOT = path.join(HOME_DIR, 'sessions');
@@ -15,10 +18,14 @@ export const ARCHIVE_ROOT = path.join(HOME_DIR, 'ccnav-archive');
 const INDEX_FILE = path.join(HOME_DIR, 'session_index.jsonl');
 
 // session_index.jsonl names about half the sessions; read it once per listing.
-function readIndex() {
+function readIndex(onError = () => {}) {
   const map = new Map();
   let text;
-  try { text = fs.readFileSync(INDEX_FILE, 'utf8'); } catch { return map; }
+  try { text = fs.readFileSync(INDEX_FILE, 'utf8'); }
+  catch (error) {
+    if (error.code !== 'ENOENT') onError(INDEX_FILE, error);
+    return map;
+  }
   for (const line of text.split('\n')) {
     if (!line.trim()) continue;
     try {
@@ -81,13 +88,14 @@ export function readSession(file, index = readIndex()) {
 }
 
 // sessions/YYYY/MM/DD/*.jsonl
-export function listSessions() {
+export function listSessions({ onError = (file, error) => console.error(`ccnav: could not read Codex session at ${file}: ${error.message}`) } = {}) {
   if (!fs.existsSync(SESSIONS_ROOT)) return [];
-  const index = readIndex();
+  const index = readIndex(onError);
   const out = [];
   const walk = (dir, depth) => {
     let entries;
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch (error) { onError(dir, error); return; }
     for (const e of entries) {
       const p = path.join(dir, e.name);
       if (e.isDirectory() && depth < 3) walk(p, depth + 1);
@@ -95,7 +103,7 @@ export function listSessions() {
         try {
           const s = readSession(p, index);
           if (s && !s.subagent) out.push(s);
-        } catch { /* unreadable file */ }
+        } catch (error) { onError(p, error); }
       }
     }
   };

package/src/sessions.mjs

@@ -5,11 +5,17 @@ import * as codex from './providers/codex.mjs';
 export const PROVIDERS = { claude, codex };
 export const AGENTS = Object.keys(PROVIDERS);
 
-// Both agents' sessions in one list, newest use first.
-export function listSessions({ agents = AGENTS } = {}) {
+const reportError = (agent, file, error) =>
+  console.error(`ccnav: could not read ${agent} sessions${file ? ` at ${file}` : ''}: ${error.message}`);
+
+// Both agents' sessions in one list, newest use first. Report unreadable sources on stderr.
+export function listSessions({ agents = AGENTS, onError = reportError } = {}) {
   const out = [];
   for (const name of agents) {
-    try { out.push(...PROVIDERS[name].listSessions()); } catch { /* provider not installed */ }
+    const provider = PROVIDERS[name];
+    if (!provider) { onError(name, null, new Error('unknown agent')); continue; }
+    try { out.push(...provider.listSessions({ onError: (file, error) => onError(name, file, error) })); }
+    catch (error) { onError(name, null, error); }
   }
   return out.sort((a, b) => b.lastUsed - a.lastUsed);
 }

package/src/windows-tab.mjs

@@ -0,0 +1,11 @@
+// Started in a new Windows Terminal tab. The payload is data, so neither shell
+// interprets session IDs or forwarded arguments as command source.
+import { launchAgent } from './platform.mjs';
+
+try {
+  const { cmd, cwd, args } = JSON.parse(Buffer.from(process.argv[2], 'base64').toString('utf8'));
+  process.exit(await launchAgent(cmd, cwd, args));
+} catch (error) {
+  console.error(`ccnav: could not start agent in new tab: ${error.message}`);
+  process.exit(127);
+}