omnilane 0.15.0 → 0.21.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.21.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.21.0",
+      "category": "development",
+      "keywords": [
+        "routing",
+        "dispatch",
+        "multi-model",
+        "codex",
+        "orchestration"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "omnilane",
+  "version": "0.21.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,59 @@ semantic version tags.
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-08-30
+
+### Added
+
+- Explicit session-mode selection for background dispatches: `--live` requires a resident session, while `--single-shot` forces a one-shot job. `--live` fails fast for a vendor without live support and names the live-capable vendors; the chosen `session_mode` is recorded in `meta.json`.
+- Gemini joins Claude in the live mailbox through the `agy` stream protocol, with the shared protocol implementation in `scripts/lib/live-protocol.sh`.
+- `--idle-timeout N` automatically closes an untended live session, records `closed by idle cap after Ns` as its close reason, and writes `idle_timeout` to `meta.json`.
+- `tests/test_live_mailbox.sh` is wired into `tests/run.sh`, expanding the suite to 94 checks.
+
+## [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
@@ -616,7 +669,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.15.0...HEAD
+[Unreleased]: https://github.com/Seraphim0916/omnilane/compare/v0.21.0...HEAD
+
+[0.21.0]: https://github.com/Seraphim0916/omnilane/compare/v0.20.0...v0.21.0
+
+[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
 

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 と Gemini が利用できる常駐バックグラウンド実行です。フォアマンが `--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 と Gemini に対応し、ほかのベンダーは通常の単発ディスパッチとして実行され、stderr と `$JOB_DIR/mode-notice.txt` に通知が残ります。`--live` は常駐セッションを必須にし、解決されたベンダーが非対応なら即時失敗します。`--single-shot` は Claude や Gemini でも単発実行を強制します。`--idle-timeout SECONDS` はアイドル上限を設定し、既定値は 900 秒、`0` で無効になります。
+
+アイドル中は API 呼び出しも料金も発生しません。既定では、新しい受信メッセージまたは結果イベントが 900 秒間なければ worker が自動で終了し、ジョブ全体タイムアウトは外側の上限として残ります。やり取りが終わったら早めに `close` できます。終了済み、またはライブでないジョブへの `jobs.sh send` は明確なエラーで失敗します。送った後に追跡しない作業、ライブ対応していないベンダー、クリーンな状態からの再実行が必要な場合には使わず、新しいディスパッチ（または完了後の `retry`）を使ってください。
+
 ## ❓ FAQ
 
 <details>
@@ -516,6 +534,34 @@ scripts/dispatch.sh --dry-run hardest-coding "…"   # 解決済みプラン、
 
 ## 📜 リリース履歴
 
+## v0.21.0 の新機能
+
+- **セッションモードを明示的に選択。** `dispatch --live` で常駐セッションを必須にするか、`--single-shot` で単発ジョブを強制できます。ライブセッション非対応ベンダーでは `--live` が即時に失敗し、対応ベンダーを表示します。
+- **Gemini がライブメールボックスに参加。** Gemini は `agy` ストリームプロトコルを介し、Claude と並んで常駐ライブジョブを実行できます。
+- **ライブジョブのアイドル上限。** `--idle-timeout N` は放置されたライブセッションを自動で閉じ、終了理由とタイムアウトを `meta.json` に記録します。
+
+## 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 イベントを

package/README.ko.md

@@ -351,6 +351,24 @@ CLI 를 사용할 수 없음, `5` 1라운드 성공 투표자 부족, `6` 2라
   `jobs.sh status` 가 `dead` 를 보고.
 - **페이로드 상한** — 과대한 태스크 텍스트는 머리/꼬리만 남기고 자동 절단.
 
+## 📬 라이브 메일함
+
+라이브 메일함은 일회성 dispatch와 다른 Claude 및 Gemini용 상주 백그라운드 실행입니다. 포어맨이 `--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와 Gemini를 지원하며, 다른 벤더는 일반 일회성 dispatch로 실행되고 stderr와 `$JOB_DIR/mode-notice.txt`에 알림이 남습니다. `--live`는 상주 세션을 필수로 하며 결정된 벤더가 지원하지 않으면 즉시 실패합니다. `--single-shot`은 Claude나 Gemini에서도 일회성 실행을 강제합니다. `--idle-timeout SECONDS`는 유휴 상한을 설정하며 기본값은 900초이고 `0`이면 비활성화됩니다.
+
+유휴 상태에서는 API 호출이나 비용이 발생하지 않습니다. 기본적으로 새 수신 메시지나 결과 이벤트가 900초 동안 없으면 worker가 자동으로 종료되며, 전체 작업 시간 제한은 바깥쪽 상한으로 유지됩니다. 대화가 끝나면 더 일찍 `close`할 수 있습니다. 끝났거나 라이브가 아닌 작업에 `jobs.sh send`를 실행하면 명확한 오류와 함께 실패합니다. 보낸 뒤 추적하지 않을 작업, 라이브 지원이 없는 벤더, 깨끗한 상태에서 다시 실행해야 하는 경우에는 쓰지 말고 새 dispatch 또는 완료 뒤 `retry`를 사용하세요.
+
 ## ❓ FAQ
 
 <details>
@@ -499,6 +517,32 @@ scripts/dispatch.sh --dry-run hardest-coding "…"   # 완전히 해석된 계
 
 ## 📜 릴리스 기록
 
+## v0.21.0 새 기능
+
+- **세션 모드를 명시적으로 선택.** `dispatch --live`로 상주 세션을 요구하거나 `--single-shot`으로 단발 작업을 강제할 수 있습니다. 라이브 세션을 지원하지 않는 벤더에서는 `--live`가 즉시 실패하고 지원 벤더를 표시합니다.
+- **Gemini가 라이브 메일함에 합류.** Gemini는 `agy` 스트림 프로토콜을 통해 Claude와 함께 상주 라이브 작업을 실행할 수 있습니다.
+- **라이브 작업의 유휴 제한.** `--idle-timeout N`은 방치된 라이브 세션을 자동으로 닫고 종료 사유와 제한 시간을 `meta.json`에 기록합니다.
+
+## 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 이벤트를

package/README.md

@@ -207,7 +207,7 @@ 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/`. The bundled Claude Code `UserPromptSubmit` hook atomically delivers up to ten matching records on the foreman's next prompt, scoped by the dispatch `workdir`; claimed records move to `inbox/consumed/`. Set `OMNILANE_INBOX=0` on dispatch to disable record creation. The default is enabled.
+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
 
@@ -228,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
@@ -412,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 or Gemini 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 idle cap and configured whole-job timeout (`--job-timeout`) can still end 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 covers Claude and Gemini; other vendors run as normal one-shot dispatches, with a notice sent to stderr and stored in `$JOB_DIR/mode-notice.txt`. `--live` requires a resident session and fails fast when the resolved vendor is not capable. `--single-shot` forces one-shot execution even for Claude or Gemini. `--idle-timeout SECONDS` sets the inactivity cap (default 900; `0` disables it).
+
+An idle mailbox makes no API calls and incurs no API spend. By default it closes after 900 seconds without a new inbox message or result event, while the whole-job timeout remains the outer cap. Close it sooner 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>
@@ -569,6 +596,34 @@ working notes, including per-benchmark caveats, live in
 
 ## 📜 Release history
 
+## What's new in v0.21.0
+
+- **Explicit session mode.** Use `dispatch --live` to require a resident session or `--single-shot` to force a one-shot job. `--live` fails immediately for incompatible vendors and lists the live-capable choices.
+- **Gemini joins the live mailbox.** Gemini can now run a resident live job through the `agy` stream protocol alongside Claude.
+- **Idle cap for live jobs.** `--idle-timeout N` automatically closes an untended live session and preserves the close reason and timeout in `meta.json`.
+
+## 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

package/README.zh-CN.md

@@ -333,6 +333,24 @@ configure.sh set|get|unset|list|diff LANE [SPEC]    # 非交互编辑/查看 rou
   而不是永远显示 `running`。
 - **任务载荷上限** — 过大的任务文本自动头尾截断,防止撑爆工作端上下文。
 
+## 📬 实时邮箱
+
+实时邮箱是 Claude 和 Gemini 可用的常驻后台派发，不是一次性派发。派发方以 `--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 和 Gemini 支持实时邮箱；其他供应商会执行普通的一次性派发，并在 stderr 和 `$JOB_DIR/mode-notice.txt` 留下提示。`--live` 明确要求常驻会话，解析出的供应商不支持时立即失败。`--single-shot` 即使遇到 Claude 或 Gemini 也强制一次性派发。`--idle-timeout SECONDS` 设置空闲上限，默认 900 秒，设为 `0` 可禁用。
+
+空闲时不会发出 API 调用，也不会产生 API 费用。默认若 900 秒内没有新邮箱消息或新结果事件，worker 会自动收尾；整个作业超时仍是外层上限。处理结束可提前执行 `close`。向已结束或不是实时邮箱的作业执行 `jobs.sh send` 会明确报错并失败。即发即忘的工作、没有实时支持的供应商，或需要从干净状态重新运行的情况都不适用；请新建一次派发，或在作业完成后使用 `retry`。
+
 ## ❓ 常见问题
 
 <details>
@@ -473,6 +491,29 @@ vendor 一律当成 `work`,而且它只能逐次明确指定,永远不是 lane
 
 ## 📜 版本历程
 
+## v0.21.0 新功能
+
+- **显式选择会话模式。** 可使用 `dispatch --live` 要求常驻会话，或用 `--single-shot` 强制单次派发；对不支持实时会话的供应商，`--live` 会立即失败并列出可用供应商。
+- **Gemini 加入实时邮箱。** Gemini 通过 `agy` 流式协议加入常驻实时任务，与 Claude 并列支持。
+- **实时任务的空闲上限。** `--idle-timeout N` 会自动关闭无人处理的实时会话，并在关闭原因与 `meta.json` 中保留超时信息。
+
+## 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 事件逐条写入

package/README.zh-TW.md

@@ -360,6 +360,24 @@ codex/claude/grok/gemini 自選 1-4 個評審。開了之後,同一個問題丟
   而不是永遠顯示 `running`。
 - **任務酬載上限** — 過大的任務文字自動頭尾截斷,防止撐爆工作端脈絡。
 
+## 📬 即時信箱
+
+即時信箱是 Claude 與 Gemini 可用的常駐背景派工，不是一次性派工。派工者以 `--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 與 Gemini 支援即時信箱；其他供應商會執行一般的一次性派工，stderr 與 `$JOB_DIR/mode-notice.txt` 都會留下提示。`--live` 會明確要求常駐工作階段，解析出的供應商不支援時立即失敗。`--single-shot` 即使遇到 Claude 或 Gemini 也會強制一次性派工。`--idle-timeout SECONDS` 設定閒置上限，預設 900 秒，設為 `0` 則停用。
+
+閒置時不會發出 API 呼叫，也不會增加 API 費用。預設若 900 秒內沒有新信箱訊息或新結果事件，工作程序會自動收尾；整體工作逾時仍是外層上限。處理完成可提早執行 `close`。對已結束或不是即時信箱的工作使用 `jobs.sh send`，會明確報錯並失敗。送出後不需追蹤的工作、沒有即時支援的供應商，或必須從乾淨狀態重跑的情況都不適用；請使用新的派工，或在工作完成後使用 `retry`。
+
 ## ❓ 常見問題
 
 <details>
@@ -497,6 +515,29 @@ vendor 一律當成 `work`,而且它只能逐次明確指定,永遠不是 lane
 
 ## 📜 版本歷程
 
+## v0.21.0 新功能
+
+- **明確選擇工作階段模式。** 可用 `dispatch --live` 要求常駐工作階段，或以 `--single-shot` 強制單次派工；對不支援即時工作階段的供應商，`--live` 會立即失敗並列出可用供應商。
+- **Gemini 加入即時信箱。** Gemini 透過 `agy` 串流協定加入常駐即時工作，與 Claude 並列支援。
+- **即時工作的閒置上限。** `--idle-timeout N` 會自動關閉無人處理的即時工作階段，並在關閉原因與 `meta.json` 留下逾時資訊。
+
+## 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 事件逐筆寫入

package/VERSION

@@ -1 +1 @@
-0.15.0
+0.21.0

package/bin/omnilane

@@ -30,7 +30,8 @@ case "$cmd" in
     ;;
   list)      exec bash "$REPO/scripts/dispatch.sh" --list ;;
   route|dispatch) exec bash "$REPO/scripts/dispatch.sh" "$@" ;;
-  jobs)      exec bash "$REPO/scripts/jobs.sh" "$@" ;;
+    jobs)      exec bash "$REPO/scripts/jobs.sh" "$@" ;;
+    goal)      exec bash "$REPO/scripts/lib/goal-loop.sh" "$@" ;;
   mcp)
     command -v node >/dev/null 2>&1 || {
       echo "omnilane: mcp requires Node.js on PATH" >&2
@@ -75,6 +76,9 @@ omnilane — one routing table, every harness
   omnilane list                         effective routing table
   omnilane route [--vendor V] [flags] LANE "TASK"
                                         dispatch or consult a model
+  omnilane goal "TEXT" [--budget-jobs N] [--budget-seconds S] [--workdir DIR]
+                                        run bounded sequential goal loop
+  omnilane goal status GOAL_ID           inspect goal budget and last action
   omnilane jobs  [--json] COMMAND [ARGS]  list, status, result, stats, recommend, wait, or audit
   omnilane mcp                          start the MCP stdio server
   omnilane completion bash|zsh|fish      print a shell completion script

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