@fastagent-sh/voicenote 0.22.1 → 0.22.2

package/README.md

@@ -177,6 +177,7 @@ vn open <slug>                  # open a note by filename fragment
 vn forget <id|filename>         # let a recording be processed again
 vn log                          # print today's log tail (--lines N / -f follow / --err include launchd.err / --date YYYY-MM-DD)
 vn errors                       # print recent ERROR logs
+vn import /path/to/audio.mp3    # copy one local recording into the durable manual-import queue
 vn login                        # sign in to ChatGPT for the notes backend (browser callback; `--device-code` for headless machines). No pi TUI needed
 vn upgrade                      # reinstall latest npm package
 vn install-launch-agent
@@ -215,6 +216,10 @@ Changes take effect on the next `vn run`. `~`, `$HOME`, and `${HOME}` are accept
 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
 
+The history range defaults to 48 hours. In the GUI, choose 7 days, 30 days, or all recordings under **Settings → Recording history to process**. Expanding it re-evaluates recordings previously filtered as `too_old`; the dashboard's filtered summary links directly to this setting.
+
+To process a local file immediately, drop one supported audio file onto the GUI. It is copied atomically to `${VOICENOTE_WORKSPACE}/_inbox`, queued even if another run is active or the recorder is disconnected, and processed before automatic recorder items without the automatic age/size/duration filters. The temporary inbox copy is removed after success and retained after failure for Retry. Imports are content-addressed, so dropping the same audio again opens the existing note instead of paying for ASR twice when a matching completed job is known.
+
 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. Use **Retry** on its GUI row to reset the budget, preserve saved outputs, and run it again; `vn forget <name>` is the CLI escape hatch that drops the record and re-queues it. Either path reuses a saved transcript instead of paying for ASR again. Both take the run lock, so retry after the active run finishes if the state file is busy.
 
 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.
@@ -227,6 +232,7 @@ Records whose source file is no longer on the recorder are forgotten on the next
 - Original audio: `${VOICENOTE_WORKSPACE}/_audio/YYYY-MM/`
 - Full transcripts: `${VOICENOTE_WORKSPACE}/_transcripts/YYYY-MM/`
 - Metadata: `${VOICENOTE_WORKSPACE}/_metadata/YYYY-MM/`
+- Pending manual imports: `${VOICENOTE_WORKSPACE}/_inbox/` (removed after success)
 - 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` writes lifecycle updates; only explicit retry/forget actions mutate it otherwise. `vn jobs` and passive GUI refreshes are pure reads, 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`
 
