omnilane 0.41.1 → 0.42.2

package/docs/completion-wakeup.md

@@ -0,0 +1,126 @@
+# 完成續驗橋接（Codex heartbeat）
+
+協定版本：2026-09-07。
+
+`scripts/completion-wakeup.py` 是獨立命令列工具：
+追蹤明確登錄的 CLI 工作、發出一次有效領取權、記錄主控送達與驗收。
+它不呼叫模型、不建立排程、不讀工作輸出，也不保證 app 已喚醒。
+真正喚醒由主控透過 `mcp__codex_app__automation_update` 註冊的 heartbeat 負責。
+這是排程輪詢，不是即時推播；本機離線、排程延遲與 app 狀態都會影響送達。
+
+## 登錄與身分
+
+每個 host/thread 只有一份 registry，同 run 可追加工作並重用 automation ID。
+主控傳入的 thread ID 必須來自 app 的實際任務，不能把 omnilane 自身 thread 名稱代入。
+只有一個 active run；不同 run 會拒絕。既有 run 已 closed 時，新 run 的 prepare 會先把完整舊紀錄
+存入私有 history，再建立 pending 的新紀錄；舊 automation ID、租約、事件與 adoption 不沿用。
+舊 run 的 poll／ack 會拒絕，不會領取新 run 的事件。原本 active／pending 的 run 從不默默被取代。
+同一 host/thread 歷史曾使用的 run_id 永不重用，以免舊 heartbeat 命令在後續同名輪次復活。
+歷史的 accepted receipt 留在原紀錄，不沿用為新 run 的驗收證據；請為每輪指定全新的 run_id。
+這是工作流程契約，不是防止同使用者程序偽造參數的安全隔離。
+
+```bash
+PY=python3
+SCRIPT=/absolute/repo/scripts/completion-wakeup.py
+BIND=(--thread-id CONTROLLER_THREAD --host-id local --run-id RUN_ID)
+$PY "$SCRIPT" prepare "${BIND[@]}" \
+  --workdir /absolute/repo --job JOB_ID --ttl-seconds 3600
+```
+
+工作必須已存在於 `~/.omnilane/jobs/JOB_ID`，且 `meta.json` 身分與工作目錄相符。
+若 metadata 的 foreman_session 非空，表示另有原主控身分，單靠 allowlist 不足以收錄。
+該欄位來自 Claude 程序綁定，並非 Codex thread ID；程式不硬比兩者。
+必須取得操作者明示採用後，把確認整理為 scoped adoption receipt，prepare 加 `--adoption-evidence`。
+未提供會回 `adoption_required:JOB_ID:IDENTITY_SHA256`，只透露工作指紋，不輸出原 session 值。
+空 foreman_session 仍可由主控的明確 allowlist 直接登錄。
+
+```json
+{
+  "source": "operator_adoption",
+  "operator_confirmed": true,
+  "controller_thread_id": "CONTROLLER_THREAD",
+  "controller_host_id": "local",
+  "run_id": "RUN_ID",
+  "job_identity_sha256": {"JOB_ID": "IDENTITY_SHA256"}
+}
+```
+
+此 receipt 必須反映已取得的明示確認，不是讓工作者自己填 true 自我授權。
+程式驗其 run/thread/host/job/fingerprint 並保存 receipt 雜湊；這是可稽核聲明，不是 OS 身分認證。
+新 run 不沿用舊 run 的 adoption；metadata 身分改動後舊 adoption 也失效。
+可用 `--home /absolute/private/path` 指定測試儲存；所有命令都要使用同一 home/binding。
+prepare 回傳工具名稱、tool_args（heartbeat/create 或 update、prompt、targetThreadId、status），
+以及 schedule_request。主控將工具接受的排程格式補入 rrule，保留既有通知偏好後呼叫工具。
+沒有直接寫 automation 設定檔，也沒有把 pending 當 active。
+
+工具成功後，由主控將實際結果整理成最小 JSON receipt（不要包含憑證或私人訊息）：
+
+```json
+{
+  "source": "automation_update",
+  "automation_id": "AUTOMATION_ID",
+  "controller_thread_id": "CONTROLLER_THREAD",
+  "controller_host_id": "local",
+  "status": "ACTIVE",
+  "effective_interval_seconds": 60
+}
+```
+
+```bash
+$PY "$SCRIPT" record-registration "${BIND[@]}" \
+  --automation-id AUTOMATION_ID --evidence /absolute/registration-receipt.json
+```
+
+支持綁入已存在的 automation。receipt 是主控對工具結果的具名聲明，腳本驗格式／綁定／雜湊，
+不自行查 app；輸出明示 caller-attested，不宣稱獨立確認排程。註冊不等於 delivered。
+
+## 排程回合接續驗收
+
+```bash
+$PY "$SCRIPT" poll "${BIND[@]}"
+```
+
+僅 registered、未過期的工作會得到 events。pending／closed 不領取，expired 要求停用。
+每事件含 event_key、job_id、exit_code、claim_token、lease_until。
+空 events 不表示已完成：可能仍執行中或已有領取租約；以 needs_disable 與 errors 判斷。
+poll 預設租約 900 秒，可用 `--lease-seconds` 調整至最多一天；有效租約期間第二次 poll 不重複領取。
+租約過期可以重播且換 token，舊 token 失效。工作內容從未作為可執行通知提示。
+
+```bash
+$PY "$SCRIPT" ack-delivered "${BIND[@]}" --event-key EVENT_KEY --claim-token CLAIM_TOKEN
+# 主控現在讀相關產物、執行原任務驗證，再留下精簡證據檔。
+$PY "$SCRIPT" ack-accepted "${BIND[@]}" --event-key EVENT_KEY --claim-token CLAIM_TOKEN \
+  --result PASS --evidence /absolute/verification-evidence.md
+```
+
+result 支援 PASS／FAIL／PARTIAL／BLOCKED；非零工作退出碼也可送達並驗收為 FAIL。
+accepted 表示主控已作驗收判定，**不是固定等同 PASS**。沒有 delivered 就拒絕 accepted。
+同一租約內相同 acknowledgement 可重試；驗收結果或證據衝突被拒絕。
+binding 或終態退出碼在 poll 後改動，ack 也會拒絕。
+
+## 停用
+
+所有登錄工作均已作驗收判定時，poll 回 needs_disable=true。
+主控先以 automation_update 停用現有 heartbeat，工具確認後寫同樣綁定、status=PAUSED 的 receipt：
+
+```bash
+$PY "$SCRIPT" closed "${BIND[@]}" --automation-id AUTOMATION_ID \
+  --evidence /absolute/paused-receipt.json
+```
+
+未驗收完的使用者停止用 `--close-reason stopped`；真正到期用 `--close-reason expired`。
+預設 completed 會檢查所有工作已判定。closed 命令本身不會停用 app 排程。
+使用者先前的停止／重開機要求與新一輪授權仍由主控處理，不自動延長期限。
+
+## 資料與限制
+
+- 僅讀 CLI 的 `meta.json` 以及 `exit`；不讀 inbox tail、out.txt、events、task、native.json、Codex 私人對話。
+- 凍結 metadata 的 lane/vendor/model/mode/workdir/foreman_session/started；忽略其他可變欄位，不因 finished 更新誤拒。
+- native 工作明確拒絕，使用原生完成通道；後續可接獨立公共終態 receipt，不應掃描 private native state。
+- 儲存於 `~/.omnilane/wakeups`，目錄 0700、檔案 0600，拒絕 symlink、非檔案、不同擁有者及超大紀錄。
+- 核心鎖使用 flock，程序結束自動釋放；registry 以同目錄暫存檔及原子替換發布。
+- 至少一次交付與冪等驗收，不宣稱 exactly-once；租約期間不得啟動第二份驗收。
+- 一個 controller registry 最多 100 個工作；metadata 綁定錯誤會出 errors，不默默接受替代工作。
+- 待真實排程回合在同主控任務送達、產物驗收、停止確認後，才可聲稱端到端 PASS。
+
+驗證命令（從 repo 根目錄執行）：`python3 -m unittest discover -s tests -p test_completion_wakeup.py`。

