@vzn/vx 0.0.632 → 0.0.633

package/src/cache/chained-cache.ts

@@ -12,6 +12,7 @@
 // (item 1020). A save that fails in EVERY layer still throws, so the
 // caller's own "cache save failed" line stays the one word on it.
 
+import { statSync } from 'node:fs'
 import type {
   Cache,
   CacheEntry,
@@ -248,6 +249,14 @@ export class ChainedCache implements CacheLayer {
     return this.owner(hash).outputsPath(hash)
   }
 
+  /** A layer that cannot say keeps a file at `outputsPath`, or nothing. */
+  artifactSize(hash: string): number | undefined {
+    const owner = this.owner(hash)
+    return owner.artifactSize !== undefined
+      ? owner.artifactSize(hash)
+      : statSync(owner.outputsPath(hash), { throwIfNoEntry: false })?.size
+  }
+
   prune(options: PruneOptions): Promise<PruneResult> {
     return this.layers[0]!.prune(options)
   }

package/src/cache/inputs.ts

@@ -92,6 +92,11 @@ const ALWAYS_IGNORE = [
   // extracts the downloaded runtime into, `<cwd>/.<16 hex>-<8 hex>.tmp/`,
   // 60 MB mid-write under the same race (2026-09-29).
   '**/.????????????????-????????.tmp/**',
+  // vx's own restore temp (archive.ts), live only while an artifact lands
+  // beside its target. A key taken meanwhile listed it, the rename removed
+  // it, and every task reading that directory was withheld its save
+  // (withastro/astro: 25 of 33 builds re-ran on a restore, X-209).
+  '**/.vx-tmp-*',
 ]
 
 const DEFAULT_FILE_GLOBS: readonly string[] = ['**/*']

package/src/cache/layer.ts

@@ -267,7 +267,7 @@ export interface InvocationRecord {
 }
 
 /**
- * One cache-key component row for the `entry_inputs` table — keyed by
+ * One cache-key component of an `entry_inputs` row (v34: one row per entry) — keyed by
  * the cache-entry HASH it belongs to, not a run. Written inside the
  * entry-save transaction (`writeArtifactAndIndex`) on a miss/save; a
  * cache HIT does not save, so it persists nothing (warm runs are free).
@@ -730,12 +730,16 @@ export interface CacheLayer {
    */
   hashFile(filePath: string): Promise<string>
   /**
-   * Absolute path to the on-disk outputs artifact for a hash —
+   * Absolute path a file-backed artifact for a hash has —
    * `<cacheDir>/<hash>.tar.zst`. Returns the path whether or
-   * not the artifact exists. Exposed for telemetry / dashboards;
-   * `restoreOutputs` is the canonical way to materialize the bytes.
+   * not the artifact exists: a small artifact lives in the index, not
+   * in a file (`artifactSize` is its size). Exposed for telemetry /
+   * dashboards; `restoreOutputs` is the canonical way to materialize
+   * the bytes.
    */
   outputsPath(hash: string): string
+  /** The stored artifact's compressed size, wherever it lives; undefined when none is stored. */
+  artifactSize?(hash: string): number | undefined
   prune(options: PruneOptions): Promise<PruneResult>
   close(): void
 }

package/src/cache/layered-cache.ts

@@ -529,6 +529,10 @@ export class LayeredCache implements CacheLayer {
     return this.local.outputsPath(hash)
   }
 
+  artifactSize(hash: string): number | undefined {
+    return this.local.artifactSize(hash)
+  }
+
   hashFile(filePath: string): Promise<string> {
     return this.local.hashFile(filePath)
   }

package/src/cache/schema.ts

@@ -1,7 +1,8 @@
 // The index's tables, one concern: what a cache.db holds. `Cache` opens the
 // file, checks `SCHEMA_VERSION` and creates these; every statement against
 // them lives in the store that owns the table (file-hashes, config-evals,
-// output-index, history) or in cache.ts for `entries` and `entry_inputs`.
+// output-index, history) or in cache.ts for `entries`, `entry_inputs` and
+// `artifacts`.
 
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
 
@@ -255,22 +256,18 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     CREATE INDEX IF NOT EXISTS main.invocations_started ON invocations(started_at);
     CREATE INDEX IF NOT EXISTS main.invocations_branch  ON invocations(branch);
     CREATE INDEX IF NOT EXISTS main.invocations_ci      ON invocations(ci);
