omnilane 0.14.0 → 0.20.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "name": "omnilane",
+  "owner": {
+    "name": "Vincent Wang",
+    "url": "https://github.com/Seraphim0916/omnilane"
+  },
+  "metadata": {
+    "description": "One routing table, cross-vendor dispatch, foreman completion inbox.",
+    "version": "0.20.0"
+  },
+  "plugins": [
+    {
+      "name": "omnilane",
+      "source": "./",
+      "description": "Route each subtask to the model that fits, dispatch it to any vendor CLI, and have finished dispatches report back into the foreman's next prompt.",
+      "version": "0.20.0",
+      "category": "development",
+      "keywords": [
+        "routing",
+        "dispatch",
+        "multi-model",
+        "codex",
+        "orchestration"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "omnilane",
+  "version": "0.20.0",
+  "description": "One routing table, every harness: classify subtasks into lanes and auto-dispatch each lane to the best vendor CLI (Codex, Claude Code, Grok Build, Antigravity) with background jobs, depth guard, and serialized codex dispatch.",
+  "author": {
+    "name": "Seraphim0916"
+  },
+  "skills": "./skills/"
+}

package/CHANGELOG.md

@@ -6,6 +6,72 @@ semantic version tags.
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-08-30
+
+### Added
+
+- `docs/roadmap.md` plans threaded dispatch (continue a job instead of
+  restarting it) and a live mailbox (message a job while it runs), with a
+  per-vendor session capability matrix. `docs/experiments/live-inbox-probe.sh`
+  is the probe backing the mailbox claim.
+
+- Finished dispatches now report themselves to the foreman. Each completed job
+  writes a private record under `$OMNILANE_HOME/inbox/`, and the bundled Claude
+  Code `UserPromptSubmit` hook delivers matching records into the foreman's next
+  prompt, so a background dispatch no longer has to be polled. Records are
+  scoped by the dispatch `workdir` and, when available, its foreman session,
+  claimed at most once, and moved to `inbox/consumed/`. Worker-output tails are
+  framed as indented data and stripped of control characters and Unicode
+  `U+2028`/`U+2029` separators, so they cannot forge a header or issue
+  instructions. Set `OMNILANE_INBOX=0` to disable record creation.
+- `.claude-plugin/marketplace.json` makes the repository installable as a Claude
+  Code plugin, which is the install path the completion notice needs:
+  `claude plugin marketplace add <repo>` then `claude plugin install
+  omnilane@omnilane`.
+- The published package now ships `hooks/`, `skills/` and `.claude-plugin/`, so
+  an npm install carries the hook script instead of only the CLI.
+- `install.sh` reports whether the completion notice is active and, when it is
+  not, prints the exact commands that enable it; the skill symlink alone does
+  not deliver notices.
+- `doctor` answers whether the completion notice is live, reading the
+  `hooks/hooks.json` of the current checkout rather than the state recorded at
+  install time — checking out a branch without the hook silently disables the
+  notice while the plugin still reports itself as enabled.
+- Claude background dispatches can now stay resident as a live mailbox. A live
+  job accepts `jobs.sh send`, `watch`, `tail`, `close`, and `retry`, and records
+  lifecycle events in `events.jsonl`. Other vendors explicitly fall back to
+  single-shot mode with a `stderr` and `mode-notice.txt` notice; `jobs.sh wait`
+  now prints `done exit=N` when the job finishes.
+- Foreman completion records are now bound to the Claude session that launched
+  the dispatch. The `SessionStart` hook records the `session_id` against the
+  parent PID and its start time, making PID reuse safe; dispatch finds that
+  identity by walking its ancestors and stamps `foreman_session` into
+  `meta.json` and completion records. The inbox consumes a session match first
+  and falls back to `workdir` for legacy records, preventing two foremen in one
+  repository from taking each other's notices.
+
+## [0.15.0] - 2026-08-28
+
+### Added
+
+- Timed-out Codex jobs now print the absolute path to the matching
+  `rollout-*.jsonl` session file, resolved from the first progress event's
+  `thread_id`, so an interrupted conversation remains directly inspectable.
+
+### Changed
+
+- Codex runner now invokes `codex exec --json`, streaming JSONL events to
+  `out.txt.progress.log` before the run exits or times out. `out.txt` and the
+  Jobs display, which reads only `out.txt` and `stderr.log`, remain unchanged.
+
+### Fixed
+
+- Timeout diagnostics no longer blame a usage-limit retry loop without evidence.
+  They now state that a timeout does not identify its cause, provide a
+  three-step check, and clarify that an empty progress log does not prove the
+  run made no progress.
+
+
 ## [0.14.0] - 2026-08-10
 
 ### Added
@@ -594,7 +660,11 @@ work to the wrong model, and records the evidence behind the shipped defaults.
 - Initial shared routing table, cross-vendor dispatcher, runners, installer,
   and baseline lint fixes.
 
-[Unreleased]: https://github.com/Seraphim0916/omnilane/compare/v0.14.0...HEAD
+[Unreleased]: https://github.com/Seraphim0916/omnilane/compare/v0.20.0...HEAD
+
+[0.20.0]: https://github.com/Seraphim0916/omnilane/compare/v0.15.0...v0.20.0
+
+[0.15.0]: https://github.com/Seraphim0916/omnilane/compare/v0.14.0...v0.15.0
 
 [0.14.0]: https://github.com/Seraphim0916/omnilane/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/Seraphim0916/omnilane/compare/v0.12.0...v0.13.0

package/README.ja.md

@@ -364,6 +364,24 @@ configure.sh set|get|unset|list|diff LANE [SPEC]    # routing.local.yaml を非
   記録し、`jobs.sh status` が `dead` を報告。
 - **ペイロード上限** — 巨大なタスクテキストは自動で頭尾トランケート。
 
+## 📬 ライブメールボックス
+
+ライブメールボックスは、1 回で完結するディスパッチとは別の、Claude 専用の常駐バックグラウンド実行です。フォアマンが `--background` で開始し、実行中にも追加の指示を送れます。終わったらフォアマンが `jobs.sh close ID` で閉じます。放置しても常駐し続けるわけではなく、設定済みのジョブ全体タイムアウト（`--job-timeout`）に達すれば終了します。
+
+```bash
+scripts/dispatch.sh --background --vendor claude hard-judgment "タイムアウトしたテストを確認する"
+# dispatch が表示したジョブ ID を $ID として保存
+scripts/jobs.sh send "$ID" "リトライ経路も確認してください。"
+scripts/jobs.sh watch "$ID"
+scripts/jobs.sh tail "$ID" --lines 20
+scripts/jobs.sh close "$ID"
+scripts/jobs.sh retry "$ID" --background
+```
+
+`watch` は `$JOB_DIR/events.jsonl` を追跡し、`tail` は公開出力の `out.txt` を読みます。ライブメールボックスを使えるのは現時点で Claude だけです。ほかのベンダーは通常の単発ディスパッチへフォールバックしますが、無通知ではありません。stderr と `$JOB_DIR/mode-notice.txt` に通知が残り、`jobs.sh status ID` にも表示されます。
+
+アイドル中は API 呼び出しも料金も発生しませんが、ジョブ全体タイムアウトの時間は進みます。やり取りが終わったら `close` してください。終了済み、またはライブでないジョブへの `jobs.sh send` は明確なエラーで失敗します。送った後に追跡しない作業、ライブ対応していないベンダー、クリーンな状態からの再実行が必要な場合には使わず、新しいディスパッチ（または完了後の `retry`）を使ってください。
+
 ## ❓ FAQ
 
 <details>
@@ -516,6 +534,38 @@ scripts/dispatch.sh --dry-run hardest-coding "…"   # 解決済みプラン、
 
 ## 📜 リリース履歴
 
+## v0.20.0 の新機能
+
+- **フォアマン完了インボックス。** バックグラウンド dispatch の完了時に非公開の
+  完了レコードを書き込み、同梱の Claude Code プラグインが一致するレコードを
+  フォアマンの次のプロンプトへ届けます。出力末尾はプロンプト注入対策済みで、
+  制御文字と `U+2028`／`U+2029` を除去し、ワーカー出力をインデントしたデータ
+  として枠付けます。
+- **インストール可能な Claude Code プラグイン。**
+  `.claude-plugin/marketplace.json` は自己参照 source を使い、公開 npm tarball
+  には `hooks/`、`skills/`、`.claude-plugin/` も含まれます。
+- **Claude のライブメールボックス。** 常駐バックグラウンド Claude ジョブは
+  実行中にメッセージを受け取り、`events.jsonl` を記録します。操作は
+  [📬 ライブメールボックス](#-ライブメールボックス) を参照してください。
+  他ベンダーは `stderr` と `mode-notice.txt` の通知付きで明示的に単発実行へ
+  フォールバックし、`jobs.sh wait` は `done exit=N` で完了します。
+- **フォアマンのセッション識別。** `SessionStart` hook は Claude `session_id` を
+  PID と開始時刻へ結び付け、PID 再利用にも安全です。dispatch は親プロセスを
+  たどって `foreman_session` を `meta.json` と完了レコードへ記録します。
+  インボックスはセッション一致を優先し、旧レコードでは `workdir` に
+  フォールバックするため、同一リポジトリ内の複数フォアマンが互いの通知を
+  取得しません。
+
+## v0.15.0 の新機能
+
+- **Codex の進捗証跡をストリーミング保存** — `codex exec --json` が JSONL イベントを
+  `out.txt.progress.log` へ逐次書き込むため、タイムアウト時にも最後に到達した手順を残せます。
+  `out.txt` と Jobs の表示は変わりません。
+- **証拠に基づくタイムアウト診断** — タイムアウト自体では原因を特定できないことを明示し、
+  三段階の確認手順と、空の進捗ログが Codex の未進行を示す証拠ではないことを案内します。
+- **rollout 記録への直接パス** — 最初の進捗イベントの `thread_id` から対応する
+  `rollout-*.jsonl` の絶対パスをタイムアウト出力に表示し、中断された会話履歴を確認できます。
+
 ## v0.14.0 の新機能
 
 - **根拠に基づくルーティング提案**：`jobs recommend` と MCP `jobs_recommend` は公開ジョブメタデータだけを読み、ルーティングを自動変更しません。

package/README.ko.md

@@ -351,6 +351,24 @@ CLI 를 사용할 수 없음, `5` 1라운드 성공 투표자 부족, `6` 2라
   `jobs.sh status` 가 `dead` 를 보고.
 - **페이로드 상한** — 과대한 태스크 텍스트는 머리/꼬리만 남기고 자동 절단.
 
+## 📬 라이브 메일함
+
+라이브 메일함은 일회성 dispatch와 다른 Claude 전용 상주 백그라운드 실행입니다. 포어맨이 `--background`로 열고, 실행 중에도 추가 지시를 보낼 수 있으며, 끝나면 `jobs.sh close ID`로 닫을 책임이 있습니다. 방치해도 영구히 남아 있지는 않습니다. 설정된 전체 작업 시간 제한(`--job-timeout`)에 도달하면 종료됩니다.
+
+```bash
+scripts/dispatch.sh --background --vendor claude hard-judgment "시간 제한 테스트 실패를 확인해 주세요"
+# dispatch가 출력한 작업 ID를 $ID로 저장
+scripts/jobs.sh send "$ID" "재시도 경로도 확인해 주세요."
+scripts/jobs.sh watch "$ID"
+scripts/jobs.sh tail "$ID" --lines 20
+scripts/jobs.sh close "$ID"
+scripts/jobs.sh retry "$ID" --background
+```
+
+`watch`는 `$JOB_DIR/events.jsonl`을 따라가고, `tail`은 공개 `out.txt`를 읽습니다. 라이브 메일함은 현재 Claude만 지원합니다. 다른 벤더는 일반 일회성 dispatch로 내려가지만 조용히 처리되지는 않습니다. stderr와 `$JOB_DIR/mode-notice.txt`에 알림이 남고, `jobs.sh status ID`에도 표시됩니다.
+
+유휴 상태에서는 API 호출이나 비용이 발생하지 않지만 전체 작업 시간 제한은 계속 소모됩니다. 대화가 끝나면 `close`하세요. 끝났거나 라이브가 아닌 작업에 `jobs.sh send`를 실행하면 명확한 오류와 함께 실패합니다. 보낸 뒤 추적하지 않을 작업, 라이브 지원이 없는 벤더, 깨끗한 상태에서 다시 실행해야 하는 경우에는 쓰지 말고 새 dispatch 또는 완료 뒤 `retry`를 사용하세요.
+
 ## ❓ FAQ
 
 <details>
@@ -499,6 +517,36 @@ scripts/dispatch.sh --dry-run hardest-coding "…"   # 완전히 해석된 계
 
 ## 📜 릴리스 기록
 
+## v0.20.0 새 기능
+
+- **Foreman 완료 수신함.** 백그라운드 디스패치가 끝나면 비공개 완료 레코드를
+  쓰고, 함께 제공되는 Claude Code 플러그인이 일치하는 레코드를 Foreman의 다음
+  프롬프트에 전달합니다. 출력 꼬리에는 프롬프트 주입 방어가 적용되어 제어 문자와
+  `U+2028`／`U+2029`를 제거하고 작업자 출력을 들여쓴 데이터로 감쌉니다.
+- **설치 가능한 Claude Code 플러그인.** `.claude-plugin/marketplace.json`은
+  자기 참조 source를 사용하며, 배포 npm tarball에는 `hooks/`, `skills/`,
+  `.claude-plugin/`도 포함됩니다.
+- **Claude 라이브 메일함.** 상주 백그라운드 Claude 작업은 실행 중 메시지를
+  받을 수 있고 `events.jsonl`을 기록합니다. 사용법은
+  [📬 라이브 메일함](#-라이브-메일함)을 참조하세요. 다른 벤더는 `stderr`와
+  `mode-notice.txt` 알림을 남긴 채 명시적으로 단발 실행으로 폴백하며,
+  `jobs.sh wait`는 `done exit=N`으로 끝납니다.
+- **Foreman 세션 식별.** `SessionStart` hook은 Claude `session_id`를 PID와
+  시작 시각에 연결하여 PID 재사용에도 안전합니다. 디스패치는 부모 프로세스를
+  따라 `foreman_session`을 `meta.json`과 완료 레코드에 기록합니다. 수신함은
+  세션 일치를 우선하고 레거시 레코드에서만 `workdir`로 폴백하므로, 한 repository의
+  여러 Foreman이 서로의 알림을 가져가지 않습니다.
+
+## v0.15.0 새 기능
+
+- **Codex 진행 증거의 스트리밍 보존** — `codex exec --json`이 JSONL 이벤트를
+  `out.txt.progress.log`에 순차 기록하므로 시간 초과가 나도 마지막으로 도달한 단계를 남깁니다.
+  `out.txt`와 Jobs 표시는 그대로입니다.
+- **증거 기반 시간 초과 진단** — 시간 초과 자체로 원인을 특정하지 않는다고 밝히고,
+  세 단계 점검 목록과 빈 진행 로그가 Codex 미진행의 증거가 아니라는 점을 안내합니다.
+- **rollout 기록으로 가는 직접 경로** — 첫 진행 이벤트의 `thread_id`로 찾은
+  `rollout-*.jsonl`의 절대 경로를 시간 초과 출력에 표시하여, 중단된 대화 이력을 확인할 수 있습니다.
+
 ## v0.14.0 새 기능
 
 - **근거 기반 라우팅 제안**: `jobs recommend`와 MCP `jobs_recommend`는 공개 작업 메타데이터만 읽고 라우팅을 자동 변경하지 않습니다.

package/README.md

@@ -205,6 +205,10 @@ header overrides that and the choice is remembered locally.
 
 Core routing does not need Python; only this UI requires Python 3.9 or newer.
 
+### Foreman completion inbox
+
+Finished dispatches write a private completion record under `$OMNILANE_HOME/inbox/`. A Claude Code `SessionStart` hook binds each foreman's hook-provided session ID to its live process ancestry, and the bundled `UserPromptSubmit` hook atomically delivers up to ten records owned by that session on the foreman's next prompt. Older records without a session ID still use the original dispatch `workdir` scope; claimed records move to `inbox/consumed/`. Set `OMNILANE_INBOX=0` on a dispatch to disable record creation; the default is enabled.
+
 ## 📦 Install
 
 Requirements: the vendor CLIs you want to route to, logged in (`codex`,
@@ -224,6 +228,15 @@ each CLI's instruction file (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`,
 versions) so the main loop remembers to consult the table; non-interactive
 installs can pass `OMNILANE_HOOKS=all|none|claude,codex`.
 
+The foreman completion notice requires the Claude Code plugin install; the
+skill-only symlink path does not deliver completion notices. Install the plugin
+from this checkout with:
+
+```bash
+claude plugin marketplace add <path to this repo>
+claude plugin install omnilane@omnilane
+```
+
 Use `./install.sh --check` for a read-only drift report. Add `--dry-run` to an
 install or `--uninstall` to preview every checkout-owned file action.
 Rollback the installer-owned links and marked reminders with
@@ -408,6 +421,24 @@ code passes through.
 - **Payload caps** — oversized task text is truncated head+tail before it can
   blow a worker's context.
 
+## 📬 Live mailbox
+
+A live mailbox is a resident Claude background dispatch, not a one-shot dispatch. The foreman opens it with `--background`, can send another instruction while it is still running, and is responsible for closing it with `jobs.sh close ID`. Leaving it unattended does not make it permanent: the configured whole-job timeout (`--job-timeout`) still ends it.
+
+```bash
+scripts/dispatch.sh --background --vendor claude hard-judgment "Review the timeout failure"
+# save the printed job ID as $ID
+scripts/jobs.sh send "$ID" "Also inspect the retry path."
+scripts/jobs.sh watch "$ID"
+scripts/jobs.sh tail "$ID" --lines 20
+scripts/jobs.sh close "$ID"
+scripts/jobs.sh retry "$ID" --background
+```
+
+`watch` follows `$JOB_DIR/events.jsonl`; `tail` reads the public `out.txt`. Live mailbox support is Claude-only today. Any other vendor runs as a normal one-shot dispatch, with a degradation notice sent to stderr and stored in `$JOB_DIR/mode-notice.txt`; `jobs.sh status ID` prints that notice as well.
+
+An idle mailbox makes no API calls and incurs no API spend, but it keeps consuming its job-timeout window. Close it when its exchange is finished. `jobs.sh send` to a finished job or a job that is not live fails with a clear error. Do not use this for fire-and-forget work, vendors without live support, or a clean-slate rerun; start a fresh dispatch (or retry a completed job) instead.
+
 ## ❓ FAQ
 
 <details>
@@ -565,6 +596,40 @@ working notes, including per-benchmark caveats, live in
 
 ## 📜 Release history
 
+## What's new in v0.20.0
+
+- **Foreman completion inbox.** Finished background dispatches write a private
+  completion record, and the bundled Claude Code plugin delivers matching
+  records into the foreman's next prompt. The output tail is injection-hardened:
+  control characters and `U+2028`/`U+2029` are removed, and worker output is
+  framed as indented data.
+- **Installable Claude Code plugin.** `.claude-plugin/marketplace.json` uses a
+  self-referencing source, and the published npm tarball includes `hooks/`,
+  `skills/`, and `.claude-plugin/`.
+- **Claude live mailbox.** Resident background Claude jobs can receive messages
+  while they run and record `events.jsonl`. For operations, see
+  [📬 Live mailbox](#-live-mailbox); other vendors explicitly fall back to
+  single-shot mode with a `stderr` and `mode-notice.txt` notice, and
+  `jobs.sh wait` ends with `done exit=N`.
+- **Foreman session identity.** The `SessionStart` hook binds a Claude
+  `session_id` to a PID plus start time, making PID reuse safe. Dispatch walks
+  its ancestors to stamp `foreman_session` into `meta.json` and completion
+  records; the inbox prefers a session match and falls back to `workdir` for
+  legacy records, so two foremen in one repository do not take each other's
+  notices.
+
+## What's new in v0.15.0
+
+- **Streaming Codex progress evidence** — `codex exec --json` now streams JSONL
+  events into `out.txt.progress.log`, so a timeout still records its last known
+  step. `out.txt` and the Jobs display remain unchanged.
+- **Evidence-led timeout diagnostics** — timeouts now state that they do not
+  identify the cause, list a three-step check, and clarify that an empty
+  progress log does not prove Codex made no progress.
+- **Direct rollout recovery path** — timeout output now prints the absolute path
+  to the matching `rollout-*.jsonl`, found from the first progress event's
+  `thread_id`, so the interrupted conversation history can be inspected.
+
 ## What's new in v0.14.0
 
 - **Evidence-based routing recommendations** — `jobs recommend` and MCP

package/README.zh-CN.md

@@ -333,6 +333,24 @@ configure.sh set|get|unset|list|diff LANE [SPEC]    # 非交互编辑/查看 rou
   而不是永远显示 `running`。
 - **任务载荷上限** — 过大的任务文本自动头尾截断,防止撑爆工作端上下文。
 
+## 📬 实时邮箱
+
+实时邮箱是 Claude 专用的常驻后台派发，不是一次性派发。派发方以 `--background` 打开后，运行中仍可追加指令，并负责用 `jobs.sh close ID` 收尾。即使无人处理，它也不会永久存在：已配置的整个作业超时（`--job-timeout`）到期后仍会终止它。
+
+```bash
+scripts/dispatch.sh --background --vendor claude hard-judgment "检查超时测试失败的原因"
+# 将 dispatch 显示的作业 ID 保存为 $ID
+scripts/jobs.sh send "$ID" "再检查重试路径。"
+scripts/jobs.sh watch "$ID"
+scripts/jobs.sh tail "$ID" --lines 20
+scripts/jobs.sh close "$ID"
+scripts/jobs.sh retry "$ID" --background
+```
+
+`watch` 会跟随 `$JOB_DIR/events.jsonl`；`tail` 读取公开的 `out.txt`。目前只有 Claude 支持实时邮箱。其他供应商都会降级为普通的一次性派发，但不是静默发生：stderr 和 `$JOB_DIR/mode-notice.txt` 都会留下提示，`jobs.sh status ID` 也会显示该提示。
+
+空闲时不会发出 API 调用，也不会产生 API 费用，但整个作业超时的时间仍在流逝。处理结束就应执行 `close`。向已结束或不是实时邮箱的作业执行 `jobs.sh send` 会明确报错并失败。即发即忘的工作、没有实时支持的供应商，或需要从干净状态重新运行的情况都不适用；请新建一次派发，或在作业完成后使用 `retry`。
+
 ## ❓ 常见问题
 
 <details>
@@ -473,6 +491,33 @@ vendor 一律当成 `work`,而且它只能逐次明确指定,永远不是 lane
 
 ## 📜 版本历程
 
+## v0.20.0 新功能
+
+- **Foreman 完成收件箱。** 后台派发完成后会写入私有完成记录，内置 Claude
+  Code 插件会在 Foreman 的下一次提示中递交匹配记录。输出尾段已做提示注入防护：
+  移除控制字符及 `U+2028`／`U+2029`，并将工作器输出框为缩进数据。
+- **可安装的 Claude Code 插件。** `.claude-plugin/marketplace.json` 使用自指
+  来源，已发布的 npm tarball 也包含 `hooks/`、`skills/` 和
+  `.claude-plugin/`。
+- **Claude 实时邮箱。** 常驻后台 Claude 作业可在运行时接收消息，并写入
+  `events.jsonl`。操作方式请见 [📬 实时邮箱](#-实时邮箱)；其他供应商会明确
+  降级为单次模式，并留下 `stderr` 与 `mode-notice.txt` 通知；`jobs.sh wait`
+  最后会输出 `done exit=N`。
+- **Foreman 会话身份。** `SessionStart` hook 会将 Claude `session_id` 绑定到
+  PID 与启动时间，避免 PID 重用误判。派发会沿父进程向上查找，将
+  `foreman_session` 写入 `meta.json` 与完成记录；收件箱优先按会话匹配，旧记录
+  才回退至 `workdir`，避免同一 repository 的两个 Foreman 互取通知。
+
+## v0.15.0 新功能
+
+- **流式保留 Codex 进度证据**：`codex exec --json` 会将 JSONL 事件逐条写入
+  `out.txt.progress.log`，即使超时也会留下最后执行到哪一步。`out.txt` 与任务列表显示保持不变。
+- **超时诊断回归证据**：超时提示明确说明它本身不足以判定原因，提供三步检查清单，并说明空的
+  进度日志不是 Codex 从未推进的证据。
+- **直接给出 rollout 记录位置**：超时输出会根据第一条进度事件的 `thread_id`，打印
+  ${CODEX_HOME:-$HOME/.codex}/sessions 下对应 `rollout-*.jsonl` 的绝对路径，便于查看
+  被中断而未回报的完整对话历程。
+
 ## v0.14.0 新功能
 
 - **基于证据的路由建议**：`jobs recommend` 与 MCP `jobs_recommend` 只读取公开作业元数据，并且不会自动修改路由。

package/README.zh-TW.md

@@ -360,6 +360,24 @@ codex/claude/grok/gemini 自選 1-4 個評審。開了之後,同一個問題丟
   而不是永遠顯示 `running`。
 - **任務酬載上限** — 過大的任務文字自動頭尾截斷,防止撐爆工作端脈絡。
 
+## 📬 即時信箱
+
+即時信箱是 Claude 專用的常駐背景派工，不是一次性派工。派工者以 `--background` 開啟後，執行中仍能補傳指示，並負責用 `jobs.sh close ID` 收尾。即使沒人處理，也不會永久存在：設定的整體工作逾時（`--job-timeout`）一到就會結束。
+
+```bash
+scripts/dispatch.sh --background --vendor claude hard-judgment "檢查逾時測試失敗的原因"
+# 將 dispatch 顯示的工作 ID 存成 $ID
+scripts/jobs.sh send "$ID" "再確認重試路徑。"
+scripts/jobs.sh watch "$ID"
+scripts/jobs.sh tail "$ID" --lines 20
+scripts/jobs.sh close "$ID"
+scripts/jobs.sh retry "$ID" --background
+```
+
+`watch` 追隨 `$JOB_DIR/events.jsonl`；`tail` 讀取公開的 `out.txt`。目前只有 Claude 支援即時信箱。其他供應商都會降級成一般的一次性派工，但通知不會被隱藏：stderr 與 `$JOB_DIR/mode-notice.txt` 都會留下提示，`jobs.sh status ID` 也會顯示它。
+
+閒置時不會發出 API 呼叫，也不會增加 API 費用，但仍會持續消耗整體工作逾時的時間。處理完成就應執行 `close`。對已結束或不是即時信箱的工作使用 `jobs.sh send`，會明確報錯並失敗。送出後不需追蹤的工作、沒有即時支援的供應商，或必須從乾淨狀態重跑的情況都不適用；請改用新的派工，或在工作完成後使用 `retry`。
+
 ## ❓ 常見問題
 
 <details>
@@ -497,6 +515,33 @@ vendor 一律當成 `work`,而且它只能逐次明確指定,永遠不是 lane
 
 ## 📜 版本歷程
 
+## v0.20.0 新功能
+
+- **Foreman 完成收件匣。** 背景派工完成後會寫入私有完成紀錄，內建的 Claude
+  Code 外掛會在 Foreman 的下一個提示中遞交相符紀錄。輸出尾段已做提示注入防護：
+  移除控制字元與 `U+2028`／`U+2029`，並把工作者輸出框成縮排資料。
+- **可安裝的 Claude Code 外掛。** `.claude-plugin/marketplace.json` 使用自指
+  來源，已發布的 npm tarball 也會包含 `hooks/`、`skills/` 和
+  `.claude-plugin/`。
+- **Claude 即時信箱。** 常駐背景 Claude 工作可在執行時接收訊息，並寫入
+  `events.jsonl`。操作方式請見 [📬 即時信箱](#-即時信箱)；其他供應商會明確
+  退化成單次模式，留下 `stderr` 與 `mode-notice.txt` 通知；`jobs.sh wait`
+  最後會印出 `done exit=N`。
+- **Foreman 工作階段身分。** `SessionStart` hook 會把 Claude `session_id` 綁定
+  至 PID 與開始時間，避免 PID 重用誤判。派工會往上走訪父程序，將
+  `foreman_session` 寫入 `meta.json` 與完成紀錄；收件匣先比對工作階段，舊紀錄
+  才回退到 `workdir`，避免同一 repository 的兩個 Foreman 互拿通知。
+
+## v0.15.0 新功能
+
+- **串流保留 Codex 進度證據**：`codex exec --json` 會把 JSONL 事件逐筆寫入
+  `out.txt.progress.log`，即使逾時也能留下最後做到哪一步。`out.txt` 與工作清單顯示維持不變。
+- **逾時診斷回到證據**：逾時訊息明示它本身不足以判定原因，提供三步檢查清單，並說明空的
+  進度日誌不是 Codex 未曾前進的證據。
+- **直接指出 rollout 記錄位置**：逾時輸出會依第一筆進度事件的 `thread_id`，印出
+  ${CODEX_HOME:-$HOME/.codex}/sessions 下對應 `rollout-*.jsonl` 的絕對路徑，方便查看
+  被中斷而未回報的完整對話歷程。
+
 ## v0.14.0 新功能
 
 - **依證據產生路由建議**：`jobs recommend` 與 MCP `jobs_recommend` 只用已完成工作的

package/VERSION

@@ -1 +1 @@
-0.14.0
+0.20.0

package/hooks/hooks.json

@@ -0,0 +1,33 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/record-foreman-session.sh",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "cat",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/routing-instruction.md"],
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/report-completions.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/record-foreman-session.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Fail-open SessionStart hook: bind Claude's session_id to its process identity.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd -P)" || exit 0
+# shellcheck source=../scripts/lib/common.sh
+source "$ROOT/scripts/lib/common.sh" >/dev/null 2>&1 || exit 0
+
+record_foreman_session() {
+  local session_id parent_pid start_time sessions entry tmp old_umask rc=0
+  session_id="$(perl -MJSON::PP -0777 -e '
+    use strict;
+    use warnings;
+    my $payload = eval { decode_json(<STDIN>) };
+    exit 1 unless ref($payload) eq "HASH";
+    my $id = $payload->{session_id};
+    exit 1 if ref($id) || !defined($id) ||
+      $id !~ /\A[A-Za-z0-9._:-]{1,256}\z/;
+    print $id;
+  ' 2>/dev/null)" || return 0
+
+  parent_pid="$PPID"
+  [[ "$parent_pid" =~ ^[1-9][0-9]{0,9}$ ]] || return 0
+  start_time="$(process_start_time "$parent_pid")" || return 0
+  sessions="$OMNILANE_HOME/sessions"
+  prepare_private_store "$sessions" "session identity store" || return 0
+  entry="$sessions/$parent_pid.json"
+  tmp="$sessions/.$parent_pid.tmp.$$-$RANDOM"
+
+  old_umask="$(umask)"
+  umask 077
+  PID_VALUE="$parent_pid" START_VALUE="$start_time" SESSION_VALUE="$session_id" \
+    perl -MJSON::PP -e '
+      use strict;
+      use warnings;
+      my $entry = {
+        pid => 0 + $ENV{PID_VALUE},
+        start_time => $ENV{START_VALUE},
+        session_id => $ENV{SESSION_VALUE},
+      };
+      print JSON::PP->new->canonical->encode($entry), "\n";
+    ' > "$tmp" || rc=$?
+  if [[ "$rc" -eq 0 ]]; then
+    chmod 600 "$tmp" || rc=$?
+  fi
+  if [[ "$rc" -eq 0 ]]; then
+    mv "$tmp" "$entry" || rc=$?
+  fi
+  umask "$old_umask"
+  if [[ "$rc" -ne 0 ]]; then
+    rm "$tmp" 2>/dev/null || true
+  fi
+  return 0
+}
+
+record_foreman_session || true
+exit 0