package/docs/native-executor.md

@@ -0,0 +1,264 @@
+# Native executor protocol (v1)
+
+`native` means a **caller-owned agent tool**, not a shell executable. Omnilane
+resolves a lane, checks explicitly supplied capabilities, and emits a pending
+handoff. The host executes the declared new/reuse strategy and ingests its actual result separately.
+Creating a handoff is not task success. Native delegation still counts as
+delegation when commander and worker use the same exact model.
+
+## Selection and terminal compatibility
+
+```sh
+# Standalone terminal: no native capability context, legacy CLI selection.
+omnilane route --dry-run hardest-coding "Review the change"
+omnilane route --executor cli --dry-run hardest-coding "Review the change"
+
+# Host-generated capability file: native when ALL requirements match.
+omnilane route --executor auto --native-context /absolute/capability.json \
+  --workdir /absolute/repo --dry-run hardest-coding "Review the change"
+
+# Fail closed instead of falling back. JSON on stdout; no provider is called.
+omnilane route --executor native --native-context /absolute/capability.json \
+  --workdir /absolute/repo hardest-coding "Review the change"
+```
+
+Native-aware selection fixes the first configured lane candidate (or the
+explicit `--vendor` row) **before** checking native or CLI availability.
+`--model` and `--effort` override that row without renaming either value. No
+model aliases/family inference or vendor substitution are performed. A native
+rejection in `auto` may use only that same resolved target's CLI; if it is
+missing, exit 4 rather than walk another vendor's fallback chain. Without a
+context, `auto` and forced `cli` preserve the historical available-CLI chain.
+`--executor cli` ignores the native context. CLI plans and metadata include
+`executor=cli` and a reason; native plans are JSON.
+
+`--executor native` returns exit 2 for missing/incompatible capability context.
+Malformed contexts are errors even in `auto`, not invitations to call a CLI.
+Native protocol support requires Python 3.9+ on the local host; the unchanged
+terminal path does not acquire that dependency. `--list` / `--explain` retain
+their legacy CLI-availability meaning and do not advertise native readiness.
+
+## Capability context
+
+The caller constructs this object from the **currently exposed tool contract**
+and its known runtime, not credentials, installed binaries, environment sniffing,
+or model family guesses. These example model/harness values are slots, not a
+catalog. Paths must be existing absolute directories (canonicalized for exact
+comparison; a parent directory does not grant child workdirs).
+
+```json
+{
+  "schema_version": 1,
+  "harness": "HARNESS_FROM_RUNTIME",
+  "vendor": "codex",
+  "current_model": "MODEL_FROM_RUNTIME",
+  "requirements": {
+    "tools": [],
+    "isolation": "shared-inherited",
+    "lifecycle": "single-shot"
+  },
+  "capabilities": [{
+    "model": "EXACT_SUPPORTED_MODEL",
+    "efforts": ["EXACT_SUPPORTED_EFFORT"],
+    "modes": ["advise"],
+    "workdirs": ["/absolute/repo"],
+    "tools": [],
+    "isolations": ["shared-inherited"],
+    "lifecycles": ["single-shot"]
+  }]
+}
+```
+
+Every field shown except `current_model` is required. Capability rows describe
+joint constraints; permission from separate rows is never combined. All arrays
+except `tools` must be nonempty. `current_model` is only needed when the routed
+model is absent or `-`; when the route explicitly selects an exact supported
+model, the caller may omit an unknown current model. The effort string is
+matched exactly; an absent effort or `-` is unknown, so native rejects it until
+the caller supplies a known explicit `--effort`. Model names are never
+hardcoded in the engine.
+
+Codex `collaboration.spawn_agent` exposes no sandbox, tool allowlist, or
+workdir restriction parameter and inherits the parent's tool/filesystem access.
+Its honest native capability uses `shared-inherited` in both the request and the
+same matching capability row. `tools: []` means no tool restriction is
+requested or advertised. `advise` and `work` remain task intent; the matched
+workdir is task context, not an OS boundary. Requests for hard `read-only`,
+`workspace-write`, or any other unsupported isolation never become shared
+native jobs: `auto` stays on the same resolved model through CLI, while forced
+native fails closed.
+
+Native supports only a caller-supervised single task. `--background`, explicit
+`--live` / `--single-shot`, `--thread`, `sysops`, explicit/environment whole-job
+or idle watchdogs, vote/multi-round and `exec` arbitration paths stay CLI or
+reject forced native. The handoff's `timeout` is a caller-enforced deadline,
+not a shell watchdog. Native has no durable worker, FIFO, implicit follow-up,
+CLI lock, scheduling, or inherited named session. Supplying a context does not
+change `routing.yaml`, `routing.local.yaml`, or host configuration.
+
+## Handoff, completion and cancellation
+
+Native route stdout is one JSON object: `schema_version`, `executor`,
+`executor_reason`, `vendor`, `model`, `effort`, `harness`, `lane`, `task`,
+`mode`, `workdir`, `requirements`, `timeout`, `worker_contract`, `job_id`,
+`task_id`, `agent_id`, `state`, `provider_invoked`, `job_state_created`.
+Normal routing returns `state=pending`, equal task/job IDs and null agent ID.
+Dry run returns `state=planned`, null IDs and creates neither job store nor job.
+Dry run does not read task stdin. It never spawns or calls a provider.
+
+`worker_contract` records `no_nested_dispatch`, the matched
+`shared-inherited` isolation, that mode is task intent, and that the caller owns
+deadline enforcement. It does not claim tool or filesystem restriction.
+
+The host invokes its real agent tool with the resolved model and effort, then
+passes the workdir, mode, task, and deadline as task intent rather than claimed
+tool or filesystem enforcement. With an explicit model override, Codex must use
+`fork_turns: "none"` (or a bounded positive history count), never
+`fork_turns: "all"`:
+
+```javascript
+collaboration.spawn_agent({
+  task_name: "native_shared_smoke",
+  fork_turns: "none",
+  model: handoff.model,
+  reasoning_effort: handoff.effort,
+  message: "Shared/inherited access. Do not delegate. Intended workdir: " +
+           handoff.workdir + ". Deadline: " + handoff.timeout +
+           " seconds. Task: " + handoff.task
+})
+```
+
+The call does not establish a filesystem boundary. The parent keeps the actual
+agent ID, waits for the real outcome, independently verifies the public result,
+and only then writes **public, sanitized** completion input:
+
+```json
+{
+  "schema_version": 1,
+  "job_id": "JOB_ID_FROM_HANDOFF",
+  "agent_id": "ACTUAL_AGENT_ID",
+  "runtime": {
+    "vendor": "codex",
+    "model": "ACTUAL_EXACT_MODEL",
+    "effort": "ACTUAL_EFFORT",
+    "harness": "ACTUAL_HARNESS",
+    "backend": "ACTUAL_AGENT_TOOL_BACKEND"
+  },
+  "outcome": "success",
+  "result": "Public result summary, not raw logs",
+  "evidence": ["Public command/result or artifact reference"]
+}
+```
+
+```sh
+omnilane jobs --json status JOB_ID
+omnilane jobs --json complete-native JOB_ID /absolute/completion.json
+omnilane jobs --json result JOB_ID
+omnilane jobs --json list --status pending
+omnilane jobs --json cancel JOB_ID
+```
+
+The reusable `jobs complete-native` interface checks the actual runtime's
+vendor/model/effort/harness against the resolved request, requires agent ID,
+backend, outcome (`success` or `failure`), result and nonempty evidence, and
+rejects malformed/extra fields, symlinks, oversized inputs and duplicate JSON
+keys. Missing/invalid/duplicate completions leave state unchanged. Completion
+and cancellation share a per-job lock and an atomic state replacement.
+
+`pending -> completed` exposes `state=done`, `native_state=completed`, exit 0
+for success or 1 for failure. Ingestion itself returns 0 for a valid failure
+record; `jobs result` returns the recorded exit code. `pending -> cancelled`
+records exit 143 and permanently rejects later completion. Neither transition
+signals a PID. If an agent was already spawned, **the caller must cancel it
+using that agent tool separately**; cancelling the record cannot stop it.
+
+Data lives under `$OMNILANE_HOME/jobs/ID/`: `task.txt`, `meta.json`,
+`native.json` and `native.lock`. Creation writes all four 0600 files inside a
+0700 hidden same-filesystem staging directory, then atomically renames it to the
+final ID under a private publication lock. Listing only accepts final ID names,
+so it never observes construction or an interrupted hidden stage. Normal
+failures clean only the creator's own stage; collisions leave the existing
+final directory untouched. The context itself and raw provider logs are not
+stored. Completion is a
+caller attestation, not independent backend authentication or proof that the
+model honored the task; the parent still verifies evidence. Do not submit
+tokens, cookies, credential/session/cache values or raw logs in any public field.
+
+Only `list`, `status`, `result`, `cancel`, `complete-native` integrate native
+jobs. Native `send`, `watch`, `close`, `wait`, `retry`, `tail`, and `rm` reject;
+inspect status while the host owns execution. Native records do not have CLI
+exit markers and are not included in completed-CLI stats/recommend/prune.
+Do not use CLI-only UI/audit/goal-loop summaries as native acceptance evidence.
+
+## Explicit existing-agent reuse（明示重用）
+
+協定版本：2026-09-07。
+Default `agent_strategy` is `new`; exhausted creation capacity never silently becomes reuse.
+Explicit `reuse` keeps the existing context and uses caller-owned `collaboration.followup_task`,
+not `collaboration.spawn_agent`. This remains one supervised task, not an automatic loop.
+
+Reuse extends the v1 capability object (values must be caller-observed, not inferred):
+
+```json
+{
+  "schema_version": 1,
+  "harness": "codex",
+  "vendor": "codex",
+  "current_model": "gpt-6-astra",
+  "current_effort": "medium",
+  "agent_strategy": "reuse",
+  "preserve_existing_context": true,
+  "new_agent_capacity": "exhausted",
+  "existing_agent": {
+    "agent_id": "/root/EXISTING_AGENT",
+    "vendor": "codex",
+    "model": "gpt-6-astra",
+    "effort": "medium",
+    "harness": "codex",
+    "state": "idle",
+    "observed_by": "caller",
+    "evidence": ["Caller-observed creation configuration and current idle state"]
+  },
+  "requirements": {"tools": [], "isolation": "shared-inherited", "lifecycle": "single-shot"},
+  "capabilities": [{
+    "model": "gpt-6-astra", "efforts": ["medium"], "modes": ["advise"],
+    "workdirs": ["/absolute/repo"], "tools": [],
+    "isolations": ["shared-inherited"], "lifecycles": ["single-shot"],
+    "agent_strategy": "reuse", "existing_agent_id": "/root/EXISTING_AGENT"
+  }]
+}
+```
+
+Reuse requires routed vendor/model/effort/harness and existing runtime to match exactly.
+`current_model` and `current_effort` must match too; capability rows/agent IDs are never combined.
+The idle declaration is caller evidence, not provider authentication or a reservation. Recheck idle
+immediately before followup; the tool may still fail. Model self-description is not creation evidence.
+Retained context may contain old instructions, so supply the new task boundary and existing AA child contract.
+
+Missing evidence is malformed context. Busy/unknown state, missing preservation, identity/strategy mismatch,
+hard isolation or unsupported lifecycle yield no reuse handoff. Forced native rejects; auto may choose
+only the original exact target's CLI for a well-formed but incompatible context.
+`new_agent_capacity` accepts available/exhausted/unknown; exhausted rejects new native selection.
+Unknown retains the old pending-handoff behavior, never asserts that an agent successfully started.
+
+Plans/status/results preserve `agent_strategy`, `existing_agent_id`, `preserve_existing_context`.
+Pending reuse `agent_id` identifies the existing target, not proof followup ran.
+`worker_contract.backend` is `collaboration.followup_task`; `reuse_observation` records the caller's evidence.
+
+```javascript
+collaboration.followup_task({
+  target: handoff.existing_agent_id,
+  message: "Keep existing context. Shared/inherited access; do not delegate. " +
+           "Apply the handoff's AA child context and task boundary. " + handoff.task
+})
+```
+
+After real response and independent verification, ingest the normal completion object with
+`agent_strategy: "reuse"`, exact existing `agent_id`, and runtime backend `collaboration.followup_task`.
+Different strategy/ID/backend is rejected without completing the job; duplicate completion is rejected.
+New completions may omit strategy or supply `new`, but must not claim the followup backend.
+Both strategies retain AA preflight, approved original registry bytes, child context, atomic publication,
+and per-job completion/cancellation locking. Reuse adds no automatic creation, permission upgrade or service.
+
+Offline coverage: `TMPDIR="$PWD/.native-test-artifacts/tmp" python3
+tests/test_native_executor.py`. Those fixtures are not a live native smoke.

