@vibe-agent-toolkit/utils 0.1.41 → 0.1.42-rc.1

package/dist/windows-shell.d.ts

@@ -10,6 +10,15 @@
  * npm-installed CLIs (`claude`, `npm`, `git` shims, …) resolve to exactly such a
  * wrapper on Windows, so any spawn that omits this handling crashes on Windows only.
  */
+/**
+ * A `command` is treated as an explicit path (used verbatim, never PATH-resolved)
+ * when it is absolute or contains a path separator. A bare name (`claude`, `npm`,
+ * `git`) is resolved on PATH via `which.sync`. This mirrors — and preserves — the
+ * behaviour callers relied on before hardening: an explicit `binPath` is spawned
+ * as-given (so a nonexistent path still surfaces as an async `'error'` event, not a
+ * synchronous `which` throw), while a bare command is looked up.
+ */
+export declare function isPathLike(command: string): boolean;
 /**
  * Determine if shell should be used for command execution on Windows.
  *
@@ -32,13 +41,28 @@
  * **Root Cause of Previous ENOENT Issues:** Likely resolved in newer Node.js versions.
  * Current testing (Node 20+) shows shell:false works correctly with absolute path.
  *
- * ## Why This Is Secure
+ * ## Why This Is Secure — and where it is only *quoted*, not secure
+ *
+ * There are two modes, and they have genuinely different properties. Describing them as
+ * one ("arguments are always an array", "we never interpolate") would be false for this
+ * module's own Windows branch, which does exactly that interpolation.
  *
- * 1. **Minimal Shell Usage:** Shell only used for .cmd/.bat/.ps1 files (required)
- * 2. **Path Validation:** Command paths resolved via `which.sync()` before execution
- * 3. **Array-Based Arguments:** Arguments passed as array, preventing injection
- * 4. **Controlled Environment:** Commands from trusted configuration, not user input
- * 5. **No String Interpolation:** Never concatenate user input into command strings
+ * 1. **Minimal Shell Usage:** the shell is used ONLY when this function returns true —
+ *    `.cmd` / `.bat` / `.ps1`, where a shell interpreter is required by design.
+ * 2. **Path Validation:** command paths are resolved via `which.sync()` before execution.
+ * 3. **Two modes:**
+ *    - **`shell: false` (every other command — the default):** arguments are handed to
+ *      `spawn`/`spawnSync` as a real argv array. Nothing re-parses them, so there is no
+ *      metacharacter surface at all. This is the mode that is *secure*.
+ *    - **`shell: true` (this function returning true):** Node's DEP0190 forbids an args
+ *      array in shell mode, so {@link buildWindowsShellLine} MUST concatenate the command
+ *      and its arguments into a single string. Safety there rests entirely on
+ *      {@link windowsShellQuote}, which *quotes* — it does not neutralize. `%VAR%` still
+ *      expands inside double quotes, and an argument containing a `"` unavoidably desyncs
+ *      `cmd.exe`'s quote tracking (that function documents the two-parser trade in full).
+ * 4. **Controlled Environment:** commands and arguments come from trusted configuration.
+ *    On the `shell: true` branch that is a *requirement*, not a nicety — do not route
+ *    untrusted input through it; spawn with `shell: false` and an args array instead.
  *
  * ## References
  *
@@ -53,10 +77,86 @@ export declare function shouldUseShell(commandPath: string): boolean;
 /**
  * Quote a single argument for a Windows `cmd.exe` command line.
  *
- * Rules:
+ * Rules (the canonical `CommandLineToArgvW` algorithm — the same one used by .NET's
+ * `PasteArguments`, Python's `subprocess.list2cmdline`, and Rust's `Command`):
  *   - An arg that's empty, or contains whitespace, quotes, or any of `& | < > ^ ( ) % !`,
  *     gets wrapped in double quotes.
- *   - Embedded double quotes become `""` (cmd.exe's escape form inside quoted strings).
+ *   - Every run of backslashes that immediately precedes a `"` — an embedded one OR the
+ *     closing one — is doubled.
+ *   - Embedded double quotes are escaped as `\"`.
+ *
+ * ## Why backslash runs must be doubled before EVERY quote, not just the last one
+ *
+ * `CommandLineToArgvW` — what the launched program uses to split the line back into argv —
+ * reads a backslash run only in relation to the character that follows it: `2n`
+ * backslashes before a `"` mean `n` literal backslashes plus a *delimiter* quote; `2n+1`
+ * mean `n` literal backslashes plus a *literal* quote; a run followed by anything else is
+ * literal. So a backslash sitting in front of a quote silently changes what that quote
+ * means, and the parse desynchronizes from there — the argument swallows the rest of the
+ * line, or a backslash vanishes.
+ *
+ * The everyday cases are not exotic: `C:\Program Files\` (a directory path with a trailing
+ * separator and a space) and `{"dir":"C:\\tools\\"}` (JSON carrying a Windows path). A
+ * previous version of this function handled only the *trailing* run and escaped quotes as
+ * `""`. Replaying it through the reference parser in `test/windows-shell.test.ts` over every
+ * string in `{a, \, ", space, %}` of length ≤ 4 corrupted 85 of 781 inputs, 74 of which
+ * swallowed the following argument; every failure contained a backslash-quote sequence. That
+ * harness now runs on every commit, and asserts 0 of 781.
+ *
+ * ## TWO PARSERS IN SERIES: why `\"` and not `""` (the deliberate trade)
+ *
+ * The string this function emits is consumed by two different parsers, in order:
+ *
+ *   1. **`cmd.exe`**, which has NO backslash escape at all. It toggles a quote flag on
+ *      every `"` it sees, and only text inside that flag is protected from `& | < > ^ ( )`.
+ *   2. **`CommandLineToArgvW`** (or the CRT's equivalent) in the process the `.cmd`/`.bat`
+ *      shim ultimately launches. The dominant real case is an npm shim forwarding `%*` to
+ *      a real `.exe`, and `%*` is the *verbatim* remaining text — so whatever we emit here
+ *      is exactly what that second parser sees.
+ *
+ * These two want opposite things, and no single byte sequence satisfies both:
+ *
+ *   - `""` keeps `cmd.exe`'s quote count even, so metacharacters stay protected — but its
+ *     meaning to the second parser is version- and implementation-dependent. It is absent
+ *     from `CommandLineToArgvW`'s documented ruleset (which specifies only the backslash
+ *     rules), and under the widely-mirrored `CommandLineToArgvW` implementation — where a
+ *     run of three quotes yields one literal quote and *resets* the quote state — the token
+ *     `"a""b"` leaves the parser back inside quotes, so the following space stops
+ *     separating arguments and the next argument is swallowed.
+ *   - `\"` is understood identically by every implementation there is (CommandLineToArgvW,
+ *     old and new CRT, .NET, Python, Rust, Wine). But `cmd.exe` does not honour the
+ *     backslash, so each embedded quote flips its quote flag: within an argument that
+ *     contains a `"`, the span following that quote is *outside* cmd's quotes and a
+ *     metacharacter there would be re-interpreted.
+ *
+ * **The trade made here: `\"`.** Delivering the argument to the child process byte-exact is
+ * the job of this function, and `\"` is the only form with no parser-variant risk. The cost
+ * is bounded and stated plainly: for an argument containing BOTH a `"` and one of
+ * `& | < > ^ ( )`, `cmd.exe` may act on that metacharacter. Arguments with no embedded
+ * quote — which is every path, and the trailing-backslash case that motivated all of this —
+ * emit exactly two quotes and keep cmd's tracking balanced, so they are unaffected.
+ *
+ * (Rust makes the opposite trade in `append_bat_arg`, emitting `""`. Its target is a batch
+ * file reading `%~1` *itself*, where cmd is the only parser and injection is the whole
+ * threat model. Ours is a shim forwarding `%*` to an `.exe`, where the second parser is the
+ * one that decides what the program actually receives. Same two parsers, different consumer,
+ * different answer.)
+ *
+ * ## These characters are QUOTED, NOT NEUTRALIZED
+ *
+ * Wrapping in double quotes stops `cmd.exe` from re-interpreting whitespace and the
+ * redirection/pipe/grouping metacharacters — but it does **not** stop variable
+ * expansion. `cmd.exe` expands `%VAR%` *inside* double quotes, so:
+ *
+ *   - an arg containing `%PATH%` is still substituted before the program sees it, and
+ *   - a literal `%` in a filename (legal on Windows) can be corrupted by that pass.
+ *
+ * `%` is in the trigger class only so such args get quoted at all; treat the value as
+ * still shell-visible. `!` has the same shape under delayed expansion (`!VAR!`) — that
+ * is off by default for `cmd /c`, so it is a caveat rather than a live bug, but a
+ * caller that enables `ENABLEDELAYEDEXPANSION` inherits the problem. If an argument
+ * must survive verbatim, do not route it through a shell at all: spawn with
+ * `shell: false` and a real args array (see {@link shouldUseShell}).
  *
  * This is narrow on purpose: it's only used when we're forced to assemble a shell string
  * for `.cmd` / `.bat` wrappers on Windows (DEP0190 path). Callers still control what's
@@ -64,12 +164,44 @@ export declare function shouldUseShell(commandPath: string): boolean;
  * re-interpreted by the shell.
  */
 export declare function windowsShellQuote(arg: string): string;
