@vzn/vx 0.0.636 → 0.0.638

package/src/orchestrator/lockfile-claim.ts

@@ -25,7 +25,7 @@ import type {
 } from './plugin.js'
 
 export interface LockfileClaimOptions {
-  /** The root-relative lockfile name, one of `WORKSPACE_FINGERPRINT_FILES`. */
+  /** The lockfile's name at the workspace root. */
   readonly file: string
   /**
    * Every project's digest from the file's text: importer directory
@@ -46,8 +46,7 @@ export interface LockfileClaimOptions {
   readonly version: number
   /**
    * `'project'` (default): each task folds its own project's digest.
-   * `'workspace'`: the whole file's hash into every task — the coarse key
-   * core would fold, through the plugin.
+   * `'workspace'`: the whole file's hash into every task — the coarse key.
    */
   readonly scope?: 'project' | 'workspace'
   /**
@@ -55,18 +54,46 @@ export interface LockfileClaimOptions {
    * (`@vzn/vx-lockfile/pnpm`). Default `'deps'`.
    */
   readonly part?: string
+  /**
+   * Each importer's links to other importers, from the same text, kept in
+   * the memo beside the digests so a `discover` hook reads them without a
+   * parse. Called once per distinct content, under either scope.
+   */
+  readonly importers?: (text: string) => ReadonlyMap<string, LockfileImporter>
 }
 
-/** The two hooks a lockfile plugin spreads into `definePlugin`. */
+/**
+ * What a lockfile records of one importer's links to the workspace's other
+ * importers: dependency name → importer directory (root-relative POSIX,
+ * `.` for the root).
+ */
+export interface LockfileImporter {
+  /** The entries it installs that resolve to an importer. */
+  readonly deps: Readonly<Record<string, string>>
+  /** Its peers that resolve to an importer, each with no installed entry of the same name. */
+  readonly peers: Readonly<Record<string, string>>
+}
+
+/** What a lockfile plugin spreads into `definePlugin` (`fingerprint`, `key`), and `importers` for its own stages. */
 export interface LockfileClaimHooks {
   readonly fingerprint: FingerprintClaim
   key(task: TaskNode, ctx: KeyHookContext): Promise<Readonly<Record<string, string>> | undefined>
+  /**
+   * `importers`' answer for the file as it is now, through the same memo
+   * and gates as `key`; undefined when the file is absent. Not a hook: a
+   * plugin calls it from its own `discover` or `project`.
+   */
+  importers(ctx: {
+    readonly workspaceRoot: string
+    readonly cacheDir: string
+  }): Promise<ReadonlyMap<string, LockfileImporter> | undefined>
 }
 
 interface Digests {
   /** xxh3 of the lockfile bytes; '' when the file is absent. */
   readonly lock: string
   readonly importers: ReadonlyMap<string, string>
+  readonly edges: ReadonlyMap<string, LockfileImporter>
 }
 
 interface Memo {
@@ -76,6 +103,7 @@ interface Memo {
   /** `extraFiles` → content hash when the digests were computed. */
   extras?: Record<string, string>
   importers: Record<string, string>
+  edges?: Record<string, LockfileImporter>
 }
 
 /** A root-relative extra file's content hash, '' when absent; a path leaving the root is never read. */
@@ -125,7 +153,16 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
   // at the same number read this one's memo: one that named no extra file
   // left the other's patch edits out of its key (X-130). The functions'
   // source stands for the claimant; a rebuild that changes it is a miss.
-  const claimant = xxh3hex([part, String(digest), String(options.extraFiles ?? '')].join('\0'))
+  // The scope too: a workspace-scope memo holds no digests.
+  const claimant = xxh3hex(
+    [
+      part,
+      scope,
+      String(digest),
+      String(options.extraFiles ?? ''),
+      String(options.importers ?? ''),
+    ].join('\0'),
+  )
   if (scope !== 'project' && scope !== 'workspace') {
     throw new Error(`scope must be 'project' or 'workspace', not ${JSON.stringify(scope)}`)
   }
@@ -149,7 +186,7 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
     try {
       identity = identityOf(await stat(full))
     } catch {
-      const digests: Digests = { lock: '', importers: new Map() }
+      const digests: Digests = { lock: '', importers: new Map(), edges: new Map() }
       seen.set(workspaceRoot, { identity: 'gone', extras: [], extraStats: {}, digests })
       return digests
     }
@@ -169,12 +206,14 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
     let extras: Record<string, string> = {}
     let extraStats: Record<string, string> = {}
     let importers: ReadonlyMap<string, string> | undefined
+    let edges: ReadonlyMap<string, LockfileImporter> = new Map()
     if (memo !== undefined) {
       const now = await hashExtras(workspaceRoot, Object.keys(memo.extras))
       if (Object.entries(memo.extras).every(([rel, h]) => now.hashes[rel] === h)) {
         extras = memo.extras
         extraStats = now.stats
         importers = memo.importers
+        edges = memo.edges
       }
     }
     if (importers === undefined) {
@@ -186,19 +225,19 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       importers =
         scope === 'workspace'
           ? new Map<string, string>()
-          : await computeAndMemo(
-              memoFile,
-              { version, claimant, lock: lockHash },
-              extras,
-              digest(text, new Map(Object.entries(extras))),
-            )
+          : digest(text, new Map(Object.entries(extras)))
+      edges = options.importers?.(text) ?? new Map()
+      // Workspace scope with no edges to keep has nothing a memo saves.
+      if (scope === 'project' || options.importers !== undefined) {
+        await writeMemo(memoFile, { version, claimant, lock: lockHash }, extras, importers, edges)
+      }
     }
     const rels = Object.keys(extras)
     const lock =
       rels.length === 0
         ? lockHash
         : xxh3hex([lockHash, ...rels.map((r) => `${r}\0${extras[r]}`)].join('\0'))
-    const digests: Digests = { lock, importers }
+    const digests: Digests = { lock, importers, edges }
     seen.set(workspaceRoot, { identity, extras: rels, extraStats, digests })
     return digests
   }