package/docs/release-notes-0.42.2.md

@@ -0,0 +1,31 @@
+# Omnilane 0.42.2
+
+This patch repairs the Grok single-shot reasoning-effort transport. It does not raise caller scores or remove the exact-AA downward-delegation gate.
+
+## Changes
+
+- Explicit Grok effort is forwarded as `--reasoning-effort VALUE`. The supported selector spellings are `low`, `medium`, `high`, and `xhigh`; invalid values fail before provider startup.
+- Grok 4.6 entries in the default routing table explicitly select `high`.
+- A scored Grok target requires a verified `cli_reasoning_effort` mapping and the exact `--reasoning-effort` flag. The existing host-local transport overlay validates host, snapshot, exact identity, evidence hashes, vendor, flag, and effort.
+- Explicit effort on the live ACP path is rejected rather than discarded. This release does not add Grok work-mode network isolation on macOS.
+
+## Verification boundary
+
+The frozen AA registry and its approved SHA remain unchanged. Transport evidence belongs to the local host; the package does not ship a blanket assertion that every Grok model/effort combination is verified.
+
+`request-selector-contract` proves how Omnilane selects the model and effort. It does not independently authenticate the upstream model's internal identity: `upstream_identity_verified` remains false. A successful reply alone is not an identity attestation.
+
+For an existing local overlay, use `selector_type: cli_reasoning_effort`, `cli_flag: --reasoning-effort`, and matching model/effort identity only after checking the installed CLI and runner. Retain absolute evidence paths and SHA-256 hashes. Changed evidence requires re-verification; do not merely relabel an old mapping as verified. Select it with `--transport-overlay /absolute/overlay.json` or `OMNILANE_AA_TRANSPORT_OVERLAY`.
+
+## Upgrade
+
+After npm publication:
+
+```sh
+npm i -g omnilane@0.42.2
+omnilane --version
+```
+
+Repo-symlink installations use the updated checkout. Do not rerun `install.sh` just to update the version. Local routing overrides take precedence; review any Grok entries still using `-`.
+
+GitHub release, npm publication, local provider smoke, and Linux CI are separate verification surfaces. Release evidence must identify each result rather than equating one with the others.

