omnilane 0.32.0 → 0.33.0

package/scripts/lib/common.sh

@@ -9,6 +9,34 @@ export OMNILANE_REPO
 # Publishable default is plain CLIs on PATH; power users add ~/.omnilane/local.sh.
 [[ -f "$OMNILANE_HOME/local.sh" ]] && source "$OMNILANE_HOME/local.sh"
 
+# The unquoted backslash case pattern intentionally matches one backslash.
+# shellcheck disable=SC1003
+json_escape() {
+  local s="$1" out="" ch escaped code i
+  for ((i = 0; i < ${#s}; i++)); do
+    ch="${s:i:1}"
+    case "$ch" in
+      '"') out="$out\\\"" ;;
+      \\) out="$out\\\\" ;;
+      $'\b') out="$out\\b" ;;
+      $'\f') out="$out\\f" ;;
+      $'\n') out="$out\\n" ;;
+      $'\r') out="$out\\r" ;;
+      $'\t') out="$out\\t" ;;
+      *)
+        LC_CTYPE=C printf -v code '%d' "'$ch"
+        if [[ "$code" -ge 0 && "$code" -lt 32 ]]; then
+          printf -v escaped '\\u%04x' "$code"
+          out="$out$escaped"
+        else
+          out="$out$ch"
+        fi
+        ;;
+    esac
+  done
+  printf '%s' "$out"
+}
+
 resolve_timeout_cmd() {
   if command -v timeout &>/dev/null; then echo "timeout";
   elif command -v gtimeout &>/dev/null; then echo "gtimeout";
@@ -284,6 +312,66 @@ prepare_private_store() { # path, diagnostic label
   chmod 700 "$store_root" || return 1
 }
 
+OMNILANE_THREAD_NAME_PATTERN='^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$'
+
+omnilane_valid_thread_name() {
+  [[ "${1:-}" =~ $OMNILANE_THREAD_NAME_PATTERN ]]
+}
+
+prepare_threads_store() {
+  prepare_private_store "$OMNILANE_HOME/threads" "thread store"
+}
+
+read_thread_state() { # path, expected name; populates THREAD_STATE_*
+  local path="$1" expected_name="$2" fields separator=$'\034'
+  THREAD_STATE_NAME=""
+  THREAD_STATE_VENDOR=""
+  THREAD_STATE_MODEL=""
+  THREAD_STATE_EFFORT=""
+  THREAD_STATE_WORKDIR=""
+  THREAD_STATE_SESSION_ID=""
+  THREAD_STATE_TURNS=""
+  THREAD_STATE_LAST_JOB_ID=""
+  THREAD_STATE_CREATED=""
+  THREAD_STATE_UPDATED=""
+
+  [[ -f "$path" && ! -L "$path" ]] || return 1
+  fields="$(perl -MJSON::PP -e '
+    use strict;
+    use warnings;
+    my ($path, $expected) = @ARGV;
+    my $size = -s $path;
+    die "invalid size\n" unless defined($size) && $size > 0 && $size <= 16384;
+    open my $fh, "<", $path or die $!;
+    local $/;
+    my $state = decode_json(<$fh>);
+    die "invalid state\n" unless ref($state) eq "HASH";
+    my @string_keys = qw(name vendor model effort workdir session_id last_job_id created updated);
+    for my $key (@string_keys) {
+      my $value = $state->{$key};
+      die "invalid $key\n" if !defined($value) || ref($value) || $value =~ /[\x00-\x1f\x7f]/;
+    }
+    die "wrong name\n" unless $state->{name} eq $expected;
+    die "invalid name\n" unless $state->{name} =~ /\A[A-Za-z0-9][A-Za-z0-9._-]{0,63}\z/;
+    die "invalid vendor\n" unless $state->{vendor} =~ /\A[a-z][a-z0-9-]*\z/;
+    die "invalid session\n" unless $state->{session_id} =~ /\A[A-Za-z0-9._:-]{1,256}\z/;
+    die "invalid turns\n" if ref($state->{turns}) || ($state->{turns} // "") !~ /\A[1-9][0-9]{0,8}\z/;
+    die "invalid job id\n" unless $state->{last_job_id} =~ /\A[0-9]{8}-[0-9]{6}-[0-9]+-[0-9]+\z/;
+    for my $key (qw(created updated)) {
+      die "invalid timestamp\n" unless $state->{$key} =~ /\A[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z\z/;
+    }
+    die "field too long\n" if length($state->{model}) > 512 || length($state->{effort}) > 128 || length($state->{workdir}) > 4096;
+    print join(chr(28), map { $state->{$_} } qw(name vendor model effort workdir session_id turns last_job_id created updated));
+  ' "$path" "$expected_name" 2>/dev/null)" || return 1
+
+  # shellcheck disable=SC2034 # globals consumed by dispatch.sh and jobs.sh
+  IFS="$separator" read -r THREAD_STATE_NAME THREAD_STATE_VENDOR \
+    THREAD_STATE_MODEL THREAD_STATE_EFFORT THREAD_STATE_WORKDIR \
+    THREAD_STATE_SESSION_ID THREAD_STATE_TURNS THREAD_STATE_LAST_JOB_ID \
+    THREAD_STATE_CREATED THREAD_STATE_UPDATED <<< "$fields"
+  [[ -n "$THREAD_STATE_UPDATED" ]]
+}
+
 prepare_inbox_store() {
   prepare_private_store "$OMNILANE_HOME/inbox" "inbox store"
 }

package/scripts/lib/job-worker.sh

@@ -21,34 +21,6 @@ RUNNER="$OMNILANE_REPO/scripts/runners/run-$VENDOR.sh"
 # Two concurrent codex execs in one target dir corrupt its job index — serialize.
 [[ "$VENDOR" == "codex" ]] && acquire_cwd_lock codex "$WORKDIR"
 
-# The backslash case pattern is intentional.
-# shellcheck disable=SC1003
-json_escape() {
-  local s="$1" out="" ch escaped code i
-  for ((i = 0; i < ${#s}; i++)); do
-    ch="${s:i:1}"
-    case "$ch" in
-      '"') out="$out\\\"" ;;
-      '\\') out="$out\\\\" ;;
-      $'\b') out="$out\\b" ;;
-      $'\f') out="$out\\f" ;;
-      $'\n') out="$out\\n" ;;
-      $'\r') out="$out\\r" ;;
-      $'\t') out="$out\\t" ;;
-      *)
-        LC_CTYPE=C printf -v code '%d' "'$ch"
-        if [[ "$code" -ge 0 && "$code" -lt 32 ]]; then
-          printf -v escaped '\\u%04x' "$code"
-          out="$out$escaped"
-        else
-          out="$out$ch"
-        fi
-        ;;
-    esac
-  done
-  printf '%s' "$out"
-}
-
 emit_mode_notice() {
   local notice="$1" notice_file="${OUTPUT_FILE%/*}/mode-notice.txt"
   printf '%s\n' "$notice" >&2

package/scripts/provider-probe.sh

@@ -23,7 +23,7 @@ json_escape() {
     ch="${s:i:1}"
     case "$ch" in
       '"') out="$out\\\"" ;;
-      '\\') out="$out\\\\" ;;
+      \\) out="$out\\\\" ;;
       $'\b') out="$out\\b" ;;
       $'\f') out="$out\\f" ;;
       $'\n') out="$out\\n" ;;