@@ -216,7 +255,7 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       files: [file],
       affected(change: FingerprintChange, ctx: FingerprintContext) {
         // One side absent: the file appeared or went — every project's
-        // installed tree is in question, and core's answer (all) is right.
+        // installed tree is in question.
         if (change.before === null || change.after === null) return undefined
         if (scope === 'workspace') return undefined
         // WHICH side failed is the whole difference between "your
@@ -248,6 +287,10 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         [part]: digestFor(digests.importers, importerOf(ctx.workspaceRoot, task.projectDir)),
       }
     },
+    async importers(ctx) {
+      const digests = await load(ctx.workspaceRoot, ctx.cacheDir)
+      return digests.lock === '' ? undefined : digests.edges
+    },
   }
 }
 
@@ -280,25 +323,42 @@ async function readMemo(
   version: number,
   claimant: string,
   lock: string,
-): Promise<{ extras: Record<string, string>; importers: Map<string, string> } | undefined> {
+): Promise<
+  | {
+      extras: Record<string, string>
+      importers: Map<string, string>
+      edges: Map<string, LockfileImporter>
+    }
+  | undefined
+> {
   try {
     const memo = (await Bun.file(memoFile).json()) as Memo
     if (memo.version !== version || memo.claimant !== claimant || memo.lock !== lock) {
       return undefined
     }
-    return { extras: memo.extras ?? {}, importers: new Map(Object.entries(memo.importers)) }
+    return {
+      extras: memo.extras ?? {},
+      importers: new Map(Object.entries(memo.importers)),
+      edges: new Map(Object.entries(memo.edges ?? {})),
+    }
   } catch {
     return undefined
   }
 }
 