package/hooks/routing-instruction.md

@@ -1,42 +1,103 @@
 <!-- omnilane-routing:start -->
-## omnilane — model routing (persistent reminder)
-
-Every task — not only implementation — is dispatched by default, even when
-the lane's first available model is the one you are running as: code edits,
-search, investigation, file reads, verification, tests, builds, deploys.
-Consult the routing table with `omnilane list` (or `scripts/dispatch.sh --list`
-inside the omnilane repo), classify the subtask into a lane, then dispatch it
-headlessly:
-
-    omnilane route [--vendor V] [--mode work] [--workdir DIR] <lane> "<task>"
-
-Advise mode is the default; pass `--mode work` only with an explicit
-`--workdir`. The commander self-executes only the reserved list: planning and
-decomposition, writing task briefs, reading worker output (`out.txt`,
-`events.jsonl`, inbox records), acceptance judgment, replies to the operator,
-git commit/push, and governance-file edits. The commander never runs commands
-itself: re-verify a worker's claim by reading its attached evidence or by
-dispatching a second worker with a different `--vendor`. Read-only work goes
-out in advise mode through named lanes — `triage` for high-volume scans,
-`long-context` for large documents, `live-search` for web or X,
-`hard-judgment` for second opinions. Invalid reasons to skip dispatch: "this
-lane is mine", "I am not dispatching so the rule does not apply", "it is only
-a file read", "dispatch is slower", "it is one line".
-
-Implementation dispatches carry `--mode work --workdir DIR --timeout 3600` or
-more; the advise default is read-only under a 600 s watchdog and yields no
-output there. Add `--background` for long tasks: on Claude Code the completion
-inbox delivers the result into your next prompt, elsewhere use `jobs.sh wait
-<id>`. Follow up a live Claude or Gemini worker with `jobs.sh send <id> "<text>"`
-/ `jobs.sh close <id>`. Wrap multi-dispatch exploratory objectives in
-`omnilane goal open`; dispatch a single obvious task directly.
-
-If the user explicitly names Claude, Codex, Grok, Gemini, or a canonical model
-alias, use the omnilane skill's consult rules and keep `--vendor` in the
-dispatch; an explicit target must not silently fall back.
-
-Lane definitions, modes, per-model rows, and safety rules live in the
-`omnilane` skill — load it and apply the row for the model you are running
-as; legacy model-routing skill variants are retired. Workers must never
-dispatch again (nested dispatch is refused, exit 86).
+<!-- source: codex-s / MacStudio; repo omnilane; approved AA v4.2 snapshot 2026-09-07 -->
+## omnilane — model routing and executor selection
+
+Delegate tasks by default, including when the resolved model is the commander's
+exact model. Native agents count as delegation; a model match is not permission
+to self-execute. Consult `omnilane list` and classify the lane, then resolve
+vendor/model/effort separately from executor choice:
+
+    omnilane route [--executor auto|native|cli] [--native-context FILE] [--vendor V] [--mode work] [--workdir DIR] <lane> "<task>"
+
+Terminal `auto` without capability context preserves legacy CLI. Build native
+capabilities only from the active agent-tool contract. Codex
+`collaboration.spawn_agent` has no sandbox/tool/workdir restriction parameters
+and inherits the parent's tools/filesystem. Its request and matching capability
+row must explicitly use `shared-inherited` with empty tool arrays;
+`advise`/`work` and workdir remain task intent, not OS isolation. Hard isolation
+stays same-model CLI in auto and rejects forced native. Supply the active
+harness/vendor, exact supported model/effort, optional known current model,
+mode/workdir, isolation, and lifecycle. Same vendor is not the same model.
+Unknown capabilities do not match. Do not infer capability from credentials,
+installed binaries, or model families. Explicit vendor/model/effort must survive
+fallback unchanged.
+
+Native is a host-callable tool, not a shell executable. A native route emits a
+machine-readable PENDING handoff JSON with task/job ID and resolved requirements.
+The caller executes the declared native strategy, passes intent plus a
+no-nested-delegation instruction, waits for the actual result, and records it with:
+
+    omnilane jobs --json complete-native JOB_ID /absolute/completion.json
+    omnilane jobs --json status JOB_ID
+    omnilane jobs --json result JOB_ID
+
+Completion includes actual agent ID, runtime vendor/model/effort/harness/backend,
+outcome, public result and evidence. A handoff alone is not success. Duplicate or
+invalid completion is rejected. Native cancellation records cancellation without
+signaling PIDs; the caller must separately stop an already-spawned agent.
+
+When the caller supplies an explicit model override, use `fork_turns: "none"` or
+a bounded positive history count; never combine it with `fork_turns: "all"`.
+Unknown caller current model may be omitted only when an exact requested model is
+explicitly selected and declared in the matching capability row.
+
+Forced CLI preserves external execution; forced native rejects missing or
+incompatible capability. Auto emits an explicit CLI reason, never a different
+vendor/model on native fallback. Background/durable/live/named CLI sessions,
+sysops, unsupported isolation and vote/arbitration/multi-round paths remain CLI.
+
+The commander owns planning, decomposition, task briefs, routing/handoff/result
+orchestration, acceptance, operator replies, git commit/push and governance edits.
+Workers execute assigned tasks and never delegate again (shell depth guard:
+exit 86; native callers must enforce the same rule). Read-only work defaults to
+advise. Implementation uses explicit `--mode work --workdir DIR --timeout 3600`
+or longer; native timeouts are caller-enforced. External long jobs can use
+`--background`, CLI `jobs wait`, live send/close and CLI goal-loop as before.
+
+If a vendor/model is explicitly named, retain `--vendor` and apply the
+omnilane skill's consultation rules. The repository skill and
+`docs/native-executor.md` define schemas, examples and limits. Only the parent
+backs up and syncs the host's managed AGENTS block after review.
+Exact-AA downward policy applies before every native/CLI candidate, fallback, retry,
+and vote constituent. Supply an exact model `--caller-context FILE`; unknown identity
+fails closed, and target score must be <= min(caller score, inherited ceiling).
+Explicit targets do not override the gate. Use `--transport-overlay FILE` only for
+host-local hashed request-selector evidence, never as a score or identity upgrade.
+Pass the job-owned child caller context to native workers; CLI propagates it itself.
+Retries intersect the current caller with the original authorizer ceiling, retain
+the target config, and revalidate integrity. Missing current caller fails closed;
+a model retry does not inherit a previous human exemption.
+Human exemption is an explicit cooperative operator assertion, never inferred for a
+model. Preserve OMNILANE_DEPTH. Failed work returns to the operator rather than an
+unapproved upward route. Observe terminal result and acceptance before ending a
+controller task; a background job/PENDING handoff is not success, and wakeup delivery
+requires its own evidence.
+
+For Codex background CLI jobs, actively bind completion to this controller before
+ending the turn: use the repository's `scripts/completion-wakeup.py prepare` with
+the actual app thread ID, local host ID, a unique run ID and exact job allowlist.
+Use its handoff with the app `automation_update` heartbeat tool; update an existing
+controller monitor instead of duplicating it. Record the successful tool receipt
+with `record-registration`. Never write scheduler files directly or label an
+unregistered handoff as active. Current caller metadata must come from this
+controller's verified runtime, not another task's context or a default model.
+
+On the scheduled callback, `poll`; stay quiet when nothing changed. For a terminal
+event, record `ack-delivered`, inspect the public result and required verification,
+then `ack-accepted` with PASS/FAIL/PARTIAL evidence. Exit zero is not acceptance.
+After all tracked events are handled, pause the actual automation with the app
+tool and record `closed` using its receipt. New runs get fresh, never-reused IDs.
+See `docs/completion-wakeup.md` for binding, leases, replay and expiry rules.
+Heartbeat is scheduled polling, not instant push. A next-prompt inbox is not wakeup.
+Without a supported callback tool, keep the controller active using `jobs wait`
+and continue acceptance on return; do not end with an unobserved background job.
+Native completion uses the host's agent callback and the same actual-result gate.
+
+Native reuse is explicit, never a silent substitute for new-agent creation. It
+requires a proven exact existing agent, caller-observed idle state and preserved
+context consent in the capability. Recheck idle before `collaboration.followup_task`;
+the completion must match strategy, agent and backend. Unknown identity or busy
+agents do not qualify. See `docs/native-executor.md`; a thread quota failure is
+not a successful run, and a cancelled pending job stays cancelled.
+
 <!-- omnilane-routing:end -->

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "omnilane",
-  "version": "0.41.1",
-  "description": "One routing table, every harness — classify subtasks into lanes and dispatch each lane to the best vendor's agentic CLI (Codex, Claude, Gemini, Grok) using your existing subscription logins.",
+  "version": "0.42.2",
+  "description": "One routing table, every harness — classify subtasks into lanes and delegate each lane through a compatible caller-owned native agent or vendor CLI.",
   "bin": {
     "omnilane": "bin/omnilane"
   },