package/scripts/release-audit.sh

@@ -57,7 +57,7 @@ json_escape() {
     ch="${value:i:1}"
     case "$ch" in
       '"') out="$out\\\"" ;;
-      '\\') out="$out\\\\" ;;
+      \\) out="$out\\\\" ;;
       $'\b') out="$out\\b" ;;
       $'\f') out="$out\\f" ;;
       $'\n') out="$out\\n" ;;

package/scripts/runners/run-claude.sh

@@ -14,6 +14,21 @@ RUN_TIMEOUT="${OMNILANE_TIMEOUT:-600}"
 
 truncate_payload "$PROMPT_FILE" 102400
 
+THREAD_MODE="${OMNILANE_THREAD_MODE:-}"
+THREAD_ID="${OMNILANE_THREAD_ID:-}"
+THREAD_ARGS=()
+if [[ -n "$THREAD_MODE" || -n "$THREAD_ID" ]]; then
+  [[ "$THREAD_ID" =~ ^[A-Za-z0-9._:-]+$ && "${#THREAD_ID}" -le 256 ]] || {
+    echo "omnilane: invalid Claude thread session id" >&2
+    exit 2
+  }
+  case "$THREAD_MODE" in
+    new) THREAD_ARGS=(--session-id "$THREAD_ID") ;;
+    resume) THREAD_ARGS=(--resume "$THREAD_ID") ;;
+    *) echo "omnilane: invalid Claude thread mode" >&2; exit 2 ;;
+  esac
+fi
+
 LIVE_INBOX="${OMNILANE_INBOX:-}"
 if [[ -n "$LIVE_INBOX" && -p "$LIVE_INBOX" ]]; then
   EVENTS_FILE="${OUTPUT_FILE}.events.jsonl"
