@fnclaude/cli 0.7.2 → 0.7.4

package/README.md

@@ -1,50 +1,238 @@
 # @fnclaude/cli
 
-The Claude Code command-line interface. Provides the `fnc` command for managing Claude Code sessions, projects, tasks, and remote triggers.
+`claude`, with the rough edges filed off.
 
-## Installation
+```sh
+fnc opus max ~/src/myproject -- "refactor the auth module"
+```
+
+No `--model claude-opus-4-5`, no `--effort max`, no `--print` gymnastics. `@fnclaude/cli` (the `fnc` binary) sits in front of `claude` and translates short, readable invocations into the full-form flags `claude` expects. Magic positional words for model and effort, capital-letter short flags for everything claude makes you spell out, and a config file for the auto-features you want on every launch. Bun-runtime; install via `bun add -g fnclaude` (or `npm i -g fnclaude`).
+
+## Platform support
+
+Supported on **Linux** and **macOS**. The codebase has a Windows fallback path (`spawn + process.exit` instead of `process.execve`) but it has never been exercised — treat it as untested. If you run on Windows, expect breakage.
+
+## Install
 
-```bash
-npm install @fnclaude/cli
-bun add @fnclaude/cli
+```sh
+bun add -g fnclaude
+# or
+npm install -g fnclaude
 ```
 
+Requires the **Bun runtime** for terminal session management. Node.js is supported for installation, but session execution runs via Bun.
+
 ## Requirements
 
-This package requires the **Bun runtime** for terminal session management. The underlying PTY layer uses node-pty with Bun's native adapter, which provides efficient cross-platform support for interactive shell sessions. Node.js as the JavaScript runtime is supported for package management and installation, but session execution runs via Bun.
+- [Bun](https://bun.sh/) >= 1.0
+- [claude](https://github.com/anthropics/claude-code) CLI installed and on your `$PATH`
+
+## Quick start
+
+```sh
+# Launch in the current directory
+fnc .
+
+# Specific model in a specific project
+fnc sonnet ~/src/myproject
+
+# High-effort opus session
+fnc opus high ~/src/myproject
+
+# Attach a shared tools directory
+fnc ~/src/myproject -A ~/src/shared-tools
+
+# Pass a prompt inline
+fnc . -- "refactor the auth module"
+
+# Collapse multiple short flags
+fnc -BVC .
+```
+
+## Features
+
+### Magic positional words
+
+The first two positional slots can be a model alias and an effort level. `fnc` intercepts them before `claude` ever sees the args.
+
+```sh
+fnc opus max ~/src/proj          # --model claude-opus-4-5 --effort max
+fnc sonnet ~/src/proj            # --model claude-sonnet-4-5
+fnc haiku low ~/src/proj         # --model claude-haiku-4-5 --effort low
+fnc ~/src/proj                   # no model flag — claude picks the default
+```
+
+Supported model aliases: `opus`, `sonnet`, `haiku`.
+Supported effort levels: `low`, `medium`, `high`, `xhigh`, `max`.
+
+A directory that happens to be named `opus`? Prefix it: `fnc ./opus`.
+
+### Capital-letter short flags
+
+`claude`'s long options are the right thing to pass and a chore to type. `fnc` maps each one to a capital-letter short flag that collapses with standard POSIX rules.
+
+```sh
+fnc -BVC ~/src/proj     # --brief --verbose --chrome
+fnc -T ~/src/proj       # --tmux
+fnc -D ~/src/proj       # --dangerously-skip-permissions
+```
+
+Full mapping in the [flag reference](#short-translations-fnc--claude) below.
+
+### Prompt after `--`
 
-## Quick Start
+Pass a prompt inline without `--print` or redirection — just drop a `--` and write the prompt. When `--name`/`-n` isn't already set, `fnc` generates a 1–3-word session label from the prompt via Haiku (see [Auto-name from prompt](#auto-name-from-prompt) below).
 
-```bash
-# Launch Claude Code with default settings
-fnc
+```sh
+fnc sonnet src/ -- "add integration tests for the payments module"
+```
 