@@ -24,8 +24,12 @@
     "README.ja.md",
     "README.ko.md",
     "SECURITY.md",
+    "config/aa-model-policy.json",
     "docs/aa-model-coverage-2026-09-05.json",
     "docs/model-capabilities-2026-09.md",
+    "docs/native-executor.md",
+    "docs/completion-wakeup.md",
+    "docs/release-notes-0.42.2.md",
     "hooks/",
     "skills/",
     ".claude-plugin/",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "omnilane",
- "version": "0.41.1",
-  "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."
+  "version": "0.42.2",
+  "description": "One routing table, every harness: classify subtasks into lanes and delegate through compatible caller-owned native agents or vendor CLIs with exact-AA downward policy and supervised jobs."
 }

package/routing.yaml

@@ -3,7 +3,7 @@
 #   vendor  = codex | claude | grok | gemini | kimi | qwen | opencode | openrouter
 #   openrouter is direct-API (needs only OPENROUTER_API_KEY + curl) and advise/consult
 #   only — it cannot edit files, so it is not in the default work-capable chains.
-#   effort  = codex reasoning effort / claude --effort / agy thinking suffix / (grok: ignored)
+#   effort  = codex reasoning effort / claude --effort / agy thinking suffix / grok --reasoning-effort
 #   Fallback chain: the first candidate whose vendor CLI is installed wins, so the
 #   same table degrades gracefully when you only subscribe to one or two vendors.
 # Override any line in ~/.omnilane/routing.local.yaml (same format; local wins).
