@vzn/vx 0.0.50 → 0.0.52

package/src/cli/run.ts

@@ -461,6 +461,7 @@ export async function resolveRunOptions(
   const anchoredTasks = tasks.filter((t) => t.includes('#'))
   let projects: string[] | undefined
   let staged: RunOptions['staged']
+  let discovered: RunOptions['discovered']
   let selectedByDiff = false
   if (bareTasks.length === 0) {
     projects = undefined
@@ -485,6 +486,7 @@ export async function resolveRunOptions(
       // The graph walk staged every config; the run reuses those entries
       // instead of evaluating and staging them a second time.
       staged = resolved.staged
+      discovered = resolved.discovered
     }
   } else if (parsed.all) {
     projects = undefined
@@ -519,6 +521,7 @@ export async function resolveRunOptions(
   if (projects !== undefined) opts.projects = projects
   if (selectedByDiff) opts.selectedByDiff = true
   if (staged !== undefined) opts.staged = staged
+  if (discovered !== undefined) opts.discovered = discovered
   if (parsed.retries !== undefined) opts.retries = parsed.retries
   if (parsed.timeout !== undefined) opts.timeout = parsed.timeout
   if (parsed.cacheDir !== undefined) opts.cacheDir = parsed.cacheDir
@@ -556,6 +559,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
         ...(parsed.frozen ? { frozen: true } : {}),
       },
     )
+    if (picked === 'interrupted') return 130
     if (!picked) return 1
     tasks = [`${picked.project}#${picked.task}`]
   }

package/src/cli/select.ts

@@ -152,6 +152,8 @@ export type FilterResolution =
       byDiff: boolean
       /** The staged load the graph walk needed, for the run to reuse (`RunOptions.staged`). */
       staged?: ReadonlyMap<string, ProjectEntry>
+      /** The discovery this pass made, for the run to reuse (`RunOptions.discovered`). */
+      discovered: { root: string; projects: ProjectMeta[] }
     }
   | { error: string }
   | { empty: string }
@@ -240,6 +242,7 @@ export async function resolveFilters(
         workspaceGlobOwners: (changed) =>
           workspaceGlobOwners(root, projects, changed, load, stagedOnce),
         fingerprintClaims: () => workspaceFingerprintClaims(root, projects, load),
+        taskEdges: async () => edges ?? taskEdgesFrom(await stagedOnce()),
       })
       affectedByFilter.set(f, names)
     } catch (err) {
@@ -316,6 +319,7 @@ export async function resolveFilters(
     names: [...selected].sort(),
     byDiff: parsed.some((f) => !f.negate && f.gitSince !== undefined),
     ...(staged !== undefined ? { staged } : {}),
+    discovered: { root, projects },
   }
 }
 
@@ -325,11 +329,15 @@ export interface PickedTask {
   description?: string
 }
 
+/**
+ * The task the user picks from a numbered menu; null when nothing was
+ * picked (said on stderr), `'interrupted'` for a Ctrl-C at the prompt.
+ */
 export async function pickTask(
   cwd: string,
   io: { input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream } = {},
   load: CliLoadOptions = {},
-): Promise<PickedTask | null> {
+): Promise<PickedTask | null | 'interrupted'> {
   const projects = await loadWorkspaceProjects(cwd)
   // The staged load: a task a `project` plugin gave a config-less package
   // is on the menu, as it is in a run.
@@ -362,8 +370,30 @@ export async function pickTask(
     input: io.input ?? process.stdin,
     output: io.output ?? process.stdout,
   })
