@hope_phenom/dsh-plugin-remote-use 0.0.0-stage → 0.2.24

package/lib/core/acp-model-overlay.js

@@ -0,0 +1,121 @@
+/**
+ * The worker's ACP session model, applied as a plugin-owned `--patch` overlay at launch.
+ *
+ * WHY A MODEL PIN AT ALL: `dsh-acp`'s `initialize` advertises `promptCapabilities.image` from the
+ * CONFIGURED route (`supportsAcpImagePrompts(ctx, provider, model)`), and a wrong or missing id
+ * turns image prompts off silently -- also breaking `read_image` inside the worker's own agent
+ * (DESIGN 14.1). The capability cannot be switched per session afterwards: the flag is fixed for
+ * the connection, so the value has to be in the launch configuration.
+ *
+ * WHY AN OVERLAY AND NOT A PROFILE EDIT: the plugin's rule is that the operator's profile belongs
+ * to the operator (see the sandbox-mediator work). `--patch` is applied AFTER the profile layer, so
+ * this file wins without touching `cordis.patch.yml`; clearing the setting simply stops passing
+ * it. The trade-off is that the value is not visible in a bare `--dump-config` -- it only appears
+ * when the same overlay is passed, which is what the plugin does at launch. The setting itself is
+ * shown on the worker's settings page, and the master can see the effect in `initialize`.
+ *
+ * The file is a YAML LIST of loader patch entries, like every other patch layer.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { resolveDshHome } from './settings-store.js'
+
+/** Name under the plugin's storage directory. */
+export const MODEL_OVERLAY_FILENAME = 'acp-model-overlay.yml'
+
+export const MODEL_OVERLAY_HEADER = '# --- dsh-plugin-remote-use managed: worker model (generated from this machine\'s "workerModel" setting) ---'
+export const MODEL_OVERLAY_FOOTER = '# --- end dsh-plugin-remote-use managed: worker model ---'
+
+/** @param {string} [home] */
+export function workerModelOverlayPath(home = resolveDshHome()) {
+  return join(home, 'storages', 'dsh-plugin-remote-use', MODEL_OVERLAY_FILENAME)
+}
+
+/**
+ * Parse the `workerModel` setting, which is `provider/model`.
+ *
+ * The FIRST slash separates provider from model: model ids may legitimately contain slashes
+ * (Hugging-Face-style ids), provider ids do not. Newlines are refused because this value becomes
+ * a YAML scalar; whitespace inside the model is refused for the same reason.
+ *
+ * @param {string} [value]
+ * @returns {{ ok: boolean, provider: string, model: string, reason: string }}
+ */
+export function parseWorkerModel(value) {
+  const text = String(value ?? '').trim()
+  if (text === '') return { ok: true, provider: '', model: '', reason: '' }
+  if (/[\r\n]/u.test(text)) return { ok: false, provider: '', model: '', reason: 'must be a single line' }
+  const slash = text.indexOf('/')
+  if (slash <= 0) return { ok: false, provider: '', model: '', reason: 'expected "provider/model"' }
+  const provider = text.slice(0, slash).trim()
+  const model = text.slice(slash + 1).trim()
+  if (!/^[A-Za-z0-9._-]+$/u.test(provider)) {
+    return { ok: false, provider: '', model: '', reason: 'the provider id has unexpected characters' }
+  }
+  if (model === '' || /\s/u.test(model)) {
+    return { ok: false, provider: '', model: '', reason: 'the model id is empty or contains whitespace' }
+  }
+  return { ok: true, provider, model, reason: '' }
+}
+
+/**
+ * The overlay text for one model. JSON string quoting is valid YAML and survives every id.
+ *
+ * @param {{ provider: string, model: string }} opts
+ * @returns {string}
+ */
+export function renderWorkerModelOverlay({ provider, model }) {
+  return [
+    MODEL_OVERLAY_HEADER,
+    '- id: acp',
+    "  name: '@deepseek-ai/dsh-acp'",
+    '  config:',
+    `    provider: ${JSON.stringify(provider)}`,
+    `    model: ${JSON.stringify(model)}`,
+    MODEL_OVERLAY_FOOTER,
+    '',
+  ].join('\n')
+}
+
+/**
+ * Write (or remove) the overlay for the configured value.
+ *
+ * EMPTY REMOVES IT: an operator who clears the setting must not leave a stale file that someone
+ * later passes by hand, and an overlay that is not passed is harmless but confusing.
+ *
+ * NO BOM, and only written when the content actually changes: the file is tiny, but rewriting it
+ * on every launch would still make its mtime meaningless for "what did the last arm use".
+ *
+ * @param {{ home?: string, value?: string }} [opts]
+ * @returns {{ ok: boolean, path: string, written: boolean, reason: string }}
+ */
+export function writeWorkerModelOverlay(opts = {}) {
+  const home = opts.home ?? resolveDshHome()
+  const parsed = parseWorkerModel(opts.value)
+  if (parsed.ok !== true) return { ok: false, path: '', written: false, reason: parsed.reason }
+  const file = workerModelOverlayPath(home)
+  if (parsed.provider === '') {
+    if (existsSync(file)) {
+      try {
+        rmSync(file, { force: true })
+      } catch (error) {
+        return { ok: false, path: '', written: false, reason: `could not remove ${file}: ${error instanceof Error ? error.message : String(error)}` }
+      }
+    }
+    return { ok: true, path: '', written: false, reason: '' }
+  }
+  const text = renderWorkerModelOverlay(parsed)
+  let previous = ''
+  try {
+    if (existsSync(file)) previous = readFileSync(file, 'utf8')
+  } catch { /* unreadable -> rewrite */ }
+  if (previous === text) return { ok: true, path: file, written: false, reason: '' }
+  try {
+    mkdirSync(join(home, 'storages', 'dsh-plugin-remote-use'), { recursive: true })
+    writeFileSync(file, text, 'utf8')
+  } catch (error) {
+    return { ok: false, path: '', written: false, reason: `could not write ${file}: ${error instanceof Error ? error.message : String(error)}` }
+  }
+  return { ok: true, path: file, written: true, reason: '' }
+}