@@ -20,17 +20,17 @@
 # standard short-context API tier — on subscription CLIs treat $ as relative ranking.
 # Your own job outcomes (~/.omnilane/jobs/) outrank these priors; edit lanes to match.
 
-hardest-coding: claude claude-fable-5-1 max | codex gpt-6-astra xhigh | grok grok-4.6 - | gemini gemini-3.8-flash-high - # correctness-first coding: Fable max leads the same-condition comparison; Astra xhigh is the default Codex quality/cost tradeoff; explicit --effort max remains available; Grok and Flash keep cross-vendor depth
+hardest-coding: claude claude-fable-5-1 max | codex gpt-6-astra xhigh | grok grok-4.6 high | gemini gemini-3.8-flash-high - # correctness-first coding: Fable max leads the same-condition comparison; Astra xhigh is the default Codex quality/cost tradeoff; explicit --effort max remains available; Grok and Flash keep cross-vendor depth
 bulk-mechanical: codex gpt-5.6-sol high | gemini gemini-3.8-flash-high - | claude claude-sonnet-5 high # endurance and migration work stays on proven Sol high; Flash 3.8 refreshes the fast middle fallback; Sonnet preserves cross-vendor depth
 triage: codex gpt-5.6-luna high | gemini gemini-3.8-flash-low - | claude claude-haiku-4-5 - # first-pass filtering favors the low-cost Luna row; Flash low and Haiku remain cheap cross-vendor fallbacks