+/**
+ * Choose the `commandToken` to hand {@link buildWindowsShellLine} on the Windows shell
+ * path. This is the ONE definition of that choice — both spawn wrappers
+ * ({@link ./safe-exec.ts} and {@link ./spawn-hardened.ts}) call it, so the two paths are
+ * provably identical rather than merely similar. They previously disagreed: the sync path
+ * emitted a raw, unquoted command, which silently broke on any explicit path containing a
+ * space (and now throws, thanks to the assertion in `buildWindowsShellLine`).
+ *
+ * Two cases, and they need opposite treatment:
+ *
+ *   - **Bare PATH name** (`claude`, `npm`) — emitted verbatim, NOT quoted and NOT replaced
+ *     by the resolved path, because `cmd.exe` must be left to re-resolve it through
+ *     `PATHEXT`. A bare name has no whitespace, so it never trips the assertion.
+ *   - **Explicit path** (absolute, or containing a separator) — the RESOLVED path, run
+ *     through {@link windowsShellQuote} so a directory with a space (`C:\Program Files\…`)
+ *     stays one token, and a trailing backslash cannot escape the closing quote and
+ *     swallow the next argument.
+ *
+ * @param command - The command as the caller supplied it (decides bare vs. explicit).
+ * @param resolvedPath - The path actually being launched (what gets quoted, when quoted).
+ */
+export declare function resolveShellCommandToken(command: string, resolvedPath: string): string;
 /**
  * Build the single `cmd.exe` command line used when a Windows shim forces shell mode
  * (Node's DEP0190 rejects `shell: true` with a separate args array, so command + args
  * must be one string). `commandToken` is the already-resolved command — a bare PATH
  * name that `cmd.exe` re-resolves via PATHEXT, or a pre-quoted explicit path — and each
  * arg is quoted via {@link windowsShellQuote} so shell metacharacters can't re-interpret.
+ *
+ * `commandToken` is emitted verbatim (quoting it here would defeat the PATHEXT lookup a
+ * bare name relies on), so quoting it is the caller's job — see
+ * {@link resolveShellCommandToken}, which is how every caller should produce it. An
+ * unquoted path containing a space — `C:\Program Files\tool.cmd` — would otherwise produce
+ * a silently broken line where `cmd.exe` tries to run `C:\Program` with `Files\tool.cmd` as
+ * its first argument. Those cases throw rather than emitting the broken line.
+ *
+ * @throws {Error} if `commandToken` is not a single `cmd.exe` token (see
+ *   {@link isSingleShellToken}). Pass it through {@link windowsShellQuote} first.
  */
 export declare function buildWindowsShellLine(commandToken: string, args: string[]): string;
 //# sourceMappingURL=windows-shell.d.ts.map

