@fastagent-sh/voicenote 0.17.9 → 0.18.0

package/README.md

@@ -53,18 +53,20 @@ The first install creates `~/.config/voicenote/config.json`. A legacy `speakers.
 Manual install:
 
 ```bash
+bun remove -g @kid7st/voicenote 2>/dev/null || true   # drop the pre-rebrand package if present (safe no-op otherwise)
 bun add -g @fastagent-sh/voicenote
 mkdir -p ~/.local/bin
 ln -sf ~/.bun/bin/vn ~/.local/bin/vn
 ```
 
-An older `git+…#main` install is replaced in place by `bun add -g @fastagent-sh/voicenote`; no uninstall needed.
+An older `git+…#main` install is replaced in place by `bun add -g @fastagent-sh/voicenote`. The one exception is the **pre-rebrand `@kid7st/voicenote`** package: it ships the same `vn` bin, so the `bun remove -g` line above clears it first (the one-line `install.sh` does this automatically).
 
 ### Windows (CLI)
 
 The CLI is cross-platform. Prerequisites: Bun, ffmpeg (provides `ffprobe.exe`), Node + pi.
 
 ```powershell
+bun remove -g @kid7st/voicenote 2>$null   # drop the pre-rebrand package if present (safe no-op otherwise)
 bun add -g @fastagent-sh/voicenote
 # Windows has no /Volumes mount points; set the recorder drive explicitly
 setx VOICENOTE_RECORD_DIR "E:\RECORD"
@@ -177,6 +179,10 @@ Changes take effect on the next `vn run`. A legacy `~/.config/voicenote/speakers
 6. The summary model (default: pi codex via ChatGPT Plus) reads the raw transcript directly, performing necessary cleanup, speaker restoration, and reconstruction of views/debates/consensus inside the notes-generation stage; if the summary fails, the next `vn run` / `vn run --latest` reuses the saved transcript and retries only the notes generation — no `vn forget` needed
 7. Write notes / metadata; the system makes no archiving decisions — files stay in the configured workspace
 
+A failing recording is retried on later runs, but at most **3 times** (whether it fails in transcription or in summarisation, and a run killed mid-job counts too). After that it is marked `Gave up` and left alone, so one broken file can't burn ASR/LLM budget on every scheduler tick — `vn forget <name>` drops the record and re-queues it. Re-queuing is not the same as re-transcribing: if the transcript is already on disk it is reused, so `vn forget` never re-pays for ASR. (`vn forget` takes the run lock, so it refuses while a run is in progress — wait for that run to finish and repeat.)
+
+Records whose source file is no longer on the recorder are forgotten on the next scan (and the removal is logged), *unless* they already produced notes or a transcript — that history is kept. This is why swapping recorders, or deleting files from the device, no longer leaves permanent "failed" rows behind.
+
 ## Output locations
 
 The installer defaults to `VOICENOTE_WORKSPACE=~/Documents/meetings`.
@@ -185,7 +191,7 @@ The installer defaults to `VOICENOTE_WORKSPACE=~/Documents/meetings`.
 - Original audio: `${VOICENOTE_WORKSPACE}/_audio/YYYY-MM/`
 - Full transcripts: `${VOICENOTE_WORKSPACE}/_transcripts/YYYY-MM/`
 - Metadata: `${VOICENOTE_WORKSPACE}/_metadata/YYYY-MM/`
-- State: `${VOICENOTE_WORKSPACE}/_state/processed.json`
+- State: `${VOICENOTE_WORKSPACE}/_state/jobs.json` — one record per recording, holding its `state` — where it is in its lifecycle (`queued`, `running`, `done`, `filtered`, `error`, or `gave_up` once retries are spent) — plus a `code` saying why (`summary_failed`, `transcribe_failed`, `interrupted`, `too_small`, …), its attempt count and its output paths. `vn run` is the only writer; `vn jobs` and the GUI dashboard are pure reads of it, so what you see is what will run. A pre-0.18 `processed.json` is converted automatically on the first run and kept as `processed.json.v1.bak`.
 - Index: `${VOICENOTE_WORKSPACE}/_index/notes.jsonl`
 
 ## Automation
@@ -223,15 +229,17 @@ bun run typecheck
 bun src/cli.ts doctor
 ```
 
-Distribution: vn ships as **source** with no build step — it only runs on bun (shebang + `bun:ffi` + `engines.bun`), and bun runs TypeScript natively, so `bin` points straight at `src/cli.ts` and the npm tarball only contains `src/{cli,envConfig,runLock}.ts`. The install script / `vn upgrade` install from the published npm package (`bun add -g @fastagent-sh/voicenote`); a `git+https` install also works directly (the git tree carries the source; no build or install script needed).
+Distribution: vn ships as **source** with no build step — it only runs on bun (shebang + `bun:ffi` + `engines.bun`), and bun runs TypeScript natively, so `bin` points straight at `src/cli.ts` and the npm tarball only contains `src/{cli,envConfig,jobs,runLock}.ts`. The install script / `vn upgrade` install from the published npm package (`bun add -g @fastagent-sh/voicenote`); a `git+https` install also works directly (the git tree carries the source; no build or install script needed).
 
 Routine release (tag triggers CI):
 
 ```bash
-npm version patch
+npm version patch   # then sync `VERSION` in src/cli.ts to match
 git push --follow-tags
 ```
 
+`src/cli.ts` hardcodes `VERSION` for `vn --version`, and `npm version` does not touch it — update both in the same commit or the CLI will report a version it isn't.
+
 The workflow lives at `.github/workflows/release.yml`: CI explicitly runs typecheck/test/build + an artifact smoke test, then `npm publish --ignore-scripts` (deterministic publishing, no lifecycle dependence). Publishing uses **npm trusted publishing (OIDC)**: no long-lived token (`id-token: write` + a Trusted Publisher configured on npmjs.com), with provenance attached automatically. A bare local `npm publish` is still guarded by `prepublishOnly` (typecheck+test+build).
 
 > **First-release exception**: npm has no pending-publisher, so trusted publishing cannot publish a package's very first version. Publish once manually with `npm login` + `npm publish --ignore-scripts`, then add a Trusted Publisher on the package settings page at npmjs.com (repo `fastagent-sh/voicenote`, workflow `release.yml`); CI takes over afterwards (the npm account needs 2FA).

package/README.zh-CN.md

@@ -53,18 +53,20 @@ bash <(curl -fsSL https://raw.githubusercontent.com/fastagent-sh/voicenote/main/
 手动安装:
 
 ```bash
+bun remove -g @kid7st/voicenote 2>/dev/null || true   # 若装过改名前的旧包则清掉(没装则安全跳过)
 bun add -g @fastagent-sh/voicenote
 mkdir -p ~/.local/bin
 ln -sf ~/.bun/bin/vn ~/.local/bin/vn
 ```
 
-旧版(`git+…#main`)安装会被 `bun add -g @fastagent-sh/voicenote` 直接替换,无需先卸载。
+旧版(`git+…#main`)安装会被 `bun add -g @fastagent-sh/voicenote` 直接替换,无需先卸载。唯一例外是**改名前的 `@kid7st/voicenote`** 包:它带同一个 `vn` 命令,所以上面的 `bun remove -g` 会先清掉它(一键 `install.sh` 会自动处理)。
 
 ### Windows(CLI)
 
 CLI 已跨平台。前置:Bun、ffmpeg(提供 `ffprobe.exe`)、Node + pi。
 
 ```powershell
+bun remove -g @kid7st/voicenote 2>$null   # 若装过改名前的旧包则清掉(没装则安全跳过)
 bun add -g @fastagent-sh/voicenote
 # Windows 无 /Volumes 挂载点,录音盘按盘符设置
 setx VOICENOTE_RECORD_DIR "E:\RECORD"
@@ -175,7 +177,11 @@ vn uninstall-launch-agent
 4. 转写:火山豆包【大模型录音文件识别标准版 API】,本地音频先传到 TOS,提交任务后轮询结果,完成后默认删除 TOS 对象
 5. 转写完成后立刻落盘原始 transcript(不做 lossy 清洗),避免后面步骤失败导致 ASR 费用白付
 6. summary 模型(默认 pi codex 走 ChatGPT Plus)直接看原始 transcript,在纪要生成阶段内部完成必要清理、说话人还原、观点/争论/共识形成过程还原;如果 summary 失败,下一次 `vn run` / `vn run --latest` 会复用已保存 transcript,直接重试纪要生成,不需要 `vn forget`
-7. 写出 notes / metadata;系统不做任何归档决定,文件留在配置的 workspace 中
+7. 写出 notes / metadata；系统不做任何归档决定，文件留在配置的 workspace 中
+
+失败的录音会在后续运行中重试，但**最多 3 次**（转写失败、纪要失败、以及被中途 kill 的运行都算）。超过后标记为 `Gave up` 并不再自动重试，避免一个坏文件每个调度周期都烧一次 ASR/LLM 额度 —— `vn forget <name>` 会删掉该记录并重新入队。重新入队不等于重新转写：磁盘上已有 transcript 时会直接复用，所以 `vn forget` 不会让你再付一次 ASR。（`vn forget` 需要 run lock，因此在某次 run 进行中时会拒绝执行 —— 等该次 run 结束后重试即可。）
+
+源文件已不在录音笔上的记录，会在下一次扫描时被遗忘（并记入日志），**已经产出纪要或 transcript 的除外** —— 那部分历史会保留。所以换录音笔、或从设备上删文件，不再会留下永久的 “失败” 条目。
 
 ## 输出位置
 
@@ -185,7 +191,7 @@ installer 默认设置:`VOICENOTE_WORKSPACE=~/Documents/meetings`。
 - 原始音频:`${VOICENOTE_WORKSPACE}/_audio/YYYY-MM/`
 - 完整转写:`${VOICENOTE_WORKSPACE}/_transcripts/YYYY-MM/`
 - metadata:`${VOICENOTE_WORKSPACE}/_metadata/YYYY-MM/`
-- 状态:`${VOICENOTE_WORKSPACE}/_state/processed.json`
+- 状态：`${VOICENOTE_WORKSPACE}/_state/jobs.json` —— 每条录音一条记录，包含 `state`（生命周期位置：`queued`、`running`、`done`、`filtered`、`error`，以及重试耗尽后的 `gave_up`）、`code`（原因：`summary_failed`、`transcribe_failed`、`interrupted`、`too_small` 等）、重试次数和产物路径。`vn run` 是唯一的写入方，`vn jobs` 和 GUI 面板都只是它的纯读取 —— 你看到的队列就是会跑的队列。0.18 之前的 `processed.json` 会在首次运行时自动转换，旧文件保留为 `processed.json.v1.bak`。
 - 索引:`${VOICENOTE_WORKSPACE}/_index/notes.jsonl`
 
 ## 自动化
@@ -223,15 +229,17 @@ bun run typecheck
 bun src/cli.ts doctor
 ```
 