-    -- v22 (Tier 3): the input-fingerprint moat. One row per cache-key
-    -- component, keyed by the cache-ENTRY hash it belongs to (NOT a
-    -- run id). Written inside the entry-save transaction — only on a
-    -- miss/save, never on a hit — so a warm all-cache-hit run writes
-    -- nothing here (the warm path does zero extra work). The
-    -- why-did-this-re-run diff reads two entry hashes (this run's
-    -- runs.hash and the previous run's) and anti-joins their rows in
-    -- SQL over (kind,name,hash); a JSON blob would force an app-side
-    -- parse + compare on every probe. ON DELETE CASCADE keeps these
-    -- rows in sync with entries (a prune sweeps them automatically).
+    -- v22 (Tier 3): the input-fingerprint moat: each cache ENTRY's key
+    -- components (NOT a run's). Written inside the entry-save transaction,
+    -- only on a miss/save, so a warm all-cache-hit run writes nothing
+    -- here. v34: one row per entry, the components a JSON array of
+    -- [kind, name, hash] in (kind, name) code-unit order. A row per
+    -- component cost a b-tree insert each, and a task with 50 input
+    -- files spent ~0.5 ms a save on them; every reader loads the whole
+    -- set by entry hash and diffs it app-side anyway. ON DELETE CASCADE
+    -- keeps it in sync with entries (a prune sweeps it automatically).
     CREATE TABLE IF NOT EXISTS ${store}.entry_inputs (
-      entry_hash TEXT NOT NULL,
-      kind       TEXT NOT NULL,
-      name       TEXT NOT NULL,
-      hash       TEXT NOT NULL,
-      PRIMARY KEY (entry_hash, kind, name),
+      entry_hash TEXT PRIMARY KEY,
+      components TEXT NOT NULL,
       FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
     );
     -- v32: what belongs to the entries rather than to one workspace: the
@@ -280,9 +277,38 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       key   TEXT PRIMARY KEY,
       value TEXT NOT NULL
     );
+    ${artifactTables(store)}
   `)
 }
 
+/**
+ * v33: an artifact of at most `INLINE_MAX` compressed bytes lives here, its
+ * exact `<hash>.tar.zst` bytes, written in the transaction that writes its
+ * rows. No foreign key and outside every drop a `SCHEMA_VERSION` reset makes:
+ * the artifact is the record and the entries only its inventory, so a reset
+ * drops the rows and keeps these, as it keeps the files. `artifacts_meta`
+ * holds the table's own layout version (`'layout'`), the one thing that may
+ * drop it. `at` is the last use a row-less sweep judges, as a file's mtime;
+ * it sits before `bytes` so reading it never walks a blob's overflow pages.
+ */
+export function createArtifactTables(db: Database, store: 'main' | 'store'): void {
+  db.exec(artifactTables(store))
+}
+
+// In the entry tables' exec, so an open runs no statement more for them.
+function artifactTables(store: 'main' | 'store'): string {
+  return `
+    CREATE TABLE IF NOT EXISTS ${store}.artifacts (
+      hash  TEXT PRIMARY KEY,
+      at    INTEGER NOT NULL,
+      bytes BLOB NOT NULL
+    ) WITHOUT ROWID;
+    CREATE TABLE IF NOT EXISTS ${store}.artifacts_meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );`
+}
+
 /**
  * A `WHERE <column> …` test against many hashes, as one statement whatever
  * their number. A list of `?` is a new statement per length, compiled each

package/src/cli/docs-corpus.ts

@@ -0,0 +1,21 @@
+// The pages `vx docs` searches: core's reference, imported as text so the
+// compiled binary carries them and an npm install reads them from the
+// package (package.json `files`). Loaded only by `vx docs`.
+import caching from '../../docs/caching.md' with { type: 'text' }
+import cli from '../../docs/cli.md' with { type: 'text' }
+import execution from '../../docs/execution.md' with { type: 'text' }
+import features from '../../docs/features.md' with { type: 'text' }
+import patterns from '../../docs/patterns.md' with { type: 'text' }
+import schema from '../../docs/schema.md' with { type: 'text' }
+import security from '../../docs/security.md' with { type: 'text' }
+
+/** Page name (its file, no `.md`) → markdown. */
+export const PAGES: Readonly<Record<string, string>> = {
+  cli,
+  schema,
+  caching,
+  execution,
+  patterns,
+  security,
+  features,
+}

package/src/cli/docs-text.d.ts

@@ -0,0 +1,5 @@
+// A markdown page imported `with { type: 'text' }` is its text (docs-corpus.ts).
+declare module '*.md' {
+  const text: string
+  export default text
+}

package/src/cli/docs.ts

@@ -0,0 +1,167 @@
+// `vx docs <query> [--limit N] [--format pretty|json]` — search vx's
+// reference offline, for an agent that cannot reach the site: each page is
+// cut at its headings, and the sections holding every query word print
+// whole, best first.
+
+import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
+
+const SITE = 'https://vznjs.github.io/vx/'
+const DEFAULT_LIMIT = 3
+
+interface DocsArgs {
+  terms: string[]
+  limit: number
+  json: boolean
+  error?: string
+}
+
+function parseDocsArgs(args: readonly string[]): DocsArgs {
+  const out: DocsArgs = { terms: [], limit: DEFAULT_LIMIT, json: false }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (a === '--format' || a.startsWith('--format=')) {
+      const fv = formatValue(a === '--format' ? args[++i] : a.slice('--format='.length), 'docs')
+      if (typeof fv === 'object') return { ...out, error: fv.error }
+      out.json = fv === 'json'
+    } else if (a === '--limit' || a.startsWith('--limit=')) {
+      const v = a === '--limit' ? args[++i] : a.slice('--limit='.length)
+      const n = Number(v)
+      if (!Number.isInteger(n) || n < 1) {
+        return {
+          ...out,
+          error: `--limit takes a whole number above 0 (got ${v ?? 'nothing'})${seeHelp('docs')}`,
+        }
+      }
+      out.limit = n
+    } else if (a.startsWith('-')) {
+      return { ...out, error: `${refusedWord(a)}: ${a}${flagHint('docs', a)}${seeHelp('docs')}` }
+    } else out.terms.push(...words(a))
+  }
+  return out
+}
+
+export interface DocsHit {
+  page: string
+  heading: string
+  url: string
+  text: string
+}
+
+function words(s: string): string[] {
+  return s.toLowerCase().match(/[a-z0-9][a-z0-9._-]*/g) ?? []
+}
+
+/** GitHub's heading anchor, which Starlight shares: lowercase, punctuation dropped, spaces to `-`. */
+function anchor(heading: string): string {
+  return heading
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N} _-]/gu, '')
+    .replace(/ /g, '-')
+}
+
+/** A page's URL on the site; `features.md` is served as `all-features/`. */
+function pageUrl(page: string): string {
+  return `${SITE}${page === 'features' ? 'all-features' : page}/`
+}
+
+interface Section {
+  page: string
+  heading: string
+  text: string
+}
+
+/** Cut a page at its headings (outside code fences); the text before the first is the page's own. */
+function sections(page: string, md: string): Section[] {
+  const out: Section[] = []
+  let heading = ''
+  let lines: string[] = []
+  let fence = false
+  const flush = () => {
+    const text = lines.join('\n').trim()
+    if (text !== '') out.push({ page, heading, text })
+  }
+  for (const line of md.split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence
+    const h = fence ? null : /^#{1,4} (.+)$/.exec(line)
+    if (h !== null) {
+      flush()
+      heading = h[1]!.replace(/`/g, '').trim()
+      lines = [line]
+    } else lines.push(line)
+  }
+  flush()
+  return out
+}
+
+function count(hay: string, term: string): number {
+  let n = 0
+  for (let i = hay.indexOf(term); i !== -1; i = hay.indexOf(term, i + term.length)) n++
+  return n
+}
+
+/** The sections holding every term, best first: a term in the heading outweighs any count in the text. */
+export function searchDocs(
+  pages: Readonly<Record<string, string>>,
+  terms: readonly string[],
+  limit: number,
+): DocsHit[] {
+  const scored: { s: Section; score: number; order: number }[] = []
+  let order = 0
+  for (const [page, md] of Object.entries(pages)) {
+    for (const s of sections(page, md)) {
+      order++
+      const head = s.heading.toLowerCase()
+      const body = s.text.toLowerCase()
+      let score = 0
+      let all = true
+      for (const t of terms) {
+        const inBody = count(body, t)
+        if (inBody === 0) all = false
+        score += (head.includes(t) ? 10 : 0) + Math.min(inBody, 5)
+      }
+      if (all) scored.push({ s, score, order })
+    }
+  }
+  scored.sort((a, b) => b.score - a.score || a.order - b.order)
+  return scored.slice(0, limit).map(({ s }) => ({
+    page: s.page,
+    heading: s.heading,
+    url: s.heading === '' ? pageUrl(s.page) : `${pageUrl(s.page)}#${anchor(s.heading)}`,
+    text: s.text,
+  }))
+}
+
+export async function docsCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseDocsArgs(args)
+  if (parsed.error) return refuse('docs', args, parsed.error, 'VX_E_USAGE')
+  if (parsed.terms.length === 0) {
+    return refuse(
+      'docs',
+      args,
+      `name what to look for, as in \`vx docs cache inputs\`${seeHelp('docs')}`,
+      'VX_E_USAGE',
+    )
+  }
+  const { PAGES } = await import('./docs-corpus.js')
+  const hits = searchDocs(PAGES, parsed.terms, parsed.limit)
+  const query = parsed.terms.join(' ')
+  if (parsed.json) {
+    process.stdout.write(`${JSON.stringify({ query, hits })}\n`)
+    return 0
+  }
+  if (hits.length === 0) {
+    process.stdout.write(
+      `vx docs: no section of ${Object.keys(PAGES).join(', ')} holds every word of "${query}"; try fewer words, or ${SITE}llms.txt\n`,
+    )
+    return 0
+  }
+  process.stdout.write(
+    hits
+      .map(
+        (h) =>
+          `── ${h.page}.md${h.heading === '' ? '' : ` § ${h.heading}`} · ${h.url}\n\n${h.text}\n`,
+      )
+      .join('\n'),
+  )
+  return 0
+}

