@vzn/vx 0.0.646 → 0.0.649

package/src/util/index.ts

@@ -19,11 +19,14 @@ export {
   gitSpawnRefusal,
   isExecutableMissing,
   isOutOfFds,
+  gitFailure,
   notAWorkTree,
   OUT_OF_FDS_HINT,
+  thrownMessage,
   wantsJson,
 } from './errors.js'
 export { configErrorFrame, configRefusal } from './config-frame.js'
+export { envFlagOn } from './env-flag.js'
 export {
   detectColors,
   dumbTerminal,
@@ -34,11 +37,11 @@ export {
   WARN,
   type ColorSupport,
 } from './colors.js'
-export { barWidth, gradientRule } from './report.js'
+export { barWidth, gradientRule, ruleWidth } from './report.js'
 import * as ui from './ui.js'
 export { refusalNotice, sayLine, sayNotice } from './refusal-notice.js'
 export { ui }
-export { xxh3, xxh3hex } from './hash.js'
+export { keysSorted, xxh3, xxh3hex } from './hash.js'
 export {
   beginRun,
   mark,
@@ -48,7 +51,7 @@ export {
   stageTimes,
   type StageTime,
 } from './timing.js'
-export { clampInt, formatElapsed, MAX_TIMEOUT_MS, parseDecimalInt } from './num.js'
+export { clampInt, formatElapsed, isMeasure, MAX_TIMEOUT_MS, parseDecimalInt } from './num.js'
 export {
   asTrees,
   BUN_GLOB_WILDCARDS,
@@ -63,6 +66,7 @@ export {
   outputNever,
   restorableOutput,
   printable,
+  hasControl,
   relPosix,
   DOT_VX_GITATTRIBUTES,
   DOT_VX_GITIGNORE,
@@ -76,6 +80,9 @@ export {
   wholeSubtreePrefixes,
   slashBraceExpansions,
   braceAlternatives,
+  braceRange,
+  BRACE_RANGE_LIMIT,
+  writableUnder,
 } from './paths.js'
 export {
   claimExitForSignal,
@@ -102,7 +109,7 @@ export { isUnsupportedBun, MIN_BUN, unsupportedBunMessage } from './bun-version.
 export { executablePath, shellArgv, taskShell } from './which.js'
 export { procfsIsOwn } from './procfs.js'
 export { hangupIgnored } from './hangup.js'
-export { ESSENTIAL_ENV } from './essential-env.js'
+export { ESSENTIAL_ENV, withoutWorkspaceBins } from './essential-env.js'
 export { gitEnv, helperEnv, hideEnvFromTasks } from './hide-env.js'
 export {
   checkIgnore,
@@ -112,9 +119,11 @@ export {
   wholeIgnored,
 } from './git-ignored.js'
 export { realPath, realpathOf } from './real-path.js'
+export { IGNORE_ALL, ignoreDir, refuseSymlink, writeNoFollow } from './write-file.js'
 export {
+  heldSecrets,
   maskedCommand,
-  maskedEmitter,
+  maskedStreams,
   maskedLine,
   MASKED,
   secretMask,
@@ -131,3 +140,10 @@ export {
   type SecretUnavailableReason,
 } from './secrets.js'
 export { terminalOf, type SecretTerminal } from './hidden-prompt.js'
+export {
+  DependencySpecError,
+  compileTaskPattern,
+  isTaskPattern,
+  parseDependencySpec,
+  type DependencySpec,
+} from './dependency-spec.js'

package/src/util/num.ts

@@ -21,6 +21,14 @@ export function clampInt(n: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, Math.floor(n)))
 }
 
+/**
+ * A timing or need SQLite may keep: finite and not below zero. Infinity
+ * stored as REAL reads back through `group_concat` as `Inf`, a NaN forecast.
+ */
+export function isMeasure(v: number): boolean {
+  return Number.isFinite(v) && v >= 0
+}
+
 /**
  * Parse a PLAIN decimal integer from user input; `null` for anything else.
  *

package/src/util/paths.ts

@@ -153,7 +153,8 @@ export function outputDirPrefixes(globs: readonly string[]): string[] | null {
  * replays old outputs as a green hit (2026-09-10, probed one by one):
  * a leading `./`, an inner `/./` segment, a doubled `//`, and a trailing
  * `/` on a pattern (`src/*\/` means the trees under `src`, so it becomes
- * `src/*\/**`; a trailing slash on a LITERAL is `asTrees`' job). Applied
+ * `src/*\/**`; a trailing slash on a LITERAL is `asTrees`' job), and a
+ * trailing `/.`, read as a trailing `/`. Applied
  * after an optional `!`; a bare `.` is the empty entry the schema refuses.
  */
 export function normalizeGlob(glob: string): string {
@@ -173,6 +174,9 @@ function normalizeWith(glob: string, wildcards: RegExp): string {
   const neg = glob.startsWith('!')
   let g = neg ? glob.slice(1) : glob
   g = g.replace(/\/{2,}/g, '/').replace(/(^|\/)(\.\/)+/g, '$1')
+  // A trailing `/.` is the directory, as a trailing `/` is: `*/.` matched
+  // no file and `!gen/.` took nothing back (2026-10-28).
+  if (g.endsWith('/.')) g = g.slice(0, -1)
   if (g === '.') g = ''
   if (wildcards.test(g) && g.endsWith('/')) g = `${g.replace(/\/+$/, '')}/**`
   return neg ? `!${g}` : g
@@ -206,7 +210,7 @@ export function isLiteralPattern(glob: string): boolean {
  * class written out nine times — a spelling that drifts is how two guards
  * come to answer differently for one pattern.
  *
- * A task glob is a standard glob (M, 2026-10-18): `[...]` is a character
+ * A task glob is a standard glob (2026-10-18): `[...]` is a character
  * class and `\[id\]` names the route directory `[id]`. An escape counts as
  * a wildcard too: such a pattern is matched by `Bun.Glob`, which reads the
  * escape, never compared as a string; `asTrees` still reads an escaped-only
@@ -224,8 +228,9 @@ export const BUN_GLOB_WILDCARDS = /[*?[\]{}]/
 
 /**
  * An extglob group: `!(…)`, `@(…)`, `+(…)`, `*(…)`, `?(…)`. npm, yarn,
- * Nx and Turbo read it; `Bun.Glob` has none, and reads the group as
- * literal text or as a plain wildcard. A task input `src/@(x|y).ts` keyed
+ * Nx and Turbo read it; `Bun.Glob` had none before 1.4.4, and vx's own
+ * matchers still read the group as literal text or as a plain wildcard.
+ * A task input `src/@(x|y).ts` keyed
  * no file, so an edit to `src/x.ts` replayed a stale hit, and a member
  * glob `packages/!(x)` took in x (turborepo#3766). Every glob vx hands
  * `Bun.Glob` from a config refuses it.
@@ -245,8 +250,8 @@ export function taskGlob(pattern: string): Bun.Glob {
  * list across two thousand tasks, and the graph's overlap checks compiled
  * each entry per task pair, 3.3 s of an astro plan (2026-10-09). A pattern
  * comes from a config, so the set is bounded by what the configs say. Kept
- * per `Bun.Glob` in force: the playground and a test swap it, and a glob
- * built by one is not the other's.
+ * per `Bun.Glob` in force: a test swaps it, and a glob built by one is not
+ * the other's.
  */
 const taskGlobs = new WeakMap<object, Map<string, Bun.Glob>>()
 const anyTaskGlobs = new WeakMap<object, Map<string, (rel: string) => boolean>>()
@@ -272,7 +277,7 @@ function compileTaskGlob(pattern: string): Bun.Glob {
   // A path with a slash on the end names no file vx lists; `Bun.Glob` reads
   // it by rules of its own (`src/**` takes `src/`, never `src`). `scan`
   // stays `Bun.Glob`'s. Set on the instance, not by a subclass, so the glob
-  // is built by whatever `Bun.Glob` is at the call (the playground's port).
+  // is built by whatever `Bun.Glob` is at the call.
   glob.match = (rel: string): boolean =>
     rel.endsWith('/') ? native.match.call(glob, rel) : compiled.test(rel)
   return glob
@@ -363,20 +368,29 @@ export function stripTrailingSlash(p: string): string {
  * may not import `cache`, and a second copy is how the two would
  * disagree — which is exactly what item 441 measured about
  * `staticPrefix`.
+ *
+ * A brace is expanded first and each alternative read alone: as one
+ * pattern, `{src,lib}` never became the two trees and `{./src,lib}/**`
+ * kept a `./` no git path holds, so an edit under either was a stale hit
+ * and the same output glob saved an empty artifact.
  */
 export function asTrees(patterns: readonly string[]): string[] {
   const out: string[] = []
   for (const raw of patterns) {
-    const p = normalizeGlob(raw)
-    if (!namesOnePath(p)) {
-      out.push(p)
-      continue
+    const alternatives = raw.includes('{') ? braceAlternatives(raw) : [raw]
+    for (const alt of alternatives) {
+      const p = normalizeGlob(alt)
+      if (!namesOnePath(p)) {
+        out.push(p)
+        continue
+      }
+      const lit = stripTrailingSlash(p)
+      if (lit.length === 0) continue
+      out.push(lit, `${lit}/**`)
     }
-    const lit = stripTrailingSlash(p)
-    if (lit.length === 0) continue
-    out.push(lit, `${lit}/**`)
   }
-  return out
+  // Two alternatives can fold to one entry (`{./src,src}`).
+  return [...new Set(out)]
 }
 
 /**
@@ -438,6 +452,23 @@ export function outputMatcher(globs: readonly string[]): (rel: string) => boolea
  */
 const OUTPUT_NEVER = ['.git/**', '.vx/**', 'vx.lock.json']
 
+/**
+ * Whether vx may write or delete at `real`, a path a link on the way
+ * resolved: under `realBase` and not in its `.git`, in any case (a
+ * case-insensitive disk reads `.GIT` as `.git`). Names are held to
+ * `OUTPUT_NEVER` lexically; this holds where a link lands
+ * (vercel/turborepo#14808). Only the base's own: a deeper `.git` (a
+ * submodule under `gen/**`, a build's `dist/.git`) is an output an entry
+ * may name, and refused only once it existed on disk, a restore failed by
+ * what the last run left.
+ */
+export function writableUnder(real: string, realBase: string): boolean {
+  if (real === realBase) return true
+  if (!real.startsWith(realBase + path.sep)) return false
+  const top = real.slice(realBase.length + 1).split(path.sep, 1)[0]!
+  return top.toLowerCase() !== '.git'
+}
+
 /**
  * `OUTPUT_NEVER` relative to the workspace root, for `outputs.workspaceFiles`:
  * those globs cross into other projects, and every project's `vx.lock.json`
@@ -487,7 +518,7 @@ export function slashBraceExpansions(pattern: string): string[] {
   return expandBraces(pattern, true)
 }
 
-/** `pattern` with every brace group of two or more alternatives expanded. */
+/** `pattern` with every brace group of two or more alternatives, or a range, expanded. */
 export function braceAlternatives(pattern: string): string[] {
   return expandBraces(pattern, false)
 }
@@ -506,20 +537,53 @@ function expandBraces(pattern: string, slashOnly: boolean): string[] {
     }
     if (close === -1) return [pattern]
     const body = pattern.slice(open + 1, close)
-    if (cuts.length === 0 || (slashOnly && !body.includes('/'))) continue
+    if (slashOnly && !body.includes('/')) continue
+    const range = cuts.length === 0 ? braceRange(body) : null
+    if (cuts.length === 0 && range === null) continue
     const head = pattern.slice(0, open)
     const tail = pattern.slice(close + 1)
     const bounds = [open, ...cuts, close]
+    const alts = range ?? bounds.slice(1).map((end, k) => pattern.slice(bounds[k]! + 1, end))
     const out: string[] = []
-    for (let k = 0; k + 1 < bounds.length; k++) {
-      const alt = pattern.slice(bounds[k]! + 1, bounds[k + 1])
-      out.push(...expandBraces(head + alt + tail, slashOnly))
-    }
+    for (const alt of alts) out.push(...expandBraces(head + alt + tail, slashOnly))
     return [...new Set(out)]
   }
   return [pattern]
 }
 
+const NUMERIC_RANGE = /^(-?\d+)\.\.(-?\d+)(?:\.\.(-?\d+))?$/
+const LETTER_RANGE = /^(?:([a-z])\.\.([a-z])|([A-Z])\.\.([A-Z]))(?:\.\.(-?\d+))?$/
+/** The most names a brace range may name: each is a glob vx compiles. */
+export const BRACE_RANGE_LIMIT = 1024
+
+/**
+ * A brace range's names, as `Bun.Glob` reads them since 1.4.4 (bash's
+ * rule): `1..3`, `3..1`, `01..03` padded, `a..c`, `1..10..3` stepped; null
+ * for any other body, a mixed-case one (`A..c` spans `[`, `\` and `]`) and
+ * one past `BRACE_RANGE_LIMIT`. vx expands it like a comma brace, so every matcher
+ * names the files `Bun.Glob` does.
+ */
+export function braceRange(body: string): string[] | null {
+  const num = NUMERIC_RANGE.exec(body)
+  const letter = num === null ? LETTER_RANGE.exec(body) : null
+  const m =
+    num ?? (letter && [letter[0], letter[1] ?? letter[3], letter[2] ?? letter[4], letter[5]])
+  if (m === null) return null
+  const from = num ? Number(m[1]) : m[1]!.charCodeAt(0)
+  const to = num ? Number(m[2]) : m[2]!.charCodeAt(0)
+  const step = Math.abs(Number(m[3] ?? 1)) || 1
+  if (Math.abs(to - from) / step >= BRACE_RANGE_LIMIT) return null
+  const padded = num !== null && [m[1]!, m[2]!].some((n) => /^-?0\d/.test(n))
+  const width = padded ? Math.max(m[1]!.length, m[2]!.length) : 0
+  const out: string[] = []
+  for (let i = from; from <= to ? i <= to : i >= to; i += from <= to ? step : -step) {
+    if (!num) out.push(String.fromCharCode(i))
+    else if (i < 0) out.push(`-${String(-i).padStart(width - 1, '0')}`)
+    else out.push(String(i).padStart(width, '0'))
+  }
+  return out
+}
+
 /**
  * Whether a path git lists as UNTRACKED is an installed dependency: it sits
  * under a `node_modules` directory. Such a file is never an input, and the
@@ -541,3 +605,9 @@ const CONTROL = /[\x00-\x1f\x7f-\x9f]/g
 export function printable(s: string): string {
   return s.replace(CONTROL, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`)
 }
+
+/** Whether `s` holds a C0/C1 control or DEL, which `printable` would escape. */
+export function hasControl(s: string): boolean {
+  // oxlint-disable-next-line no-control-regex
+  return /[\x00-\x1f\x7f-\x9f]/.test(s)
+}

package/src/util/report.ts

@@ -14,10 +14,15 @@ export function barWidth(colors: ColorSupport): number {
   return columns === undefined ? 50 : Math.max(10, Math.min(50, columns - LABEL))
 }
 
+/** A rule's width, flush with the bars: the footer's and a task frame's section rules. */
+export function ruleWidth(colors: ColorSupport): number {
+  return LABEL + barWidth(colors)
+}
+
 /** `─ <mark> ` + dashes, flush with the bars. Shared by the run summary and every report. */
 export function gradientRule(colors: ColorSupport, mark = 'vx'): string {
   const head = `─ `
-  const width = LABEL + barWidth(colors)
+  const width = ruleWidth(colors)
   const dashes = '─'.repeat(Math.max(8, width - 3 - mark.length))
   if (!colors.enabled) return `${head}${mark} ${dashes}`
   const chunks = 8

package/src/util/secret-mask.ts

@@ -23,6 +23,7 @@ const NOT_SECRET = /_(FILE|PATH|DIR)$|^GIT_CONFIG_KEY_\d+$/i
  */
 const secretNames = new Map<string, boolean>()
 
+/** Whether vx masks a variable's value by its name alone (`NPM_TOKEN`, not `NPM_TOKEN_FILE`). */
 export function secretNamed(name: string): boolean {
   let secret = secretNames.get(name)
   if (secret === undefined) {
@@ -46,9 +47,28 @@ const MIN_SECRET_CHARS = 6
 
 export const MASKED = '***'
 
+/**
+ * Secrets this process holds that no environment names: a plugin's
+ * keychain answers (`ctx.secret`). A server's reply that echoed one
+ * printed it whole in the warning, beside masked task output.
+ */
+const held = new Set<string>()
+
+/** `value` is masked wherever this process's secrets are, from now on. */
+export function holdSecret(value: string): void {
+  held.add(value)
+}
+
+/** How many values `holdSecret` holds: a mask built with fewer is stale. */
+export function heldSecrets(): number {
+  return held.size
+}
+
 export interface SecretMask {
   /** `text` with every secret value replaced. */
   mask(text: string): string
+  /** Where `mask` replaces a value in `text`: `[start, end)` pairs, in order. */
+  spans(text: string): Array<[start: number, end: number]>
   /**
    * A mask for a stream of chunks: a value split across two chunks is
    * still caught, by holding back only a tail that could begin one until
@@ -101,6 +121,8 @@ export function secretMask(
     }
     for (const name of named) add(source[name])
   }
+  // This process's secrets: the environment's and the held ones.
+  if (sources.includes(process.env)) for (const value of held) add(value)
   if (values.size === 0) return null
   // Longest first, so a value holding another is replaced whole.
   const sorted = [...values].sort((a, b) => b.length - a.length)
@@ -137,6 +159,13 @@ export function secretMask(
   }
   return {
     mask,
+    spans(text) {
+      const out: Array<[number, number]> = []
+      pattern.lastIndex = 0
+      for (let m = pattern.exec(text); m !== null; m = pattern.exec(text))
+        out.push([m.index, m.index + m[0].length])
+      return out
+    },
     maskCut(head, tail) {
       let h = head.length - partialTail(head)
       pattern.lastIndex = 0
@@ -202,7 +231,7 @@ export interface TaskEnvSecrets {
  * value is written whole or in chunks that arrive together; one split by
  * a pause longer than that is not caught.
  */
-export function maskedEmitter(
+function maskedEmitter(
   mask: SecretMask,
   emit: (text: string) => void,
   idleMs = 25,
@@ -226,3 +255,35 @@ export function maskedEmitter(
     end,
   }
 }
+
+/**
+ * A task's two streams, each through `maskedEmitter`, in the order the
+ * task wrote them. Each held its own tail, so a stdout tail that could
+ * begin a value waited out the idle bound while stderr printed, and the
+ * run log, live and cached, put the stderr line first. A chunk on one
+ * stream now emits the other's held tail before it: a value split by a
+ * write to the other stream is not caught, as one split by a pause.
+ */
+export function maskedStreams(
+  mask: SecretMask,
+  emitOut: (text: string) => void,
+  emitErr: (text: string) => void,
+  idleMs = 25,
+): { out(chunk: string): void; err(chunk: string): void; end(): void } {
+  const out = maskedEmitter(mask, emitOut, idleMs)
+  const err = maskedEmitter(mask, emitErr, idleMs)
+  return {
+    out(chunk) {
+      err.end()
+      out.push(chunk)
+    },
+    err(chunk) {
+      out.end()
+      err.push(chunk)
+    },
+    end() {
+      out.end()
+      err.end()
+    },
+  }
+}

package/src/util/secrets.ts

@@ -1,10 +1,11 @@
 // A plugin's secrets, kept in the OS keychain (`Bun.secrets`) under the
 // plugin's own name, and asked for on the terminal when a plugin offers a
-// prompt and someone can answer (owner, 2026-10-17). Core reads no
+// prompt and someone can answer (2026-10-17). Core reads no
 // environment here: a variable, an option or a config file is the
 // plugin's to check first, so the keychain is always the last source.
 
 import { type SecretTerminal, terminalOf } from './hidden-prompt.js'
+import { holdSecret } from './secret-mask.js'
 
 /** What `ctx.secret` is asked: the entry's name, and the question to ask on a terminal. */
 export interface SecretRequest {
@@ -114,7 +115,10 @@ export class SecretBroker {
     let storeDown = false
     try {
       const stored = await this.store.get(entry)
-      if (stored) return stored
+      if (stored) {
+        holdSecret(stored)
+        return stored
+      }
     } catch {
       // No keychain (headless Linux without libsecret).
       storeDown = true
@@ -124,6 +128,7 @@ export class SecretBroker {
     const asked = this.prompting.then(() => this.ask(req.key, req.prompt!))
     this.prompting = asked.catch(() => undefined)
     const answer = await asked
+    holdSecret(answer)
     try {
       await this.store.set({ ...entry, value: answer })
     } catch (err) {

package/src/util/size.ts

@@ -24,11 +24,13 @@ export function parseSize(input: string): number | null {
 /**
  * Parse `<n><unit>` where unit is ms/s/m/h/d, case-insensitively (`parseSize`
  * has always been case-insensitive; this matched only lowercase, so `30D`
- * was rejected while `1GB` and `1gb` both worked).
+ * was rejected while `1GB` and `1gb` both worked). Minutes are `m` only:
+ * `M` is a month to systemd, and `--older-than 1M` read as a minute
+ * empties the cache.
  */
 export function parseDuration(input: string): number | null {
   const m = input.match(/^(\d+)(ms|[smhd])$/i)
-  if (!m) return null
+  if (!m || m[2] === 'M') return null
   const n = parseDecimalInt(m[1]!)
   if (n === null) return null
   // Lowercase before the switch: with the /i flag an uppercase `M` would
@@ -55,8 +57,14 @@ export function formatBytes(n: number): string {
   if (n < 1024) return `${n} B`
   const units = ['KB', 'MB', 'GB', 'TB']
   let v = n / 1024
+  // The tier is the printed value's: 1 MiB less a byte printed `1024 KB`,
+  // and 10 KiB less one `10.0 KB`.
+  const shown = (x: number): string => {
+    const one = x.toFixed(1)
+    return Number(one) < 10 ? one : x.toFixed(0)
+  }
   for (const u of units) {
-    if (v < 1024) return `${v.toFixed(v < 10 ? 1 : 0)} ${u}`
+    if (Number(shown(v)) < 1024) return `${shown(v)} ${u}`
     v /= 1024
   }
   return `${v.toFixed(0)} PB`

package/src/util/tail.ts

@@ -46,7 +46,12 @@ export function appendTail(t: Tail, chunk: string, limit = PERSISTENT_TAIL_CHARS
   // A single chunk over the cap is the one place we copy.
   if (t.chars > limit) {
     const only = t.chunks[0]!
-    const keep = only.slice(only.length - limit)
+    let start = only.length - limit
+    // A cut between a surrogate pair opened the frame on a lone low
+    // surrogate, which the terminal's UTF-8 encode prints as U+FFFD.
+    const first = only.charCodeAt(start)
+    if (first >= 0xdc00 && first <= 0xdfff) start++
+    const keep = only.slice(start)
     t.dropped += only.length - keep.length
     t.chunks[0] = keep
     t.chars = keep.length

package/src/util/timing.ts

@@ -9,6 +9,7 @@
 // prints (a push per stage, ~15 a run): a telemetry sink draws them as
 // spans (`stageTimes`). The per-call `span`s stay off unless enabled.
 
+import { detectColors, paint } from './colors.js'
 const enabled = process.env.VX_DEBUG_TIMING === 'true' || process.env.VX_DEBUG_TIMING === '1'
 let t0 = Bun.nanoseconds()
 // The wall clock at t0, read then: `performance.timeOrigin` plus the
@@ -117,5 +118,16 @@ export function printTimings(): void {
       '             (wall per call, summed; concurrent calls overlap — compare spans, not totals)',
     )
   }
-  process.stderr.write(lines.join('\n') + '\n')
+  const c = detectColors(process.stderr)
+  process.stderr.write(
+    `${lines
+      .map((l) =>
+        l.startsWith('[vx timing]')
+          ? `${paint('#06b6d4', '[vx timing]', c, { bold: true })}${paint('', l.slice(11), c, { dim: true })}`
+          : l.startsWith('             (')
+            ? paint('', l, c, { dim: true })
+            : l,
+      )
+      .join('\n')}\n`,
+  )
 }

package/src/util/ui.ts

@@ -45,11 +45,23 @@ export const place = (text: string): Inline => (text === 'local' ? text : id(tex
 /** Text in a tone's color. */
 export const tone = (t: Tone, text: string): Inline => ({ style: t, text })
 
+// oxlint-disable-next-line no-control-regex
+const CONTROL = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g
+
+/**
+ * `s` with every control byte but a tab and a line break as `\xNN`: a
+ * notice quotes paths and names, anyone's bytes, and one holding `ESC ]0;`
+ * retitled the terminal. The colors are the components' own, added after.
+ */
+const plainText = (s: string): string =>
+  s.replace(CONTROL, (ch) => `\\x${ch.charCodeAt(0).toString(16).padStart(2, '0')}`)
+
 /** One inline as text, colored for `c`. */
 export function inline(x: Inline, c: ColorSupport): string {
-  if (typeof x === 'string') return x
+  if (typeof x === 'string') return plainText(x)
   if (Array.isArray(x)) return (x as readonly Inline[]).map((p) => inline(p, c)).join('')
-  const { style, text } = x as { style: Style; text: string }
+  const { style } = x as { style: Style; text: string }
+  const text = plainText((x as { text: string }).text)
   switch (style) {
     case 'dim':
       return paint('', text, c, { dim: true })
@@ -81,9 +93,55 @@ export function status(t: Tone, verb: string, headline: Inline): Block {
   ])
 }
 
+/**
+ * A line vx says mid-run (`[vx] cache save failed: …`, `vx watch: …`), its
+ * words as they always read and its tag in the tone's hue; a line with no
+ * tag is painted whole. One string, no newline: the run's own streams write it.
+ */
+export function tagged(t: Tone, line: string, c: ColorSupport): string {
+  const body = line.replace(/\n+$/, '')
+  const tag = /^(?:\[vx\]|vx(?: [a-z][\w-]*){0,2}:|[\w@/.-]+: )/.exec(body)?.[0].trimEnd()
+  return tag === undefined
+    ? paint(HUE[t], body, c)
+    : `${paint(HUE[t], tag, c, { bold: true })}${body.slice(tag.length)}`
+}
+
+/** `tagged` on a stream (stderr unless told), colored for it. */
+export function say(t: Tone, line: string, stream: 'out' | 'err' = 'err'): void {
+  const s = stream === 'out' ? process.stdout : process.stderr
+  s.write(`${tagged(t, line, detectColors(s))}\n`)
+}
+
+/**
+ * A file or excerpt shown whole (`vx init --dry`, `vx docs`): its title rule
+ * bold, its body behind a dim gutter. Uncolored it is the bare text, so a
+ * pipe gets the bytes it would copy.
+ */
+export function excerpt(title: string, body: string): Block {
+  return block((c) => {
+    if (!c.enabled) return [`── ${title} ──`, ...body.split('\n')]
+    const gutter = paint(INFO, '│', c, { dim: true })
+    return [
+      paint(INFO, `── ${title} ──`, c, { bold: true }),
+      ...body
+        .split('\n')
+        .map((l, i, all) => (i === all.length - 1 && l === '' ? l : `${gutter} ${l}`)),
+    ]
+  })
+}
+
 /** Indented short lines: what is wrong, or what happened. */
 export function text(...items: Inline[]): Block {
-  return block((c) => items.flatMap((i) => lines(i, c).map((l) => `${INDENT}${l}`)))
+  return block((c) =>
+    items.flatMap((i) =>
+      lines(typeof i === 'string' ? prose(i) : i, c).map((l) => `${INDENT}${l}`),
+    ),
+  )
+}
+
+/** Plain words dim, each `command` in them bold: no line of vx reads plain white. */
+function prose(text: string): Inline {
+  return text.split(/(`[^`\n]+`)/).map((p, i) => (i % 2 === 1 ? cmd(p) : p === '' ? p : dim(p)))
 }
 
 /** An indented dim line: why it matters. */

package/src/util/which.ts

@@ -53,7 +53,7 @@ let dashMissedOn: string | undefined
  * The shell vx runs commands in: `dash` on macOS when vx's PATH has it,
  * else `sh` on vx's PATH. macOS's `/bin/sh` is a stub that execs bash, two
  * images for one shell, and bash where Linux runs dash, so a command read
- * one way on a Mac and another on Linux CI (owner, 2026-10-04).
+ * one way on a Mac and another on Linux CI (2026-10-04).
  */
 export function taskShell(): string {
   if (process.platform === 'darwin') {