-分发:vn 以**源码**分发,没有构建步骤 —— 它只在 bun 上运行(shebang + `bun:ffi` + `engines.bun`),而 bun 原生跑 TypeScript,所以 `bin` 直接指向 `src/cli.ts`,npm tarball 只带 `src/{cli,envConfig,runLock}.ts`。安装脚本 / `vn upgrade` 从已发布的 npm 包安装(`bun add -g @fastagent-sh/voicenote`);`git+https` 安装也能直接用(git 树自带源码,无需 build 或安装脚本)。
+分发:vn 以**源码**分发,没有构建步骤 —— 它只在 bun 上运行(shebang + `bun:ffi` + `engines.bun`),而 bun 原生跑 TypeScript,所以 `bin` 直接指向 `src/cli.ts`,npm tarball 只带 `src/{cli,envConfig,jobs,runLock}.ts`。安装脚本 / `vn upgrade` 从已发布的 npm 包安装(`bun add -g @fastagent-sh/voicenote`);`git+https` 安装也能直接用(git 树自带源码,无需 build 或安装脚本)。
 
 日常发布(打 tag 触发 CI):
 
 ```bash
-npm version patch
+npm version patch   # 然后把 src/cli.ts 里的 `VERSION` 同步成一样
 git push --follow-tags
 ```
 
+`src/cli.ts` 里硬编码了 `VERSION`(供 `vn --version` 用),而 `npm version` 不会改它 —— 请在同一个 commit 里一起更新,否则 CLI 会报一个它并不是的版本号。
+
 workflow 位于 `.github/workflows/release.yml`:CI 显式跑 typecheck/test/build + 产物冒烟,再 `npm publish --ignore-scripts`(确定发布,不依赖 lifecycle)。发布走 **npm trusted publishing(OIDC)**:免长期 token(`id-token: write` + npmjs.com 上配好 Trusted Publisher),自动带 provenance。本地裸 `npm publish` 则由 `prepublishOnly`(typecheck+test+build)兼底。
 
 > **首发例外**:npm 无 pending-publisher,trusted publishing 发不了包的第一个版本。先本机 `npm login` 后手动 `npm publish --ignore-scripts` 发一次,再到 npmjs.com 包设置页加 Trusted Publisher(repo `fastagent-sh/voicenote`、workflow `release.yml`),之后 CI 自动接管(需 npm 账号开 2FA)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/voicenote",
-  "version": "0.17.9",
+  "version": "0.18.0",
   "description": "Voice recordings → diarized transcripts → integrated semantic Markdown notes. Currently optimized for the PHILIPS VTR6500 recorder, but the workflow is generic.",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,7 @@
   "files": [
     "src/cli.ts",
     "src/envConfig.ts",
+    "src/jobs.ts",
     "src/runLock.ts",
     "README.md",
     "LICENSE"

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { cac } from 'cac'
 import { deriveNoProxy, envKeysToEmbed, hydrateFromFileEnv, parseFileEnv } from './envConfig'
 import { parseLockOwner } from './runLock'
+import { applyOutcome, buildJobsView, classify, emptyState, localIso, MAX_ATTEMPTS, migrateLegacyState, ownsOutput, parseJobsLimit, parseStateFile, parseStrictJson, patchJob, pruneUnseen, reconcileInterrupted, startAttempt, SUMMARY_FAILED_STATUS, type CurrentJob, type JobRecord, type StateFile } from './jobs'
 import { createHash, createHmac, randomUUID } from 'node:crypto'
 import { appendFile, chmod, mkdir, readFile, writeFile, copyFile, rename, unlink, stat, readdir, rm } from 'node:fs/promises'
 import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, openSync, closeSync, statSync, readSync, unlinkSync, renameSync } from 'node:fs'
@@ -11,7 +12,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 import { spawn, spawnSync } from 'node:child_process'
 import os from 'node:os'
 
-const VERSION = '0.17.9'
+const VERSION = '0.18.0'
 const LAUNCH_AGENT_LABEL = 'sh.fastagent.voicenote'
 const LAUNCH_AGENT_LABEL_LEGACY = 'com.kid7st.voicenote' // pre-fastagent installs; cleaned up on install
 const TASK_NAME = 'VoiceNote'   // Windows Task Scheduler name (mac uses LAUNCH_AGENT_LABEL)
@@ -402,25 +403,26 @@ async function readJson<T>(path: string, fallback: T): Promise<T> {
   try { return JSON.parse(await readFile(path, 'utf8')) as T } catch (e) { warnSideEffect(`parse ${path}`, e); return fallback }
 }
 