+  // On a terminal readline takes Ctrl-C and Ctrl-D itself, raw, and
+  // rejects the pending question with an AbortError — which reached the
+  // user as `vx: AbortError: Aborted with Ctrl+C` and a stack, exit 1.
+  // A SIGINT listener tells the two apart: Ctrl-C is an interrupt (exit 130,
+  // as a run's), Ctrl-D an answer that never came.
+  const abort = new AbortController()
+  let interrupted = false
+  rl.on('SIGINT', () => {
+    interrupted = true
+    abort.abort()
+  })
   try {
-    const answer = (await rl.question(`Pick a task [1-${entries.length}]: `)).trim()
+    let answer: string
+    try {
+      answer = (
+        await rl.question(`Pick a task [1-${entries.length}]: `, { signal: abort.signal })
+      ).trim()
+    } catch (err) {
+      if (!(err instanceof Error) || err.name !== 'AbortError') throw err
+      if (interrupted) return 'interrupted'
+      out.write('\n')
+      process.stderr.write(`vx run: no task picked\n`)
+      return null
+    }
     const n = Number(answer)
     if (!Number.isInteger(n) || n < 1 || n > entries.length) {
       process.stderr.write(`vx run: invalid selection: ${answer}\n`)

package/src/cli/upgrade.ts

@@ -2,14 +2,17 @@
 // Asks the GitHub release API for the asset of this os/arch and the
 // SHA-256 digest it publishes, downloads the asset, verifies the digest,
 // writes next to the current executable, atomic rename over it. The
-// digest is what makes a cut transfer (a proxy that drops a connection,
-// a disk that fills) or a swapped asset a refusal instead of a binary
-// that does not start: the rename is the last step, and a mismatch
-// replaces nothing.
+// digest is what makes a cut or corrupted transfer (a proxy that drops a
+// connection, a disk that fills) a refusal instead of a binary that does
+// not start: the rename is the last step, and a mismatch replaces
+// nothing. It guards the TRANSFER only: the digest comes from the same
+// release API as the download URL, and GitHub recomputes it when an asset
+// is uploaded, so whoever can replace the asset replaces its digest too
+// (item 1096). Nothing here verifies who built the binary.
 // Named `upgrade` (not `update`) per CLI convention: bun upgrade,
 // deno upgrade — "update" is what package managers do to indexes.
 
-import { chmod, rename, rm } from 'node:fs/promises'
+import { chmod, chown, link, rename, rm, stat } from 'node:fs/promises'
 import { seeHelp } from './help.js'
 import { UserError } from '../util/index.js'
 import { VERSION } from '../version.js'
@@ -70,6 +73,8 @@ function assetName(): string {
 
 /** What the release API says about the asset this platform installs. */
 export interface ReleaseAsset {
+  /** The release's tag, as the API names it (`v0.4.0`). */
+  tag: string
   url: string
   /** Lower-case hex SHA-256 of the asset's bytes. */
   sha256: string
@@ -113,7 +118,16 @@ export function releaseAsset(release: unknown, name: string): ReleaseAsset {
       `vx upgrade: release ${tag} publishes no SHA-256 digest for ${name} — nothing to verify the download against, so it is not attempted`,
     )
   }
-  return { url, sha256: m[1]!.toLowerCase() }
+  return { tag, url, sha256: m[1]!.toLowerCase() }
+}
+
+/**
+ * Whether a release tag names the version this binary is: the upgrade
+ * re-downloaded and replaced a binary with itself, printing `X → latest`
+ * (item 1098). Tags are `v<version>`; a bare version is accepted too.
+ */
+export function isThisVersion(tag: string, version: string): boolean {
+  return tag === `v${version}` || tag === version
 }
 
 /**
@@ -134,8 +148,26 @@ async function fetchOrRefuse(url: string, init: RequestInit, what: string): Prom
   }
 }
 
+/**
+ * A response's body, read to the end. The headers can arrive and the
+ * connection drop before the body does (a proxy that cuts a transfer):
+ * Bun rejects the read with its own `TypeError` (`ECONNRESET`, "The socket
+ * connection was closed unexpectedly"), which `fetchOrRefuse` never sees
+ * and the CLI printed as an internal error with a stack.
+ */
+async function readOrRefuse<T>(read: () => Promise<T>, url: string, what: string): Promise<T> {
+  try {
+    return await read()
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    throw new UserError(
+      `vx upgrade: could not ${what} from ${new URL(url).host} (${message}) — nothing replaced; check the network or the proxy and re-run`,
+    )
+  }
+}
+
 /** The release document for `latest` or a tag, from the GitHub API. */
-async function fetchRelease(tag: string | undefined): Promise<unknown> {
+export async function fetchRelease(tag: string | undefined): Promise<unknown> {
   const url =
     tag === undefined
       ? `https://api.github.com/repos/${REPO}/releases/latest`
@@ -149,25 +181,47 @@ async function fetchRelease(tag: string | undefined): Promise<unknown> {
     'read the release',
   )
   if (!res.ok) {
+    // GitHub answers an unauthenticated address past its hourly budget with
+    // 403 (or 429) and says so in the headers; "could not read the release
+    // (403)" read as a permissions fault (item 1098).
+    const reset = Number(res.headers.get('x-ratelimit-reset'))
+    const limited =
+      (res.status === 403 || res.status === 429) && res.headers.get('x-ratelimit-remaining') === '0'
     throw new UserError(
-      `vx upgrade: could not read the release (${res.status}) — ${url}${res.status === 404 && tag !== undefined ? ` (is ${tag} a release tag?)` : ''}`,
+      limited
+        ? `vx upgrade: GitHub's API rate limit for this address is spent${Number.isFinite(reset) && reset > 0 ? ` until ${new Date(reset * 1000).toISOString()}` : ''} — re-run after that`
+        : `vx upgrade: could not read the release (${res.status}) — ${url}${res.status === 404 && tag !== undefined ? ` (is ${tag} a release tag?)` : ''}`,
     )
   }
-  return (await res.json()) as unknown
+  // A body that is not JSON (a captive portal's page, a proxy's error
+  // page served with a 200) is the same refusal as a cut one.
+  return await readOrRefuse(() => res.json() as Promise<unknown>, url, 'read the release')
 }
 
 /**
  * Download `url`, verify its SHA-256 against `sha256`, and atomically
- * replace `dest` with it. Exported for tests (which stub `fetch` and
- * point `dest` at a tmp file); the CLI wires it to the release asset
- * and process.execPath.
+ * replace `dest` with it, keeping `dest`'s mode (and, as root, its owner):
+ * a 0750 install came back 0755 and owned by whoever upgraded (item 1097).
+ * `starts`, when given, is asked of the replaced binary; false puts the old
+ * one back, since the digest proves the bytes, not that this machine can
+ * run them (a CPU below the build's target, a `noexec` mount), and the
+ * upgrade reported success over a vx that no longer started. Exported for
+ * tests (which stub `fetch` and point `dest` at a tmp file); the CLI wires
+ * it to the release asset and process.execPath.
  */
-export async function replaceBinary(dest: string, url: string, sha256: string): Promise<void> {
+export async function replaceBinary(
+  dest: string,
+  url: string,
+  sha256: string,
+  starts?: (dest: string) => boolean,
+): Promise<void> {
   const res = await fetchOrRefuse(url, { redirect: 'follow' }, 'download the release asset')
   if (!res.ok) {
     throw new UserError(`vx upgrade: download failed (${res.status}) — ${url}`)
   }
-  const bytes = new Uint8Array(await res.arrayBuffer())
+  const bytes = new Uint8Array(
+    await readOrRefuse(() => res.arrayBuffer(), url, 'download the release asset'),
+  )
   if (bytes.byteLength === 0) {
     throw new UserError(`vx upgrade: empty download — ${url}`)
   }
@@ -178,27 +232,54 @@ export async function replaceBinary(dest: string, url: string, sha256: string):
     )
   }
   const tmp = `${dest}.upgrade-${process.pid}`
+  const old = `${dest}.previous-${process.pid}`
+  let kept = false
   try {
+    const was = await stat(dest).catch(() => null)
     await Bun.write(tmp, bytes)
-    await chmod(tmp, 0o755)
+    // Its mode, executable wherever it is readable: a 0750 install stays
+    // group-only, and a binary is never left without its execute bits.
+    await chmod(tmp, was === null ? 0o755 : (was.mode & 0o7777) | ((was.mode & 0o444) >> 2))
+    if (was !== null && process.getuid?.() === 0) await chown(tmp, was.uid, was.gid)
+    // A second name for the binary being replaced, so a new one that does
+    // not start can be put back; the rename below stays the one atomic swap.
+    if (starts !== undefined && was !== null) {
+      await link(dest, old)
+      kept = true
+    }
     await rename(tmp, dest)
   } catch (err) {
     await rm(tmp, { force: true })
+    if (kept) await rm(old, { force: true })
     const msg = err instanceof Error ? err.message : String(err)
     throw new UserError(
       `vx upgrade: could not replace ${dest} (${msg}) — ` +
         `check permissions, or reinstall with npm install -g @vzn/vx`,
     )
   }
+  if (starts === undefined || starts(dest)) {
+    if (kept) await rm(old, { force: true })
+    return
+  }
+  if (kept) await rename(old, dest)
+  throw new UserError(
+    `vx upgrade: the new binary did not start on this machine (\`${dest} --version\` failed)${kept ? ' — the previous vx is back in place' : ''}. Nothing else changed; report it with this os/arch`,
+  )
 }
 
 export async function upgradeCmd(args: readonly string[]): Promise<number> {
-  const tag = args.find((a) => !a.startsWith('-'))
   const unknown = args.find((a) => a.startsWith('-'))
   if (unknown !== undefined) {
     process.stderr.write(`vx upgrade: unknown flag: ${unknown}${seeHelp('upgrade')}\n`)
     return 1
   }
+  // One release is installed; a second tag was dropped without a word and
+  // the first one went in (`vx upgrade v0.0.22 v0.0.23`).
+  const [tag, extra] = args
+  if (extra !== undefined) {
+    process.stderr.write(`vx upgrade: unexpected argument: ${extra}${seeHelp('upgrade')}\n`)
+    return 1
+  }
   if (!isCompiledBinary()) {
     throw new UserError(
       'vx upgrade only works for the compiled binary. ' +
@@ -214,12 +295,19 @@ export async function upgradeCmd(args: readonly string[]): Promise<number> {
     )
   }
   const asset = releaseAsset(await fetchRelease(tag), assetName())
+  if (isThisVersion(asset.tag, VERSION)) {
+    process.stdout.write(`vx upgrade: already at ${VERSION} (${asset.tag}) — nothing to do\n`)
+    return 0
+  }
   process.stdout.write(`vx upgrade: ${VERSION} → ${tag ?? 'latest'} (${dest})\n`)
-  await replaceBinary(dest, asset.url, asset.sha256)
-  // Report the replaced binary's own version — the new build speaks
-  // for itself rather than this process guessing.
-  const proc = Bun.spawnSync({ cmd: [dest, '--version'], stdout: 'pipe', stderr: 'pipe' })
-  const v = new TextDecoder().decode(proc.stdout).trim()
-  process.stdout.write(`vx upgrade: installed ${v || '(version check failed)'}\n`)
+  // The replaced binary's own version: the new build speaks for itself
+  // rather than this process guessing, and one that cannot is rolled back.
+  let installed = ''
+  await replaceBinary(dest, asset.url, asset.sha256, (bin) => {
+    const proc = Bun.spawnSync({ cmd: [bin, '--version'], stdout: 'pipe', stderr: 'pipe' })
+    installed = new TextDecoder().decode(proc.stdout).trim()
+    return proc.exitCode === 0 && installed.startsWith('vx ')
+  })
+  process.stdout.write(`vx upgrade: installed ${installed}\n`)
   return 0
 }

package/src/cli/watch.ts

@@ -23,7 +23,7 @@ import {
   xxh3,
 } from '../util/index.js'
 import { asTrees } from '../cache/index.js'
-import { parseRunArgs, resolveRunOptions } from './run.js'
+import { parseRunArgs, resolveRunOptions, type RunArgs } from './run.js'
 import {
   fingerprintClaims,
   forwardedSignal,
@@ -397,30 +397,37 @@ export function armWatcher(
   return { watcher, ready }
 }
 
-export async function watchCmd(args: readonly string[]): Promise<number> {
-  const parsed = parseRunArgs(args)
-  if (parsed.error) {
-    process.stderr.write(`vx watch: ${parsed.error}\n`)
-    return 1
-  }
-
+/**
+ * The run flags a watch loop cannot honour, as the refusal line it prints; null
+ * when there is none. `WATCH_REFUSED_FLAGS` (help.ts) is the same list for
+ * the help line and the completions, and a test holds the two together.
+ */
+export function watchRefusal(parsed: RunArgs): string | null {
   if (parsed.dry !== undefined || parsed.graph !== undefined) {
-    process.stderr.write(`vx watch: --dry / --graph are not supported in watch mode\n`)
-    return 1
+    return 'vx watch: --dry / --graph are not supported in watch mode'
   }
   if (parsed.summarize !== undefined || parsed.profile !== undefined) {
-    process.stderr.write(
-      `vx watch: --summarize / --profile are not supported in watch mode (would overwrite per cycle)\n`,
-    )
-    return 1
+    return 'vx watch: --summarize / --profile are not supported in watch mode (would overwrite per cycle)'
   }
   // All three format ONE run's result and are consumed by `runCmd` alone, so
   // a watch loop silently ignored them. `--verbosity 0` is not rejected: it
   // asks for the output watch already gives.
   if (parsed.report !== undefined || parsed.reportFile !== undefined || parsed.verbosity > 0) {
-    process.stderr.write(
-      `vx watch: --report / --report-file / --verbosity are not supported in watch mode (they report a single run)\n`,
-    )
+    return 'vx watch: --report / --report-file / --verbosity are not supported in watch mode (they report a single run)'
+  }
+  return null
+}
+
+export async function watchCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseRunArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx watch: ${parsed.error}\n`)
+    return 1
+  }
+
+  const refused = watchRefusal(parsed)
+  if (refused !== null) {
+    process.stderr.write(`${refused}\n`)
     return 1
   }
   if (parsed.tasks.length === 0) {
@@ -459,9 +466,10 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // run()'s process.argv fallback put the bin's absolute path there, so
   // `vx last --list` showed `$ /…/bin.ts watch build` beside `$ vx run build`.
   opts.command = ['vx', 'watch', ...args].join(' ')
-  // A staged load from the selection pass is one run's worth of configs;
-  // every cycle after an edit must evaluate live.
+  // A staged load and a discovery from the selection pass are one run's
+  // worth; every cycle after an edit must load and list live.
   delete opts.staged
+  delete opts.discovered
   process.once('SIGINT', () => {
     process.stdout.write('\nvx watch: stopped\n')
     stop.abort('SIGINT')
@@ -509,8 +517,17 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // Uncaught, it ended watch at start while the same break mid-watch did
   // not (item 1017).
   let held: HeldPersistent | undefined
+  let refusedToStart = false
   try {
-    held = (await runOrchestrator(opts)).persistent
+    const initial = await runOrchestrator(opts)
+    held = initial.persistent
+    // A run that failed having run nothing refused to start: a requested
+    // name no project declares (run() says which, with a "did you mean").
+    // `vx run` exits 1 on it; `vx watch buidl` watched on, re-running the
+    // same refusal on every change, since no edit to an input can declare
+    // a task. A name only the diff left out (`--affected`) is `ok` and
+    // keeps watching.
+    refusedToStart = !initial.ok && initial.outcomes.length === 0
   } catch (err) {
     process.stderr.write(
       `vx watch: cycle failed: ${err instanceof Error ? err.message : String(err)}\n`,
@@ -520,6 +537,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     await held?.stop(forwardedSignal(stop.signal.reason))
     return 0
   }
+  if (refusedToStart) return 1
 
   const load: CliLoadOptions = {
     ...(opts.cacheDir !== undefined ? { cacheDir: opts.cacheDir } : {}),

package/src/config.ts

@@ -190,8 +190,10 @@ export interface TaskConfig {
  * write grant costs on Linux, is in `docs/schema.md` under
  * `exec.sandbox`.
  *
- * Paths are project-relative, absolute, or `~`-expanded — and are path
- * PREFIXES, never globs (a glob cannot be enforced by a mount).
+ * Paths are project-relative, absolute, or `~`-expanded, and may be
+ * globs: macOS matches the pattern in the policy, Linux expands it when
+ * the task starts (a mount cannot hold a pattern), so a file created
+ * later is not covered there — grant its directory.
  */
 export interface SandboxConfig {
   /** Capabilities granted on top of the task's own declarations. */
@@ -219,8 +221,11 @@ export interface SandboxConfig {
    * ignore: { write: ['*.bun-build'] }   // bun --compile stages a random
    *                                      // temp name in the cwd
    * ```
+   *
+   * A denial is classed read, write, systemInfo or network, so those four
+   * are what can be ignored.
    */
-  ignore?: SandboxGrants
+  ignore?: SandboxIgnore
   /**
    * Accept a weaker sandbox when vx itself already runs inside one
    * (a container, another sandbox). Without it, nesting fails fast rather
@@ -231,15 +236,23 @@ export interface SandboxConfig {
   weakerNetworkIsolation?: boolean
 }
 
+/** The denials `sandbox.ignore` can leave out of the report: patterns per class. */
+export interface SandboxIgnore {
+  read?: string[]
+  write?: string[]
+  systemInfo?: string[]
+  network?: string[]
+}
+
 export interface SandboxGrants {
   /**
-   * Readable path prefixes, added to the baseline — which is
+   * Readable paths or globs, added to the baseline — which is
    * `node_modules`, NOT `cache.inputs.files`. A task that reads its own
    * source in the sandbox says so here.
    */
   read?: string[]
   /**
-   * Writable path prefixes. The task can write NOTHING without these:
+   * Writable paths or globs. The task can write NOTHING without these:
    * declaring `cache.outputs.files` grants no write, and a task whose
    * only declaration is its outputs writes into a tmpfs that evaporates
    * (vx then warns that `cache.outputs` matched no files).

package/src/exec/executor.ts

@@ -173,8 +173,9 @@ export interface TaskPlacement {
   readonly command: string
   /**
    * Must run on this machine: the task is persistent, depends (transitively)
-   * on a persistent or sandboxed task, is sandboxed itself, or declares
-   * `exec.remote: false`. A `remote` executor is never offered such a task.
+   * on a persistent or sandboxed task, is sandboxed itself, declares
+   * `exec.remote: false`, or folds a runtime probe into its key (this
+   * machine's `node -v`). A `remote` executor is never offered such a task.
    */
   readonly pinnedLocal: boolean
   /** Declares `cache` — the only tasks whose input set is described, and so the only ones that can ship. */

package/src/exec/index.ts

@@ -6,7 +6,7 @@ export {
   runCommand,
   runPersistent,
   PersistentReadyError,
-  shellQuote,
+  withForwardArgs,
   signalExitCode,
   exitSignal,
   type CaptureConfig,

package/src/exec/runner.ts

@@ -82,6 +82,64 @@ export function shellQuote(arg: string): string {
   return `'${arg.replace(/'/g, `'\\''`)}'`
 }
 
+/**
+ * Where a shell comment still open at the end of `command` starts, or -1.
+ * A `#` opens one only unquoted and at the start of a word (`a#b`, `$#` and
+ * `${#x}` are words), and a newline closes it.
+ */
+function trailingCommentStart(command: string): number {
+  let quote = ''
+  let comment = -1
+  let atWordStart = true
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i]!
+    if (comment >= 0) {
+      if (c === '\n') {
+        comment = -1
+        atWordStart = true
+      }
+      continue
+    }
+    if (quote === "'") {
+      if (c === "'") quote = ''
+      continue
+    }
+    if (c === '\\') {
+      i++
+      atWordStart = false
+      continue
+    }
+    if (quote === '"') {
+      if (c === '"') quote = ''
+      continue
+    }
+    if (c === "'" || c === '"') {
+      quote = c
+      atWordStart = false
+      continue
+    }
+    if (c === '#' && atWordStart) {
+      comment = i
+      continue
+    }
+    atWordStart = /[\s;&|()<>]/.test(c)
+  }
+  return comment
+}
+
+/**
+ * The command a task runs with the args after `--` appended, shell-quoted.
+ * They go before a trailing comment: appended after it, `echo args: # show`
+ * ran without them and said nothing (item 1060).
+ */
+export function withForwardArgs(command: string, args: readonly string[] | undefined): string {
+  if (!args || args.length === 0) return command
+  const quoted = args.map(shellQuote).join(' ')
+  const comment = trailingCommentStart(command)
+  if (comment < 0) return `${command} ${quoted}`
+  return `${command.slice(0, comment).trimEnd()} ${quoted} ${command.slice(comment)}`
+}
+
 // Any shell control/expansion character means the wrapping `sh` has real
 // work to do (chaining, pipes, redirects, globbing, variables, subshells,
 // backgrounding) and must stay resident.
@@ -296,6 +354,15 @@ export async function drainOrAbort(
  */
 const READY_MATCH_WINDOW_CHARS = 64 * 1024
 
+/**
+ * Terminal escapes a `readyWhen` pattern is matched without: CSI (colour,
+ * cursor), OSC (titles, links) and the two-byte forms. Vite under
+ * `FORCE_COLOR` prints `\x1b[1mLocal\x1b[22m:`, which `Local:` never matched
+ * (item 1059). The streamed bytes keep them; only the tested text drops them.
+ */
+// eslint-disable-next-line no-control-regex -- ESC is the point
+const TERMINAL_ESCAPE_RE = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])/g
+
 /**
  * Why a persistent task never became ready — the reason every label and
  * record reads instead of a fabricated exit (item 270). `exitCode` is the
@@ -420,11 +487,16 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
   }
 
   // Stream readers. Each stream owns a pending fragment so a regex
-  // match isn't missed across chunk boundaries. The match runs over
-  // the WHOLE fragment, including a trailing partial line — prompt-
-  // style markers ("Listening on :3000" with no newline) would never
-  // resolve ready under line-by-line-only matching. Complete lines
-  // that didn't match are discarded after each test to bound memory.
+  // match isn't missed across chunk boundaries. The pattern is tested
+  // against each line on its own — without its break and without terminal
+  // escapes — so `^` and `$` anchor to a line as a user reads it; a whole
+  // fragment holding `booting\nready\n` failed `^ready` and `ready$`
+  // alike (item 1059). `\r` ends a line too: a progress bar's frames are
+  // lines to a reader. The trailing partial line is tested as well —
+  // prompt-style markers ("Listening on :3000" with no newline) would
+  // never resolve ready under complete-lines-only matching.
+  const readyLine = (re: RegExp, line: string): boolean =>
+    re.test(line.includes('\x1b') ? line.replace(TERMINAL_ESCAPE_RE, '') : line)
   const consumeChunks = async (
     stream: ReadableStream<Uint8Array> | number | undefined,
     isStderr: boolean,
@@ -442,23 +514,32 @@ export function runPersistent(opts: PersistentOptions): PersistentSpawn {
       else opts.onStdout?.(chunk)
       if (readyRe && readyAt === undefined) {
         fragment += chunk
-        if (readyRe.test(fragment)) {
+        let start = 0
+        for (let i = 0; i < fragment.length; i++) {
+          const c = fragment.charCodeAt(i)
+          if (c !== 10 && c !== 13) continue
+          if (readyLine(readyRe, fragment.slice(start, i))) {
+            markReady()
+            fragment = ''
+            return
+          }
+          start = i + 1
+        }
+        fragment = fragment.slice(start)
+        if (readyLine(readyRe, fragment)) {
           markReady()
           fragment = ''
-        } else {
-          const lastNl = fragment.lastIndexOf('\n')
-          if (lastNl >= 0) fragment = fragment.slice(lastNl + 1)
-          // Dropping complete lines assumes the stream HAS line breaks.
-          // `\r`-only output — a progress bar, a spinner — is one endless
-          // line, so the trim above never fires and the fragment becomes a
-          // third unbounded accumulator (measured 464 MiB in 6 s, and the
-          // per-chunk `test` over an ever-growing string makes it quadratic
-          // in CPU too). Keep the most RECENT window: a match may span the
-          // chunk boundary, and no readiness marker is anywhere near this
-          // long.
-          if (fragment.length > READY_MATCH_WINDOW_CHARS) {
-            fragment = fragment.slice(fragment.length - READY_MATCH_WINDOW_CHARS)
-          }
+          return
+        }
+        // Dropping complete lines assumes the stream HAS line breaks. Output
+        // with none is one endless line, so the fragment would become a
+        // third unbounded accumulator (measured 464 MiB in 6 s, and the
+        // per-chunk `test` over an ever-growing string makes it quadratic
+        // in CPU too). Keep the most RECENT window: a match may span the
+        // chunk boundary, and no readiness marker is anywhere near this
+        // long.
+        if (fragment.length > READY_MATCH_WINDOW_CHARS) {
+          fragment = fragment.slice(fragment.length - READY_MATCH_WINDOW_CHARS)
         }
       }
     }
@@ -566,10 +647,7 @@ export function spawnFailureText(err: unknown, cwd: string, what = 'task'): stri
 
 export async function runCommand(opts: RunOptions): Promise<RunResult> {
   const start = Date.now()
-  const fullCommand =
-    opts.forwardArgs && opts.forwardArgs.length > 0
-      ? opts.command + ' ' + opts.forwardArgs.map(shellQuote).join(' ')
-      : opts.command
+  const fullCommand = withForwardArgs(opts.command, opts.forwardArgs)
 
   let proc: ReturnType<typeof Bun.spawn>
   try {