-hard-judgment: claude claude-fable-5-1 xhigh | codex gpt-6-astra xhigh | grok grok-4.6 - # strongest same-condition judgment row first, then an independently verified Codex family and Grok; this lane is not a controller selector
-taste-final: claude claude-fable-5-1 xhigh | codex gpt-6-astra xhigh | grok grok-4.6 - | gemini gemini-3.8-flash-high - # final prose and style still require human taste review; general quality evidence orders the candidates without claiming an aesthetic benchmark
-consult: codex gpt-6-astra xhigh | claude claude-fable-5-1 xhigh | grok grok-4.6 - | gemini gemini-3.8-flash-medium - # direct named-model consultation chain; keep --vendor to pin the requested family and prevent fallback
+hard-judgment: claude claude-fable-5-1 xhigh | codex gpt-6-astra xhigh | grok grok-4.6 high # strongest same-condition judgment row first, then an independently verified Codex family and Grok; this lane is not a controller selector
+taste-final: claude claude-fable-5-1 xhigh | codex gpt-6-astra xhigh | grok grok-4.6 high | gemini gemini-3.8-flash-high - # final prose and style still require human taste review; general quality evidence orders the candidates without claiming an aesthetic benchmark
+consult: codex gpt-6-astra xhigh | claude claude-fable-5-1 xhigh | grok grok-4.6 high | gemini gemini-3.8-flash-medium - # direct named-model consultation chain; keep --vendor to pin the requested family and prevent fallback
 ui-draft: codex gpt-5.6-sol high | claude claude-fable-5-1 xhigh | gemini gemini-3.8-flash-high - # UI drafts require a design system or references; measured coding/agent evidence supports the order but does not prove visual taste
 long-context: gemini gemini-3.8-flash-medium - | codex gpt-5.6-terra max | claude claude-opus-5 medium # Flash medium leads long-document synthesis; Terra and Opus stay because context capacity alone does not prove task quality
 fast-agentic: gemini gemini-3.8-flash-low - | codex gpt-5.6-luna high | claude claude-haiku-4-5 - # low-latency tool loops favor Flash low; Luna and Haiku retain cross-vendor fallback depth