@@ -242,7 +248,7 @@ launchctl enable gui/$(id -u)/sh.fastagent.voicenote
 vn status
 ```
 
-The LaunchAgent invokes `vn run` every 60 seconds. It skips safely when no recorder is plugged in; once the VTR6500 is connected, new recordings are processed automatically.
+The LaunchAgent invokes `vn run` every 60 seconds. Without a recorder it still processes queued local imports; once the VTR6500 is connected, new recorder items are processed automatically too.
 
 > `config.json` changes are picked up by the background agent on its next run. The plist stores only a fixed PATH and executable paths: **after changing `VOICENOTE_PI_BIN`, re-run `vn install-launch-agent --load`** (`vn upgrade` does this automatically). Shell-only settings are deliberately not copied into the scheduler; persist them with `vn config set`. If pi or ASR is not configured, the agent skips before spending ASR.
 
@@ -282,10 +288,10 @@ The workflow lives at `.github/workflows/release.yml`: CI explicitly runs typech
 
 A self-contained macOS `.app` (Tauri v2) for **non-terminal users**: the target machine needs no pre-installed bun / pi / ffprobe / global `vn`.
 
-**Positioning**: the GUI is a status dashboard with quick access to output and manual Sync/Retry controls. The full pipeline still runs autonomously every 60s via the background LaunchAgent using the bundled CLI (it keeps running with the GUI closed).
+**Positioning**: the GUI is a status dashboard with quick access to output, drag-to-import, and manual Sync/Retry controls. The full pipeline still runs autonomously every 60s via the background LaunchAgent using the bundled CLI (it keeps running with the GUI closed).
 
 - First run: settings (identity / Volcano keys / proxy). The notes model comes from pi; ChatGPT users can sign in from the Status panel (`vn login`'s browser-callback flow).
-- After that: the main view shows agent activity and recent notes, opens outputs, and can retry failed recordings.
+- After that: the main view shows agent activity and recent notes, opens outputs, retries failed recordings, and accepts one local audio file dropped anywhere on the window.
 
 ### What's bundled
 

package/README.zh-CN.md

@@ -172,6 +172,7 @@ vn open <slug>                  # 按文件名片段打开纪要
 vn forget <id|filename>         # 让某条录音重新被处理
 vn log                          # 打印今天日志末尾(--lines N / -f 跟随 / --err 含 launchd.err / --date YYYY-MM-DD)
 vn errors                       # 打印最近 ERROR 日志
+vn import /path/to/audio.mp3    # 把一个本地录音复制进持久化手动导入队列
 vn login                        # 登录 ChatGPT, 纪要后端用(默认浏览器回调; 无头机器用 `--device-code`)。无需开 pi TUI
 vn upgrade                      # reinstall latest npm package
 vn install-launch-agent
@@ -210,6 +211,10 @@ vn uninstall-launch-agent
 6. summary 模型(由 pi 自身配置决定)直接看原始 transcript,在纪要生成阶段内部完成必要清理、说话人还原、观点/争论/共识形成过程还原;如果 summary 失败,下一次 `vn run` / `vn run --latest` 会复用已保存 transcript,直接重试纪要生成,不需要 `vn forget`
 7. 写出 notes / metadata；系统不做任何归档决定，文件留在配置的 workspace 中
 
+历史范围默认是 48 小时。GUI 可在**设置 → 处理多长时间范围内的录音**中选择最近 7 天、30 天或全部录音。扩大范围后，之前因 `too_old` 被过滤的录音会按新条件重新入队；dashboard 的过滤汇总也会直接链接到该设置。
+
+需要立即处理本地文件时，把一个支持的音频文件拖进 GUI 即可。应用会先原子复制到 `${VOICENOTE_WORKSPACE}/_inbox`；即使当前正在运行其他任务或录音笔未连接，也会持久排队。手动导入优先于录音笔的自动扫描任务，并跳过自动扫描的时间、大小和时长过滤。成功后删除 inbox 临时副本，失败时保留以供“重试”。导入按内容寻址；当系统已知相同内容的完成记录时，再次拖入会打开已有纪要，不会重复支付 ASR。
+
 失败的录音会在后续运行中重试，但**最多 3 次**（转写失败、纪要失败、以及被中途 kill 的运行都算）。超过后标记为 `Gave up` 并不再自动重试，避免一个坏文件每个调度周期都烧一次 ASR/LLM 额度。点击 GUI 记录上的**重试**会重置次数、保留已有产物并立即再跑；CLI 也可以用 `vn forget <name>` 删除记录后重新入队。两种方式都会复用磁盘上已有的 transcript，不会重复支付 ASR 费用。它们都需要 run lock；如果当前正在处理，请等本次 run 结束后再重试。
 
 源文件已不在录音笔上的记录，会在下一次扫描时被遗忘（并记入日志），**已经产出纪要或 transcript 的除外** —— 那部分历史会保留。所以换录音笔、或从设备上删文件，不再会留下永久的 “失败” 条目。
@@ -222,6 +227,7 @@ vn uninstall-launch-agent
 - 原始音频:`${VOICENOTE_WORKSPACE}/_audio/YYYY-MM/`
 - 完整转写:`${VOICENOTE_WORKSPACE}/_transcripts/YYYY-MM/`
 - metadata:`${VOICENOTE_WORKSPACE}/_metadata/YYYY-MM/`
+- 待处理的手动导入：`${VOICENOTE_WORKSPACE}/_inbox/`（成功后删除）
 - 状态：`${VOICENOTE_WORKSPACE}/_state/jobs.json` —— 每条录音一条记录，包含 `state`（生命周期位置：`queued`、`running`、`done`、`filtered`、`error`，以及重试耗尽后的 `gave_up`）、`code`（原因：`summary_failed`、`transcribe_failed`、`interrupted`、`too_small` 等）、重试次数和产物路径。`vn run` 写入正常生命周期变化，除此之外只有显式重试或 forget 操作会修改它；`vn jobs` 和 GUI 的被动刷新都是纯读取，因此看到的队列就是实际会跑的队列。0.18 之前的 `processed.json` 会在首次运行时自动转换，旧文件保留为 `processed.json.v1.bak`。
 - 索引:`${VOICENOTE_WORKSPACE}/_index/notes.jsonl`
 
@@ -237,7 +243,7 @@ launchctl enable gui/$(id -u)/sh.fastagent.voicenote
 vn status
 ```
 