@@ -118,7 +133,7 @@ PY
   exit "$RC"
 fi
 
-ARGS=(--disable-slash-commands --model "$MODEL" --output-format text)
+ARGS=(--disable-slash-commands --model "$MODEL")
 [[ -n "$EFFORT" && "$EFFORT" != "-" ]] && ARGS+=(--effort "$EFFORT")
 if [[ "$MODE" == "advise" ]]; then
   # Read-only surface: the worker can inspect the repo but not change or run anything.
@@ -126,18 +141,62 @@ if [[ "$MODE" == "advise" ]]; then
 else
   ARGS+=(--permission-mode acceptEdits)
 fi
+if [[ -n "$THREAD_MODE" ]]; then
+  ARGS+=(--verbose --output-format stream-json)
+  ARGS+=("${THREAD_ARGS[@]}")
+else
+  ARGS+=(--output-format text)
+fi
 ARGS+=(-p "$(cat "$PROMPT_FILE")")
 
 set +e
 (
   cd "$WORKDIR" || exit 127
-  run_with_timeout "$RUN_TIMEOUT" env \
-    OMNILANE_DEPTH=1 \
-    "$CLAUDE_BIN" "${ARGS[@]}" > "${OUTPUT_FILE}.tmp" 2> "${OUTPUT_FILE}.stderr.log"
+  if [[ -n "$THREAD_MODE" ]]; then
+    run_with_timeout "$RUN_TIMEOUT" env \
+      OMNILANE_DEPTH=1 \
+      "$CLAUDE_BIN" "${ARGS[@]}" > "${OUTPUT_FILE}.events.jsonl" 2> "${OUTPUT_FILE}.stderr.log"
+  else
+    run_with_timeout "$RUN_TIMEOUT" env \
+      OMNILANE_DEPTH=1 \
+      "$CLAUDE_BIN" "${ARGS[@]}" > "${OUTPUT_FILE}.tmp" 2> "${OUTPUT_FILE}.stderr.log"
+  fi
 )
 RC=$?
 set -e
 
