@fnclaude/cli 0.7.5 → 0.7.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnclaude/cli",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "fnclaude CLI implementation (TypeScript rewrite, in progress)",
   "license": "MIT",
   "repository": {

package/src/argParser.ts

@@ -177,7 +177,7 @@ export function parseArgs(argv: readonly string[], home: string): ParsedArgs {
   const passthrough: string[] = [];
   let noTmux = false;
   let worktreeSet = false;
-  let worktreeArg = '';
+  let worktreeArg: string | undefined;
 
   // Magic slots: filled at most once each, in strict order.
   let magicModel = '';

package/src/args/preserve.ts

@@ -106,6 +106,12 @@ export function preserveArgs(
   while (i < origArgs.length) {
     const tok = origArgs[i] as string;
 
+    // `--` separates flags from the original session's initial prompt
+    // (everything after is the prompt body). Carrying it across a
+    // relaunch shadows the transfer's @summary file or re-prompts after
+    // --resume on restart — drop the separator and the entire tail.
+    if (tok === '--') break;
+
     // Equals-form (--flag=value): match by the flag-prefix-before-= part.
     if (deny !== null) {
       const eq = tok.indexOf('=');

package/src/args.ts

@@ -75,9 +75,9 @@ export interface BaseArgs {
 
   /**
    * WorktreeArg is the name/value given with -w / --worktree (or the 2nd
-   * positional / +workspace suffix), or "" if the flag was bare.
+   * positional / +workspace suffix), or undefined if the flag was bare.
    */
-  readonly worktreeArg: string;
+  readonly worktreeArg: string | undefined;
 
   /**
    * UsedNoopFallback is true when CWD was filled by the noop fallback (no

package/src/autoname.ts

@@ -59,15 +59,15 @@ export function shouldAutoName(passthrough: readonly string[]): boolean {
 
 /**
  * extractPrompt returns the first non-empty token after "--" in passthrough.
- * Returns "" if not found.
+ * Returns undefined if not found.
  */
-export function extractPrompt(passthrough: readonly string[]): string {
+export function extractPrompt(passthrough: readonly string[]): string | undefined {
   const sepIdx = passthrough.indexOf('--');
-  if (sepIdx < 0) return '';
+  if (sepIdx < 0) return undefined;
   for (const t of passthrough.slice(sepIdx + 1)) {
     if (t !== '') return t;
   }
-  return '';
+  return undefined;
 }
 
 // ── stop-words + heuristic fallback ────────────────────────────────────────
@@ -123,9 +123,9 @@ const RE_WHITESPACE = /\s+/g;
 
 /**
  * sanitizeSlug cleans raw LLM output into a valid kebab slug (up to 3 dash-
- * separated segments). Returns "" when nothing survives sanitization.
+ * separated segments). Returns undefined when nothing survives sanitization.
  */
-export function sanitizeSlug(raw: string): string {
+export function sanitizeSlug(raw: string): string | undefined {
   let s = raw.trim().toLowerCase();
   s = s.replace(RE_WHITESPACE, '-');
   s = s.replace(RE_NON_SLUG, '');
@@ -136,7 +136,7 @@ export function sanitizeSlug(raw: string): string {
   s = parts.slice(0, 3).join('-');
   // Trim again in case joining re-introduced edge dashes.
   s = s.replace(/^-+|-+$/g, '');
-  return s;
+  return s !== '' ? s : undefined;
 }
 
 // ── LLM client abstraction ──────────────────────────────────────────────────
@@ -235,11 +235,12 @@ export function claudeCliFn(model: string, spawnFn: SpawnFn = defaultSpawnFn): L
  * On any error the function falls back to heuristicName silently.
  */
 export async function generateName(
-  prompt: string,
+  prompt: string | undefined,
   cfg: NameConfig,
   apiKey: string,
   llmFn?: LlmClientFn,
 ): Promise<string> {
+  const resolved = prompt ?? '';
   let usingCLI = false;
   if (!llmFn) {
     if (apiKey) {
@@ -261,11 +262,11 @@ export async function generateName(
   const timer = setTimeout(() => controller.abort(), timeoutMs);
 
   try {
-    const raw = await llmFn(cfg.model, prompt, controller.signal);
+    const raw = await llmFn(cfg.model, resolved, controller.signal);
     const name = sanitizeSlug(raw);
-    return name !== '' ? name : heuristicName(prompt);
+    return name !== undefined ? name : heuristicName(resolved);
   } catch {
-    return heuristicName(prompt);
+    return heuristicName(resolved);
   } finally {
     clearTimeout(timer);
   }

package/src/hostAliases.ts

@@ -1,27 +1,34 @@
-// Port of src/host_aliases.go (fnclaude/fnclaude Go reference).
+// Load the {host-short} alias map.
 //
-// Load the {host-short} alias map from up to two layered files. System file
-// ships with fnclaude (canonical defaults, root-owned, regenerated on
-// upgrade); user file optionally overrides per-key. Both files are JSON
-// objects mapping fully-qualified host → short alias.
+// Builtin defaults (BUILTIN_HOST_ALIASES) ship with the package — npm install
+// has no hook to drop a JSON file under /usr/share, so the canonical 4 host
+// mappings live in source. Users override per-key via
+// ~/.local/share/fnrhombus/host-aliases.json.
 //
-// Missing files are silently treated as empty maps. If a user template uses
+// Missing user file is silently treated as empty. If a user template uses
 // {host-short} and the merged map has no entry for the current host, the
 // substitution step calls missingHostShortError() to produce a message
-// naming both file paths and a copy-pasteable JSON example.
+// naming the user file path and a copy-pasteable JSON example.
 
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 /**
- * Install-dir LUT, owned by the fnclaude package. The AUR PKGBUILD installs
- * the file here with sensible defaults.
+ * Bundled host-alias defaults. These ship with the package and are
+ * always present; the user file (if any) overrides per key.
+ *
+ * Kept in sync with the Go reference's AUR PKGBUILD install fixture.
  */
-export const HOST_ALIASES_SYSTEM_PATH = '/usr/share/fnrhombus/host-aliases.json';
+export const BUILTIN_HOST_ALIASES: Readonly<Record<string, string>> = Object.freeze({
+  'github.com': 'gh',
+  'gitlab.com': 'gl',
+  'bitbucket.org': 'bb',
+  'codeberg.org': 'cb',
+});
 
 /**
- * Per-user override path. Wins per-key against the system file.
+ * Per-user override path. Wins per-key against the builtin defaults.
  */
 export function hostAliasesUserPath(home: string): string {
   return join(home, '.local', 'share', 'fnrhombus', 'host-aliases.json');
@@ -39,17 +46,22 @@ export interface LoadHostAliasesResult {
 }
 
 /**
- * Read both files (if present) and merge them, user-level winning per
- * key. Either or both missing returns whatever is available (or empty).
+ * Return the merged alias map: builtin defaults overlaid with the user
+ * file (if present). User entries win per key. Missing user file is the
+ * common path and stays silent.
  */
 export function loadHostAliases(home: string): LoadHostAliasesResult {
-  return mergeHostAliases([HOST_ALIASES_SYSTEM_PATH, hostAliasesUserPath(home)]);
+  const userResult = mergeHostAliases([hostAliasesUserPath(home)]);
+  const merged: Record<string, string> = { ...BUILTIN_HOST_ALIASES };
+  for (const k of Object.keys(userResult.aliases)) {
+    merged[k] = userResult.aliases[k] as string;
+  }
+  return { aliases: merged, warnings: userResult.warnings };
 }
 
 /**
  * Read each path (if it exists) and merge per-key with later entries
- * winning over earlier ones. Callers order system-first, user-second so
- * user wins on conflict.
+ * winning over earlier ones.
  */
 export function mergeHostAliases(paths: string[]): LoadHostAliasesResult {
   const merged: Record<string, string> = {};
@@ -106,9 +118,9 @@ export function readHostAliasesFile(path: string): ReadHostAliasesFileResult {
 
 /**
  * Build the error emitted when a template uses {host-short} but no alias
- * is configured for the current host. Same message shape as the JS
- * plugin's missingHostShortError so users see consistent guidance from
- * either consumer.
+ * is configured for the current host. Points only at the user file path
+ * since builtins already cover the common forges and any further
+ * overrides go in the user file.
  *
  * `home` is injected so callers in tests can pin the user-path output
  * without touching $HOME; production callers should pass `process.env.HOME
@@ -119,9 +131,8 @@ export function missingHostShortError(host: string, home?: string): Error {
   const userPath = hostAliasesUserPath(h);
   return new Error(
     `cannot resolve {host-short} for host ${JSON.stringify(host)}: no alias configured.\n` +
-      `Add an entry to one of:\n` +
-      `  ${HOST_ALIASES_SYSTEM_PATH}  (system, requires sudo)\n` +
-      `  ${userPath}  (user-level, takes precedence on conflict)\n` +
+      `Add an entry to:\n` +
+      `  ${userPath}\n` +
       `Example:\n` +
       `  { "github.com": "gh", "gitlab.com": "gl" }`,
   );

package/src/mcp/protocol.ts

@@ -200,12 +200,149 @@ export function encodeResponse(resp: Response): Buffer {
  * The line may or may not include the terminating '\n'; both are accepted
  * (matches Go's bufio.ReadBytes which keeps the delimiter).
  *
- * Throws on malformed JSON.
+ * Throws on malformed JSON or on payloads that fail boundary validation
+ * (see `validateRequest` for the rules). Wire input is untrusted —
+ * anything that knows the socket path can submit JSON, and the dispatcher
+ * acts on it (re-exec, file writes, clipboard). Validate before handing
+ * to the dispatcher rather than scattering checks across handlers.
  */
 export function decodeRequest(line: string | Buffer): Request {
   const text = typeof line === 'string' ? line : line.toString('utf8');
   const trimmed = text.endsWith('\n') ? text.slice(0, -1) : text;
-  return JSON.parse(trimmed) as Request;
+  const raw: unknown = JSON.parse(trimmed);
+  return validateRequest(raw);
+}
+
+// ── Request validation ─────────────────────────────────────────────────────
+
+/**
+ * Maximum byte length for each string field on a Request. Values are sized
+ * to the field's job:
+ *   - overrides (model, effort, permission_mode, agent): short identifiers
+ *   - allowed_tools: comma-joined tool names, room for ~30 longest
+ *   - session_id: UUID-shaped, but we don't pre-validate the shape here
+ *     (that lives in the handler so the error message can mention UUID)
+ *   - destination / name: filesystem paths / kebab-case names
+ *   - text (clipboard): bounded for typical clipboard payloads
+ *   - summary: continuity blob — generous but bounded; a malicious peer
+ *     submitting hundreds of MB would otherwise wedge the writeFile path
+ */
+const STRING_LIMITS: Record<string, number> = {
+  // Shared overrides
+  model: 64,
+  effort: 64,
+  permission_mode: 64,
+  allowed_tools: 4096,
+  agent: 256,
+  // Restart / switch / spawn
+  session_id: 128,
+  destination: 4096,
+  name: 256,
+  summary: 1024 * 1024, // 1 MiB
+  // Copy
+  text: 1024 * 1024, // 1 MiB
+};
+
+/** Discriminated union of fields legal for each Op. */
+const STRING_FIELDS_BY_OP: Record<Op, readonly string[]> = {
+  restart: ['session_id', 'model', 'effort', 'permission_mode', 'allowed_tools', 'agent'],
+  switch: [
+    'destination',
+    'name',
+    'summary',
+    'session_id',
+    'model',
+    'effort',
+    'permission_mode',
+    'allowed_tools',
+    'agent',
+  ],
+  spawn: [
+    'destination',
+    'name',
+    'summary',
+    'model',
+    'effort',
+    'permission_mode',
+    'allowed_tools',
+    'agent',
+  ],
+  copy_to_clipboard: ['text'],
+};
+
+const BOOL_FIELDS: readonly string[] = ['brief', 'chrome', 'ide', 'verbose', 'confirmed'];
+
+/** Field names that are filesystem paths and must reject ".." traversal. */
+const PATH_FIELDS: readonly string[] = ['destination'];
+
+const KNOWN_OPS: readonly Op[] = ['restart', 'switch', 'spawn', 'copy_to_clipboard'];
+
+/**
+ * Validate a parsed JSON value as a Request. Returns the validated value
+ * (typed as Request) on success; throws Error with a human-readable
+ * reason on failure. The caller (`decodeRequest`) is the only intended
+ * entry point — handlers consume the typed Request and trust its shape.
+ *
+ * Checks performed:
+ *  1. Value is a plain object (not array, null, or scalar).
+ *  2. `op` is one of the four known string discriminants.
+ *  3. Every string field on the per-op allowlist is either absent or a
+ *     string under its byte-length cap, with no null bytes.
+ *  4. Path-shaped fields (`destination`) additionally reject `..`
+ *     segments (delimited by `/` or string ends).
+ *  5. Boolean override fields are either absent, true, false, or null
+ *     (null is treated as "preserve existing" by handlers).
+ *
+ * Unknown extra keys are tolerated (forward compatibility with newer
+ * clients) but their values are not validated.
+ */
+export function validateRequest(value: unknown): Request {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('request must be a JSON object');
+  }
+  const obj = value as Record<string, unknown>;
+  const op = obj.op;
+  if (typeof op !== 'string' || !KNOWN_OPS.includes(op as Op)) {
+    throw new Error(`unknown op ${JSON.stringify(op)}`);
+  }
+  const allowed = STRING_FIELDS_BY_OP[op as Op];
+  for (const field of allowed) {
+    const v = obj[field];
+    if (v === undefined) continue;
+    if (typeof v !== 'string') {
+      throw new Error(`field ${field} must be a string`);
+    }
+    if (v.includes('\x00')) {
+      throw new Error(`field ${field} contains a null byte`);
+    }
+    const cap = STRING_LIMITS[field] ?? 1024;
+    if (Buffer.byteLength(v, 'utf8') > cap) {
+      throw new Error(`field ${field} exceeds max length ${cap}`);
+    }
+    if (PATH_FIELDS.includes(field) && hasParentSegment(v)) {
+      throw new Error(`field ${field} contains a path-traversal segment ("..")`);
+    }
+  }
+  for (const field of BOOL_FIELDS) {
+    const v = obj[field];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== 'boolean') {
+      throw new Error(`field ${field} must be a boolean`);
+    }
+  }
+  return obj as unknown as Request;
+}
+
+/**
+ * Returns true when the path contains a literal `..` segment — i.e. `..`
+ * delimited by `/` (or by start/end of the string). Catches `../etc`,
+ * `/foo/../bar`, `foo/..`, and bare `..`; ignores `foo..bar` and any
+ * other substring where `..` is part of a larger name.
+ */
+function hasParentSegment(p: string): boolean {
+  // Split on '/' is sufficient — POSIX path semantics, and a Windows
+  // backslash path would never be a legitimate destination on the wire.
+  return p.split('/').includes('..');
 }
 
 /** Decode one newline-terminated JSON line into a Response. */

package/src/mcp/socketListener.ts

@@ -14,7 +14,7 @@
  */
 
 import { createServer, type Server, type Socket } from 'node:net';
-import { writeFile, unlink } from 'node:fs/promises';
+import { writeFile, unlink, chmod } from 'node:fs/promises';
 import type { Config } from '../config.js';
 import { handoffContentPath, type HandoffSpec } from '../handoff.js';
 import {
@@ -144,6 +144,15 @@ export class SocketListener {
    * Open the AF_UNIX listener at spec.socketPath and start the accept
    * loop. Best-effort removes any stale socket file from a prior crashed
    * invocation at this path (net listen errors with EADDRINUSE otherwise).
+   *
+   * The socket file is chmod'd to 0600 immediately after bind so other
+   * UIDs on the host cannot dial it. Node's createServer() does NOT honor
+   * a mode option for AF_UNIX paths — it inherits the process umask, which
+   * defaults to 022 (world-readable) or worse depending on caller. We
+   * tighten unconditionally rather than rely on umask discipline at every
+   * launch site. The race window between bind and chmod is small (single
+   * tick) but real; we accept it as the trade vs. a per-process umask
+   * dance that would still leak any *other* file created in the same tick.
    */
   static async start(opts: StartOptions): Promise<SocketListener> {
     try {
@@ -169,6 +178,23 @@ export class SocketListener {
       server.once('listening', onOk);
       server.listen(opts.spec.socketPath);
     });
+    // Tighten the socket to owner-only rw — see method-level note above.
+    // Windows AF_UNIX implementations don't honor POSIX modes; the chmod
+    // call is a no-op there but harmless.
+    try {
+      await chmod(opts.spec.socketPath, 0o600);
+    } catch (err) {
+      // Don't leave a world-readable socket up if we can't tighten it.
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      try {
+        await unlink(opts.spec.socketPath);
+      } catch {
+        // already gone
+      }
+      throw new Error(
+        `failed to chmod socket to 0600 at ${opts.spec.socketPath}: ${(err as Error).message}`,
+      );
+    }
     return listener;
   }
 
@@ -305,7 +331,7 @@ export class SocketListener {
       !flagPresent(withOverrides, '--permission-mode')
     ) {
       const live = readLivePermissionMode(this.launchCWD, sid);
-      if (live !== '') {
+      if (live !== undefined) {
         withOverrides = [...withOverrides, '--permission-mode', live];
       }
     }
@@ -351,7 +377,7 @@ export class SocketListener {
       sid !== ''
     ) {
       const live = readLivePermissionMode(this.launchCWD, sid);
-      if (live !== '') {
+      if (live !== undefined) {
         withOverrides = [...withOverrides, '--permission-mode', live];
       }
     }

package/src/prompts.ts

@@ -16,6 +16,7 @@ import { statSync } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
 import { resolveSelfPath } from './paths.js';
 
 export interface PromptSet {
@@ -55,6 +56,16 @@ export interface LoadPromptsResult {
  *     contains the shipped prompts/. This is the production path for any
  *     `npm i -g @fnclaude/cli` install.
  *  4. `<exe-dir>/../share/fnclaude/prompts/` — FHS/AUR install layout.
+ *  5. `<module-dir>/../prompts/` — umbrella-install layout: when invoked
+ *     via `npm i -g fnclaude` (the umbrella package), `process.argv[1]`
+ *     points at the umbrella's `bin/fnc.js`, which `await import`s into
+ *     `@fnclaude/cli/bin/fnc.js`. Candidates 2–4 all anchor at the
+ *     umbrella's exe-dir and miss the cli package entirely. Anchoring at
+ *     this module's own location reliably reaches the cli package root,
+ *     since `prompts.ts` always lives inside `@fnclaude/cli` regardless
+ *     of which bin invoked it. Works for both the `dist/prompts.js`
+ *     (installed) and `src/prompts.ts` (dev) layouts — both sit one
+ *     level under the package root where `prompts/` ships.
  *
  * Symlinks in the exe path are resolved before the search.
  *
@@ -110,10 +121,17 @@ export function findPromptsDir(): FindPromptsDirResult {
   // resolveSelfPath handles the argv[1] / execPath / realpathSync logic.
   const exeDir = dirname(resolveSelfPath());
 
+  // Anchor at this module's own location to catch the umbrella-install
+  // layout where argv[1] points at the fnclaude umbrella's bin/fnc.js
+  // (which delegates into @fnclaude/cli via dynamic import). The exe-dir
+  // candidates miss the cli package in that shape; this one doesn't.
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+
   const candidates = [
     join(exeDir, 'prompts'),
     join(exeDir, '..', 'prompts'),
     join(exeDir, '..', 'share', 'fnclaude', 'prompts'),
+    join(moduleDir, '..', 'prompts'),
   ];
   for (const c of candidates) {
     try {

package/src/pty.ts

@@ -12,7 +12,7 @@
 
 import { mkdir, rmdir, stat } from 'node:fs/promises';
 import type { Stats } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, isAbsolute, resolve as resolvePath } from 'node:path';
 import type { Config } from './config.js';
 import type { HandoffSpec } from './handoff.js';
 import { isFlag, isMagicWord, preserveArgs, splitLeadingMagic } from './args/preserve.js';
@@ -119,8 +119,18 @@ export interface CrossCwdMatch {
 
 /**
  * Scan `tail` for the cross-cwd redirect message. Returns null when no
- * match is found. When multiple matches appear (unlikely but defensive),
- * the LAST match wins.
+ * match is found OR when the captured `dest` fails safety validation.
+ * When multiple matches appear (unlikely but defensive), the LAST match
+ * wins.
+ *
+ * Security note: the `dest` capture flows into `silentRelaunch` and
+ * becomes the cwd for the relaunched process. The PTY stream is not a
+ * trusted channel — a hostile MCP tool (or any subprocess that prints to
+ * claude's terminal) can emit a fake "To resume, run: cd /tmp/evil &&
+ * claude --resume <uuid>" line and steer the parent into relaunching in
+ * an attacker-controlled directory. We refuse to act on a dest unless
+ * it's an absolute path that survives canonicalisation unchanged and
+ * contains no null bytes / `..` segments.
  */
 export function detectCrossCwd(tail: Buffer): CrossCwdMatch | null {
   // Decode as Latin-1 so every byte maps to a code unit; the regex matches
@@ -137,7 +147,32 @@ export function detectCrossCwd(tail: Buffer): CrossCwdMatch | null {
     last = m;
   }
   if (last === null) return null;
-  return { dest: last[1]!, uuid: last[2]! };
+  const dest = last[1]!;
+  if (!isSafeDest(dest)) return null;
+  return { dest, uuid: last[2]! };
+}
+
+/**
+ * Reject `dest` values that shouldn't be honored as relaunch cwds:
+ *  - contains a null byte
+ *  - is not an absolute path (a relative dest would resolve against
+ *    whatever the current cwd happens to be — non-obvious to a user
+ *    reading the relaunch and easy to abuse)
+ *  - contains a `..` segment delimited by `/` (path traversal)
+ *  - doesn't round-trip through `path.resolve` (catches `/foo/./bar`,
+ *    trailing slashes, and any other non-canonical form a peer might
+ *    cook up to slip past parent-segment detection)
+ *
+ * On Windows we'd also want backslash handling; the cross-cwd-resume
+ * flow is POSIX-only by design (the Windows PTY stub disables it) so
+ * this validator targets POSIX paths.
+ */
+function isSafeDest(dest: string): boolean {
+  if (dest.includes('\x00')) return false;
+  if (!isAbsolute(dest)) return false;
+  if (dest.split('/').includes('..')) return false;
+  if (resolvePath(dest) !== dest) return false;
+  return true;
 }
 
 // ── reconstructArgv ────────────────────────────────────────────────────────

package/src/resolver.ts

@@ -75,6 +75,11 @@ export interface ResolveDeps {
   ghCmd: (args: readonly string[]) => Promise<GhResult>;
   /** Shell out `gh repo clone <ownerRepo> <dest>`. */
   runClone: (ownerRepo: string, dest: string) => Promise<void>;
+  /**
+   * User-visible log line (e.g. "cloning X → Y"). Production writes to
+   * stderr; tests stub it to silence test output and assert on the call.
+   */
+  log: (message: string) => void;
 }
 
 // ── Production dependency wiring ───────────────────────────────────────────
@@ -111,6 +116,9 @@ export function productionDeps(): ResolveDeps {
     },
     ghCmd,
     runClone,
+    log: (msg: string) => {
+      process.stderr.write(msg.endsWith('\n') ? msg : `${msg}\n`);
+    },
   };
 }
 
@@ -494,7 +502,7 @@ async function cloneAndReturn(
   }
 
   // Clone. gh decides SSH vs HTTPS from its config.
-  process.stderr.write(`fnclaude: cloning ${ref.owner}/${ref.name} → ${target}\n`);
+  deps.log(`fnclaude: cloning ${ref.owner}/${ref.name} → ${target}`);
   try {
     await deps.runClone(`${ref.owner}/${ref.name}`, target);
   } catch (e) {

package/src/sessionState.ts

@@ -58,7 +58,7 @@ export function sessionJSONLPath(launchCWD: string, sessionID: string): string {
  * scan with last-wins semantics is correct (and adequate at the file
  * sizes real sessions reach).
  *
- * Returns `""` if the file is missing, unreadable, or contains no
+ * Returns `undefined` if the file is missing, unreadable, or contains no
  * permission-mode records. Callers should fall back to startup-arg
  * preservation in that case.
  *
@@ -70,15 +70,15 @@ export function sessionJSONLPath(launchCWD: string, sessionID: string): string {
 export function readLivePermissionMode(
   launchCWD: string,
   sessionID: string,
-): string {
+): string | undefined {
   const path = sessionJSONLPath(launchCWD, sessionID);
   let data: string;
   try {
     data = readFileSync(path, 'utf8');
   } catch {
-    return '';
+    return undefined;
   }
-  let latest = '';
+  let latest: string | undefined;
   for (const line of data.split('\n')) {
     if (line.length === 0) continue;
     let r: { type?: unknown; permissionMode?: unknown };

package/src/worktree.ts

@@ -63,10 +63,10 @@ export interface WorktreeInfo {
   /** Absolute filesystem path of the worktree. */
   path: string;
   /**
-   * Bare branch name (e.g. "feat-x" or "worktree-feat-x"); "" if the
+   * Bare branch name (e.g. "feat-x" or "worktree-feat-x"); undefined if the
    * worktree is detached.
    */
-  branch: string;
+  branch: string | undefined;
 }
 
 /**
@@ -86,7 +86,7 @@ export function listWorktrees(dir: string, runner: GitRunner = defaultGitRunner)
   const result: WorktreeInfo[] = [];
   for (const block of out.split('\n\n')) {
     let path = '';
-    let branch = '';
+    let branch: string | undefined;
     for (const line of block.split('\n')) {
       if (line.startsWith('worktree ')) {
         path = line.slice('worktree '.length).trim();
@@ -114,20 +114,21 @@ export function listWorktrees(dir: string, runner: GitRunner = defaultGitRunner)
  *   3. Basename of the path    == query  (last-resort fallback for worktrees
  *      whose branch was renamed or whose creator skipped the convention)
  *
- * Returns null when no entry matches. Empty `query` short-circuits to null
- * so that detached worktrees (branch="") can't be matched by accident.
+ * Returns null when no entry matches. Undefined `query` short-circuits to
+ * null so that detached worktrees (branch=undefined) can't be matched by
+ * accident.
  */
 export function findWorktree(
   worktrees: readonly WorktreeInfo[],
-  query: string,
+  query: string | undefined,
 ): WorktreeInfo | null {
-  if (query === '') return null;
+  if (query === undefined) return null;
 
   for (const wt of worktrees) {
     if (wt.branch === query) return wt;
   }
   for (const wt of worktrees) {
-    if (wt.branch !== '' && stripWorktreePrefix(wt.branch) === query) return wt;
+    if (wt.branch !== undefined && stripWorktreePrefix(wt.branch) === query) return wt;
   }
   for (const wt of worktrees) {
     if (basename(wt.path) === query) return wt;
@@ -153,7 +154,7 @@ function basename(p: string): string {
  * No input is mutated. The four cases:
  *
  *   1. worktreeSet=false → carry through with worktreeMatched=false.
- *   2. Bare -w (worktreeArg="") → append --worktree to passthrough,
+ *   2. Bare -w (worktreeArg=undefined) → append --worktree to passthrough,
  *      worktreeMatched=false.
  *   3. Existing worktree matched → swap cwd to the worktree path, set
  *      worktreeMatched=true, suppress --worktree.
@@ -173,7 +174,7 @@ export function applyWorktreeIntercept(
   }
 
   // Bare -w with no name: push --worktree back through unchanged.
-  if (a.worktreeArg === '') {
+  if (a.worktreeArg === undefined) {
     return withIntercepted(a, {
       passthrough: [...a.passthrough, '--worktree'],
       worktreeMatched: false,