package/lib/core/approval-queue.js

@@ -0,0 +1,216 @@
+/**
+ * A holding area for approvals the review engine refuses to decide on its own.
+ *
+ * WHY IT EXISTS: `decideApproval` marks `danger-full-access` (and anything else it cannot
+ * justify) as `needsHuman`. Until now that meant an immediate refusal, so a task that
+ * genuinely needed a wider scope could never be completed -- there was no way to say yes.
+ * This queue turns "needs a human" into "waits for a human, then times out as a refusal".
+ *
+ * FAIL CLOSED IS THE DEFAULT, NOT AN AFTERTHOUGHT:
+ *   * an entry that nobody answers settles as `reject-once` when its budget expires;
+ *   * `dispose()` settles everything still pending as `reject-once`, so a plugin unload
+ *     cannot leave a request hanging until the bridge's own timeout;
+ *   * an unknown or already-settled id is not decidable, and `decide()` reports that
+ *     instead of silently succeeding.
+ *
+ * The budget is deliberately SHORTER than the bridge's `approvalTimeoutMs`: the bridge also
+ * races the callback against its own timer, and if that fires first the queue would keep a
+ * ghost entry that no human can ever act on. Settling here first means the recorded outcome
+ * is always the one the worker actually received.
+ */
+
+/** How much earlier than the bridge's timeout this queue gives up. */
+export const QUEUE_LEAD_MS = 2_000
+
+/** Settled entries kept for the page's "recent decisions" list. */
+const HISTORY_LIMIT = 50
+
+/** How much of a tool call's arguments the page shows. Enough to judge, short of a dump. */
+const RAW_INPUT_LIMIT = 400
+
+/** One entry as the PAGE sees it: no resolver, no unbounded payload. */
+function publicEntry(entry) {
+  return {
+    id: entry.id,
+    peerId: entry.peerId,
+    taskId: entry.taskId,
+    toolCallId: entry.toolCallId,
+    toolName: entry.toolName,
+    requiredTier: entry.requiredTier,
+    // What the WORKER asked for, when it asked explicitly. `requiredTier` is the plugin's own
+    // inference of the minimum that would do, and the two disagree in exactly the case that
+    // matters: a request for the unrestricted tier showed as "needs workspace-write" on the very
+    // row a human was deciding (PITFALLS F22).
+    requestedTier: entry.requestedTier,
+    reason: entry.reason,
+    source: entry.source,
+    createdAt: entry.createdAt,
+    ageMs: entry.ageMs,
+    rawInput: entry.rawInput,
+  }
+}
+
+/** Truncate a tool call's arguments so the page cannot be handed an unbounded blob. */
+function summarizeRawInput(rawInput) {
+  if (rawInput === undefined || rawInput === null) return ''
+  let text
+  try {
+    text = typeof rawInput === 'string' ? rawInput : JSON.stringify(rawInput)
+  } catch {
+    return '(unserialisable)'
+  }
+  if (text === undefined) return ''
+  return text.length > RAW_INPUT_LIMIT ? `${text.slice(0, RAW_INPUT_LIMIT)}…` : text
+}
+
+export class ApprovalQueue {
+  /**
+   * @param {object} [opts]
+   * @param {() => number} [opts.now]
+   * @param {number} [opts.timeoutMs] how long one request may wait before it is refused
+   * @param {(entry: object) => void} [opts.onSettle] audit hook; called once per entry
+   */
+  constructor(opts = {}) {
+    this.now = opts.now ?? (() => Date.now())
+    this.timeoutMs = Number.isFinite(opts.timeoutMs) ? Math.max(1, Number(opts.timeoutMs)) : 178_000
+    this.onSettle = typeof opts.onSettle === 'function' ? opts.onSettle : () => {}
+    this.disposed = false
+    this.seq = 0
+    /** @type {Map<string, object>} entries still waiting, holding their resolvers */
+    this.pending = new Map()
+    /** @type {object[]} settled outcomes, newest last */
+    this.history = []
+  }
+
+  /** Entries the page may act on. */
+  list() {
+    const now = this.now()
+    return [...this.pending.values()]
+      .map((entry) => publicEntry({ ...entry, ageMs: Math.max(0, now - entry.createdAt) }))
+      .sort((a, b) => a.createdAt - b.createdAt)
+  }
+
+  /** Settled outcomes, newest first. */
+  recent(limit = 20) {
+    return this.history.slice(-Math.max(0, limit)).reverse()
+  }
+
+  get pendingCount() {
+    return this.pending.size
+  }
+
+  /**
+   * Hold one approval request open.
+   *
+   * @param {{ peerId: string, taskId?: string, toolCallId?: string, toolName?: string,
+   *           rawInput?: unknown, requiredTier?: string, reason?: string, source?: string }} input
+   * @returns {Promise<'allow-once'|'reject-once'>} the option a human chose, or a refusal
+   */
+  request(input) {
+    if (this.disposed) return Promise.resolve('reject-once')
+
+    this.seq += 1
+    const id = `ap${this.seq}-${this.now().toString(36)}`
+    const entry = {
+      id,
+      peerId: String(input?.peerId ?? ''),
+      taskId: String(input?.taskId ?? ''),
+      toolCallId: String(input?.toolCallId ?? ''),
+      toolName: String(input?.toolName ?? ''),
+      requiredTier: String(input?.requiredTier ?? ''),
+      requestedTier: String(input?.requestedTier ?? ''),
+      reason: String(input?.reason ?? ''),
+      source: String(input?.source ?? ''),
+      rawInput: summarizeRawInput(input?.rawInput),
+      createdAt: this.now(),
+      timer: undefined,
+      resolve: undefined,
+      settled: false,
+    }
+
+    const promise = new Promise((resolve) => {
+      entry.resolve = resolve
+      entry.timer = setTimeout(() => {
+        this.#settle(id, 'reject-once', 'timeout')
+      }, this.timeoutMs)
+      // Never hold the process open for a request nobody may answer.
+      if (typeof entry.timer?.unref === 'function') entry.timer.unref()
+    })
+
+    this.pending.set(id, entry)
+    return promise
+  }
+
+  /**
+   * Apply a decision made outside the queue.
+   *
+   * `by` records WHERE the decision came from, and it is not decoration: the settings page calls
+   * this through the same route a script would, so labelling every call `human` made the audit
+   * claim human involvement for approvals a harness had granted. Measured 2026-10-14: the only
+   * `allow-once` row in the live trail came from this repo's own probe, and it read `by=human`.
+   *
+   * The default is `api` -- the conservative label. A caller that cannot prove a person clicked
+   * must not be recorded as one.
+   *
+   * @param {string} id
+   * @param {'allow'|'deny'} decision
+   * @param {'page'|'api'} [by] `page` only for a request that carried a browser Origin header
+   * @returns {{ ok: boolean, error?: string, optionId?: string }}
+   */
+  decide(id, decision, by = 'api') {
+    if (decision !== 'allow' && decision !== 'deny') {
+      return { ok: false, error: `decision must be "allow" or "deny", got ${JSON.stringify(decision)}` }
+    }
+    if (!this.pending.has(id)) {
+      // Not "silently fine": the page is showing a stale entry, or one that timed out
+      // between render and click.
+      return { ok: false, error: `no pending approval "${id}" (it may have timed out)` }
+    }
+    const optionId = decision === 'allow' ? 'allow-once' : 'reject-once'
+    this.#settle(id, optionId, by === 'page' ? 'page' : 'api')
+    return { ok: true, optionId }
+  }
+
+  /** Settle one entry exactly once, resolve its promise, and audit the outcome. */
+  #settle(id, optionId, by) {
+    const entry = this.pending.get(id)
+    if (entry === undefined || entry.settled) return
+    entry.settled = true
+    this.pending.delete(id)
+    clearTimeout(entry.timer)
+
+    const settledAt = this.now()
+    const outcome = {
+      id: entry.id,
+      peerId: entry.peerId,
+      taskId: entry.taskId,
+      toolCallId: entry.toolCallId,
+      toolName: entry.toolName,
+      requiredTier: entry.requiredTier,
+      requestedTier: entry.requestedTier,
+      source: entry.source,
+      reason: entry.reason,
+      optionId,
+      by,
+      createdAt: entry.createdAt,
+      settledAt,
+      waitedMs: Math.max(0, settledAt - entry.createdAt),
+    }
+    this.history.push(outcome)
+    if (this.history.length > HISTORY_LIMIT) this.history.splice(0, this.history.length - HISTORY_LIMIT)
+
+    // The audit hook must never break the approval path it is observing.
+    try {
+      this.onSettle(outcome)
+    } catch { /* audited elsewhere; a logging failure must not change the decision */ }
+
+    entry.resolve(optionId)
+  }
+
+  /** Refuse everything still waiting. Idempotent. */
+  dispose() {
+    if (this.disposed) return
+    this.disposed = true
+    for (const id of [...this.pending.keys()]) this.#settle(id, 'reject-once', 'disposed')
+  }
+}