+if [[ -n "$THREAD_MODE" ]]; then
+  if [[ "$RC" -eq 0 ]]; then
+    if ! python3 - "$OUTPUT_FILE.events.jsonl" "${OUTPUT_FILE}.tmp" <<'PY'
+import json
+import pathlib
+import sys
+
+events_path = pathlib.Path(sys.argv[1])
+output_path = pathlib.Path(sys.argv[2])
+last_result = None
+with events_path.open(encoding="utf-8") as events:
+    for raw_line in events:
+        try:
+            event = json.loads(raw_line)
+        except json.JSONDecodeError:
+            continue
+        if event.get("type") == "result" and isinstance(event.get("result"), str):
+            last_result = event["result"]
+if last_result is None:
+    raise SystemExit(1)
+output_path.write_text(last_result.rstrip("\n") + "\n", encoding="utf-8")
+PY
+    then
+      echo "omnilane: Claude thread stream ended without readable result event" >> "${OUTPUT_FILE}.stderr.log"
+      RC=1
+    fi
+  fi
+  if [[ "$RC" -ne 0 && -s "${OUTPUT_FILE}.stderr.log" ]]; then
+    cat "${OUTPUT_FILE}.stderr.log" >&2
+    cat "${OUTPUT_FILE}.stderr.log" > "${OUTPUT_FILE}.tmp"
+  fi
+fi
 [[ -f "${OUTPUT_FILE}.tmp" ]] && mv "${OUTPUT_FILE}.tmp" "$OUTPUT_FILE"
 [[ -s "${OUTPUT_FILE}.stderr.log" ]] || rm "${OUTPUT_FILE}.stderr.log" 2>/dev/null || true
 exit "$RC"

package/scripts/runners/run-codex.sh

@@ -14,19 +14,46 @@ MODE="$1"; WORKDIR="$2"; MODEL="$3"; EFFORT="$4"; PROMPT_FILE="$5"; OUTPUT_FILE=
 CODEX_BIN="${CODEX_BIN:-codex}"
 RUN_TIMEOUT="${OMNILANE_TIMEOUT:-600}"
 
+THREAD_MODE="${OMNILANE_THREAD_MODE:-}"
+THREAD_ID="${OMNILANE_THREAD_ID:-}"
+if [[ -n "$THREAD_MODE" || -n "$THREAD_ID" ]]; then
+  [[ "$THREAD_ID" =~ ^[A-Za-z0-9._:-]+$ && "${#THREAD_ID}" -le 256 ]] || {
+    echo "omnilane: invalid Codex thread session id" >&2
+    exit 2
+  }
+  case "$THREAD_MODE" in
+    new) ;;
+    resume) ;;
+    *) echo "omnilane: invalid Codex thread mode" >&2; exit 2 ;;
+  esac
+fi
+
 # --skip-git-repo-check: the operator chose WORKDIR explicitly; codex would
 # otherwise refuse any directory that is not a trusted git repo.
 # --json: without it codex writes nothing until it exits, so a watchdog kill
 # leaves an empty progress log that looks identical to a run that never started.
-ARGS=(exec --json -m "$MODEL" -o "${OUTPUT_FILE}.tmp" --skip-git-repo-check)
+if [[ "$THREAD_MODE" == "resume" ]]; then
+  ARGS=(exec resume --json -m "$MODEL" -o "${OUTPUT_FILE}.tmp" --skip-git-repo-check)
+else
+  ARGS=(exec --json -m "$MODEL" -o "${OUTPUT_FILE}.tmp" --skip-git-repo-check)
+fi
 [[ -n "$EFFORT" && "$EFFORT" != "-" ]] && ARGS+=(-c "model_reasoning_effort=\"$EFFORT\"")
 if [[ "$MODE" == "advise" ]]; then
-  ARGS+=(--ephemeral -s read-only)
+  [[ -z "$THREAD_MODE" ]] && ARGS+=(--ephemeral)
+  SANDBOX=read-only
 elif [[ "$MODE" == "sysops" ]]; then
-  ARGS+=(-s danger-full-access)
+  SANDBOX=danger-full-access
+else
+  SANDBOX=workspace-write
+fi
+# `codex exec resume` has no -s/--sandbox flag (rejects it with exit 2); the
+# same policy is only reachable there through the sandbox_mode config override.
+if [[ "$THREAD_MODE" == "resume" ]]; then
+  ARGS+=(-c "sandbox_mode=\"$SANDBOX\"")
 else