package/src/cli/help.ts

@@ -108,13 +108,14 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx run [OPTIONS] [TASK | PKG#TASK ...] [-- forwarded-args...]',
     '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
     '  vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
-    '  vx lock [--check]',
-    '  vx init [--dry] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
+    '  vx lock [--check] [--format pretty|json]',
+    '  vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
     '  vx upgrade [TAG]',
     '  vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--format pretty|json]',
     '  vx info [--format pretty|json] [--cache-dir <path>]',
     '  vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]',
     '  vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]',
+    '  vx docs <query> [--limit N] [--format pretty|json]',
     '  vx completions bash|zsh|fish',
     '  vx help [VERB]',
     '  vx version',
@@ -241,6 +242,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       TODO(vx-migrate) comments. Beside turbo.json or nx.json:',
     '                       runs @vzn/vx-migrate, which asks native or keep.',
     '      --dry            Print the generated files instead of writing them.',
+    '      --format json    With --dry: the plan as one JSON document (schemas/init.json).',
     '      --force          Overwrite existing vx.config.* files.',
     '      --mjs            Write .mjs files (no type import) instead of .ts.',
     '      --native         Turbo or Nx: write a vx.config.ts per package (no question).',
@@ -256,6 +258,13 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                           every flag of each. `eval "$(vx completions bash)"`,',
     '                           or write it where the shell loads completions from.',
     '',
+    'Docs:',
+    '  vx docs <query>      Search the reference offline (cli, schema, caching, execution,',
+    '                       patterns, security, features): the sections holding every',
+    '                       word of the query print whole, best first, with their URL.',
+    '      --limit N        How many sections (default 3).',
+    '      --format json    {query, hits: [{page, heading, url, text}]}.',
+    '',
     'Config lock:',
     '  vx lock              Evaluate every vx.config in the current environment and',
     '                       freeze the resolved objects into vx-lock.json. Plain runs',
@@ -264,7 +273,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx lock --check      Audit the lock: file-changed hash report PLUS a full',
     '                       re-evaluation compared against the frozen objects. Exits 1',
     '                       on drift (e.g. configs that read env vars). Run it before',
-    '                       `vx run --frozen` in CI.',
+    '                       `vx run --frozen` in CI. With --format json it prints',
+    '                       {upToDate, audited, notAudited, problems}.',
     '',
     ...(pluginCommands.length > 0 ? ['Plugin commands:', ...pluginCommands, ''] : []),
   ].join('\n')