-LaunchAgent 每 60 秒调用 `vn run`。没插录音笔时安全跳过;插上 VTR6500 后自动处理新录音。
+LaunchAgent 每 60 秒调用 `vn run`。没插录音笔时仍会处理本地导入队列；插上 VTR6500 后也会自动处理录音笔里的新录音。
 
 > 后台 agent 会在下一次运行时读取 `config.json` 的改动。plist 只保存固定 PATH 和可执行文件路径：**改了 `VOICENOTE_PI_BIN` 后需重跑 `vn install-launch-agent --load`**（`vn upgrade` 会自动处理）。shell 中临时设置的值不会复制进 scheduler，请用 `vn config set` 持久化。未配置 pi / ASR 时，agent 会在支付 ASR 成本前跳过。
 
@@ -277,10 +283,10 @@ workflow 位于 `.github/workflows/release.yml`:CI 显式跑 typecheck、测试
 
 面向**非终端用户**:一个自包含的 macOS `.app`(Tauri v2),目标机器无需预装 bun / pi / ffprobe / 全局 `vn`。
 
-**定位**:GUI 是工作状态 dashboard，提供产出快捷入口以及手动同步/重试。全流程仍由后台 LaunchAgent 用包内 CLI 每 60s 自主运行(关掉 GUI 也跑)。
+**定位**:GUI 是工作状态 dashboard，提供产出快捷入口、拖拽导入以及手动同步/重试。全流程仍由后台 LaunchAgent 用包内 CLI 每 60s 自主运行(关掉 GUI 也跑)。
 
 - 首次:配置向导(身份 / Volcano keys / 代理)→ ChatGPT 登录(设备无终端,走 `vn login` 的浏览器回调流)
-- 之后:主界面显示 agent 活动和最近纪要，可打开产物或重试失败录音
+- 之后:主界面显示 agent 活动和最近纪要，可打开产物、重试失败录音，也可把一个本地音频文件拖到窗口任意位置立即排队
 
 ### 打包内容
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/voicenote",
-  "version": "0.22.1",
+  "version": "0.22.2",
   "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",

package/src/cli.ts

@@ -5,7 +5,7 @@ import { parseLockOwner } from './runLock'
 import { tosObject, type TosConfig as VolcanoTosConfig } from './tos'
 import { applyOutcome, buildJobsView, classify, emptyState, localIso, MAX_ATTEMPTS, migrateLegacyState, ownsOutput, parseJobsLimit, parseStateFile, parseStrictJson, patchJob, pruneUnseen, reconcileInterrupted, requeueFailed, startAttempt, SUMMARY_FAILED_STATUS, type CurrentJob, type JobRecord, type StateFile } from './jobs'
 import { createHash, randomUUID } from 'node:crypto'
-import { appendFile, chmod, mkdir, readFile, writeFile, copyFile, rename, unlink, stat, readdir } from 'node:fs/promises'
+import { appendFile, chmod, mkdir, readFile, writeFile, copyFile, rename, unlink, stat, readdir, rmdir, utimes } from 'node:fs/promises'
 import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, openSync, closeSync, statSync, readSync, unlinkSync, renameSync } from 'node:fs'
 import { dlopen, FFIType, suffix } from 'bun:ffi'
 import { basename, dirname, extname, join, resolve } from 'node:path'