-# Specify a model and effort level
-fnc opus max ~/my-project
+### Multi-directory MCP injection
 
-# Open Claude in a specific worktree
-fnc ~/my-project my-feature-branch
+Need claude to see a second project's MCP config and settings? Pass it as an extra positional or with `-A`/`--also`. `fnc` injects `--add-dir`, `--mcp-config`, and `--settings` for each extra dir automatically.
 
-# Resume your most recent session
-fnc continue
+```sh
+fnc src/ -A tools/ -A shared/
+# or equivalently:
+fnc src/ tools/ shared/
 ```
 
-## Usage
+Each extra dir gets `--mcp-config <dir>/.mcp.json` (if the file exists) and `--settings <dir>/.claude/settings.json` (if it exists). The primary dir is launched in; extra dirs are attached.
+
+### Auto-features you configure once
+
+Tired of typing `--tmux` every launch? Set it once in config and forget it.
 
-```bash
-fnc --help
+```toml
+# ~/.config/fnclaude/config.toml
+[auto]
+tmux = "worktree"   # inject --tmux when you're creating a worktree via -w
 ```
 
-For more details on available commands and features, run `fnc help` or see the main fnclaude documentation.
+Off by default. The per-invocation override `--no-tmux` lets you escape for a single run without touching config.
+
+`auto.tmux = "worktree"` is the only valid non-default value: it injects `--tmux` only when you're explicitly creating a new worktree via `-w` (which claude requires for `--tmux` anyway). `fnc` never spawns worktrees on its own — that's always a user-initiated action.
+
+> **What about `--dangerously-skip-permissions` and `--ide`?** Use claude's own settings: `permissions.defaultMode` and `skipDangerousModePermissionPrompt` in `~/.claude/settings.json`, plus `autoConnectIde` in `~/.claude.json`. The CLI flags themselves (`-D`, `--dangerously-skip-permissions`, `-I`, `--ide`) still pass through verbatim for per-invocation use.
+
+### Auto-name from prompt
+
+When you pass a prompt after `--` (and aren't resuming an existing session), `fnc` generates a short hyphenated session label via Haiku and injects it as `--name`. The call has a 3-second timeout; on timeout, missing API key, or any error, it falls back to a heuristic that strips stop-words and takes the first three meaningful tokens.
+
+```sh
+fnc . -- "refactor the auth module"
+# → --name refactor-auth-module
+```
 
-## Key Features
+Skipped for `-p`/`--print`, `-r`/`--resume`, `-c`/`--continue`, and `--from-pr` — those don't create new named sessions. Requires `ANTHROPIC_API_KEY`; suppress the missing-key warning with `FNCLAUDE_QUIET_MISSING_API_KEY=1` (or the config equivalent) if you'd rather just rely on the heuristic.
 
-- **Model selection**: Pass `opus`, `sonnet`, or `haiku` as the first argument to pick a model alias
-- **Effort levels**: Set effort with `low`, `medium`, `high`, `xhigh`, or `max` as the second argument
-- **Worktree switching**: Automatically swap to a named worktree with `-w <name>` or as a positional argument
-- **Session resume**: Resume previous sessions with `fnc continue` or pick one interactively with `fnc resume`
-- **MCP integration**: Built-in Model Context Protocol server for seamless Claude integration
+### Cross-cwd `--resume`
+
+`claude --resume` normally exits with a "this conversation is from a different directory" message when you pick a session from elsewhere via the picker. `fnc` scans the last 4 KB of claude's output, catches that message after exit, and transparently re-execs a fresh `fnc` in the destination directory. The picker just works across all your projects — no flicker, no manual `cd`.
+
+Linux and macOS only; on Windows `fnc` falls back to a plain exec (no PTY, no detection).
+
+### Worktree intercept
+
+`fnc -w <name>` looks up `<name>` against the existing git worktrees of the project repo. If it matches, `fnc` swaps its cwd to that worktree and drops the `-w` flag — no new worktree is created, no duplicate. If it doesn't match, the flag passes through and the name doubles as the session `--name`.
+
+```sh
+fnc -w feature-branch    # cds to the feature-branch worktree if it exists
+fnc -w new-thing         # passes -w new-thing through; sets --name new-thing
+```
+
+### Auto-handoff from noop sessions
+
+When `fnc` is launched with no positional path, it drops into a "noop" session whose system prompt makes claude act as a router: classify the user's prompt into general-Q&A, read-shaped, or action-on-a-project. Action requests get written as a handoff file to a temp path and the relaunch command fires automatically (or with a confirmation, depending on `auto.handoff`).
+
+`auto.handoff` controls how the noop router proposes the relaunch:
+
+- `"never"` — paste-flow only. claude renders the relaunch command and copies it to the clipboard.
+- `"ask"` (default) — claude asks "Want me to switch you over now?" before doing anything.
+- `"<N>"` (seconds, e.g. `"5"`) — countdown auto-switch. `"0"` means instant.
+
+## Reference
+
+### Argument grammar
+
+The first two positional arguments may be "magic" shorthands:
+
+- **Position 1**: if the value is exactly `opus`, `sonnet`, or `haiku`, it is translated to `--model <alias>` and consumed. Otherwise treated as a path.
+- **Position 2**: only checked when position 1 was a model alias. If the value is exactly `low`, `medium`, `high`, `xhigh`, or `max`, it is translated to `--effort <level>` and consumed. Otherwise treated as a path.
+- **Position 3+**: never magic.
+
+To pass a literal directory named `opus`, prefix with `./`: `fnc ./opus`
+
+After magic slots resolve, the first remaining positional is the directory to launch `claude` in. Subsequent positionals are "extra dirs" that each receive `--add-dir`, `--mcp-config`, and `--settings` injection (files must exist for the latter two).
+
+Use `--` to separate `fnc` args from the prompt string:
+
+```sh
+fnc sonnet src/ -- "do the thing"
+```
+
+### Flag reference
+
+#### fnc-owned flags
+
+| Flag | Long | Description |
+|---|---|---|
+| | `--no-tmux` | Suppress auto-`--tmux` for this invocation |
+| `-A <dir>` | `--also <dir>` | Add an extra dir (repeatable) |
+| `-h` | `--help` | Print the flag reference and exit |
+| `-v` | `--version` | Print `fnc`'s version and exit |
+
+#### Short translations (fnc → claude)
+
+| Short | Long | Value |
+|---|---|---|
+| `-A` | `--also` | required (fnc-owned) |
+| `-B` | `--brief` | none |
+| `-C` | `--chrome` | none |
+| `-D` | `--dangerously-skip-permissions` | none |
+| `-F` | `--fork-session` | none |
+| `-G` | `--agent` | required |
+| `-I` | `--ide` | none |
+| `-M` | `--permission-mode` | required |
+| `-P` | `--from-pr` | optional |
+| `-R` | `--remote-control` | optional |
+| `-T` | `--tmux` | optional |
+| `-V` | `--verbose` | none |
+| `-W` | `--allowedTools` | required |
+
+Short flags follow standard POSIX collapsing: `-BVC` expands to `-B -V -C`. Only the last flag in a collapsed group may take a value. All other flags pass through to `claude` verbatim.
+
+### Config file
+
+Location: `$XDG_CONFIG_HOME/fnclaude/config.toml` (fallback `~/.config/fnclaude/config.toml`). A missing file is not an error — all defaults apply.
+
+Precedence: **CLI flag > env var > config file > built-in default**
+
+```toml
+[name]
+model = "claude-haiku-4-5"   # model for auto-generated session names
+timeout = "3s"               # timeout for the name-generation API call
+quiet_missing_api_key = false
+
+[auto]
+tmux = "never"      # "never" | "worktree"
+handoff = "ask"     # "never" | "ask" | non-negative integer seconds
+```
+
+#### Env var mapping
+
+| Config key | Env var |
+|---|---|
+| `name.model` | `FNCLAUDE_NAME_MODEL` |
+| `name.timeout` | `FNCLAUDE_NAME_TIMEOUT` |
+| `name.quiet_missing_api_key` | `FNCLAUDE_QUIET_MISSING_API_KEY` |
+| `auto.tmux` | `FNCLAUDE_TMUX` |
+| `auto.handoff` | `FNCLAUDE_HANDOFF` |
+
+`ANTHROPIC_API_KEY` is read (standard) for the auto-name LLM call.
 
 ## Status
 
-The CLI is actively maintained. Current release is published to npm under `@latest` and `@next` dist-tags. See the main fnclaude repository for release notes and version history.
+The CLI is a recent TypeScript rewrite of the original Go binary. It is actively maintained and published to npm under `@latest`. See the [main fnclaude repository](https://github.com/fnrhombus/fnclaude) for release notes and version history.
+
+File bugs and feature requests on [GitHub Issues](https://github.com/fnrhombus/fnclaude/issues).

package/package.json

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

package/src/argParser.ts

@@ -16,7 +16,7 @@
  */
 
 import { join as pathJoin } from 'node:path';
-import type { Args } from './args.js';
+import { brandParsed, type ParsedArgs } from './args.js';
 
 // ── Magic-word vocabularies ────────────────────────────────────────────────
 
@@ -163,11 +163,15 @@ export function parseShortFlag(arg: string, rest: readonly string[]): ParseShort
  * parseArgs is the canonical argv parser. `home` is the user's home dir
  * (typically `os.homedir()`); it's used to derive the noop fallback path.
  *
+ * Returns a `ParsedArgs` — the first stage of the immutable argv pipeline.
+ * Notably absent: `worktreeMatched`. That value only becomes meaningful
+ * after the intercept stage and is part of `InterceptedArgs` instead.
+ *
  * Throws Error on invalid input (too many positionals, missing values,
  * collapsed-group misuse, two subcommands, etc.). The Go original returns
  * `(Args, error)`; TS uses throw for the natural shape.
  */
-export function parseArgs(argv: readonly string[], home: string): Args {
+export function parseArgs(argv: readonly string[], home: string): ParsedArgs {
   let firstPath = '';
   const extraDirs: string[] = [];
   const passthrough: string[] = [];
@@ -339,7 +343,7 @@ export function parseArgs(argv: readonly string[], home: string): Args {
   const cwd = firstPathSet ? firstPath : defaultNoopDir(home);
   const usedNoopFallback = !firstPathSet;
 
-  return {
+  return brandParsed({
     cwd,
     extraDirs,
     passthrough: finalPassthrough,
@@ -347,34 +351,17 @@ export function parseArgs(argv: readonly string[], home: string): Args {
     worktreeSet,
     worktreeArg,
     usedNoopFallback,
-    worktreeMatched: false,
-  };
+  });
 }
 
-// ── Passthrough inspection helpers (used downstream by buildArgv etc.) ─────
-
-/**
- * True when any token is `--setting-sources` or starts with `--setting-sources=`.
- */
-export function settingSourcesInPassthrough(passthrough: readonly string[]): boolean {
-  return passthrough.some(
-    (t) => t === '--setting-sources' || t.startsWith('--setting-sources='),
-  );
-}
-
-/**
- * True when the exact token appears, or any `token=<anything>` form.
- */
-export function tokenInPassthrough(passthrough: readonly string[], long: string): boolean {
-  const prefix = `${long}=`;
-  return passthrough.some((t) => t === long || t.startsWith(prefix));
-}
-
-/**
- * True when --name or -n (bare or =value) appears anywhere in passthrough.
- */
-export function nameInPassthrough(passthrough: readonly string[]): boolean {
-  return passthrough.some(
-    (t) => t === '--name' || t === '-n' || t.startsWith('--name=') || t.startsWith('-n='),
-  );
-}
+// ── Passthrough inspection helpers ─────────────────────────────────────────
+//
+// The canonical implementations live in passthrough.ts. Re-exported here
+// for back-compat with callers that grew up importing them from argParser.
+// New code should import from passthrough.ts directly.
+
+export {
+  nameInPassthrough,
+  settingSourcesInPassthrough,
+  tokenInPassthrough,
+} from './passthrough.js';

package/src/args/preserve.ts

@@ -16,7 +16,7 @@
  * port mirrors every case 1:1.
  */
 
-import type { Request } from '../mcp/protocol.js';
+import type { RequestOverrides } from '../mcp/protocol.js';
 
 // ── Magic-word vocabularies (must match argParser.ts) ──────────────────────
 
@@ -219,7 +219,7 @@ export const transferDenyBareOK: ReadonlySet<string> = new Set([
  */
 export function applyOverrides(
   preserved: readonly string[],
-  req: Request,
+  req: RequestOverrides,
 ): string[] {
   let out = preserved.slice();
 

package/src/args.ts

@@ -1,62 +1,239 @@
 /**
- * Args holds the result of parsing fnclaude's own argv.
+ * Stage-typed argv pipeline.
  *
- * Mirrors the Go `Args` struct in src/main.go from the upstream Go
- * implementation. Property docstrings keep that mapping explicit; the parser
- * in argParser.ts is the only producer of values here.
+ * fnclaude's argv flows through five stages — parse, resolve, intercept,
+ * auto-name, sanitize — before being handed to buildArgv. Earlier the
+ * intermediate state was a single mutable `Args` bag passed through every
+ * step, each free to rewrite any field. The pipeline's *ordering* was a
+ * runtime invariant only: nothing stopped `buildArgv` from being called
+ * before `applyWorktreeIntercept`, and `worktreeMatched` started life as a
+ * placeholder boolean on the parsed shape, even though it has no meaningful
+ * value until intercept has run.
+ *
+ * The new shape uses distinct types per stage. Each function takes its
+ * predecessor's output type as input and returns the next stage's type.
+ * The shapes are structurally readonly and brand-discriminated, so:
+ *
+ *   - `parseArgs` returns `ParsedArgs`, which has NO `worktreeMatched`
+ *     field at all — the invariant "the intercept hasn't run yet" is
+ *     encoded in the type, not a sentinel value.
+ *   - `applyWorktreeIntercept` returns `InterceptedArgs`, which has
+ *     `worktreeMatched` materialized. Passing a `ParsedArgs` to `buildArgv`
+ *     is a compile error because `InterceptedArgs` is what `buildArgv`
+ *     accepts.
+ *   - Stages are immutable; each function returns a new value. The
+ *     pipeline composes by value, not by aliased reference.
+ *
+ * The brand fields (`__stage`) only exist in the type system — they're
+ * never assigned at runtime. The brand functions (`brandParsed` etc.) are
+ * named casts that document the boundary at which the stage transition
+ * happens.
+ */
+
+// ── Base shape ─────────────────────────────────────────────────────────────
+
+/**
+ * Fields every stage carries. All readonly: stage transitions produce new
+ * objects, never mutate.
  */
-export interface Args {
+export interface BaseArgs {
   /**
    * CWD is the directory claude will be launched in (first positional, or
-   * the noop fallback when no positionals are given).
+   * the noop fallback when no positionals are given). The interpretation
+   * narrows as stages progress — `ParsedArgs.cwd` is whatever the user
+   * typed; later stages have it resolved to an absolute path and/or
+   * swapped to a matched-worktree path.
    */
-  cwd: string;
+  readonly cwd: string;
 
   /**
    * ExtraDirs collects all -A / --also values in order. Positional 2 is the
    * worktree slot; -A is the only way to supply extra dirs.
    */
-  extraDirs: string[];
+  readonly extraDirs: readonly string[];
 
   /**
    * Passthrough is everything else, preserved in order, to be forwarded to
    * claude verbatim. Short flags are already translated to their long
-   * forms.
+   * forms. Later stages may *extend* this slice (e.g. the intercept pushes
+   * `--worktree <name>`, auto-name prepends `--name <name>`).
    */
-  passthrough: string[];
+  readonly passthrough: readonly string[];
 
   /**
    * NoTmux is true when the user passed --no-tmux (eaten by fnclaude; not
    * forwarded to claude).
    */
-  noTmux: boolean;
+  readonly noTmux: boolean;
 
   /**
    * WorktreeSet is true when the user passed -w / --worktree, OR supplied
-   * a 2nd positional after magic + subcommand consumption.
+   * a 2nd positional after magic + subcommand consumption, OR the Resolve
+   * step picked up a `+workspace` suffix from a repo reference.
    */
-  worktreeSet: boolean;
+  readonly worktreeSet: boolean;
 
   /**
    * WorktreeArg is the name/value given with -w / --worktree (or the 2nd
-   * positional), or "" if the flag was bare.
+   * positional / +workspace suffix), or "" if the flag was bare.
    */
-  worktreeArg: string;
+  readonly worktreeArg: string;
 
   /**
    * UsedNoopFallback is true when CWD was filled by the noop fallback (no
    * positional path given). Caller uses this to gate seed-noop behavior —
    * explicit paths don't get auto-seeded.
    */
-  usedNoopFallback: boolean;
+  readonly usedNoopFallback: boolean;
+}
+
+// ── Brand machinery ────────────────────────────────────────────────────────
+
+/**
+ * `Branded<T, K>` tags `T` with a phantom string literal `K` so two
+ * otherwise-structurally-identical types become assignment-incompatible.
+ * The `__stage` property exists only in the type — runtime values never
+ * carry it.
+ */
+type Branded<T, K extends string> = T & { readonly __stage: K };
+
+// ── Stage 1: parsed ────────────────────────────────────────────────────────
+
+/**
+ * Output of `parseArgs`. The argv has been split into structural fields,
+ * but no I/O has run yet — `cwd` is still the user-typed string, the
+ * worktree intercept hasn't queried git, and no autoname has been generated.
+ *
+ * Has NO `worktreeMatched` field. That value only becomes meaningful after
+ * the intercept stage, and encoding its absence in the type means a stale
+ * `worktreeMatched: false` can't accidentally be read by a downstream step.
+ */
+export type ParsedArgs = Branded<BaseArgs, 'parsed'>;
+
+// ── Stage 2: resolved ──────────────────────────────────────────────────────
+
+/**
+ * Output of the Resolve / tilde-expand step. `cwd` is an absolute path
+ * (when a path or repo ref was resolved) or the noop fallback. The Resolve
+ * step may also have promoted a `+workspace` suffix into `worktreeSet` +
+ * `worktreeArg`.
+ *
+ * Still no `worktreeMatched` — that's the next stage.
+ */
+export type ResolvedArgs = Branded<BaseArgs, 'resolved'>;
+
+// ── Stage 3: intercepted ───────────────────────────────────────────────────
 
+/**
+ * Output of `applyWorktreeIntercept`. `worktreeMatched` is now meaningful:
+ * true iff an existing worktree of the project repo matched
+ * `worktreeArg` (and `cwd` was swapped to that worktree's path). Downstream
+ * consumers (`buildArgv`'s auto-tmux gate, primarily) treat matched=true
+ * as "no new worktree being created this run" and avoid injecting flags
+ * that only make sense when claude is about to spin up a fresh worktree.
+ *
+ * `passthrough` may have been extended with `--worktree`, `--worktree <name>`,
+ * or `--name <name>` depending on whether the intercept matched.
+ */
+export interface InterceptedFields {
   /**
-   * WorktreeMatched is set by applyWorktreeIntercept when -w / --worktree
-   * was resolved against an existing worktree of the project repo (cwd was
-   * swapped to that worktree). Downstream consumers (buildArgv's auto-tmux
-   * gate, primarily) treat matched=true as "no new worktree being created
-   * this run" and avoid injecting flags that only make sense when claude
-   * is about to spin up a fresh worktree.
+   * True iff -w / --worktree was resolved against an existing worktree of
+   * the project repo (and cwd was swapped to that worktree).
    */
-  worktreeMatched: boolean;
+  readonly worktreeMatched: boolean;
 }
+
+export type InterceptedArgs = Branded<BaseArgs & InterceptedFields, 'intercepted'>;
+
+// ── Brand constructors ─────────────────────────────────────────────────────
+//
+// Each brand function is a named cast — it doesn't validate anything,
+// it just documents *where* the stage transition happens in the pipeline.
+// The asserted shape carries all the invariants the stage promises.
+
+/**
+ * Stamp a `BaseArgs`-shaped value as `ParsedArgs`. Only `parseArgs` should
+ * call this.
+ */
+export function brandParsed(a: BaseArgs): ParsedArgs {
+  return a as ParsedArgs;
+}
+
+/**
+ * Stamp a `BaseArgs`-shaped value as `ResolvedArgs`. Called after the
+ * Resolve / tilde-expand step (or to short-circuit when the input is
+ * already absolute and doesn't need resolution).
+ */
+export function brandResolved(a: BaseArgs): ResolvedArgs {
+  return a as ResolvedArgs;
+}
+
+/**
+ * Stamp a `BaseArgs & InterceptedFields`-shaped value as `InterceptedArgs`.
+ * Only `applyWorktreeIntercept` should call this.
+ */
+export function brandIntercepted(a: BaseArgs & InterceptedFields): InterceptedArgs {
+  return a as InterceptedArgs;
+}
+
+// ── Stage transitions (replace one or more fields, restamp the brand) ──────
+
+/**
+ * Return a new `ResolvedArgs` with the given field overrides. Used by the
+ * Resolve step to swap `cwd` (and possibly `worktreeSet` / `worktreeArg`)
+ * without mutating the parsed value.
+ */
+export function withResolved(
+  a: ParsedArgs | ResolvedArgs,
+  overrides: Partial<BaseArgs>,
+): ResolvedArgs {
+  return brandResolved({ ...(a as BaseArgs), ...overrides });
+}
+
+/**
+ * Return a new `InterceptedArgs` from a `ResolvedArgs` plus the
+ * intercept's outputs. `InterceptedFields` (currently just `worktreeMatched`)
+ * is mandatory in the overrides so the brand can't be applied without it.
+ */
+export function withIntercepted(
+  a: ResolvedArgs,
+  overrides: Partial<BaseArgs> & InterceptedFields,
+): InterceptedArgs {
+  return brandIntercepted({ ...(a as BaseArgs), ...overrides });
+}
+
+/**
+ * Return a new `InterceptedArgs` with `passthrough` (or other fields)
+ * replaced. Used by the auto-name and sanitize steps — both operate on the
+ * passthrough slice and produce a new slice; the rest of the args carries
+ * through unchanged.
+ *
+ * Returns `InterceptedArgs` (not a separate "named" / "sanitized" type)
+ * because no new invariants are established at those steps — only the
+ * passthrough slice changes shape, and that's already an in-stage edit
+ * the intercept itself does.
+ */
+export function withPassthroughUpdate(
+  a: InterceptedArgs,
+  overrides: Partial<BaseArgs>,
+): InterceptedArgs {
+  // Carry worktreeMatched through; only overrides win.
+  return brandIntercepted({
+    ...(a as BaseArgs & InterceptedFields),
+    ...overrides,
+  });
+}
+
+// ── Back-compat re-export ──────────────────────────────────────────────────
+
+/**
+ * `Args` was the single mutable bag the pipeline threaded through before
+ * the stage-typed refactor. Retained as an alias for `InterceptedArgs` so
+ * external consumers (the published `index.ts` surface, test helpers in
+ * downstream tooling) keep working while the refactor lands. New code
+ * should use the stage-specific types directly.
+ *
+ * @deprecated Use `ParsedArgs` / `ResolvedArgs` / `InterceptedArgs` per
+ *   the position in the pipeline.
+ */
+export type Args = InterceptedArgs;