-async function computeAndMemo(
+async function writeMemo(
   memoFile: string,
   identity: Pick<Memo, 'version' | 'claimant' | 'lock'>,
   extras: Record<string, string>,
   importers: ReadonlyMap<string, string>,
-): Promise<ReadonlyMap<string, string>> {
-  const memo: Memo = { ...identity, extras, importers: Object.fromEntries(importers) }
+  edges: ReadonlyMap<string, LockfileImporter>,
+): Promise<void> {
+  const memo: Memo = {
+    ...identity,
+    extras,
+    importers: Object.fromEntries(importers),
+    ...(edges.size > 0 ? { edges: Object.fromEntries(edges) } : {}),
+  }
   // Write-then-rename: a reader never sees a half-written memo, and two
   // concurrent runs each land a whole one.
   const tmp = `${memoFile}.tmp-${process.pid}-${Date.now()}`
@@ -309,7 +369,6 @@ async function computeAndMemo(
     // The memo is a speed-up, never a requirement: the digests are
     // computed either way, and the next run computes them again.
   }
-  return importers
 }
 
 function decode(bytes: Uint8Array): string {

package/src/orchestrator/logger.ts

@@ -1,5 +1,5 @@
 import type { TaskNode, TaskOutcome } from '../graph/index.js'
-import { detectColors, type ColorSupport } from './colors.js'
+import { settingEnv } from '../settings.js'
 import {
   formatFrameClose,
   formatFrameOpen,
@@ -20,7 +20,7 @@ import {
   type StatusStream,
   type WorkerSlot,
 } from './status-line.js'
-import { formatSummarySection, neverStarted, type RunContext } from './summary.js'
+import { formatSummarySection, neverStarted, ranUnsaved, type RunContext } from './summary.js'
 import { isGroupTask } from '../graph/index.js'
 import {
   appendTail,
@@ -29,6 +29,8 @@ import {
   resetTail,
   tailText,
   type Tail,
+  detectColors,
+  type ColorSupport,
 } from '../util/index.js'
 import { isCacheHit } from './telemetry.js'
 import { failedLabel, outcomeWord, ranNoCache } from './events.js'
@@ -177,7 +179,10 @@ export function resolveOutputView(
     ...(gha ? { gha: true } : {}),
     ...(ci ? { ci: true } : {}),
   })
-  if (options.outputLogs !== undefined) return mk(options.outputLogs)
+  // `run.outputLogs`: chosen before the workspace loads, so flag, then variable.
+  const outputLogs =
+    options.outputLogs ?? (settingEnv('run.outputLogs', env) as OutputView['mode'] | undefined)
+  if (outputLogs !== undefined) return mk(outputLogs)
   if (ci) return mk('full')
   if (options.flow !== undefined) return mk(options.flow)
   return mk('full')
@@ -198,6 +203,8 @@ export function defaultLogger(
     tty?: boolean
     /** The args after `--`: a requested task's `$ <command>` line shows them, as it ran. */
     forwardArgs?: readonly string[]
+    /** `false`: no summary in the live region and no blank line opening the log (`RunOptions.footer`). */
+    footer?: boolean
     /** The environment that names the terminal (`TERM_PROGRAM`, …); `process.env` by default. */
     env?: Readonly<Record<string, string | undefined>>
   } = {},
@@ -295,6 +302,7 @@ export function defaultLogger(
   let etaMs: number | undefined
   let critical: string | undefined
   let blocks: ReadonlyMap<string, number> | undefined
+  let expected: ReadonlyMap<string, number> | undefined
   let etaAtMs = 0
   const signals = writer.enabled
     ? terminalSignals(opts.env ?? process.env)
@@ -311,6 +319,10 @@ export function defaultLogger(
   // as `+k more` on the stats line. Focused flow keeps its lifecycle:
   // the region dies the moment a requested node starts streaming.
   let slots: (WorkerSlot | null)[] = []
+  // Rows shown: the most workers busy at once so far. An idle row past it
+  // was noise (a 10-core machine drew 9 on a one-chain run); it never
+  // shrinks, so a row never jumps.
+  let shownSlots = 0
   const slotQueue: WorkerSlot[] = []
   let succeeded = 0
   // Executed with no `cache` block: never a miss, counted apart.
@@ -318,6 +330,8 @@ export function defaultLogger(
   let upToDate = 0
   let restoredLocal = 0
   let restoredRemote = 0
+  let saved = 0
+  let notSaved = 0
   let skippedCount = 0
   let savedMs = 0
   // Cache-miss duration spread, accumulated incrementally (the same
@@ -375,16 +389,16 @@ export function defaultLogger(
       if (text.length < KEPT_LINE_CAP) held.rest = text
       else {
         held.rest = ''
-        writer.write(fenced(formatKeptLines(node, text, colors)))
+        taskWrite(fenced(formatKeptLines(node, text, colors)))
       }
       return
     }
     held.rest = text.slice(cut + 1)
-    writer.write(fenced(formatKeptLines(node, text.slice(0, cut), colors)))
+    taskWrite(fenced(formatKeptLines(node, text.slice(0, cut), colors)))
   }
   const flushKept = (): void => {
     for (const held of keptLines.values()) {
-      if (held.rest.length > 0) writer.write(fenced(formatKeptLines(held.node, held.rest, colors)))
+      if (held.rest.length > 0) taskWrite(fenced(formatKeptLines(held.node, held.rest, colors)))
       held.rest = ''
     }
   }
@@ -404,6 +418,7 @@ export function defaultLogger(
       etaMs = f.etaMs
       critical = f.critical
       blocks = f.blocks
+      expected = f.expected
     }
     if (signals.progress && total > 0) {
       const elapsed = now - startedAtMs
@@ -421,38 +436,44 @@ export function defaultLogger(
     }
     // The live summary IS the final summary's section, built from the
     // same formatter so the region visually becomes the printout.
-    const summaryLines = formatSummarySection(
-      {
-        failed,
-        successful: succeeded + upToDate + restoredLocal + restoredRemote,
-        skipped: skippedCount,
-        total,
-        upToDate,
-        restoredLocal,
-        restoredRemote,
-        miss: succeeded + failed - noCache,
-        noCache,
-        savedMs,
-        left: total - done,
-        ...(etaMs !== undefined ? { etaMs } : {}),
-        spread:
-          spreadCount > 0
-            ? { maxMs: spreadMax, minMs: spreadMin, sumMs: spreadSum, count: spreadCount }
-            : null,
-      },
-      Date.now() - startedAtMs,
-      colors,
-      runContext,
-    )
+    const summaryLines =
+      opts.footer === false
+        ? []
+        : formatSummarySection(
+            {
+              failed,
+              successful: succeeded + upToDate + restoredLocal + restoredRemote,
+              skipped: skippedCount,
+              total,
+              upToDate,
+              restoredLocal,
+              restoredRemote,
+              saved,
+              notSaved,
+              miss: succeeded + failed - noCache,
+              noCache,
+              savedMs,
+              left: total - done,
+              ...(etaMs !== undefined ? { etaMs } : {}),
+              spread:
+                spreadCount > 0
+                  ? { maxMs: spreadMax, minMs: spreadMin, sumMs: spreadSum, count: spreadCount }
+                  : null,
+            },
+            Date.now() - startedAtMs,
+            colors,
+            runContext,
+          )
     writer.setRegion(
       formatStatusRegion(
         {
           pinnedPersistent,
-          slots,
+          slots: slots.slice(0, shownSlots),
           overflow: slotQueue.length,
           nowMs: Date.now(),
           summaryLines,
           ...(blocks !== undefined ? { blocks } : {}),
+          ...(expected !== undefined ? { expected } : {}),
           ...(critical !== undefined ? { critical } : {}),
         },
         colors,
@@ -478,8 +499,21 @@ export function defaultLogger(
     writer.clearStatus()
   }
 
+  // The task log opens with one blank line before its first row, on a
+  // terminal and off one (M, 2026-10-14). A note vx prints before it is
+  // no task row (`status`). Without a footer, the caller frames the log
+  // (`vx watch` opens each cycle with its own line).
+  let logOpened = opts.footer === false
+  const taskWrite = (chunk: string): void => {
+    if (!logOpened && chunk.length > 0) {
+      logOpened = true
+      writer.write(`\n${chunk}`)
+      return
+    }
+    writer.write(chunk)
+  }
   const emitLine = (line: string): void => {
-    writer.write(`${line}\n`)
+    taskWrite(`${line}\n`)
     lineEmitted = true
   }
   // formatTaskBlock returns '' for group tasks (no exec) — skip the
@@ -487,14 +521,14 @@ export function defaultLogger(
   const emitBlock = (block: string): void => {
     if (block.length === 0) return
     const lead = lineEmitted || streamedSinceBlock ? '\n' : ''
-    writer.write(`${lead}${block}\n`)
+    taskWrite(`${lead}${block}\n`)
     lineEmitted = false
     streamedSinceBlock = false
   }
   // Live-frame close lines end a frame the same way emitBlock does:
   // with a trailing blank line, resetting the separator state.
   const emitFrameClose = (line: string): void => {
-    writer.write(`${line}\n\n`)
+    taskWrite(`${line}\n\n`)
     lineEmitted = false
     streamedSinceBlock = false
   }
@@ -549,6 +583,7 @@ export function defaultLogger(
       startedAtMs = Date.now()
       const cap = Math.max(1, Math.min(info.concurrency ?? 10, 10))
       slots = Array.from({ length: cap }, () => null)
+      shownSlots = 0
       if (writer.enabled && !statusDead && ticker === null) {
         // Keeps the per-worker elapsed time ticking between task events
         // (the time IS the motion — there's no spinner). The writer
@@ -585,8 +620,10 @@ export function defaultLogger(
       }
       const slot: WorkerSlot = { id: node.id, startedMs: Date.now() }
       const free = slots.indexOf(null)
-      if (free >= 0) slots[free] = slot
-      else slotQueue.push(slot)
+      if (free >= 0) {
+        slots[free] = slot
+        shownSlots = Math.max(shownSlots, free + 1)
+      } else slotQueue.push(slot)
       refresh(true)
     },
     forecast(load) {
@@ -675,7 +712,7 @@ export function defaultLogger(
       if (streamsLive(node)) {
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
-        writer.write(chunk)
+        taskWrite(chunk)
         return
       }
       const tail = persistentTails.get(node.id)
@@ -691,7 +728,7 @@ export function defaultLogger(
       if (streamsLive(node)) {
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
-        writer.write(chunk)
+        taskWrite(chunk)
         return
       }
       const tail = persistentTails.get(node.id)
@@ -747,7 +784,7 @@ export function defaultLogger(
             (framesTerminal && holdsTerminal(node)))
         if (framed && streamsLive(node)) {
           if (streamMidLine) {
-            writer.write('\n')
+            taskWrite('\n')
             streamMidLine = false
           }
           emitFrameClose(formatFrameClose(node, outcome, colors))
@@ -804,6 +841,8 @@ export function defaultLogger(
           case 'success':
             succeeded++
             if (ranNoCache(outcome)) noCache++
+            if (outcome.saved === true) saved++
+            else if (ranUnsaved(outcome)) notSaved++
             break
           case 'cache-hit':
             if (outcome.restored === false) upToDate++
@@ -830,7 +869,7 @@ export function defaultLogger(
       if (isGroupTask(node)) return
       if (holdsTerminal(node) && streamsLive(node) && outcome.status !== 'skipped') {
         if (streamMidLine) {
-          writer.write('\n')
+          taskWrite('\n')
           streamMidLine = false
         }
         emitFrameClose(formatFrameClose(node, outcome, colors))
@@ -908,7 +947,7 @@ export function defaultLogger(
               // and up-to-date included (owner: "always full frame
               // for a single task").
               if (streamMidLine) {
-                writer.write('\n')
+                taskWrite('\n')
                 streamMidLine = false
               }
               emitFrameClose(formatFrameClose(node, outcome, colors))
@@ -1003,7 +1042,7 @@ export function defaultLogger(
               // The message is ours (a literal, an integer and a signal
               // name); only the title carries user input.
               emitBlock(
-                `::error title=${ghaProperty(node.id)}::${failedLabel(outcome.exitCode, outcome.timedOut, outcome.sandboxViolations, outcome.notReady)}\n${body}`,
+                `::error title=${ghaProperty(node.id)}::${failedLabel(outcome.exitCode, outcome.timedOut, outcome.sandboxViolations, outcome.notReady, outcome.inputMoved)}\n${body}`,
               )
             } else {
               emitBlock(

package/src/orchestrator/metrics.ts

@@ -1,15 +1,18 @@
 // Run-history queries — pure functions over a `bun:sqlite` Database.
 //
 // `vx why` and `vx last` read through them, and so can any out-of-process
-// surface (an MCP server plugin, a dashboard). One canonical home for every
+// surface. One canonical home for every
 // aggregate over the runs / entries tables. The schema itself is owned by
 // src/cache/cache.ts.
 //
-// Pure SQL + JSON-safe return shapes. No Cache lifecycle here; the
+// Pure SQL + JSON-safe return shapes (`inputWriters` also stats the
+// files it names). No Cache lifecycle here; the
 // caller opens and closes. bigints are serialized as decimal strings
 // for JSON compatibility (matches the WireEvent timeUnixNano rule).
 
 import type { Database } from 'bun:sqlite'
+import { statSync } from 'node:fs'
+import path from 'node:path'
 // The keyed-run predicate lives beside the schema in cache/cache.ts, so a
 // rule written once cannot drift.
 import { KEYED_RUNS_SQL } from '../cache/index.js'
@@ -18,6 +21,10 @@ import { clampInt, MASKED, secretNamed } from '../util/index.js'
 import type { TaskInputComponent } from './task-hash.js'
 import { isPassStatus } from './telemetry.js'
 
+// A recorded `cache_policy` is the `--cache-policy` spec (`local:rw,remote:r`).
+const readsCache = (spec: string): boolean => /(?:^|,)(?:local|remote):w?r/.test(spec)
+const writesCache = (spec: string): boolean => /(?:^|,)(?:local|remote):r?w/.test(spec)
+
 // ---------------------------------------------------------------------------
 // Run listing + detail
 // ---------------------------------------------------------------------------
@@ -409,8 +416,8 @@ function unchangedKeyNote(
       p: string
     } | null
   )?.p
-  if (policy !== undefined && !policy.split(',').some((axis) => axis === 'lR' || axis === 'rR')) {
-    return 'cache key unchanged — re-executed because this run did not read the cache (--force, or a --cache without read)'
+  if (policy !== undefined && !readsCache(policy)) {
+    return 'cache key unchanged — re-executed because this run did not read the cache (--force, or a --cache-policy without read)'
   }
   // `get` answers null, not undefined, for no row.
   const createdAt = (
@@ -435,7 +442,7 @@ function unchangedKeyNote(
       const row = db
         .query('SELECT cache_policy AS p, failed_count AS f FROM invocations WHERE run_id = ?')
         .get(id) as { p: string; f: number } | null
-      const writes = row?.p.split(',').some((axis) => axis === 'lW' || axis === 'rW') === true
+      const writes = row !== null && writesCache(row.p)
       return writes ? (row?.f ?? 0) : 0
     }
     const before = failedWithWrites(prev.runId)
@@ -469,8 +476,8 @@ function unchangedKeyNote(
               p: string
             } | null
           )?.p
-    if (prevPolicy !== undefined && !prevPolicy.split(',').some((a) => a === 'lW' || a === 'rW')) {
-      return 'cache key unchanged — the previous run on this key did not write the cache (--no-cache, or a --cache without write), so there was nothing to hit'
+    if (prevPolicy !== undefined && !writesCache(prevPolicy)) {
+      return 'cache key unchanged — the previous run on this key did not write the cache (--no-cache, or a --cache-policy without write), so there was nothing to hit'
     }
     return 'cache key unchanged — the previous run on this key executed but no entry for it is in the cache (its save failed, or it was pruned since), so there was nothing to hit'
   }
@@ -479,8 +486,7 @@ function unchangedKeyNote(
 
 /**
  * The latest recorded run of a task (run_id may be NULL on very old rows).
- * One query for `vx why` and `vx mcp`: the CLI defaulted to it while the
- * tool demanded a run id an agent had to fetch first (2026-09-16).
+ * `vx why`'s default when no run id is given.
  */
 export function latestRunId(db: Database, taskId: string): string | null {
   const [project, task] = splitTaskId(taskId)
@@ -875,6 +881,69 @@ export function rootCauses(
   return roots
 }
 
+export interface InputWriter {
+  /** The task whose key read the file. */
+  taskId: string
+  /** Workspace-relative, as the key names it. */
+  file: string
+  /** The tasks that were running when the file last changed. */
+  writers: string[]
+}
+
+/**
+ * Slack around a task's recorded window: its edges are rounded to the
+ * millisecond and a write lands just before the process exits.
+ */
+const WRITE_SLACK_MS = 5
+
+/**
+ * For each moved input file of `taskId` and of each root cause, the
+ * recorded tasks that were running when the file last changed: a task
+ * that writes a file another key reads re-keys that task on every run.
+ * The file's mtime against the recorded windows, so
+ * a writer that runs each time is named from its latest run, and an
+ * edit made outside a run names none.
+ */
+export function inputWriters(
+  db: Database,
+  workspaceRoot: string,
+  taskId: string,
+  entries: CacheKeyDiff['entries'],
+  roots: readonly RootCause[],
+): InputWriter[] {
+  const during = db.query(
+    `SELECT project, task FROM runs
+      WHERE started_at <= ?1 + ${WRITE_SLACK_MS} AND ended_at >= ?1 - ${WRITE_SLACK_MS}
+        AND status != 'skipped'
+      GROUP BY project, task ORDER BY MIN(started_at) LIMIT 3`,
+  )
+  const out: InputWriter[] = []
+  const owners = [
+    { taskId, entries },
+    ...roots.map((r) => ({ taskId: r.chain.at(-1)!, entries: r.entries })),
+  ]
+  for (const owner of owners) {
+    for (const e of owner.entries) {
+      if (e.kind !== 'file' || e.change === 'removed') continue
+      let mtime: number
+      try {
+        mtime = statSync(path.join(workspaceRoot, e.name)).mtimeMs
+      } catch {
+        continue
+      }
+      const rows = during.all(mtime) as { project: string; task: string }[]
+      if (rows.length > 0) {
+        out.push({
+          taskId: owner.taskId,
+          file: e.name,
+          writers: rows.map((r) => `${r.project}#${r.task}`),
+        })
+      }
+    }
+  }
+  return out
+}
+
 // ---------------------------------------------------------------------------
 // Run comparison — diff a run against the immediately-previous invocation
 // ---------------------------------------------------------------------------

package/src/orchestrator/miss-save.ts

@@ -81,6 +81,8 @@ export interface SaveMissArgs {
   ownOutputFiles?: string[] | undefined
   /** `ownOutputFiles` for `cache.outputs.workspaceFiles` (A-43). */
   ownWsOutputFiles?: string[] | undefined
+  /** A sandboxed task's reach: a symlinked output it could not read is refused (`sandboxReadable`). */
+  readable?: ((real: string) => boolean) | undefined
   /** The Tier-3 input fingerprint rows captured by the pre-exec describe. */
   captured: readonly TaskInputComponent[]
   command: string
@@ -176,6 +178,7 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
         ? { workspaceOutputFiles: wsOutputFiles, workspaceRoot: a.workspaceRoot }
         : {}),
       inputComponents: a.captured.map((c) => ({ entryHash: a.hash, ...c })),
+      readable: a.readable,
       // No `exitCode`: the save only runs under `effectiveExitCode === 0`, and
       // the contract no longer accepts one — so the invariant is enforced by
       // the type rather than by every call site remembering the gate.