-  ARGS+=(-s workspace-write)
+  ARGS+=(-s "$SANDBOX")
 fi
+[[ "$THREAD_MODE" == "resume" ]] && ARGS+=("$THREAD_ID" -)
 
 truncate_payload "$PROMPT_FILE" 140000
 

package/scripts/runners/run-gemini.sh

@@ -14,6 +14,21 @@ AGY_BIN="${AGY_BIN:-agy}"
 RUN_TIMEOUT="${OMNILANE_TIMEOUT:-600}"
 CAPACITY_PATTERN='MODEL_CAPACITY_EXHAUSTED|No capacity available for model|rateLimitExceeded|RESOURCE_EXHAUSTED'
 
+THREAD_MODE="${OMNILANE_THREAD_MODE:-}"
+THREAD_ID="${OMNILANE_THREAD_ID:-}"
+THREAD_ARGS=()
+if [[ -n "$THREAD_MODE" || -n "$THREAD_ID" ]]; then
+  [[ "$THREAD_ID" =~ ^[A-Za-z0-9._:-]+$ && "${#THREAD_ID}" -le 256 ]] || {
+    echo "omnilane: invalid Gemini thread session id" >&2
+    exit 2
+  }
+  case "$THREAD_MODE" in
+    new) ;;
+    resume) THREAD_ARGS=(--conversation "$THREAD_ID") ;;
+    *) echo "omnilane: invalid Gemini thread mode" >&2; exit 2 ;;
+  esac
+fi
+
 truncate_payload "$PROMPT_FILE" 140000
 
 # Both modes run inside the target WORKDIR so the worker can actually see the
@@ -142,6 +157,38 @@ PY
   exit "$RC"
 fi
 
+if [[ -n "$THREAD_MODE" ]]; then
+  set +e
+  (
+    cd "$RUN_DIR" || exit 127
+    env -u GEMINI_API_KEY -u GOOGLE_API_KEY -u GOOGLE_AI_API_KEY \
+      NO_BROWSER=1 OMNILANE_DEPTH=1 \
+      "$AGY_BIN" --dangerously-skip-permissions --add-dir "$RUN_DIR" \
+      "${MODE_ARGS[@]}" ${MODEL_ARGS[@]+"${MODEL_ARGS[@]}"} \
+      --print-timeout "${RUN_TIMEOUT}s" --output-format json \
+      "${THREAD_ARGS[@]}" -p "$(cat "$PROMPT_FILE")" \
+      > "${OUTPUT_FILE}.result.json" 2> "${OUTPUT_FILE}.stderr.log"
+  )
+  RC=$?
+  set -e
+  if [[ "$RC" -eq 0 ]]; then
+    if ! python3 - "${OUTPUT_FILE}.result.json" "${OUTPUT_FILE}.tmp" <<'PY'
+import json
+import pathlib
+import sys
+
+result = json.loads(pathlib.Path(sys.argv[1]).read_text(encoding="utf-8"))
+response = result.get("response")
+if result.get("status") != "SUCCESS" or not isinstance(response, str):
+    raise SystemExit(1)
+pathlib.Path(sys.argv[2]).write_text(response.rstrip("\n") + "\n", encoding="utf-8")
+PY
+    then
+      echo "omnilane: Gemini thread result was not readable SUCCESS JSON" >> "${OUTPUT_FILE}.stderr.log"
+      RC=1
+    fi
+  fi
+else
 set +e
 (
   cd "$RUN_DIR" || exit 127
@@ -158,8 +205,9 @@ set +e
 )
 RC=$?
 set -e
+fi
 
-if grep -Eiq "$CAPACITY_PATTERN" "${OUTPUT_FILE}.tmp" "${OUTPUT_FILE}.stderr.log" 2>/dev/null; then
+if grep -Eiq "$CAPACITY_PATTERN" "${OUTPUT_FILE}.tmp" "${OUTPUT_FILE}.result.json" "${OUTPUT_FILE}.stderr.log" 2>/dev/null; then
   echo "omnilane: gemini capacity exhausted" >> "${OUTPUT_FILE}.stderr.log"
   RC=126
 fi