package/lib/core/audit-log.js

@@ -0,0 +1,322 @@
+/**
+ * Append-only audit trail for approvals.
+ *
+ * WHY IT EXISTS: the page can show what is pending, but "who approved what, and when" has to
+ * outlive the process. Without it an approval is indistinguishable from a rule the engine
+ * applied silently, which is exactly the question an operator asks after the fact.
+ *
+ * WHY ITS OWN FILE RATHER THAN THE SETTINGS FILE: the settings file is rewritten whole on
+ * every save. An audit trail must be APPEND-ONLY -- a rewrite is a chance to lose the very
+ * record you are trying to keep.
+ *
+ * WHY IT NEVER THROWS: it observes the approval path. A full disk or a locked file must not
+ * turn into a failed approval, so every failure is reported through `lastError` and the
+ * caller carries on. That is a deliberate trade: an audit trail that can veto an operation
+ * is worse than one that reports it could not write.
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { resolveDshHome } from './settings-store.js'
+
+/** How many bytes of the tail the page reads. Enough for a screenful, cheap to read. */
+const TAIL_BYTES = 256 * 1024
+
+/** Rows kept in memory for the page, newest last. */
+const MEMORY_LIMIT = 200
+
+/**
+ * Rotate the live file once it reaches this size.
+ *
+ * WHY A CAP AT ALL: the trail is append-only and, until 0.2.12, unbounded -- it grew for as long as
+ * the plugin was installed. An append-only file has no natural stopping point, so "nobody noticed"
+ * is exactly what unbounded growth looks like. At the measured ~670 bytes per row this is roughly
+ * 12,000 rows, i.e. years of ordinary use: a cap that bounds the worst case without costing an
+ * operator anything they would miss.
+ */
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024
+
+/** Rotated files kept beside the live one. The oldest beyond this is deleted -- see `#prune`. */
+const DEFAULT_KEEP_FILES = 5
+
+/** `audit.<stamp>.jsonl`, i.e. an archive rather than the live `audit.jsonl`. */
+const ARCHIVE_RE = /^audit\..+\.jsonl$/
+
+/**
+ * The `by` values that mean "nobody decided this".
+ *
+ * `timeout` is the queue's own budget expiring; `disposed` is the plugin unloading with the
+ * request still open; `no-answerer` is the engine finding no one who could answer. All three
+ * are refusals the operator had no chance to see at the moment they happened.
+ */
+const MISSED_BY = new Set(['timeout', 'disposed', 'no-answerer'])
+
+/**
+ * The row that moves the operator-facing view's starting point.
+ *
+ * WHY A WATERMARK AND NOT A DELETE: this file is the evidence trail for "who approved what".
+ * Erasing the misses would make the trail lie about what happened, and the operator's own request
+ * to clear a list is not a reason to destroy a record of an unattended refusal. Appending a row
+ * keeps both facts -- every miss, and the fact that the view was cleared, when, and by which route.
+ */
+const CLEARED_KIND = 'approvals-cleared'
+
+/** @param {Record<string, string | undefined>} [env] */
+export function auditPath(env = process.env) {
+  return join(resolveDshHome(env), 'storages', 'dsh-plugin-remote-use', 'audit.jsonl')
+}
+
+export class AuditLog {
+  /**
+   * @param {object} [opts]
+   * @param {Record<string, string | undefined>} [opts.env]
+   * @param {() => number} [opts.now]
+   * @param {(level: 'warn', message: string) => void} [opts.log]
+   */
+  constructor(opts = {}) {
+    const env = opts.env ?? process.env
+    this.file = auditPath(env)
+    this.now = opts.now ?? (() => Date.now())
+    this.log = opts.log ?? (() => {})
+    /** Rotate the live file at this size. <= 0 disables rotation (keep everything). */
+    this.maxBytes = Number.isFinite(opts.maxBytes) ? Number(opts.maxBytes) : DEFAULT_MAX_BYTES
+    /** How many archives to keep. < 0 keeps every archive. */
+    this.keepFiles = Number.isFinite(opts.keepFiles) ? Number(opts.keepFiles) : DEFAULT_KEEP_FILES
+    /** @type {object[]} newest last */
+    this.rows = []
+    this.lastError = ''
+    /**
+     * WHERE THE VISIBLE VIEW STARTS: the index of the newest clear watermark in `rows`, or -1 when
+     * no clear has happened (everything visible).
+     *
+     * BY POSITION, NOT BY TIMESTAMP. The first implementation compared ISO timestamps, and the test
+     * for "a miss recorded after the clear is shown again" failed: `at` has millisecond resolution,
+     * so a row written in the same millisecond as the watermark compared as `<=` and vanished. Index
+     * order is the file's real order, exact at any speed.
+     */
+    this.clearedIndex = -1
+    /** The watermark's timestamp, for display only. */
+    this.clearedAt = ''
+    /** Who cleared it, so a rotation can carry the watermark forward without inventing an actor. */
+    this.clearedBy = ''
+    this.#loadTail()
+  }
+
+  /** Point the view at whatever the newest watermark in memory says (-1 = none). */
+  #adoptWatermark() {
+    let index = -1
+    for (let i = this.rows.length - 1; i >= 0; i -= 1) {
+      if (this.rows[i]?.kind === CLEARED_KIND) { index = i; break }
+    }
+    this.clearedIndex = index
+    this.clearedAt = index === -1 || typeof this.rows[index]?.at !== 'string' ? '' : this.rows[index].at
+    this.clearedBy = index === -1 ? '' : String(this.rows[index]?.by ?? '')
+  }
+
+  /** Read recent rows so the page has history across a restart. */
+  #loadTail() {
+    if (!existsSync(this.file)) return
+    try {
+      const size = statSync(this.file).size
+      const start = Math.max(0, size - TAIL_BYTES)
+      // A partial first line is expected when reading a tail; JSON.parse drops it below.
+      const text = readFileSync(this.file, 'utf8').slice(start)
+      for (const line of text.split('\n')) {
+        if (line.trim() === '') continue
+        try {
+          const row = JSON.parse(line)
+          if (row !== null && typeof row === 'object') this.rows.push(row)
+        } catch { /* a torn or partial line is skipped, never fatal */ }
+      }
+      if (this.rows.length > MEMORY_LIMIT) this.rows.splice(0, this.rows.length - MEMORY_LIMIT)
+      this.#adoptWatermark()
+    } catch (error) {
+      this.lastError = `could not read ${this.file}: ${error instanceof Error ? error.message : String(error)}`
+      this.log('warn', this.lastError)
+    }
+  }
+
+  /**
+   * Append one row. Never throws.
+   * @param {object} row
+   * @returns {boolean} whether it reached the disk
+   */
+  record(row) {
+    // Before writing, not after: the point of the cap is that the file never exceeds it.
+    this.#rotateIfNeeded()
+    const entry = { at: new Date(this.now()).toISOString(), ...row }
+    this.rows.push(entry)
+    if (this.rows.length > MEMORY_LIMIT) {
+      const dropped = this.rows.length - MEMORY_LIMIT
+      this.rows.splice(0, dropped)
+      // Keep the watermark pointing at its OWN row after a trim. Dropping the watermark's row means
+      // every row before it went too, so everything left is after the clear: -1 (all visible) is
+      // then the correct answer, not a stale index into a shifted array.
+      this.clearedIndex = Math.max(-1, this.clearedIndex - dropped)
+    }
+    try {
+      mkdirSync(dirname(this.file), { recursive: true })
+      appendFileSync(this.file, `${JSON.stringify(entry)}\n`, 'utf8')
+      this.lastError = ''
+      return true
+    } catch (error) {
+      this.lastError = `could not append to ${this.file}: ${error instanceof Error ? error.message : String(error)}`
+      this.log('warn', this.lastError)
+      return false
+    }
+  }
+
+  /** Recent rows, newest first. */
+  tail(limit = 30) {
+    return this.rows.slice(-Math.max(0, limit)).reverse()
+  }
+
+  /** Bytes on disk for the live file, 0 when it does not exist yet. */
+  get bytes() {
+    try {
+      return statSync(this.file).size
+    } catch {
+      return 0
+    }
+  }
+
+  /** The rotated archives beside the live file, oldest first. */
+  archives() {
+    try {
+      return readdirSync(dirname(this.file))
+        .filter((name) => ARCHIVE_RE.test(name))
+        .map((name) => {
+          let size = 0
+          try { size = statSync(join(dirname(this.file), name)).size } catch { /* raced away */ }
+          return { name, bytes: size }
+        })
+        .sort((a, b) => a.name.localeCompare(b.name))
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Rotate before the live file would exceed the cap.
+   *
+   * ROTATE, NEVER TRUNCATE. Truncating the live file is the one operation this class must not do:
+   * the whole reason the trail is its own append-only file is that a rewrite is a chance to lose the
+   * record you are trying to keep (see the header). Renaming keeps every byte written so far intact
+   * and gives the next write a fresh file to append to.
+   */
+  #rotateIfNeeded() {
+    if (!(this.maxBytes > 0)) return
+    let size = 0
+    try { size = statSync(this.file).size } catch { return }  // no file yet: nothing to rotate
+    if (size < this.maxBytes) return
+    this.#rotate()
+  }
+
+  #rotate() {
+    const dir = dirname(this.file)
+    // Sortable and second-resolution; a second rotation inside the same second takes a suffix
+    // rather than overwriting an archive it just created.
+    const stamp = new Date(this.now()).toISOString().replace(/\.\d+Z$/, '').replace(/[-:]/g, '').replace('T', '-')
+    let target = join(dir, `audit.${stamp}.jsonl`)
+    for (let n = 1; existsSync(target); n += 1) target = join(dir, `audit.${stamp}.${n}.jsonl`)
+    try {
+      renameSync(this.file, target)
+    } catch (error) {
+      // Unrotated is the safe failure: the trail keeps growing instead of losing rows.
+      this.lastError = `could not rotate ${this.file}: ${error instanceof Error ? error.message : String(error)}`
+      this.log('warn', this.lastError)
+      return
+    }
+
+    // CARRY THE WATERMARK INTO THE NEW FILE. The clear watermark lives as a ROW, and rotation moves
+    // the row it lives in to the archive -- which `#loadTail` does not read. Without this, every
+    // restart after a rotation would resurrect the misses the operator had cleared.
+    if (this.clearedIndex >= 0) {
+      const carried = { at: this.clearedAt, kind: CLEARED_KIND, by: this.clearedBy, carried: true }
+      try {
+        appendFileSync(this.file, `${JSON.stringify(carried)}\n`, 'utf8')
+      } catch (error) {
+        this.lastError = `could not carry the clear watermark into ${this.file}: ${error instanceof Error ? error.message : String(error)}`
+        this.log('warn', this.lastError)
+      }
+    }
+    this.#prune()
+  }
+
+  /** Delete the oldest archives beyond `keepFiles`. THE ONLY DESTRUCTIVE ACT IN THIS FILE. */
+  #prune() {
+    if (this.keepFiles < 0) return
+    const archives = this.archives()
+    const excess = archives.length - this.keepFiles
+    if (excess <= 0) return
+    for (const archive of archives.slice(0, excess)) {
+      try {
+        unlinkSync(join(dirname(this.file), archive.name))
+        // Reported rather than silent: removing evidence is worth a line in the operator's log,
+        // even when it is the retention rule doing exactly what it was configured to do.
+        this.log('warn', `audit retention removed the oldest archive: ${archive.name}`)
+      } catch (error) {
+        this.lastError = `could not remove ${archive.name}: ${error instanceof Error ? error.message : String(error)}`
+        this.log('warn', this.lastError)
+      }
+    }
+  }
+
+  /**
+   * Approvals that expired with nobody answering -- the ones the operator never saw.
+   *
+   * WHY THIS IS NOT JUST `tail()` FILTERED IN THE PAGE: six such rows sat in the live trail on
+   * 2026-10-14 (five of them inside eight minutes) and the operator had never seen a single
+   * prompt. A refusal that leaves no trace the page can surface is indistinguishable from the
+   * plugin being broken, so the misses get their own accessor instead of hiding among the rows
+   * that were decided.
+   *
+   * `disposed` counts as missed: the request was still waiting when the plugin unloaded, so no
+   * person ever answered it either. The page labels the two differently.
+   *
+   * @param {number} [limit] how many to return, newest first
+   */
+  missed(limit = 20) {
+    return this.missedAll().slice(0, Math.max(0, limit))
+  }
+
+  /** Every miss still in the operator-facing view, newest first. */
+  missedAll() {
+    return this.#visible()
+      .filter((row) => row?.kind === 'approval' && MISSED_BY.has(String(row.by ?? '')))
+      .reverse()
+  }
+
+  get missedCount() {
+    return this.#visible().reduce((n, row) => (row?.kind === 'approval' && MISSED_BY.has(String(row.by ?? '')) ? n + 1 : n), 0)
+  }
+
+  /**
+   * Rows at or after the last clear watermark -- what the operator-facing views show.
+   */
+  #visible() {
+    return this.rows.slice(this.clearedIndex + 1)
+  }
+
+  /**
+   * Move the view's starting point past everything recorded so far.
+   *
+   * NOTHING IS DELETED -- see `CLEARED_KIND`. The caller gets the number of misses the views will
+   * stop showing, so the page can say what it did instead of looking like it did nothing.
+   *
+   * @param {string} [by] provenance of the click ('page' for a person, 'api' otherwise)
+   * @returns {number} misses the views stop showing
+   */
+  clear(by = 'api') {
+    const cleared = this.missedCount
+    this.record({ kind: CLEARED_KIND, by })
+    this.clearedIndex = this.rows.length - 1
+    this.clearedAt = typeof this.rows[this.clearedIndex]?.at === 'string' ? this.rows[this.clearedIndex].at : ''
+    this.clearedBy = String(by)
+    return cleared
+  }
+
+  get size() {
+    return this.rows.length
+  }
+}