package/dist/windows-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"windows-shell.d.ts","sourceRoot":"","sources":["../src/windows-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAiB3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAElF"}
+{"version":3,"file":"windows-shell.d.ts","sourceRoot":"","sources":["../src/windows-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAiB3D;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2BrD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtF;AAsCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAWlF"}

package/dist/windows-shell.js

@@ -10,6 +10,18 @@
  * npm-installed CLIs (`claude`, `npm`, `git` shims, …) resolve to exactly such a
  * wrapper on Windows, so any spawn that omits this handling crashes on Windows only.
  */
+import { isAbsoluteAnyPlatform } from './path-core.js';
+/**
+ * A `command` is treated as an explicit path (used verbatim, never PATH-resolved)
+ * when it is absolute or contains a path separator. A bare name (`claude`, `npm`,
+ * `git`) is resolved on PATH via `which.sync`. This mirrors — and preserves — the
+ * behaviour callers relied on before hardening: an explicit `binPath` is spawned
+ * as-given (so a nonexistent path still surfaces as an async `'error'` event, not a
+ * synchronous `which` throw), while a bare command is looked up.
+ */
+export function isPathLike(command) {
+    return isAbsoluteAnyPlatform(command) || command.includes('/') || command.includes('\\');
+}
 /**
  * Determine if shell should be used for command execution on Windows.
  *
@@ -32,13 +44,28 @@
  * **Root Cause of Previous ENOENT Issues:** Likely resolved in newer Node.js versions.
  * Current testing (Node 20+) shows shell:false works correctly with absolute path.
  *
- * ## Why This Is Secure
+ * ## Why This Is Secure — and where it is only *quoted*, not secure
  *
- * 1. **Minimal Shell Usage:** Shell only used for .cmd/.bat/.ps1 files (required)
- * 2. **Path Validation:** Command paths resolved via `which.sync()` before execution
- * 3. **Array-Based Arguments:** Arguments passed as array, preventing injection
- * 4. **Controlled Environment:** Commands from trusted configuration, not user input
- * 5. **No String Interpolation:** Never concatenate user input into command strings
+ * There are two modes, and they have genuinely different properties. Describing them as
+ * one ("arguments are always an array", "we never interpolate") would be false for this
+ * module's own Windows branch, which does exactly that interpolation.
+ *
+ * 1. **Minimal Shell Usage:** the shell is used ONLY when this function returns true —
+ *    `.cmd` / `.bat` / `.ps1`, where a shell interpreter is required by design.
+ * 2. **Path Validation:** command paths are resolved via `which.sync()` before execution.
+ * 3. **Two modes:**
+ *    - **`shell: false` (every other command — the default):** arguments are handed to
+ *      `spawn`/`spawnSync` as a real argv array. Nothing re-parses them, so there is no
+ *      metacharacter surface at all. This is the mode that is *secure*.
+ *    - **`shell: true` (this function returning true):** Node's DEP0190 forbids an args
+ *      array in shell mode, so {@link buildWindowsShellLine} MUST concatenate the command
+ *      and its arguments into a single string. Safety there rests entirely on
+ *      {@link windowsShellQuote}, which *quotes* — it does not neutralize. `%VAR%` still
+ *      expands inside double quotes, and an argument containing a `"` unavoidably desyncs
+ *      `cmd.exe`'s quote tracking (that function documents the two-parser trade in full).
+ * 4. **Controlled Environment:** commands and arguments come from trusted configuration.
+ *    On the `shell: true` branch that is a *requirement*, not a nicety — do not route
+ *    untrusted input through it; spawn with `shell: false` and an args array instead.
  *
  * ## References
  *
@@ -65,13 +92,96 @@ export function shouldUseShell(commandPath) {
     const lowerPath = commandPath.toLowerCase();
     return lowerPath.endsWith('.cmd') || lowerPath.endsWith('.bat') || lowerPath.endsWith('.ps1');
 }
+/**
+ * Characters that force an argument to be wrapped in double quotes: whitespace, a quote,
+ * and `cmd.exe`'s metacharacters. Also the predicate {@link buildWindowsShellLine} uses to
+ * decide whether an *unquoted* command token is safe — "a token {@link windowsShellQuote}
+ * would have left alone" is exactly the token cmd.exe cannot split or re-interpret.
+ */
+const SHELL_QUOTE_TRIGGER = /["\s&|<>^()%!]/;
 /**
  * Quote a single argument for a Windows `cmd.exe` command line.
  *
- * Rules:
+ * Rules (the canonical `CommandLineToArgvW` algorithm — the same one used by .NET's
+ * `PasteArguments`, Python's `subprocess.list2cmdline`, and Rust's `Command`):
  *   - An arg that's empty, or contains whitespace, quotes, or any of `& | < > ^ ( ) % !`,
  *     gets wrapped in double quotes.
- *   - Embedded double quotes become `""` (cmd.exe's escape form inside quoted strings).
+ *   - Every run of backslashes that immediately precedes a `"` — an embedded one OR the
+ *     closing one — is doubled.
+ *   - Embedded double quotes are escaped as `\"`.
+ *
+ * ## Why backslash runs must be doubled before EVERY quote, not just the last one
+ *
+ * `CommandLineToArgvW` — what the launched program uses to split the line back into argv —
+ * reads a backslash run only in relation to the character that follows it: `2n`
+ * backslashes before a `"` mean `n` literal backslashes plus a *delimiter* quote; `2n+1`
+ * mean `n` literal backslashes plus a *literal* quote; a run followed by anything else is
+ * literal. So a backslash sitting in front of a quote silently changes what that quote
+ * means, and the parse desynchronizes from there — the argument swallows the rest of the
+ * line, or a backslash vanishes.
+ *
+ * The everyday cases are not exotic: `C:\Program Files\` (a directory path with a trailing
+ * separator and a space) and `{"dir":"C:\\tools\\"}` (JSON carrying a Windows path). A
+ * previous version of this function handled only the *trailing* run and escaped quotes as
+ * `""`. Replaying it through the reference parser in `test/windows-shell.test.ts` over every
+ * string in `{a, \, ", space, %}` of length ≤ 4 corrupted 85 of 781 inputs, 74 of which
+ * swallowed the following argument; every failure contained a backslash-quote sequence. That
+ * harness now runs on every commit, and asserts 0 of 781.
+ *
+ * ## TWO PARSERS IN SERIES: why `\"` and not `""` (the deliberate trade)
+ *
+ * The string this function emits is consumed by two different parsers, in order:
+ *
+ *   1. **`cmd.exe`**, which has NO backslash escape at all. It toggles a quote flag on
+ *      every `"` it sees, and only text inside that flag is protected from `& | < > ^ ( )`.
+ *   2. **`CommandLineToArgvW`** (or the CRT's equivalent) in the process the `.cmd`/`.bat`
+ *      shim ultimately launches. The dominant real case is an npm shim forwarding `%*` to
+ *      a real `.exe`, and `%*` is the *verbatim* remaining text — so whatever we emit here
+ *      is exactly what that second parser sees.
+ *
+ * These two want opposite things, and no single byte sequence satisfies both:
+ *
+ *   - `""` keeps `cmd.exe`'s quote count even, so metacharacters stay protected — but its
+ *     meaning to the second parser is version- and implementation-dependent. It is absent
+ *     from `CommandLineToArgvW`'s documented ruleset (which specifies only the backslash
+ *     rules), and under the widely-mirrored `CommandLineToArgvW` implementation — where a
+ *     run of three quotes yields one literal quote and *resets* the quote state — the token
+ *     `"a""b"` leaves the parser back inside quotes, so the following space stops
+ *     separating arguments and the next argument is swallowed.
+ *   - `\"` is understood identically by every implementation there is (CommandLineToArgvW,
+ *     old and new CRT, .NET, Python, Rust, Wine). But `cmd.exe` does not honour the
+ *     backslash, so each embedded quote flips its quote flag: within an argument that
+ *     contains a `"`, the span following that quote is *outside* cmd's quotes and a
+ *     metacharacter there would be re-interpreted.
+ *
+ * **The trade made here: `\"`.** Delivering the argument to the child process byte-exact is
+ * the job of this function, and `\"` is the only form with no parser-variant risk. The cost
+ * is bounded and stated plainly: for an argument containing BOTH a `"` and one of
+ * `& | < > ^ ( )`, `cmd.exe` may act on that metacharacter. Arguments with no embedded
+ * quote — which is every path, and the trailing-backslash case that motivated all of this —
+ * emit exactly two quotes and keep cmd's tracking balanced, so they are unaffected.
+ *
+ * (Rust makes the opposite trade in `append_bat_arg`, emitting `""`. Its target is a batch
+ * file reading `%~1` *itself*, where cmd is the only parser and injection is the whole
+ * threat model. Ours is a shim forwarding `%*` to an `.exe`, where the second parser is the
+ * one that decides what the program actually receives. Same two parsers, different consumer,
+ * different answer.)
+ *
+ * ## These characters are QUOTED, NOT NEUTRALIZED
+ *
+ * Wrapping in double quotes stops `cmd.exe` from re-interpreting whitespace and the
+ * redirection/pipe/grouping metacharacters — but it does **not** stop variable
+ * expansion. `cmd.exe` expands `%VAR%` *inside* double quotes, so:
+ *
+ *   - an arg containing `%PATH%` is still substituted before the program sees it, and
+ *   - a literal `%` in a filename (legal on Windows) can be corrupted by that pass.
+ *
+ * `%` is in the trigger class only so such args get quoted at all; treat the value as
+ * still shell-visible. `!` has the same shape under delayed expansion (`!VAR!`) — that
+ * is off by default for `cmd /c`, so it is a caveat rather than a live bug, but a
+ * caller that enables `ENABLEDELAYEDEXPANSION` inherits the problem. If an argument
+ * must survive verbatim, do not route it through a shell at all: spawn with
+ * `shell: false` and a real args array (see {@link shouldUseShell}).
  *
  * This is narrow on purpose: it's only used when we're forced to assemble a shell string
  * for `.cmd` / `.bat` wrappers on Windows (DEP0190 path). Callers still control what's
@@ -79,10 +189,90 @@ export function shouldUseShell(commandPath) {
  * re-interpreted by the shell.
  */
 export function windowsShellQuote(arg) {
-    if (arg === '' || /["\s&|<>^()%!]/.test(arg)) {
-        return `"${arg.replaceAll('"', '""')}"`;
+    if (arg !== '' && !SHELL_QUOTE_TRIGGER.test(arg)) {
+        return arg;
     }
-    return arg;
+    // Walk the argument, holding each backslash run until we see what follows it: a run
+    // before a quote (embedded, or the closing one) is doubled so the quote keeps its own
+    // meaning; a run before anything else is literal and emitted as-is.
+    let quoted = '"';
+    let backslashes = 0;
+    for (const char of arg) {
+        if (char === '\\') {
+            backslashes += 1;
+            continue;
+        }
+        if (char === '"') {
+            // 2n backslashes (now literal) + one more to escape the quote => 2n+1.
+            quoted += '\\'.repeat(backslashes * 2 + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        quoted += '\\'.repeat(backslashes) + char;
+        backslashes = 0;
+    }
+    // Trailing run: doubled, so the closing quote terminates the argument instead of being
+    // escaped by it (`"C:\Program Files\"` would otherwise swallow the next argument).
+    return `${quoted}${'\\'.repeat(backslashes * 2)}"`;
+}
+/**
+ * Choose the `commandToken` to hand {@link buildWindowsShellLine} on the Windows shell
+ * path. This is the ONE definition of that choice — both spawn wrappers
+ * ({@link ./safe-exec.ts} and {@link ./spawn-hardened.ts}) call it, so the two paths are
+ * provably identical rather than merely similar. They previously disagreed: the sync path
+ * emitted a raw, unquoted command, which silently broke on any explicit path containing a
+ * space (and now throws, thanks to the assertion in `buildWindowsShellLine`).
+ *
+ * Two cases, and they need opposite treatment:
+ *
+ *   - **Bare PATH name** (`claude`, `npm`) — emitted verbatim, NOT quoted and NOT replaced
+ *     by the resolved path, because `cmd.exe` must be left to re-resolve it through
+ *     `PATHEXT`. A bare name has no whitespace, so it never trips the assertion.
+ *   - **Explicit path** (absolute, or containing a separator) — the RESOLVED path, run
+ *     through {@link windowsShellQuote} so a directory with a space (`C:\Program Files\…`)
+ *     stays one token, and a trailing backslash cannot escape the closing quote and
+ *     swallow the next argument.
+ *
+ * @param command - The command as the caller supplied it (decides bare vs. explicit).
+ * @param resolvedPath - The path actually being launched (what gets quoted, when quoted).
+ */
+export function resolveShellCommandToken(command, resolvedPath) {
+    return isPathLike(command) ? windowsShellQuote(resolvedPath) : command;
+}
+/**
+ * Is `token` a single `cmd.exe` token — one thing cmd will treat as the command, with no
+ * way for it to split or re-interpret the rest?
+ *
+ * Two admissible shapes, and nothing else:
+ *
+ *   - **Unquoted:** a token {@link windowsShellQuote} would have left alone — no
+ *     whitespace, no quote, no metacharacter. A bare PATH name (`claude`, `npm`) or a
+ *     space-free path.
+ *   - **Quoted:** exactly ONE balanced outer pair with no further quote inside it, e.g.
+ *     `"C:\Program Files\tool.cmd"`. Stripping that pair must leave a body cmd cannot
+ *     escape from.
+ *
+ * The interior-quote check is the whole point. The previous predicate was "starts with `"`
+ * and ends with `"`", which is true of an entire crafted command line —
+ * `"a b" && calc "x"` — so a caller could hand over something that runs `calc` and this
+ * function would wave it through as "already quoted".
+ *
+ * The empty string is neither shape, and needs saying because it slipped between both
+ * branches: `''` does not start with `"`, and `SHELL_QUOTE_TRIGGER` cannot match a string
+ * with no characters, so the metacharacter branch returned true. `buildWindowsShellLine('',
+ * ['calc', 'b'])` was accepted and emitted `" calc b"` — a line whose first cmd.exe token
+ * is `calc`, i.e. the caller's first *argument* silently promoted into the command
+ * position. The explicit length check is what makes "one token" mean *one*, not *at most
+ * one*. (Whitespace-only tokens were already rejected — `\s` is in the trigger class.)
+ */
+function isSingleShellToken(token) {
+    if (token.length === 0) {
+        return false;
+    }
+    if (token.startsWith('"')) {
+        return token.length >= 2 && token.endsWith('"') && !token.slice(1, -1).includes('"');
+    }
+    return !SHELL_QUOTE_TRIGGER.test(token);
 }
 /**
  * Build the single `cmd.exe` command line used when a Windows shim forces shell mode
@@ -90,8 +280,25 @@ export function windowsShellQuote(arg) {
  * must be one string). `commandToken` is the already-resolved command — a bare PATH
  * name that `cmd.exe` re-resolves via PATHEXT, or a pre-quoted explicit path — and each
  * arg is quoted via {@link windowsShellQuote} so shell metacharacters can't re-interpret.
+ *
+ * `commandToken` is emitted verbatim (quoting it here would defeat the PATHEXT lookup a
+ * bare name relies on), so quoting it is the caller's job — see
+ * {@link resolveShellCommandToken}, which is how every caller should produce it. An
+ * unquoted path containing a space — `C:\Program Files\tool.cmd` — would otherwise produce
+ * a silently broken line where `cmd.exe` tries to run `C:\Program` with `Files\tool.cmd` as
+ * its first argument. Those cases throw rather than emitting the broken line.
+ *
+ * @throws {Error} if `commandToken` is not a single `cmd.exe` token (see
+ *   {@link isSingleShellToken}). Pass it through {@link windowsShellQuote} first.
  */
 export function buildWindowsShellLine(commandToken, args) {
+    if (!isSingleShellToken(commandToken)) {
+        throw new Error(`buildWindowsShellLine: commandToken is not a single cmd.exe token: ${commandToken}. ` +
+            'It must be either a bare name with no whitespace/quote/metacharacter, or one ' +
+            'balanced double-quoted token with no quote inside it. Wrap it with ' +
+            'windowsShellQuote() first — cmd.exe would otherwise split it or run part of it ' +
+            'as a separate command.');
+    }
     return `${commandToken} ${args.map(windowsShellQuote).join(' ')}`;
 }
 //# sourceMappingURL=windows-shell.js.map

package/dist/windows-shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"windows-shell.js","sourceRoot":"","sources":["../src/windows-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB;IAChD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yFAAyF;IACzF,4FAA4F;IAC5F,yDAAyD;IACzD,2EAA2E;IAC3E,EAAE;IACF,gDAAgD;IAChD,wEAAwE;IACxE,4DAA4D;IAE5D,yEAAyE;IACzE,MAAM,SAAS,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;IAC5C,OAAO,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChG,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,GAAG,KAAK,EAAE,IAAI,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7C,OAAO,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB,EAAE,IAAc;IACxE,OAAO,GAAG,YAAY,IAAI,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACpE,CAAC"}
+{"version":3,"file":"windows-shell.js","sourceRoot":"","sources":["../src/windows-shell.ts"],"names":[],"mappings":"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"}

package/dist/yaml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @vibe-agent-toolkit/utils/yaml
+ *
+ * Byte-surgical YAML value updates that replace or insert without reflowing
+ * the surrounding document. Pure with respect to Node builtins, but it pulls
+ * in `yaml` — roughly 271KB bundled. Quarantined behind its own subpath.
+ */
+export * from './yaml/surgical-yaml.js';
+//# sourceMappingURL=yaml.d.ts.map

package/dist/yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,yBAAyB,CAAC"}

package/dist/yaml.js

@@ -0,0 +1,9 @@
+/**
+ * @vibe-agent-toolkit/utils/yaml
+ *
+ * Byte-surgical YAML value updates that replace or insert without reflowing
+ * the surrounding document. Pure with respect to Node builtins, but it pulls
+ * in `yaml` — roughly 271KB bundled. Quarantined behind its own subpath.
+ */
+export * from './yaml/surgical-yaml.js';
+//# sourceMappingURL=yaml.js.map

package/dist/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,yBAAyB,CAAC"}

package/dist/zod.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @vibe-agent-toolkit/utils/zod
+ *
+ * Version-agnostic Zod type introspection via duck typing on `_def.typeName`,
+ * so it works across Zod v3 and v4 even when library and consumer versions
+ * differ. Pure — reaches no Node builtin. Isolating it here means consumers
+ * who never touch Zod are not coupled to the `zod` peer range.
+ */
+export * from './zod-introspection.js';
+//# sourceMappingURL=zod.d.ts.map

package/dist/zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../src/zod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,wBAAwB,CAAC"}

package/dist/zod.js

@@ -0,0 +1,10 @@
+/**
+ * @vibe-agent-toolkit/utils/zod
+ *
+ * Version-agnostic Zod type introspection via duck typing on `_def.typeName`,
+ * so it works across Zod v3 and v4 even when library and consumer versions
+ * differ. Pure — reaches no Node builtin. Isolating it here means consumers
+ * who never touch Zod are not coupled to the `zod` peer range.
+ */
+export * from './zod-introspection.js';
+//# sourceMappingURL=zod.js.map

package/dist/zod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.js","sourceRoot":"","sources":["../src/zod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,wBAAwB,CAAC"}