package/scripts/runners/run-grok.sh

@@ -17,14 +17,30 @@ MAX_ATTEMPTS="${OMNILANE_GROK_MAX_ATTEMPTS:-5}"
   exit 2
 }
 
+THREAD_MODE="${OMNILANE_THREAD_MODE:-}"
+THREAD_ID="${OMNILANE_THREAD_ID:-}"
+THREAD_ARGS=()
+if [[ -n "$THREAD_MODE" || -n "$THREAD_ID" ]]; then
+  [[ "$THREAD_ID" =~ ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$ ]] || {
+    echo "omnilane: invalid Grok thread session id" >&2
+    exit 2
+  }
+  case "$THREAD_MODE" in
+    new) THREAD_ARGS=(--session-id "$THREAD_ID") ;;
+    resume) THREAD_ARGS=(--resume "$THREAD_ID") ;;
+    *) echo "omnilane: invalid Grok thread mode" >&2; exit 2 ;;
+  esac
+fi
+
 # Subscription OAuth path: an exhausted API key in env causes 403s.
 unset XAI_API_KEY 2>/dev/null || true
 
 truncate_payload "$PROMPT_FILE" 140000
 
 ARGS=(--cwd "$WORKDIR" --model "$MODEL"
-      --no-memory --no-subagents --no-plan --no-alt-screen
-      --output-format plain --verbatim --prompt-file "$PROMPT_FILE")
+  --no-memory --no-subagents --no-plan --no-alt-screen
+  --output-format plain --verbatim --prompt-file "$PROMPT_FILE")
+ARGS+=("${THREAD_ARGS[@]}")
 [[ "$MODE" == "advise" ]] && ARGS+=(--permission-mode plan)
 # Web/X search stays ON by default — it is this vendor's signature lane.
 [[ "${OMNILANE_GROK_NO_WEB:-0}" == "1" ]] && ARGS+=(--disable-web-search)

package/skills/omnilane/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: omnilane
-description: 'Universal model-routing table + cross-vendor dispatch for ANY harness (Claude Code, Codex, Grok Build, Antigravity). Use when delegating subtasks, choosing a model for work, planning multi-part tasks, or when asked about model routing, delegate, dispatch, which model, tier selection, escalate, 派工, 模型路由. One routing table; implementation work dispatches by default via dispatch.sh — the main loop self-executes only reserved commander items.'
+description: 'Universal model-routing table + cross-vendor dispatch for ANY harness (Claude Code, Codex, Grok Build, Antigravity). Use when delegating subtasks, choosing a model for work, planning multi-part tasks, or when asked about model routing, delegate, dispatch, which model, tier selection, escalate, 派工, 模型路由. One routing table; every task dispatches by default via dispatch.sh — the main loop self-executes only reserved commander items.'
 ---
 
 # omnilane — one routing table, every harness
@@ -9,13 +9,31 @@ You (the main loop) may be Claude, GPT, Grok, or Gemini. The procedure is identi
 
 1. **Identify your main model.** You know which model you are running as.
 2. **Split the work into subtasks and classify each into a lane** (table below).