-async function writeJson(path: string, data: any): Promise<void> {
+// Write via tmp+rename so readers only ever see a complete file. Anything whose
+// mere existence is later treated as a signal MUST go through this: a half
+// written file that still parses is worse than no file at all.
+async function writeFileAtomic(path: string, body: string): Promise<void> {
   await mkdir(dirname(path), { recursive: true })
   const tmp = `${path}.tmp`
-  await writeFile(tmp, JSON.stringify(data, null, 2), 'utf8')
+  await writeFile(tmp, body, 'utf8')
   await rename(tmp, path)
 }
 
+const writeJson = (path: string, data: any) => writeFileAtomic(path, JSON.stringify(data, null, 2))
+
 async function appendJsonl(path: string, data: any): Promise<void> {
   await mkdir(dirname(path), { recursive: true })
   await appendFile(path, JSON.stringify(data) + '\n', 'utf8')
 }
 
-const SUMMARY_FAILED_STATUS = 'summary_failed_transcript_saved'
 const RAW_TRANSCRIPT_MARKER = '## Raw transcript (no lossy cleanup)\n\n'
 const RAW_TRANSCRIPT_MARKER_LEGACY = '## 原始 transcript（不做 lossy 清洗）\n\n' // pre-0.18 files on disk
 
-function isSummaryFailedEntry(entry: any): boolean {
-  return entry?.status === SUMMARY_FAILED_STATUS
-}
 
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -480,6 +482,9 @@ function formatElapsed(ms: number): string {
 
 function progressStep(step: number, total: number, title: string, detail?: string): void {
   console.log(`▶ Step ${step}/${total}: ${title}${detail ? ` — ${detail}` : ''}`)
+  // Single hook for live progress: the dashboard shows the same string the log
+  // does, instead of regex-guessing the step from log text.
+  reportStep(title)
 }
 
 async function withHeartbeat<T>(label: string, work: () => Promise<T>, heartbeatSeconds = 60): Promise<T> {
@@ -785,42 +790,47 @@ function isCandidateFile(path: string): boolean {
   return true
 }
 
-async function scanRecordings(config: Config): Promise<Recording[]> {
-  if (!existsSync(config.recordDir)) return []
+/**
+ * `complete` is false when any part of the listing was lost — the glob threw, or
+ * a file we had just seen could not be read. It gates pruning: "not in the scan"
+ * only means "gone from the recorder" if the scan actually saw everything, and
+ * treating a half-read device as authoritative would delete live queue entries
+ * along with their retry counters.
+ */
+async function scanRecordings(config: Config): Promise<{ recordings: Recording[]; complete: boolean }> {
+  if (!existsSync(config.recordDir)) return { recordings: [], complete: false }
   const recordings: Recording[] = []
-  for await (const file of new Bun.Glob('**/*').scan({ cwd: config.recordDir, absolute: true, dot: true })) {
-    if (!isCandidateFile(file)) continue
-    const st = await stat(file).catch(() => null)
-    if (!st?.isFile()) continue
-    recordings.push({
-      sourcePath: file,
-      sizeBytes: st.size,
-      modifiedAt: st.mtime.toISOString(),
-      durationSeconds: await ffprobeDuration(file),
-      sourceId: await sourceIdFor(file),
-      recordedAt: parseRecordedAt(file),
-    })
+  let complete = true
+  try {
+    for await (const file of new Bun.Glob('**/*').scan({ cwd: config.recordDir, absolute: true, dot: true })) {
+      if (!isCandidateFile(file)) continue
+      const st = await stat(file).catch(() => null)
+      // Listed a moment ago but unreadable now: the device is going away, or
+      // this file is. Either way the listing is no longer trustworthy.
+      if (!st) { complete = false; continue }
+      if (!st.isFile()) continue
+      try {
+        recordings.push({
+          sourcePath: file,
+          sizeBytes: st.size,
+          modifiedAt: st.mtime.toISOString(),
+          durationSeconds: await ffprobeDuration(file),
+          sourceId: await sourceIdFor(file),
+          recordedAt: parseRecordedAt(file),
+        })
+      } catch (e) { complete = false; warnSideEffect(`read ${basename(file)} during scan`, e) }
+    }
+  } catch (e) {
+    complete = false
+    warnSideEffect('scan recorder', e)
   }
   // Oldest first: backlog is drained in chronological order, so every file is
   // guaranteed a turn before newer arrivals jump the queue.
-  return recordings.sort((a, b) => a.recordedAt.getTime() - b.recordedAt.getTime())
+  recordings.sort((a, b) => a.recordedAt.getTime() - b.recordedAt.getTime())
+  return { recordings, complete }
 }
 
-function shouldSkip(rec: Recording, state: Json, config: Config, force: boolean, mode: RunMode): [boolean, string] {
-  const processed = state.processed_source_ids?.[rec.sourceId]
-  if (processed && !force) {
-    // A summary failure is not a completed job: the expensive transcript was
-    // saved, so the next normal notes run should resume at summary instead of
-    // requiring `vn forget` and paying ASR again.
-    if (mode === 'notes' && isSummaryFailedEntry(processed)) return [false, '']
-    return [true, 'already_processed']
-  }
-  const ageHours = (Date.now() - rec.recordedAt.getTime()) / 3600_000
-  if (config.maxAgeHours > 0 && ageHours > config.maxAgeHours) return [true, `too_old:${ageHours.toFixed(0)}h>${config.maxAgeHours}h`]
-  if (rec.sizeBytes < config.minBytes) return [true, `too_small:${rec.sizeBytes}<${config.minBytes}`]
-  if (rec.durationSeconds !== null && rec.durationSeconds < config.minDurationSeconds) return [true, `too_short:${rec.durationSeconds.toFixed(1)}<${config.minDurationSeconds}`]
-  return [false, '']
-}
+const limitsOf = (config: Config) => ({ maxAgeHours: config.maxAgeHours, minBytes: config.minBytes, minDurationSeconds: config.minDurationSeconds })
 
 // ────────────────────────────────────────────────────────────────────────────
 // File path planning
@@ -836,9 +846,9 @@ function initialLocalFiles(config: Config, rec: Recording): LocalFiles {
   }
 }
 
-function localFilesFromState(config: Config, rec: Recording, entry: any): LocalFiles {
+function localFilesFromState(config: Config, rec: Recording, entry: JobRecord | undefined): LocalFiles {
   const fallback = initialLocalFiles(config, rec)
-  const paths = entry?.final_paths || entry?.local_paths || {}
+  const paths = entry?.paths || {}
   return {
     audio: typeof paths.audio === 'string' ? paths.audio : fallback.audio,
     transcript: typeof paths.transcript === 'string' ? paths.transcript : fallback.transcript,
@@ -847,11 +857,13 @@ function localFilesFromState(config: Config, rec: Recording, entry: any): LocalF
   }
 }
 
-function resumableTranscriptFiles(config: Config, rec: Recording, state: Json, mode: RunMode, force: boolean): LocalFiles | null {
+// Resume on the evidence, not on a state label: if the transcript is on disk,
+// re-running ASR is money spent for nothing. Keying this off `notes_failed`
+// instead meant `vn forget` (which drops the record) silently re-paid for ASR,
+// even though the transcript was still sitting there.
+function resumableTranscriptFiles(config: Config, rec: Recording, store: StateFile, mode: RunMode, force: boolean): LocalFiles | null {
   if (force || mode !== 'notes') return null
-  const entry = state.processed_source_ids?.[rec.sourceId]
-  if (!isSummaryFailedEntry(entry)) return null
-  const files = localFilesFromState(config, rec, entry)
+  const files = localFilesFromState(config, rec, store.jobs[rec.sourceId])
   return existsSync(files.transcript) ? files : null
 }
 
@@ -1762,7 +1774,11 @@ async function processRecording(config: Config, rec: Recording, opts: any): Prom
     // if a later step (summary) blows up. We use the initial (untitled) path;
     // if summary succeeds we'll move it to the titled path below.
     await mkdir(dirname(files.transcript), { recursive: true })
-    await writeFile(files.transcript, transcriptMarkdown(config, rec, transcript, { mode }), 'utf8')
+    // Atomic: "transcript exists on disk" is what makes a later run skip ASR, so
+    // a run killed mid-write must not leave a truncated file behind. The raw
+    // marker sits near the top, so a partial write would still pass
+    // readSavedTranscript()'s checks and get summarised as if complete.
+    await writeFileAtomic(files.transcript, transcriptMarkdown(config, rec, transcript, { mode }))
     console.log(`✓ Transcript saved: ${files.transcript}`)
   }
 
@@ -1825,7 +1841,9 @@ async function processRecording(config: Config, rec: Recording, opts: any): Prom
       console.log(`✓ PDF: ${pdf}`)
     }
   } else if (needsNotes && summaryError) {
-    const stubBody = `# Pending summary: ${basename(rec.sourcePath)}\n\n> ⚠ Transcription completed and saved, but the summary stage failed; retry needed.\n\n- Transcript file: \`${files.transcript}\`\n- Original audio: \`${rec.sourcePath}\`\n- Failure reason: ${meta.summary_error}\n- Retry command: \`vn run --latest\`\n`
+    // No unconditional "just re-run" promise: after MAX_ATTEMPTS the job is
+    // `gave_up` and further runs skip it, so the note has to name both ways out.
+    const stubBody = `# Pending summary: ${basename(rec.sourcePath)}\n\n> ⚠ Transcription completed and saved, but the summary stage failed; retry needed.\n\n- Transcript file: \`${files.transcript}\`\n- Original audio: \`${rec.sourcePath}\`\n- Failure reason: ${meta.summary_error}\n- Retry: the next \`vn run\` reuses the saved transcript automatically (no new transcription cost). After ${MAX_ATTEMPTS} failed attempts it stops retrying — run \`vn forget ${basename(rec.sourcePath)}\` to queue it again.\n`
     await writeFile(files.notes, stubBody, 'utf8')
     console.log(`⚠ Stub notes (summary failed): ${files.notes}`)
   } else if (opts.pdf) {
@@ -1857,6 +1875,132 @@ async function processRecording(config: Config, rec: Recording, opts: any): Prom
   return meta
 }
 
+// ────────────────────────────────────────────────────────────────────────────
+// Job state — `vn run` is the only writer; every view is a pure read of this.
+// ────────────────────────────────────────────────────────────────────────────
+
+// Named for what it holds: every recording's job state, not just the processed
+// ones. (Pre-0.18 this was `processed.json` with two reason-keyed buckets.)
+const statePathFor = (config: Config) => join(config.workspace, '_state', 'jobs.json')
+
+const legacyStatePathFor = (config: Config) => join(config.workspace, '_state', 'processed.json')
+
+/**
+ * Read-only load. On an un-migrated workspace this converts in memory and does
+ * NOT write: `vn jobs` and the GUI's poll both come through here without the run
+ * lock, and a write from a view could race a live `vn run`. Persisting the
+ * conversion is migrateStateOnDisk()'s job, under the lock.
+ */
+// The legacy read is the one irreversible read in the codebase, so it gets the
+// same strictness as the new format — `readJson` swallows a parse failure and
+// returns `{}`, which here would mean "nothing was ever processed" and re-pay
+// for every recording's ASR.
+async function readLegacyState(config: Config): Promise<Json> {
+  const path = legacyStatePathFor(config)
+  return parseStrictJson(await readFile(path, 'utf8'), path) as Json
+}
+
+async function loadState(config: Config): Promise<StateFile> {
+  const path = statePathFor(config)
+  if (!existsSync(path) && existsSync(legacyStatePathFor(config))) {
+    return migrateLegacyState(await readLegacyState(config), nowIso())
+  }
+  const store = existsSync(path) ? parseStateFile(await readFile(path, 'utf8'), path) : emptyState()
+  lastSavedState.set(path, JSON.stringify(store))
+  return store
+}
+
+// Inline rather than a repo script: most installs are the GUI's compiled
+// sidecar, which has no checkout to run a script from — and starting from empty
+// is not an option, it would re-transcribe everything and pay for ASR twice.
+// Call only with the run lock held.
+async function migrateStateOnDisk(config: Config): Promise<void> {
+  const path = statePathFor(config)
+  const legacy = legacyStatePathFor(config)
+  if (existsSync(path) || !existsSync(legacy)) return
+  const store = migrateLegacyState(await readLegacyState(config), nowIso())
+  await writeJson(path, store)
+  lastSavedState.set(path, JSON.stringify(store))
+  await rename(legacy, `${legacy}.v1.bak`).catch(e => warnSideEffect('archive pre-0.18 state', e))
+  console.log(`Converted ${basename(legacy)} → ${basename(path)} (${Object.keys(store.jobs).length} records; old file kept as .v1.bak)`)
+}
+
+// The scheduler ticks every 60s and the workspace is often a synced folder
+// (iCloud/Dropbox). Rewriting an unchanged state file on every tick would be
+// pure sync noise, so writes are content-gated. Keyed by path, not a single
+// value: `vn serve` handles config.set (which can move the workspace) and runs
+// in one process, and a shared key could skip the first write to a new path.
+const lastSavedState = new Map<string, string>()
+async function saveState(config: Config, store: StateFile): Promise<void> {
+  const path = statePathFor(config)
+  const serialized = JSON.stringify(store)
+  if (serialized === lastSavedState.get(path)) return
+  await writeJson(path, store)
+  lastSavedState.set(path, serialized)
+}
+
+/** Upsert the scan-time facts; never touches lifecycle fields. */
+function recordFor(store: StateFile, rec: Recording): JobRecord {
+  const existing = store.jobs[rec.sourceId]
+  const next: JobRecord = existing ?? {
+    name: basename(rec.sourcePath), source_path: rec.sourcePath, recorded_at: localIso(rec.recordedAt),
+    size_bytes: rec.sizeBytes, duration_seconds: rec.durationSeconds,
+    state: 'queued', code: null, detail: null, attempts: 0, updated_at: nowIso(), title: null, paths: null,
+  }
+  next.source_path = rec.sourcePath
+  next.size_bytes = rec.sizeBytes
+  next.duration_seconds = rec.durationSeconds
+  store.jobs[rec.sourceId] = next
+  return next
+}
+
+function setJobState(store: StateFile, id: string, patch: Partial<JobRecord>): void {
+  const entry = store.jobs[id]
+  if (entry) patchJob(entry, patch, nowIso())
+}
+
+// The live job, declared by the run itself. Lives next to run.lock (machine
+// state, not workspace data) and carries the pid so a reader can tell a live
+// job from one whose process was killed.
+const CURRENT_PATH = join(STATE_DIR, 'current.json')
+
+function writeCurrent(sourceId: string, step: string, startedAt: string): void {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true })
+    // tmp+rename, same rule as writeFileAtomic: this file's existence and
+    // contents are the live-job signal, and progressStep rewrites it at every
+    // step. A truncated write would read back as null and show a running job
+    // as queued.
+    const tmp = `${CURRENT_PATH}.tmp`
+    writeFileSync(tmp, JSON.stringify({ pid: process.pid, source_id: sourceId, step, started_at: startedAt } satisfies CurrentJob))
+    renameSync(tmp, CURRENT_PATH)
+  } catch (e) { warnSideEffect('write current job', e) }
+}
+
+function clearCurrent(): void {
+  try { unlinkSync(CURRENT_PATH) } catch (e: any) { if (e?.code !== 'ENOENT') warnSideEffect('clear current job', e) }
+}
+
+// Step reporting from inside the pipeline: a job is only "the current job" for
+// as long as this run says so, so the step is written, never guessed from logs.
+let currentJobId: string | null = null
+let currentJobStartedAt = ''
+function reportStep(step: string): void {
+  if (currentJobId) writeCurrent(currentJobId, step, currentJobStartedAt)
+}
+
+function readCurrent(): CurrentJob | null {
+  try {
+    const c = JSON.parse(readFileSync(CURRENT_PATH, 'utf8'))
+    return Number.isFinite(c?.pid) && typeof c?.source_id === 'string' ? c : null
+  } catch { return null }
+}
+
+function pidAlive(pid: number): boolean {
+  if (!(pid > 0)) return false
+  try { process.kill(pid, 0); return true } catch (e: any) { return e?.code === 'EPERM' }
+}
+
 async function runPipeline(opts: any): Promise<void> {
   wireDailyLog()
   const config = getConfig()
@@ -1874,10 +2018,16 @@ async function runPipeline(opts: any): Promise<void> {
 
 async function runPipelineLocked(config: Config, opts: any): Promise<void> {
   await ensureDirs(config)
-  const statePath = join(config.workspace, '_state', 'processed.json')
-  const state = await readJson<Json>(statePath, { processed_source_ids: {}, skipped_source_ids: {} })
-  state.processed_source_ids ||= {}
-  state.skipped_source_ids ||= {}
+  // --dry-run is a zero-side-effect diagnostic; the migration renames the legacy
+  // file and permanently drops its `error:*` entries. loadState converts in
+  // memory, so a dry run still sees the right picture.
+  if (!opts.dryRun) await migrateStateOnDisk(config)
+  const store = await loadState(config)
+  // We hold the run lock, so nothing else can own a `running` record: any that
+  // survive are debris from a killed run. Their attempt was already counted, so
+  // this is what makes the retry cap cover crashes as well as thrown errors.
+  const interrupted = reconcileInterrupted(store.jobs, nowIso())
+  if (interrupted.length) console.log(`Reclaimed ${interrupted.length} job(s) left running by an interrupted run: ${interrupted.slice(0, 3).map(j => j.name).join(', ')}`)
 
   if (!existsSync(config.recordDir)) {
     if (shouldLogIdleStatus(`missing:${config.recordDir}`)) {
@@ -1885,25 +2035,31 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
     }
     return
   }
-  const recordings = await scanRecordings(config)
+  const { recordings, complete: scanComplete } = await scanRecordings(config)
   const mode = normalizeRunMode(opts)
   const force = Boolean(opts.force)
   const eligible: Recording[] = []
   const skipCounts: Record<string, number> = {}
   const skipSamples: Record<string, string[]> = {}
   const verboseSkips = Boolean(opts.verbose || opts.dryRun)
+  const seen = new Set<string>()
+  const limits = limitsOf(config)
   for (const rec of recordings) {
-    const [skip, reason] = shouldSkip(rec, state, config, force, mode)
-    if (skip) {
-      const reasonKey = reason.split(':')[0] || reason
-      skipCounts[reasonKey] = (skipCounts[reasonKey] || 0) + 1
-      ;(skipSamples[reasonKey] ||= []).push(basename(rec.sourcePath))
-      if (!state.skipped_source_ids[rec.sourceId] && reason !== 'already_processed') {
-        state.skipped_source_ids[rec.sourceId] = { source_path: rec.sourcePath, reason, size_bytes: rec.sizeBytes, duration_seconds: rec.durationSeconds, seen_at: nowIso() }
-      }
-      if (verboseSkips) console.log(`  Skip: ${basename(rec.sourcePath)} (${reason})`)
-    } else eligible.push(rec)
-  }
+    seen.add(rec.sourceId)
+    const entry = recordFor(store, rec)
+    const verdict = classify(rec, store.jobs[rec.sourceId], limits, { force, notesMode: mode === 'notes', now: Date.now() })
+    if (verdict.run) { eligible.push(rec); continue }
+    skipCounts[verdict.code] = (skipCounts[verdict.code] || 0) + 1
+    ;(skipSamples[verdict.code] ||= []).push(entry.name)
+    if (verdict.persist) setJobState(store, rec.sourceId, { state: 'filtered', code: verdict.code, detail: verdict.detail })
+    if (verboseSkips) console.log(`  Skip: ${entry.name} (${verdict.code}${verdict.detail ? `: ${verdict.detail}` : ''})`)
+  }
+  // Only prune against a listing we believe to be complete: if the recorder went
+  // away mid-glob the scan is partial, and pruning would wipe live queue entries
+  // (they'd return on the next scan, but their retry counters would not).
+  const dropped = pruneUnseen(store.jobs, seen, scanComplete && existsSync(config.recordDir))
+  // The only routine path that deletes state — never do it silently.
+  if (dropped.length) console.log(`Forgot ${dropped.length} record(s) whose source is no longer on the recorder: ${dropped.slice(0, 3).map(j => j.name).join(', ')}${dropped.length > 3 ? `…(+${dropped.length - 3})` : ''}`)
   const skipSummary = Object.entries(skipCounts).map(([reason, count]) => `${reason}=${count}`).join(', ') || 'none'
   const scanLine = `Scan summary: found=${recordings.length}; eligible=${eligible.length}; skipped=${recordings.length - eligible.length} (${skipSummary})`
   const samplesLine = !verboseSkips && Object.keys(skipSamples).length
@@ -1917,7 +2073,7 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
   // --dry-run, which is a zero-side-effect diagnostic and should still print the
   // plan even on an unconfigured machine.
   if (targets.length && !opts.dryRun) {
-    const needsAsr = targets.some(rec => !resumableTranscriptFiles(config, rec, state, mode, force))
+    const needsAsr = targets.some(rec => !resumableTranscriptFiles(config, rec, store, mode, force))
     if (needsAsr && !config.volcano) {
       if (shouldLogIdleStatus(`asr-misconfig:${config.recordDir}`)) console.error('ASR not configured: Volcano needs VOLCANO_ASR_KEY / VOLCANO_TOS_*. Skipping; run `vn doctor`, fix config, then re-run.')
       return
@@ -1938,20 +2094,59 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
     if (samplesLine) console.log(samplesLine)
     console.log(`Queue: processing ${targets.length} recording(s)${latestOnly ? ' (--latest)' : ''}. Remaining after this run: ${Math.max(0, eligible.length - targets.length)}`)
   }
+  if (opts.dryRun) {
+    // Print the plan and touch nothing: no attempt counted, no state written.
+    for (const rec of targets) {
+      const plan = await processRecording(config, rec, { ...opts, resumeFromTranscriptFiles: resumableTranscriptFiles(config, rec, store, mode, force) })
+      console.log(JSON.stringify(plan, null, 2))
+    }
+    return
+  }
+  await saveState(config, store)
+
   for (const rec of targets) {
+    const entry = store.jobs[rec.sourceId]!
+    // --force means "start over", so it refunds the retry budget too. Without
+    // this it only skips one refusal: a spent record would be back at `gave_up`
+    // the moment this attempt failed.
+    if (force) patchJob(entry, { attempts: 0 }, nowIso())
+    currentJobId = rec.sourceId
+    currentJobStartedAt = nowIso()
+    startAttempt(entry, nowIso())
+    await saveState(config, store)
+    writeCurrent(rec.sourceId, 'starting', currentJobStartedAt)
     try {
-      const resumeFromTranscriptFiles = resumableTranscriptFiles(config, rec, state, mode, force)
+      const resumeFromTranscriptFiles = resumableTranscriptFiles(config, rec, store, mode, force)
       const result = await processRecording(config, rec, { ...opts, resumeFromTranscriptFiles })
-      if (!opts.dryRun) {
-        state.processed_source_ids[rec.sourceId] = { source_path: rec.sourcePath, processed_at: nowIso(), status: result.status, title: result.title, final_paths: result.final_paths }
-        delete state.skipped_source_ids[rec.sourceId]
-      }
+      applyOutcome(entry, result.status === SUMMARY_FAILED_STATUS
+        ? { kind: 'summary_failed', title: result.title ?? null, paths: result.final_paths ?? null, message: String(result.summary_error ?? 'summary failed; transcript saved') }
+        : { kind: 'done', title: result.title ?? null, paths: result.final_paths ?? null }, nowIso())
     } catch (e: any) {
-      console.error(`ERROR processing ${rec.sourcePath}: ${e?.message || e}`)
-      state.skipped_source_ids[rec.sourceId] = { source_path: rec.sourcePath, reason: `error:${e?.message || e}`, seen_at: nowIso() }
+      const message = String(e?.message || e)
+      console.error(`ERROR processing ${rec.sourcePath}: ${message}`)
+      // Source vanished mid-run (recorder unplugged, file deleted) AND nothing
+      // was produced: that's not a failed job, it's a job that no longer exists.
+      // Drop it so it can't linger as a permanent "failed" row. A record that
+      // already owns output is history — same rule pruneUnseen follows — and
+      // deleting it would re-pay for ASR when the recorder comes back.
+      if (!existsSync(rec.sourcePath) && !ownsOutput(entry)) {
+        console.log(`Forgot ${entry.name}: source left the recorder before it produced anything`)
+        delete store.jobs[rec.sourceId]
+      } else {
+        applyOutcome(entry, { kind: 'failed', message }, nowIso())
+      }
+    } finally {
+      currentJobId = null
+      clearCurrent()
+      await saveState(config, store)   // per job, not per batch: a kill -9 costs one job, not the batch
+    }
+    // Whole recorder went away — every remaining target would fail the same way
+    // and churn ASR-free but noisy retries. Stop and let the next run rescan.
+    if (!existsSync(config.recordDir)) {
+      console.error(`Recorder disappeared mid-run (${config.recordDir}); stopping. Remaining recordings stay queued.`)
+      break
     }
   }
-  if (!opts.dryRun) await writeJson(statePath, state)
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -2316,20 +2511,24 @@ async function openTarget(arg?: string): Promise<void> {
 
 async function forgetRecording(needle: string): Promise<void> {
   const config = getConfig()
-  const statePath = join(config.workspace, '_state', 'processed.json')
-  const state = await readJson<Json>(statePath, { processed_source_ids: {}, skipped_source_ids: {} })
-  let removed = 0
-  for (const bucket of ['processed_source_ids', 'skipped_source_ids']) {
-    for (const id of Object.keys(state[bucket] || {})) {
-      const entry = state[bucket][id]
-      if (id === needle || entry?.source_path?.includes(needle)) {
-        delete state[bucket][id]
+  // Under the run lock: `vn run` holds the state file in memory for the length
+  // of a batch and re-saves after every job, so an unlocked delete here would be
+  // silently resurrected by the next save.
+  const lock = await acquireRunLock()
+  if (!lock) { console.error('A voicenote run is in progress, so the state file is busy. Re-run this once it finishes (`vn jobs` shows what it is working on).'); process.exitCode = 1; return }
+  try {
+    await migrateStateOnDisk(config)
+    const store = await loadState(config)
+    let removed = 0
+    for (const [id, entry] of Object.entries(store.jobs)) {
+      if (id === needle || entry.source_path.includes(needle) || entry.name.includes(needle)) {
+        delete store.jobs[id]
         removed++
       }
     }
-  }
-  await writeJson(statePath, state)
-  console.log(`forgot ${removed} record(s)`)
+    await saveState(config, store)
+    console.log(`forgot ${removed} record(s)`)
+  } finally { await lock.release() }
 }
 
 async function showLog(opts: { lines?: number; follow?: boolean; err?: boolean; date?: string }): Promise<void> {
@@ -2524,102 +2723,36 @@ async function collectDoctor() {
   }
 }
 
-// Recent processed notes (for the GUI dashboard). Reads the canonical jsonl index.
-// Parse the agent log tail for the recording being processed right now (if any),
-// and which pipeline step it's on. Heuristic but cheap.
-function currentJobFromLog(): { status: 'processing'; name: string; step: string } | null {
-  const tail = readLogTail(agentLogPath(), 8192).split('\n')
-  let name: string | null = null
-  let processing = false
-  let step = 'Preparing'
-  for (const line of tail) {
-    const m = line.match(/voicenote job:\s*(.+?)\s*===/)
-    if (m) { name = m[1]!; processing = true; step = 'Preparing'; continue }
-    if (/✓ Completed|Idle:|ERROR processing/i.test(line)) processing = false
-    if (processing) {
-      if (/Step 3|integrated semantic notes|generate/i.test(line)) step = 'Generating notes'
-      else if (/Step 2|Transcribe|Volcano|transcrib/i.test(line)) step = 'Transcribing'
-      else if (/Step 1|Copy audio/i.test(line)) step = 'Preparing'
-    }
-  }
-  return processing && name ? { status: 'processing', name, step } : null
-}
-
-// Unified processing status of recent recordings (for the GUI status board):
-// the live job (if any) + queued on the recorder (pending) + completed (done) +
-// transcript-saved-but-notes-failed (summary_failed) + errored (failed, will
-// auto-retry) + filtered (skipped: too_small/too_short).
-async function jobsListData(limit: number): Promise<{ items: Json[] }> {
+// The dashboard/CLI view of every recording's processing status. A pure read of
+// the state file `vn run` writes, grouped by jobs.ts. Nothing here rescans
+// the recorder or parses logs: the queue shown IS the queue that runs, and it
+// stays visible when the recorder is unplugged.
+async function jobsListData(limit: number): Promise<{ items: Json[]; total: number; queued_total: number; recorder_present: boolean }> {
   const config = getConfig()
-  const statePath = join(config.workspace, '_state', 'processed.json')
-  const state = await readJson<Json>(statePath, { processed_source_ids: {}, skipped_source_ids: {} })
-  // VTR6500 names recordings YYYYMMDDHHMMSS — show that as the recording time;
-  // fall back to the processed/seen timestamp.
-  const recTime = (name: string, at: string | null): string | null => {
-    const m = name.match(/(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})/)
-    if (m) return `${m[1]}-${m[2]}-${m[3]} ${m[4]}:${m[5]}`
-    return at ? at.slice(0, 16).replace('T', ' ') : null
-  }
-  const items: Json[] = []
-  const live = currentJobFromLog()
-  if (live) items.push({ ...live, title: null, at: null, time: recTime(live.name, null), notes: null })
-  const done: Json[] = []
-  const knownPaths = new Set<string>()
-  for (const [id, e] of Object.entries<any>(state.processed_source_ids || {})) {
-    if (e.source_path) knownPaths.add(e.source_path)
-    const name = basename(e.source_path || id)
-    done.push({ status: isSummaryFailedEntry(e) ? 'summary_failed' : 'done', name, title: e.title ?? null, at: e.processed_at ?? null, time: recTime(name, e.processed_at ?? null), notes: e.final_paths?.notes ?? e.local_paths?.notes ?? null })
-  }
-  for (const [id, e] of Object.entries<any>(state.skipped_source_ids || {})) {
-    if (e.source_path) knownPaths.add(e.source_path)
-    const name = basename(e.source_path || id)
-    const rawReason = String(e.reason || '')
-    const isError = rawReason.startsWith('error')
-    // Filter reasons are machine diagnostics (`too_small:1234<100000`); show a
-    // human label instead. Error strings stay raw — that's the diagnostic.
-    const reason = rawReason.startsWith('too_small') ? 'Recording too small, skipped' : rawReason.startsWith('too_short') ? 'Recording too short, skipped' : rawReason.startsWith('too_old') ? 'Recording too old, skipped' : (e.reason ?? null)
-    done.push({ status: isError ? 'failed' : 'skipped', name, title: null, at: e.seen_at ?? null, time: recTime(name, e.seen_at ?? null), reason, notes: null })
-  }
-  done.sort((a, b) => String(b.at || '').localeCompare(String(a.at || '')))
-  // Pending: candidate files on the recorder with no state entry yet. Matched by
-  // source_path (not sourceId) so a status poll doesn't hash every file on the
-  // recorder. ponytail: path match misses a re-recorded same-path file, and the
-  // minDurationSeconds filter is absent (ffprobe per poll is too dear) — a
-  // too-short file shows "pending" until a run flips it to "skipped". Fine for a
-  // status view — the pipeline itself still dedupes by content hash and filters
-  // by duration.
-  const pending: Json[] = []
-  if (existsSync(config.recordDir)) {
-    for await (const file of new Bun.Glob('**/*').scan({ cwd: config.recordDir, absolute: true, dot: true })) {
-      if (!isCandidateFile(file) || knownPaths.has(file)) continue
-      if (config.maxAgeHours > 0 && Date.now() - parseRecordedAt(file).getTime() > config.maxAgeHours * 3600_000) continue
-      const st = await stat(file).catch(() => null)
-      if (!st?.isFile() || st.size < config.minBytes) continue
-      const name = basename(file)
-      pending.push({ status: 'pending', name, title: null, at: null, time: recTime(name, null), notes: null })
-    }
-    // Queue order: oldest first, same sort key as the pipeline (parseRecordedAt).
-    pending.sort((a, b) => parseRecordedAt(String(a.name)).getTime() - parseRecordedAt(String(b.name)).getTime())
-    // Cap the queue so a large backlog can't crowd done/failed out of the limit
-    // window; the overflow collapses into one aggregate row.
-    const PENDING_SHOWN = 10
-    if (pending.length > PENDING_SHOWN) {
-      const extra = pending.length - PENDING_SHOWN
-      pending.length = PENDING_SHOWN
-      pending.push({ status: 'pending', name: `…${extra} more queued`, title: null, at: null, time: null, notes: null })
-    }
-  }
-  // Don't double-list the live job if it's also in pending/done.
-  const liveName = live?.name
-  for (const j of [...pending, ...done]) { if (liveName && j.name === liveName) continue; items.push(j) }
-  return { items: items.slice(0, limit) }
+  const store = await loadState(config)
+  // One existsSync on the mount point — not the recursive glob the old pending
+  // section ran on every poll, and always current.
+  return buildJobsView(store, readCurrent(), { limit, alive: pidAlive, recorderPresent: existsSync(config.recordDir) })
 }
 
 async function jobsList(opts: { limit?: number; json?: boolean }): Promise<void> {
-  const data = await jobsListData(Number(opts.limit) || 30)
+  let limit: number
+  try { limit = parseJobsLimit(opts.limit, 30) } catch (e: any) { console.error(e.message); process.exitCode = 1; return }
+  const data = await jobsListData(limit)
   if (opts.json) { console.log(JSON.stringify(data, null, 2)); return }
-  if (!data.items.length) { console.log('No jobs yet.'); return }
-  for (const j of data.items) console.log(`[${j.status}] ${j.title || j.name}${j.step ? ' · ' + j.step : ''}${j.reason ? ' · ' + String(j.reason).slice(0, 120) : ''}`)
+  if (!data.items.length) {
+    console.log(data.recorder_present ? 'No jobs yet.' : 'No jobs yet. (recorder not connected)')
+    return
+  }
+  for (const j of data.items) {
+    const suffix = [j.step, j.detail].filter(Boolean).join(' \u00b7 ')
+    console.log(`[${j.status}] ${j.title || j.name}${suffix ? ' \u00b7 ' + suffix.slice(0, 140) : ''}`)
+  }
+  // Truncation used to be silent, which is how a 126-entry backlog read as 27.
+  if (data.total > data.items.length) console.log(`\u2026 ${data.total - data.items.length} more (vn jobs --limit 0 to show all)`)
+  if (!data.recorder_present) {
+    console.log(data.queued_total ? `Recorder not connected \u2014 ${data.queued_total} recording(s) waiting for it.` : 'Recorder not connected.')
+  }
 }
 
 async function doctor(opts: { json?: boolean } = {}): Promise<void> {
@@ -2691,7 +2824,7 @@ async function dispatchServe(req: any, send: (o: unknown) => void): Promise<void
       case 'config.get': result = configGetData(); break
       case 'config.set': result = await configSetData(params || {}); break
       case 'doctor': result = await collectDoctor(); break
-      case 'jobs': result = await jobsListData(Number(params?.limit) || 40); break
+      case 'jobs': result = await jobsListData(parseJobsLimit(params?.limit, 40)); break
       case 'ensure_agent': result = await ensureScheduler(!!params?.force); break
       case 'run': {
         // Long-running (minutes) like login: ack immediately so the GUI's 60s
@@ -2796,7 +2929,7 @@ cli.command('list', 'List notes in a month')
   .action(listMeetings)
 
 cli.command('last', 'Print summary of most recent processed recording').action(lastMeeting)
-cli.command('jobs', 'Show processing status of recordings (live + pending + done + summary_failed + failed + skipped)')
+cli.command('jobs', 'Show every recording\'s processing status (running, queued, done, failed, gave up, filtered)')
   .option('--limit <n>', 'How many to list', { default: 30 })
   .option('--json', 'Output as JSON (for the GUI)')
   .action((opts: { limit?: number; json?: boolean }) => jobsList(opts))
@@ -2804,7 +2937,7 @@ cli.command('jobs', 'Show processing status of recordings (live + pending + done
 
 cli.command('open [target]', 'Open notes dir, config dir (`config`), logs dir (`logs`), or a note matching the slug').action((target?: string) => openTarget(target))
 
-cli.command('forget <key>', 'Remove a recording from processed/skipped state so it can be reprocessed').action((key: string) => forgetRecording(key))
+cli.command('forget <key>', 'Drop a recording\'s job record so it is queued again (a saved transcript on disk is still reused)').action((key: string) => forgetRecording(key))
 
 cli.command('log', 'Print the daily log (today by default)')
   .option('--lines <n>', 'How many trailing lines to print', { default: 30 })

package/src/jobs.ts

@@ -0,0 +1,437 @@
+// The job-state model: what should run (classify), what should be forgotten
+// (pruneUnseen), and how it all reads back (buildJobsView).
+//
+// `vn jobs` used to assemble one view from three unrelated sources — a regex
+// over the launchd log (live), a second glob of the recorder (pending), and the
+// state file (everything else) — so the three could never agree. Now `vn run` is
+// the only writer and every view is a pure read. Keeping the *decisions* here
+// too (not just the grouping) is deliberate: the queue you see and the queue
+// that runs must come from one function, or they drift apart again.
+//
+// No fs, no process, no clock — all injected — so every rule is testable
+// (see jobs.test.ts).
+//
+// The invariant worth naming: a record left in `running` by a process that is
+// no longer alive is NOT running. Liveness is a pid check injected by the
+// caller, never inferred from log text — that inference is what used to wedge
+// a failed job at "Processing" forever.
+
+// Lifecycle position only. WHY a job is where it is lives in `code`, so no two
+// fields have to agree about the same fact — an earlier cut expressed "gave up"
+// as `code` while leaving `state` alone, and the view and the classifier
+// promptly disagreed about what such a record was.
+export type JobState = 'queued' | 'running' | 'done' | 'filtered' | 'error' | 'gave_up'
+
+/** Which stage produced a failure; also carries the filter reason. */
+export type JobCode = 'transcribe_failed' | 'summary_failed' | 'interrupted' | 'too_small' | 'too_short' | 'too_old' | null
+
+export type JobRecord = {
+  name: string
+  source_path: string
+  /** Local wall-clock `YYYY-MM-DDTHH:mm:ss` — sorts lexicographically, no TZ drift. */
+  recorded_at: string
+  size_bytes: number
+  duration_seconds: number | null
+  state: JobState
+  code: JobCode
+  detail: string | null
+  attempts: number
+  updated_at: string
+  title: string | null
+  paths: Record<string, string | null> | null
+}
+
+export type StateFile = {
+  version: 2
+  jobs: Record<string, JobRecord>
+}
+
+/**
+ * Does this record own files on disk? Evidence, not a state enum: a
+ * `summary_failed` record has a transcript and a stub note, and enumerating
+ * states would have to remember that. Deleting such a record loses real work
+ * and re-pays for ASR when the recorder comes back.
+ */
+export const ownsOutput = (j: JobRecord): boolean => j.paths != null
+
+// Give up auto-retrying a recording that keeps blowing up, so a permanently
+// broken file can't burn an ASR (or LLM) call every scheduler tick. `vn forget`
+// drops the record and puts it back in the queue.
+export const MAX_ATTEMPTS = 3
+
+/** The subset of JobCode a refusal may write to disk. */
+export type FilterCode = Extract<JobCode, 'too_small' | 'too_short' | 'too_old'>
+
+// Split by whether the refusal is persisted, so the code that reaches disk is
+// typed as such. A single `code: string` needed a cast at the write site, and
+// the cast was the only thing keeping a display-only reason out of the record.
+export type Verdict =
+  | { run: true }
+  | { run: false; persist: true; code: FilterCode; detail: string | null }
+  | { run: false; persist: false; code: 'already_done' | 'gave_up'; detail: string | null }
+
+export type ScanFacts = { recordedAt: Date; sizeBytes: number; durationSeconds: number | null }
+export type Limits = { maxAgeHours: number; minBytes: number; minDurationSeconds: number }
+
+/**
+ * The single answer to "should this recording run now, and in what form".
+ * `vn jobs` reads back what this decided instead of re-deriving it with looser
+ * rules, which is why the shown queue and the real queue can no longer disagree.
+ */
+export function classify(
+  rec: ScanFacts,
+  entry: JobRecord | undefined,
+  limits: Limits,
+  opts: { force: boolean; notesMode: boolean; now: number },
+): Verdict {
+  if (opts.force) return { run: true }
+  if (entry?.state === 'done') return { run: false, persist: false, code: 'already_done', detail: null }
+  // Only the summary is outstanding, and this run doesn't make summaries. The
+  // transcription stage is genuinely finished — re-running it would pay for ASR
+  // again and then mark the job `done` with no notes, permanently.
+  if (entry?.code === 'summary_failed' && !opts.notesMode) return { run: false, persist: false, code: 'already_done', detail: null }
+  // Retries are spent. reconcileInterrupted() is what puts a record here, so
+  // this branch needs no knowledge of *how* the attempts were used up.
+  if (entry?.state === 'gave_up') return { run: false, persist: false, code: 'gave_up', detail: entry.detail }
+
+  // Filters are deterministic properties of the file, checked before anything
+  // stateful so a too-short file can't ping-pong between error and queued.
+  const ageHours = (opts.now - rec.recordedAt.getTime()) / 3600_000
+  if (limits.maxAgeHours > 0 && ageHours > limits.maxAgeHours) return { run: false, persist: true, code: 'too_old', detail: `${ageHours.toFixed(0)}h > ${limits.maxAgeHours}h` }
+  if (rec.sizeBytes < limits.minBytes) return { run: false, persist: true, code: 'too_small', detail: `${rec.sizeBytes} < ${limits.minBytes} bytes` }
+  if (rec.durationSeconds !== null && rec.durationSeconds < limits.minDurationSeconds) return { run: false, persist: true, code: 'too_short', detail: `${rec.durationSeconds.toFixed(0)}s < ${limits.minDurationSeconds}s` }
+
+  // `error`, `queued` and `running` are retryable — `error` used to be terminal,
+  // which is how 127 dead entries piled up without a single retry. Anything else
+  // came off disk hand-edited or from a newer build: refuse it rather than run
+  // it, so the scheduler and the view (which shows it as unrecognised) agree.
+  if (entry && !RUNNABLE_STATES.has(entry.state)) {
+    return { run: false, persist: false, code: 'gave_up', detail: `Unrecognised state '${entry.state}'; \`vn forget ${entry.name}\` to start over` }
+  }
+  return { run: true }
+}
+
+const RUNNABLE_STATES = new Set<JobState>(['queued', 'running', 'error'])
+
+/** Every way a started attempt can end. */
+export type Outcome =
+  | { kind: 'done'; title: string | null; paths: Record<string, string | null> | null }
+  | { kind: 'summary_failed'; title: string | null; paths: Record<string, string | null> | null; message: string }
+  | { kind: 'failed'; message: string }
+  | { kind: 'interrupted' }
+
+/**
+ * The single place a started attempt is turned back into a record. It lives
+ * next to classify() and buildJobsView() on purpose: `running` used to be
+ * interpreted independently by all three, so they disagreed about what an
+ * interrupted-and-spent job was — the view called it "Queued" while the
+ * classifier refused to ever run it again.
+ */
+export function applyOutcome(entry: JobRecord, outcome: Outcome, now: string): void {
+  const spent = entry.attempts >= MAX_ATTEMPTS
+  const giveUp = (code: JobCode, why: string) => patchJob(entry, {
+    state: spent ? 'gave_up' : 'error',
+    code,
+    detail: spent
+      ? `${why} — gave up after ${entry.attempts} attempts; \`vn forget ${entry.name}\` to retry`
+      : `${why} (attempt ${entry.attempts}/${MAX_ATTEMPTS})`,
+  }, now)
+
+  switch (outcome.kind) {
+    case 'done':
+      // Only a clean finish refunds the budget.
+      patchJob(entry, { state: 'done', code: null, detail: null, title: outcome.title, paths: outcome.paths, attempts: 0 }, now)
+      return
+    case 'summary_failed':
+      // The expensive transcript is on disk; keep its paths so a retry resumes
+      // there. Retrying notes re-runs the LLM, so it spends from the same budget.
+      patchJob(entry, { title: outcome.title, paths: outcome.paths }, now)
+      giveUp('summary_failed', outcome.message)
+      return
+    case 'failed':
+      giveUp('transcribe_failed', outcome.message)
+      return
+    case 'interrupted':
+      giveUp('interrupted', 'Run was interrupted before this job reported back')
+      return
+  }
+}
+
+/** Open an attempt. Counted here, not at the end: a run killed mid-job (kill -9,
+ *  OOM, SIGTERM) never reaches an end, and an uncounted attempt retries forever. */
+export function startAttempt(entry: JobRecord, now: string): void {
+  patchJob(entry, { state: 'running', code: null, detail: null, attempts: entry.attempts + 1 }, now)
+}
+
+/**
+ * Reclaim records left `running` by a dead run. Safe to do wholesale because the
+ * caller holds the run lock: no other run can own a `running` record right now.
+ */
+export function reconcileInterrupted(jobs: Record<string, JobRecord>, now: string): JobRecord[] {
+  const stale = Object.values(jobs).filter(j => j.state === 'running')
+  for (const j of stale) applyOutcome(j, { kind: 'interrupted' }, now)
+  return stale
+}
+
+/**
+ * Convert the pre-0.18 layout (two reason-keyed buckets) to the one-map form.
+ * Pure so the one irreversible step in this codebase is testable: `error:*`
+ * entries are dropped, and they never come back.
+ */
+export function migrateLegacyState(raw: Record<string, any>, now: string): StateFile {
+  const jobs: Record<string, JobRecord> = {}
+  const nameOf = (path: string, id: string) => String(path || id).split(/[/\\]/).pop()!
+  const recordedAt = (name: string, fallback: string | undefined): string => {
+    const m = name.match(/(20\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/)
+    if (m) return `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}`
+    const d = fallback ? new Date(fallback) : null
+    return d && !Number.isNaN(+d) ? localIso(d) : '1970-01-01T00:00:00'
+  }
+  for (const [id, e] of Object.entries<any>(raw.processed_source_ids ?? {})) {
+    const name = nameOf(e.source_path, id)
+    jobs[id] = {
+      name, source_path: e.source_path ?? '', recorded_at: recordedAt(name, e.processed_at),
+      size_bytes: e.size_bytes ?? 0, duration_seconds: e.duration_seconds ?? null,
+      state: e.status === SUMMARY_FAILED_STATUS ? 'error' : 'done',
+      code: e.status === SUMMARY_FAILED_STATUS ? 'summary_failed' : null,
+      detail: e.status === SUMMARY_FAILED_STATUS ? 'Summary failed before 0.18; the saved transcript will be reused' : null,
+      attempts: 0, updated_at: e.processed_at ?? now,
+      title: e.title ?? null, paths: e.final_paths ?? e.local_paths ?? null,
+    }
+  }
+  for (const [id, e] of Object.entries<any>(raw.skipped_source_ids ?? {})) {
+    const reason = String(e.reason ?? '')
+    // `error:*` entries were scan artifacts, not jobs — overwhelmingly ENOENT
+    // from a recorder unplugged mid-run. Dropping them re-queues whatever is
+    // still on the device and forgets the rest.
+    if (reason.startsWith('error')) continue
+    const code = reason.split(':')[0] as JobCode
+    const name = nameOf(e.source_path, id)
+    jobs[id] = {
+      name, source_path: e.source_path ?? '', recorded_at: recordedAt(name, e.seen_at),
+      size_bytes: e.size_bytes ?? 0, duration_seconds: e.duration_seconds ?? null,
+      state: 'filtered', code, detail: reason.slice((code ?? '').length + 1) || null,
+      attempts: 0, updated_at: e.seen_at ?? now, title: null, paths: null,
+    }
+  }
+  return { version: 2, jobs }
+}
+
+/**
+ * Drop records the scan no longer sees. A queued/filtered/error record whose
+ * file is gone was a scan artifact, not a job — keeping them is how 127 dead
+ * entries accumulated. Records that produced output are history and stay.
+ *
+ * `scanComplete` is the guard, not an optimisation: a partial listing (recorder
+ * yanked mid-glob) would otherwise wipe live queue entries. They'd come back on
+ * the next scan, but their retry counters wouldn't. It lives here rather than at
+ * the call site so the rule whose failure wipes a queue is covered by tests.
+ */
+export function pruneUnseen(jobs: Record<string, JobRecord>, seen: Set<string>, scanComplete: boolean): JobRecord[] {
+  if (!scanComplete) return []
+  const dropped: JobRecord[] = []
+  for (const [id, j] of Object.entries(jobs)) {
+    if (seen.has(id) || ownsOutput(j)) continue
+    delete jobs[id]
+    dropped.push(j)   // the record, not the id: the caller must be able to name what it forgot
+  }
+  return dropped
+}
+
+export type CurrentJob = { pid: number; source_id: string; step: string; started_at: string }
+
+export type JobView = {
+  status: 'running' | 'queued' | 'done' | 'notes_failed' | 'error' | 'gave_up' | 'filtered'
+  name: string
+  title: string | null
+  time: string | null
+  step: string | null
+  detail: string | null
+  notes: string | null
+}
+
+export const SUMMARY_FAILED_STATUS = 'summary_failed_transcript_saved'
+
+/** Local wall clock, not UTC: recorder filenames are local time and the view sorts on this string. */
+export function localIso(d: Date): string {
+  const p = (n: number) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
+}
+
+/**
+ * Apply a patch, reporting whether anything actually changed.
+ *
+ * The no-op guard is load-bearing, not tidiness: `classify` re-derives the same
+ * verdict for every filtered recording on every 60s scan, so an unconditional
+ * `updated_at` bump would make the state file differ on each tick and defeat the
+ * content-gated write that keeps synced workspaces quiet.
+ */
+export function patchJob(entry: JobRecord, patch: Partial<JobRecord>, now: string): boolean {
+  if (Object.entries(patch).every(([k, v]) => (entry as any)[k] === v)) return false
+  Object.assign(entry, patch, { updated_at: now })
+  return true
+}
+
+export const emptyState = (): StateFile => ({ version: 2, jobs: {} })
+
+/**
+ * One meaning of `limit` for both front doors (the CLI flag and the GUI's RPC):
+ * 0 = no limit, absent = `fallback`, anything else must be a non-negative
+ * integer. Coercing garbage to a default is how a truncated list gets mistaken
+ * for a complete one — the exact bug this module exists to remove.
+ */
+export function parseJobsLimit(raw: unknown, fallback: number): number {
+  if (raw === undefined || raw === null || raw === '') return fallback
+  const n = Number(raw)
+  if (!Number.isInteger(n) || n < 0) throw new Error(`Invalid limit '${raw}': expected a non-negative integer (0 = no limit).`)
+  return n === 0 ? Infinity : n
+}
+
+/**
+ * Parse a state file, throwing on anything that isn't one.
+ *
+ * Deliberately strict: a truncated or sync-mangled file that silently read as
+ * "nothing was ever processed" would re-transcribe the entire history, pay for
+ * ASR a second time, and then overwrite the evidence on the next save.
+ */
+export function parseStateFile(text: string, path: string): StateFile {
+  const parsed = parseStrictJson(text, path)
+  const version = (parsed as any)?.version
+  // A newer build's file must not be reinterpreted as v2: unknown states would
+  // be re-run by the classifier while the view calls them unrecognised.
+  if (Number.isFinite(version) && version > 2) {
+    throw new Error(`${path} was written by a newer voicenote (state version ${version}). Upgrade rather than risk re-processing everything.`)
+  }
+  const raw = (parsed as any)?.jobs
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error(`${path} is not a job-state file (no \`jobs\` map). Refusing to continue rather than re-processing everything.`)
+  }
+  // Normalise at the boundary rather than trusting field by field downstream.
+  // `attempts` especially: a missing value makes `attempts >= MAX_ATTEMPTS`
+  // compare as NaN, which is false — the retry cap would silently never apply
+  // and a broken recording would burn ASR every scheduler tick.
+  const jobs: Record<string, JobRecord> = {}
+  for (const [id, j] of Object.entries<any>(raw)) {
+    if (!j || typeof j !== 'object') continue
+    jobs[id] = {
+      ...j,
+      name: typeof j.name === 'string' ? j.name : id,
+      source_path: typeof j.source_path === 'string' ? j.source_path : '',
+      recorded_at: typeof j.recorded_at === 'string' ? j.recorded_at : '',
+      attempts: Number.isInteger(j.attempts) && j.attempts >= 0 ? j.attempts : 0,
+      paths: j.paths && typeof j.paths === 'object' ? j.paths : null,
+    }
+  }
+  return { version: 2, jobs }
+}
+
+/** JSON.parse with the message a user can act on. */
+export function parseStrictJson(text: string, path: string): unknown {
+  let parsed: unknown
+  try { parsed = JSON.parse(text) } catch (e: any) {
+    throw new Error(`${path} is unreadable (${e?.message || e}). Move it aside to start over — but note that re-processing every recording costs ASR again.`)
+  }
+  if (!parsed || typeof parsed !== 'object') throw new Error(`${path} is not a JSON object. Refusing to continue rather than re-processing everything.`)
+  return parsed
+}
+
+const FILTER_LABELS: Record<string, string> = {
+  too_small: 'too small',
+  too_short: 'too short',
+  too_old: 'too old',
+}
+
+/** `2026-07-29T12:06:29` → `2026-07-29 12:06`. */
+export function displayTime(recordedAt: string | null): string | null {
+  if (!recordedAt) return null
+  return recordedAt.slice(0, 16).replace('T', ' ')
+}
+
+function foldFiltered(records: JobRecord[]): JobView | null {
+  if (!records.length) return null
+  const counts = new Map<string, number>()
+  for (const r of records) {
+    const key = FILTER_LABELS[r.code ?? ''] ?? r.code ?? 'filtered'
+    counts.set(key, (counts.get(key) ?? 0) + 1)
+  }
+  const detail = [...counts].map(([label, n]) => `${label} ×${n}`).join(', ')
+  return {
+    status: 'filtered',
+    name: `${records.length} recording${records.length > 1 ? 's' : ''} filtered out`,
+    title: null, time: null, step: null, detail, notes: null,
+  }
+}
+
+export function buildJobsView(
+  state: StateFile,
+  current: CurrentJob | null,
+  opts: { limit: number; alive: (pid: number) => boolean; recorderPresent: boolean },
+): { items: JobView[]; total: number; queued_total: number; recorder_present: boolean } {
+  // Two independent conditions must agree before a row is shown as running:
+  // the declaring process is alive, AND the record itself says `running`.
+  // current.json survives a kill -9, so the pid alone could be recycled by an
+  // unrelated long-lived process and wedge a finished job at "Processing" —
+  // the very failure this rewrite exists to remove.
+  const claimed = current && opts.alive(current.pid) ? current : null
+  const live = claimed && state.jobs?.[claimed.source_id]?.state === 'running' ? claimed : null
+
+  const running: JobView[] = []
+  const queued: JobView[] = []
+  const attention: JobView[] = []
+  const done: JobView[] = []
+  const filtered: JobRecord[] = []
+
+  for (const [id, j] of Object.entries(state.jobs ?? {})) {
+    const base = {
+      name: j.name,
+      title: j.title ?? null,
+      time: displayTime(j.recorded_at),
+      step: null,
+      detail: null as string | null,
+      notes: j.paths?.notes ?? null,
+      _t: j.recorded_at ?? '',
+    }
+    if (live && live.source_id === id) { running.push({ ...base, status: 'running', step: live.step }); continue }
+    switch (j.state) {
+      case 'done': done.push({ ...base, status: 'done' }); break
+      // A `running` record with no live process is a crashed run; the next run
+      // reconciles it. Until then it belongs with the work still to do.
+      case 'running':
+      case 'queued': queued.push({ ...base, status: 'queued' }); break
+      // A saved transcript with a failed summary reads better as its own row:
+      // the stub note is openable and the retry is cheap (no ASR).
+      case 'error': attention.push({ ...base, status: j.code === 'summary_failed' ? 'notes_failed' : 'error', detail: j.detail }); break
+      case 'gave_up': attention.push({ ...base, status: 'gave_up', detail: j.detail }); break
+      case 'filtered': filtered.push(j); break
+      // `state` comes off disk and could be hand-edited or written by a newer
+      // build. Showing an unknown value as "done" would hide unprocessed work,
+      // so surface it instead.
+      default: attention.push({ ...base, status: 'error', detail: `Unrecognised state '${j.state}'` })
+    }
+  }
+
+  // Sort and display share one key (recorded_at). They used to differ — list
+  // sorted by processing time, rows labelled with recording time — which is why
+  // the list looked shuffled.
+  const asc = (a: any, b: any) => String(a._t).localeCompare(String(b._t))
+  queued.sort(asc)
+  attention.sort((a, b) => -asc(a, b))
+  done.sort((a, b) => -asc(a, b))
+
+  const filteredRow = foldFiltered(filtered)
+  // Priority is the array order: live work, then the queue, then anything needing
+  // attention, then history. Everything is subject to `limit` — exempting the
+  // head would make one broken credential (every recording failing MAX_ATTEMPTS
+  // times into `attention`) an unbounded list, with `total` claiming it was whole.
+  const ordered = [...running, ...queued, ...attention, ...done]
+  const items: JobView[] = ordered.slice(0, Math.max(0, opts.limit - (filteredRow ? 1 : 0)))
+  if (filteredRow) items.push(filteredRow)
+  const total = ordered.length + (filteredRow ? 1 : 0)
+
+  for (const it of items) delete (it as any)._t
+  // `queued_total` is pre-truncation on purpose: "N recordings waiting" counted
+  // from the visible page would contradict the "… X more" line right above it.
+  // Read `recorder_present` live from the caller, never stored — a persisted
+  // flag would keep claiming the recorder is connected after the agent stops.
+  return { items, total, queued_total: running.length + queued.length, recorder_present: opts.recorderPresent }
+}