-live-search: grok grok-4.6 - | gemini gemini-3.8-flash-high - | claude claude-sonnet-5 high | off # Grok remains the native X/web choice; Flash and Sonnet provide generic web-search fallback, not equivalent social context
-coding-overflow: grok grok-4.6 - | gemini gemini-3.8-flash-high - | kimi kimi-k3 - | qwen qwen3-coder-plus - | opencode - - | off # explicit quota-relief lane; keep all existing non-Codex fallbacks and do not infer unverified Qwen aliases from another harness
+live-search: grok grok-4.6 high | gemini gemini-3.8-flash-high - | claude claude-sonnet-5 high | off # Grok remains the native X/web choice; Flash and Sonnet provide generic web-search fallback, not equivalent social context
+coding-overflow: grok grok-4.6 high | gemini gemini-3.8-flash-high - | kimi kimi-k3 - | qwen qwen3-coder-plus - | opencode - - | off # explicit quota-relief lane; keep all existing non-Codex fallbacks and do not infer unverified Qwen aliases from another harness
 arbitrate: off - - # opinion panel remains opt-in because each voter and round consumes quota
                                                 # Enable: `arbitrate: vote codex,claude,grok -` (any 1-4 of codex/claude/grok/gemini)
                                                 # Debate round (each voter rebuts the others): set the effort field to 2.