@@ -52,7 +52,9 @@ type Recording = {
   modifiedAt: string
   durationSeconds: number | null
   sourceId: string
+  contentHash: string
   recordedAt: Date
+  imported: boolean
 }
 
 type LocalFiles = {
@@ -354,8 +356,10 @@ function formatSeconds(seconds: number | null | undefined): string {
 // File state IO
 // ────────────────────────────────────────────────────────────────────────────
 
+const inboxPathFor = (config: Config) => join(config.workspace, '_inbox')
+
 async function ensureDirs(config: Config): Promise<void> {
-  for (const dir of ['_state', '_index', '_audio', '_transcripts', '_metadata']) {
+  for (const dir of ['_state', '_index', '_audio', '_transcripts', '_metadata', '_inbox']) {
     await mkdir(join(config.workspace, dir), { recursive: true })
   }
 }
@@ -646,10 +650,10 @@ async function sha256File(path: string): Promise<string> {
   return h.digest('hex')
 }
 
-async function sourceIdFor(path: string): Promise<string> {
-  const st = await stat(path)
-  const digest = await sha256File(path)
-  return createHash('sha256').update(`${path}|${st.size}|${Math.floor(st.mtimeMs / 1000)}|${digest}`).digest('hex')
+function sourceIdFor(path: string, size: number, mtimeMs: number, digest: string, imported = false): string {
+  // Manual imports are content-addressed: dropping the same audio again must
+  // find its existing job even after the temporary inbox copy was removed.
+  return imported ? `import:${digest}` : createHash('sha256').update(`${path}|${size}|${Math.floor(mtimeMs / 1000)}|${digest}`).digest('hex')
 }
 
 function runCommand(command: string, args: string[], timeoutMs = 20000): Promise<{ stdout: string; stderr: string; code: number }> {
@@ -744,41 +748,49 @@ function isCandidateFile(path: string): boolean {
  * treating a half-read device as authoritative would delete live queue entries
  * along with their retry counters.
  */
-async function toRecording(config: Config, file: string): Promise<Recording> {
+async function toRecording(config: Config, file: string, imported = false): Promise<Recording> {
   const st = await stat(file)
+  const contentHash = await sha256File(file)
   return {
     sourcePath: file,
     sizeBytes: st.size,
     modifiedAt: st.mtime.toISOString(),
     durationSeconds: await ffprobeDuration(config, file),
-    sourceId: await sourceIdFor(file),
+    sourceId: sourceIdFor(file, st.size, st.mtimeMs, contentHash, imported),
+    contentHash,
     recordedAt: parseRecordedAt(file),
+    imported,
   }
 }
 
 async function scanRecordings(config: Config): Promise<{ recordings: Recording[]; complete: boolean }> {
-  if (!existsSync(config.recordDir)) return { recordings: [], complete: false }
   const recordings: Recording[] = []
-  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(await toRecording(config, file))
-      } catch (e) { complete = false; warnSideEffect(`read ${basename(file)} during scan`, e) }
+  const recorderPresent = existsSync(config.recordDir)
+  let complete = recorderPresent
+  const roots = [
+    ...(recorderPresent ? [{ dir: config.recordDir, imported: false }] : []),
+    ...(existsSync(inboxPathFor(config)) ? [{ dir: inboxPathFor(config), imported: true }] : []),
+  ]
+  for (const root of roots) {
+    try {
+      for await (const file of new Bun.Glob('**/*').scan({ cwd: root.dir, 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(await toRecording(config, file, root.imported))
+        } catch (e) { complete = false; warnSideEffect(`read ${basename(file)} during scan`, e) }
+      }
+    } catch (e) {
+      complete = false
+      warnSideEffect(`scan ${root.imported ? 'import inbox' : 'recorder'}`, 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.
-  recordings.sort((a, b) => a.recordedAt.getTime() - b.recordedAt.getTime())
+  // Explicit imports go first; each group remains oldest-first.
+  recordings.sort((a, b) => Number(b.imported) - Number(a.imported) || a.recordedAt.getTime() - b.recordedAt.getTime())
   return { recordings, complete }
 }
 
@@ -1735,13 +1747,16 @@ async function saveState(config: Config, store: StateFile): Promise<void> {
 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),
+    name: basename(rec.sourcePath), source_path: rec.sourcePath, content_hash: rec.contentHash, 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,
+    ...(rec.imported ? { origin: 'import' as const } : {}),
   }
   next.source_path = rec.sourcePath
+  next.content_hash = rec.contentHash
   next.size_bytes = rec.sizeBytes
   next.duration_seconds = rec.durationSeconds
+  next.origin = rec.imported ? 'import' : undefined
   store.jobs[rec.sourceId] = next
   return next
 }
@@ -1831,15 +1846,17 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
   // filters (age/size/duration) don't apply — the user named the file.
   const single = opts.file ? resolve(String(opts.file)) : null
   if (single && !statSync(single, { throwIfNoEntry: false })?.isFile()) throw new Error(`Not a file: ${single}`)
-  if (!single && !existsSync(config.recordDir)) {
+  if (single && !isCandidateFile(single)) throw new Error(`Unsupported audio file. Use: ${[...AUDIO_EXTENSIONS].join(', ')}`)
+  const recorderPresent = existsSync(config.recordDir)
+  const { recordings, complete: scanComplete } = single
+    ? { recordings: [await toRecording(config, single)], complete: false }
+    : await scanRecordings(config)
+  if (!single && !recorderPresent && !recordings.length) {
     if (shouldLogIdleStatus(`missing:${config.recordDir}`)) {
-      console.log(`Idle: recorder not mounted or record dir missing: ${config.recordDir} (repeated idle logs suppressed for 30m)`)
+      console.log(`Idle: recorder not mounted and no manual imports are queued: ${config.recordDir} (repeated idle logs suppressed for 30m)`)
     }
     return
   }
-  const { recordings, complete: scanComplete } = single
-    ? { recordings: [await toRecording(config, single)], complete: false }
-    : await scanRecordings(config)
   const mode = normalizeRunMode(opts)
   const force = Boolean(opts.force)
   const eligible: Recording[] = []
@@ -1849,17 +1866,28 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
   // idle-suppressed silence meant for the 60s scheduler tick.
   const verboseSkips = Boolean(opts.verbose || opts.dryRun || single)
   const seen = new Set<string>()
-  const limits = single
-    ? { maxAgeHours: 0, minBytes: 0, minDurationSeconds: 0 }
-    : { maxAgeHours: config.maxAgeHours, minBytes: config.minBytes, minDurationSeconds: config.minDurationSeconds }
+  const automaticLimits = { maxAgeHours: config.maxAgeHours, minBytes: config.minBytes, minDurationSeconds: config.minDurationSeconds }
+  const manualLimits = { maxAgeHours: 0, minBytes: 0, minDurationSeconds: 0 }
   for (const rec of recordings) {
     seen.add(rec.sourceId)
+    const completedDuplicate = rec.imported && !store.jobs[rec.sourceId]
+      ? completedJobByHash(store, rec.contentHash)
+      : undefined
+    if (completedDuplicate) {
+      const name = basename(rec.sourcePath)
+      skipCounts.already_done = (skipCounts.already_done || 0) + 1
+      ;(skipSamples.already_done ||= []).push(name)
+      if (!opts.dryRun) await removeImportedSource(rec.sourcePath)
+      if (verboseSkips) console.log(`  Skip: ${name} (already_done)`)
+      continue
+    }
     const entry = recordFor(store, rec)
-    const verdict = classify(rec, store.jobs[rec.sourceId], limits, { force, notesMode: mode === 'notes', now: Date.now() })
+    const verdict = classify(rec, store.jobs[rec.sourceId], single || rec.imported ? manualLimits : automaticLimits, { 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) patchJob(entry, { state: 'filtered', code: verdict.code, detail: verdict.detail }, nowIso())
+    if (rec.imported && verdict.code === 'already_done' && !opts.dryRun) await removeImportedSource(rec.sourcePath)
     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
@@ -1908,8 +1936,9 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
   }
   await saveState(config, store)
 
-  for (const rec of targets) {
+  for (const [targetIndex, rec] of targets.entries()) {
     const entry = store.jobs[rec.sourceId]!
+    let importedDone = false
     // --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.
@@ -1925,6 +1954,7 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
       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())
+      importedDone = rec.imported && result.status !== SUMMARY_FAILED_STATUS
     } catch (e: any) {
       const message = String(e?.message || e)
       console.error(`ERROR processing ${rec.sourcePath}: ${message}`)
@@ -1944,9 +1974,10 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
       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 (!single && !existsSync(config.recordDir)) {
+    if (importedDone) await removeImportedSource(rec.sourcePath)
+    // Whole recorder went away — every remaining recorder target would fail the
+    // same way. Local imports do not depend on the recorder and keep running.
+    if (!single && !existsSync(config.recordDir) && targets.slice(targetIndex + 1).some(target => !target.imported)) {
       console.error(`Recorder disappeared mid-run (${config.recordDir}); stopping. Remaining recordings stay queued.`)
       break
     }
@@ -2288,6 +2319,74 @@ async function openTarget(arg?: string): Promise<void> {
   console.log(`open ${target}`)
 }
 
+function completedJobByHash(store: StateFile, digest: string): [string, JobRecord] | undefined {
+  return Object.entries(store.jobs).find(([, job]) => job.state === 'done' && job.content_hash === digest)
+}
+
+type ImportResult = {
+  status: 'queued' | 'running' | 'gave_up' | 'already_done'
+  id: string
+  name: string
+  title: string | null
+  notes: string | null
+}
+
+async function importRecording(file: string, opts: { json?: boolean }): Promise<void> {
+  const source = resolve(file)
+  const sourceStat = await stat(source).catch(() => null)
+  if (!sourceStat?.isFile()) throw new Error(`Not a file: ${source}`)
+  if (!isCandidateFile(source)) throw new Error(`Unsupported audio file. Use: ${[...AUDIO_EXTENSIONS].join(', ')}`)
+
+  const config = getConfig()
+  await ensureDirs(config)
+  const digest = await sha256File(source)
+  const id = `import:${digest}`
+  const store = await loadState(config)
+  const entry = store.jobs[id]
+  const doneMatch = entry?.state === 'done'
+    ? [id, entry] as const
+    : entry ? undefined : completedJobByHash(store, digest)
+  let result: ImportResult
+
+  if (doneMatch) {
+    const [doneId, done] = doneMatch
+    result = { status: 'already_done', id: doneId, name: done.name, title: done.title, notes: done.paths?.notes ?? null }
+  } else {
+    const digestDir = join(inboxPathFor(config), digest)
+    const queuedName = (await readdir(digestDir).catch(() => []))
+      .find(name => isCandidateFile(name) && statSync(join(digestDir, name), { throwIfNoEntry: false })?.isFile())
+    const existingSource = entry?.source_path && existsSync(entry.source_path) ? entry.source_path : null
+    const inboxFile = existingSource ?? (queuedName ? join(digestDir, queuedName) : join(digestDir, basename(source)))
+    if (!existsSync(inboxFile)) {
+      await mkdir(dirname(inboxFile), { recursive: true })
+      const tmp = join(dirname(inboxFile), `.${basename(inboxFile)}.tmp-${process.pid}`)
+      try {
+        await copyFile(source, tmp)
+        await utimes(tmp, sourceStat.atime, sourceStat.mtime)
+        await rename(tmp, inboxFile)
+      } finally {
+        await unlink(tmp).catch(() => {})
+      }
+    }
+    result = {
+      status: entry?.state === 'running' ? 'running' : entry?.state === 'gave_up' ? 'gave_up' : 'queued',
+      id, name: entry?.name ?? basename(source), title: entry?.title ?? null, notes: entry?.paths?.notes ?? null,
+    }
+  }
+
+  if (opts.json) console.log(JSON.stringify(result))
+  else if (result.status === 'already_done') console.log(`already processed: ${result.title || result.name}`)
+  else console.log(`${result.status}: ${result.name}`)
+}
+
+async function removeImportedSource(path: string): Promise<void> {
+  try { await unlink(path) }
+  catch (e: any) { if (e?.code !== 'ENOENT') { warnSideEffect(`remove imported source ${path}`, e); return } }
+  await rmdir(dirname(path)).catch((e: any) => {
+    if (e?.code !== 'ENOENT' && e?.code !== 'ENOTEMPTY') warnSideEffect(`remove empty import dir ${dirname(path)}`, e)
+  })
+}
+
 async function forgetRecording(needle: string): Promise<void> {
   const config = getConfig()
   // Under the run lock: `vn run` holds the state file in memory for the length
@@ -2641,6 +2740,9 @@ cli.command('jobs', 'Show every recording\'s processing status (running, queued,
 
 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('import <file>', 'Copy one audio file into the durable manual-import queue')
+  .option('--json', 'Output structured status (for the GUI)')
+  .action((file: string, opts: { json?: boolean }) => importRecording(file, opts))
 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('retry <id>', 'Requeue one failed recording while retaining saved outputs').action((id: string) => retryRecording(id))
 

package/src/jobs.ts

@@ -28,6 +28,7 @@ type JobCode = 'transcribe_failed' | 'summary_failed' | 'interrupted' | 'too_sma
 export type JobRecord = {
   name: string
   source_path: string
+  content_hash?: string
   /** Local wall-clock `YYYY-MM-DDTHH:mm:ss` — sorts lexicographically, no TZ drift. */
   recorded_at: string
   size_bytes: number
@@ -39,6 +40,7 @@ export type JobRecord = {
   updated_at: string
   title: string | null
   paths: Record<string, string | null> | null
+  origin?: 'import'
 }
 
 export type StateFile = {
@@ -101,17 +103,17 @@ export function classify(
   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.
+  // `error`, `queued` and `running` are retryable. A previously `filtered`
+  // record is runnable too once it passes the CURRENT filters, so widening the
+  // history range in Settings actually re-queues recordings marked `too_old`.
+  // Anything else came off disk hand-edited or from a newer build: refuse it.
   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'])
+const RUNNABLE_STATES = new Set<JobState>(['queued', 'running', 'error', 'filtered'])
 
 /** Every way a started attempt can end. */
 type Outcome =
@@ -256,6 +258,8 @@ type JobView = {
   step: string | null
   detail: string | null
   notes: string | null
+  history_filtered: boolean
+  imported: boolean
 }
 
 export const SUMMARY_FAILED_STATUS = 'summary_failed_transcript_saved'
@@ -368,6 +372,7 @@ function foldFiltered(records: JobRecord[]): JobView | null {
     status: 'filtered',
     name: `${records.length} recording${records.length > 1 ? 's' : ''} filtered out`,
     title: null, time: null, step: null, detail, notes: null,
+    history_filtered: records.some(r => r.code === 'too_old'), imported: false,
   }
 }
 
@@ -375,7 +380,7 @@ 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 } {
+): { items: JobView[]; total: number; queued_total: number; recorder_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
@@ -399,6 +404,8 @@ export function buildJobsView(
       step: null,
       detail: null as string | null,
       notes: j.paths?.notes ?? null,
+      history_filtered: false,
+      imported: j.origin === 'import',
       _t: j.recorded_at ?? '',
     }
     if (live && live.source_id === id) { running.push({ ...base, status: 'running', step: live.step }); continue }
@@ -443,5 +450,11 @@ export function buildJobsView(
   // 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 }
+  return {
+    items,
+    total,
+    queued_total: running.length + queued.length,
+    recorder_queued_total: [...running, ...queued].filter(job => !job.imported).length,
+    recorder_present: opts.recorderPresent,
+  }
 }