package/src/cli/index.ts

@@ -109,6 +109,8 @@ export async function run(argv: readonly string[]): Promise<number> {
       return await (await import('./cache.js')).cacheCmd(rest)
     case 'lock':
       return await (await import('./lock.js')).lockCmd(rest)
+    case 'docs':
+      return await (await import('./docs.js')).docsCmd(rest)
     case 'init':
       return await (await import('./init.js')).initCmd(rest)
     case 'upgrade':

package/src/cli/init.ts

@@ -1,4 +1,4 @@
-// `vx init [--dry] [--force] [--mjs] [--native|--keep]` — a workspace from nowhere:
+// `vx init [--dry [--format json]] [--force] [--mjs] [--native|--keep]` — a workspace from nowhere:
 // one vx.config.ts per package from its package.json scripts, and the
 // workspace file every run needs. In a Turbo or Nx repo it hands over to
 // `@vzn/vx-migrate` (`migrate`), which asks a terminal whether to write
@@ -10,7 +10,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { mkdir, unlink } from 'node:fs/promises'
 import path from 'node:path'
-import { flagHint, seeHelp } from './help.js'
+import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import { PLUGIN_TEMPLATES } from './plugin-templates.js'
 import { isCompiledBinary } from './upgrade.js'
 import { VERSION } from '../version.js'
@@ -34,6 +34,8 @@ interface InitArgs {
   plugin?: string
   /** `--native` / `--keep` in a Turbo or Nx repo; unset, vx-migrate asks a terminal. */
   mode?: 'native' | 'keep'
+  /** `--format json` (with `--dry`): the plan as one JSON document. */
+  json?: boolean
   error?: string
 }
 
@@ -51,6 +53,10 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
         }
       }
       out.plugin = seam