-3. **Dispatch implementation work by default — even when the lane's model is
-   you.** Self-execute only reserved commander items: planning and
-   decomposition, writing task briefs, reviewing reports, acceptance checks,
-   replies to the operator, git commit/push, read-only verification, and
-   fixes of one line or less. Dispatch:
+3. **Dispatch every task by default — even when the lane's model is you:**
+   implementation, search, investigation, file reads, verification, tests,
+   builds, deploys. The commander self-executes only: planning and
+   decomposition, writing task briefs, reading worker reports and job files
+   (`out.txt`, `events.jsonl`, inbox records), acceptance judgment, replies to
+   the operator, git commit/push, and edits to governance files. Read-only
+   work goes out in advise mode: `triage` for high-volume scans, `long-context`
+   for large documents, `live-search` for web or X, `hard-judgment` for second
+   opinions. Editing work uses `--mode work --workdir <repo> --timeout 3600`
+   or more. Re-verify a worker's claim by reading its attached evidence or by
+   dispatching a second worker (change `--vendor`); the commander runs no
+   commands itself. 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". Dispatch:
    `<repo>/scripts/dispatch.sh [--vendor V] [--mode work] [--workdir DIR] <lane> "<task>"`
    Add `--background` for long tasks; poll with `scripts/jobs.sh status|result <id>`.
+   Use `--thread NAME` when later claude, codex, grok or gemini dispatches
+   must retain earlier context. Threads in 0.33.0 pin vendor, model, effort and
+   physical workdir; inspect or remove local state with `scripts/jobs.sh threads`,
+   `threads show NAME`, and `threads rm NAME` (removal leaves the vendor session).
+   Implementation dispatches (code edits, new files, tests, builds, deploys)
+   must carry `--mode work --workdir <repo>` and a `--timeout` of at least
+   3600 seconds. The advise default is a read-only worker under a 600 s
+   per-call watchdog, and on an implementation task it yields zero output.
+   Advise stays the default for reviews, questions, and second opinions.
    Before changing lane order from anecdotal outcomes, run
    `scripts/jobs.sh recommend [--last N] [--lane L] [--min-samples N]` and report
    its evidence threshold. The command is read-only and never changes routing.
@@ -132,6 +150,24 @@ delete jobs, or edit configuration. Natural-language interpretation and
 dispatch stay in this skill and the CLI. Manage the local board with
 `omnilane ui start|status|url|stop`, and stop it when monitoring is finished.
 
+## Job lifecycle defaults
+
+- **Completion inbox**: with the Claude Code plugin's hooks installed, a
+  finished `--background` job is delivered into the foreman's next prompt by
+  the bundled `UserPromptSubmit` hook, so do not poll for it. Outside Claude
+  Code, block on `scripts/jobs.sh wait <id> [--timeout N]` instead.
+- **Live mailbox**: a `--background` dispatch to Claude or Gemini is a
+  resident worker. Send follow-up instructions with `scripts/jobs.sh send <id>
+  "<text>"` and end it with `scripts/jobs.sh close <id>`; other vendors (and
+  `--single-shot`) run one-shot. Do not use a mailbox for fire-and-forget work.
+- **Goal orchestration**: when the next step depends on the previous result,
+  wrap the dispatches in `omnilane goal open "<objective>" --workdir DIR`, then
+  `goal dispatch <goal-id> ...`, `goal note`, `goal status`, `goal close --summary`.
+  Budgets are unlimited unless `--budget-jobs` / `--budget-seconds` is passed.
+  A single obvious task is dispatched directly, never through a goal.
+- **Job hygiene**: `scripts/jobs.sh cancel <id>` stops a runaway job.
+  `stats`, `recommend`, and `audit` are read-only and never change routing.
+
 ## Rules
 
 - **Dispatch in `advise` mode by default** (read-only worker). Use `--mode work`
@@ -160,7 +196,7 @@ dispatch stay in this skill and the CLI. Manage the local board with
 - **Claude Fable 5.1 main**: hard judgment, taste finalization, and the hardest
   coding are yours. Dispatch bulk work to Sol high and long-context or fast
   loops to Gemini 3.7 Flash.
-- **Claude Opus 5 main**: judgment and taste remain strong self-execute lanes;
+- **Claude Opus 5 main**: judgment and taste remain its strongest lanes, but the commander still dispatches them;
   use local overrides when its lower hallucination rate or price is preferred.
 - **Claude Sonnet main**: coordination/tools/mid-tier coding only; never
   self-assign top judgment or hardest implementation.