+    } else if (a === '--format' || a.startsWith('--format=')) {
+      const fv = formatValue(a === '--format' ? args[++i] : a.slice('--format='.length), 'init')
+      if (typeof fv === 'object') return { ...out, error: fv.error }
+      out.json = fv === 'json'
     } else if (a === '--dry') out.dry = true
     else if (a === '--force') out.force = true
     else if (a === '--mjs') out.mjs = true
@@ -81,9 +87,15 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
 
 export async function initCmd(args: readonly string[]): Promise<number> {
   const parsed = parseInitArgs(args)
-  if (parsed.error) {
-    process.stderr.write(`vx init: ${parsed.error}\n`)
-    return 1
+  if (parsed.error) return refuse('init', args, parsed.error, 'VX_E_USAGE')
+  // In the verb, not the parser: completion asks the parser one flag at a time.
+  if (parsed.json === true && (!parsed.dry || parsed.plugin !== undefined)) {
+    return refuse(
+      'init',
+      args,
+      `--format json prints the workspace plan, so it needs --dry and no --plugin${seeHelp('init')}`,
+      'VX_E_USAGE',
+    )
   }
   if (parsed.plugin !== undefined) return scaffoldPlugin(parsed.plugin, parsed)
   const reads: LoadReads = new Map()
@@ -163,6 +175,7 @@ export async function initCmd(args: readonly string[]): Promise<number> {
     notes: [...(await unreadWorkspaces(root, workspace.packageGlobs)), ...unmapped],
     unmapped: unmapped.length > 0,
     dry: parsed.dry,
+    json: parsed.json === true,
     force: parsed.force,
     init: true,
     format: parsed.mjs ? 'mjs' : 'ts',
@@ -211,6 +224,7 @@ async function migrate(root: string, args: InitArgs): Promise<number> {
     args.force && '--force',
     args.mjs && '--mjs',
     args.mode === 'native' && '--native',
+    args.json === true && '--format=json',
   ].filter((f): f is string => typeof f === 'string')
   return Bun.spawn(migrateCommand(root, flags), {
     cwd: root,
@@ -257,7 +271,7 @@ async function adopt(
       )
     }
   } else if (args.dry) {
-    process.stdout.write(`── ${name} ──\n${text}\n`)
+    if (args.json !== true) process.stdout.write(`── ${name} ──\n${text}\n`)
   } else {
     if (existing !== undefined && existing !== name) await unlink(path.join(root, existing))
     await Bun.write(path.join(root, name), text)
@@ -278,6 +292,21 @@ async function adopt(
         : kept
           ? ''
           : `${cache}(): ${remote}, so vx shares that remote cache (inert where the variable is unset).\n`
+  if (args.json === true) {
+    process.stdout.write(
+      `${JSON.stringify({
+        dry: true,
+        source,
+        files: kept ? [] : [{ path: name, contents: text }],
+        kept: kept ? [existing] : [],
+        replaced: !kept && existing !== undefined && existing !== name ? [existing] : [],
+        todos: [],
+        notes: cacheLine === '' ? [] : [cacheLine.trimEnd()],
+        next: adoptionNext(root, runner, source),
+      })}\n`,
+    )
+    return 0
+  }
   process.stdout.write(
     `vx init: ${source} found — ${runner}() from @vzn/vx-migrate, a temporary start until vx init --native writes native config; nothing else written.\n` +
       `${wrote}\n${cacheLine}\nnext: ${adoptionNext(root, runner, source)}\n`,

package/src/cli/lock.ts

@@ -3,7 +3,7 @@
 // current environment. Design: docs/design/config-lock-2026-06.md.
 
 import type { ProjectConfig } from '../config.js'
-import { flagHint, refusedWord, seeHelp } from './help.js'
+import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 import { relPosix, secretMask, xxh3hex } from '../util/index.js'
 import {
   findWorkspaceRoot,
@@ -22,16 +22,22 @@ import { discoverCliProjects } from './workspace-config.js'
 
 interface LockArgs {
   check: boolean
+  format: 'pretty' | 'json'
   error?: string
 }
 
 export function parseLockArgs(args: readonly string[]): LockArgs {
-  const out: LockArgs = { check: false }
-  for (const a of args) {
+  const out: LockArgs = { check: false, format: 'pretty' }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
     if (a === '--check') out.check = true
-    else
+    else if (a === '--format' || a.startsWith('--format=')) {
+      const fv = formatValue(a === '--format' ? args[++i] : a.slice(9), 'lock')
+      if (typeof fv === 'object') return { ...out, ...fv }
+      out.format = fv
+    } else
       return {
-        check: false,
+        ...out,
         error: `${refusedWord(a)}: ${a}${flagHint('lock', a)}${seeHelp('lock')}`,
       }
   }
@@ -42,10 +48,15 @@ type ConfiguredMeta = ProjectMeta & { configPath: string }
 
 export async function lockCmd(args: readonly string[]): Promise<number> {
   const parsed = parseLockArgs(args)
-  if (parsed.error) {
-    process.stderr.write(`vx lock: ${parsed.error}\n`)
-    return 1
-  }
+  if (parsed.error) return refuse('lock', args, parsed.error, 'VX_E_USAGE')
+  // Writing the lock prints one line; only the audit has an answer to shape.
+  if (parsed.format === 'json' && !parsed.check)
+    return refuse(
+      'lock',
+      args,
+      `--format json answers --check only${seeHelp('lock')}`,
+      'VX_E_USAGE',
+    )
   const reads: LoadReads = new Map()
   const root = await findWorkspaceRoot(process.cwd(), reads)
   const workspace = await loadWorkspace(root, reads)
@@ -62,7 +73,7 @@ export async function lockCmd(args: readonly string[]): Promise<number> {
   // count above leaves out — `locked 0 project configs` on a turbo() repo
   // read like an audit of something (2026-09-16).
   const bare = all.length - metas.length
-  if (parsed.check) return await checkLock(root, metas, bare)
+  if (parsed.check) return await checkLock(root, metas, bare, parsed.format === 'json')
   return await writeLock(root, metas, bare)
 }
 
@@ -154,13 +165,29 @@ function secretsIn(projects: Record<string, LockfileEntry>): Array<{ at: string;
  *      catches eval-time env-var drift that file hashes cannot see —
  *      file bytes unchanged, resolved value changed.
  */
-async function checkLock(root: string, metas: ConfiguredMeta[], bare: number): Promise<number> {
+async function checkLock(
+  root: string,
+  metas: ConfiguredMeta[],
+  bare: number,
+  json: boolean,
+): Promise<number> {
+  const answer = (problems: string[]): number => {
+    if (json) {
+      const out = {
+        upToDate: problems.length === 0,
+        audited: metas.length,
+        notAudited: bare,
+        problems,
+      }
+      process.stdout.write(`${JSON.stringify(out)}\n`)
+    }
+    return problems.length === 0 ? 0 : 1
+  }
   const lock = await readLockfile(root)
   if (!lock) {
-    process.stderr.write(
-      `vx lock --check: no ${LOCKFILE_NAME} at ${root} — run \`vx lock\` first\n`,
-    )
-    return 1
+    const problem = `no ${LOCKFILE_NAME} at ${root} — run \`vx lock\` first`
+    if (!json) process.stderr.write(`vx lock --check: ${problem}\n`)
+    return answer([problem])
   }
   const results = await Promise.all(
     metas.map(async (m): Promise<string | null> => {
@@ -200,6 +227,7 @@ async function checkLock(root: string, metas: ConfiguredMeta[], bare: number): P
       )
     }
   }
+  if (json) return answer(failures)
   if (failures.length > 0) {
     for (const f of failures) process.stderr.write(`vx lock --check: ${f}\n`)
     return 1