omnilane 0.15.0 → 0.20.0

package/plugin.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "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."
+}

package/scripts/dispatch.sh

@@ -637,6 +637,10 @@ chmod 700 "$JOBS_ROOT"
 JOB_ID="$(date +%Y%m%d-%H%M%S)-$$-$RANDOM"
 JOB_DIR="$JOBS_ROOT/$JOB_ID"
 mkdir -m 700 "$JOB_DIR"
+FOREMAN_SESSION=""
+if resolved_foreman_session="$(find_foreman_session "$$" 2>/dev/null)"; then
+  FOREMAN_SESSION="$resolved_foreman_session"
+fi
 
 if [[ "$TASK" == "-" ]]; then
   (umask 077; cat > "$JOB_DIR/task.txt")
@@ -645,10 +649,11 @@ else
 fi
 
 # meta "timeout" is the resolved per-CLI-call watchdog cap, not a whole-job total.
-(umask 077; printf '{"lane":"%s","vendor":"%s","model":"%s","effort":"%s","timeout":%s,"job_timeout":%s,"mode":"%s","workdir":"%s","candidate":"%s/%s","started":"%s"}\n' \
+(umask 077; printf '{"lane":"%s","vendor":"%s","model":"%s","effort":"%s","timeout":%s,"job_timeout":%s,"mode":"%s","workdir":"%s","foreman_session":"%s","candidate":"%s/%s","started":"%s"}\n' \
   "$(json_escape "$LANE")" "$(json_escape "$VENDOR")" "$(json_escape "$MODEL")" \
   "$(json_escape "$EFFORT")" "$TIMEOUT" "$JOB_TIMEOUT_JSON" "$(json_escape "$MODE")" \
-  "$(json_escape "$WORKDIR")" "$RESOLVED_IDX" "$RESOLVED_TOTAL" \
+  "$(json_escape "$WORKDIR")" "$(json_escape "$FOREMAN_SESSION")" \
+  "$RESOLVED_IDX" "$RESOLVED_TOTAL" \
   "$(date -u +%FT%TZ)" > "$JOB_DIR/meta.json")
 
 secure_job_files() {
@@ -685,9 +690,10 @@ write_completion_record() {
   finished="$(date -u +%FT%TZ)" || return 1
   old_umask="$(umask)"
   umask 077
-  printf '{"job_id":"%s","lane":"%s","vendor":"%s","model":"%s","mode":"%s","workdir":"%s","exit":%s,"finished":"%s","tail":"%s"}\n' \
+  printf '{"job_id":"%s","lane":"%s","vendor":"%s","model":"%s","mode":"%s","workdir":"%s","foreman_session":"%s","exit":%s,"finished":"%s","tail":"%s"}\n' \
     "$(json_escape "$JOB_ID")" "$(json_escape "$LANE")" "$(json_escape "$VENDOR")" \
     "$(json_escape "$MODEL")" "$(json_escape "$MODE")" "$(json_escape "$WORKDIR")" \
+    "$(json_escape "$FOREMAN_SESSION")" \
     "$rc" "$(json_escape "$finished")" "$(json_escape "$tail_value")" > "$tmp" || write_rc=$?
   if [[ "$write_rc" -eq 0 ]]; then
     chmod 600 "$tmp" || write_rc=$?
@@ -696,7 +702,8 @@ write_completion_record() {
     mv "$tmp" "$final" || write_rc=$?
   fi
   umask "$old_umask"
-  rm -f "$tmp" 2>/dev/null || true
+  # no -f: force-flag rm is blocked by some environments' destructive guards
+  rm "$tmp" 2>/dev/null || true
   return "$write_rc"
 }
 

package/scripts/doctor.sh

@@ -123,6 +123,132 @@ else
   report PASS state "$OMNILANE_HOME is accessible"
 fi
 
+completion_plugin_state() {
+  local config_dir state
+  config_dir="${CLAUDE_CONFIG_DIR:-${HOME:-}/.claude}"
+  state="$(perl -MJSON::PP -e '
+    use strict;
+    use warnings;
+    my ($repo, @paths) = @ARGV;
+    my ($seen, $enabled, $source) = (0, undef, undef);
+    for my $path (@paths) {
+      next unless -e $path;
+      $seen = 1;
+      open my $fh, "<", $path or do { print "unknown"; exit 0 };
+      local $/;
+      my $settings = eval { decode_json(<$fh>) };
+      close $fh;
+      if ($@ || ref($settings) ne "HASH") { print "unknown"; exit 0 }
+      my $plugins = $settings->{enabledPlugins};
+      if (ref($plugins) eq "HASH" && exists $plugins->{"omnilane\@omnilane"}) {
+        $enabled = $plugins->{"omnilane\@omnilane"};
+      }
+      my $markets = $settings->{extraKnownMarketplaces};
+      if (ref($markets) eq "HASH" && exists $markets->{omnilane}) {
+        my $market = $markets->{omnilane};
+        $source = ref($market) eq "HASH" ? $market->{source} : undef;
+      }
+    }
+    if (!$seen) { print "unknown"; exit 0 }
+    my $enabled_ok = ref($enabled) &&
+      eval { $enabled->isa("JSON::PP::Boolean") } && $enabled;
+    my $source_ok = ref($source) eq "HASH" &&
+      defined($source->{source}) && !ref($source->{source}) &&
+      defined($source->{path}) && !ref($source->{path}) &&
+      $source->{source} eq "directory" && $source->{path} eq $repo;
+    print $enabled_ok && $source_ok ? "active" : "inactive";
+  ' "$REPO" "$config_dir/settings.json" "$config_dir/settings.local.json" 2>/dev/null)" || state=unknown
+  case "$state" in
+    active|inactive|unknown) printf '%s\n' "$state" ;;
+    *) printf '%s\n' unknown ;;
+  esac
+}
+
+completion_manifest_registers_hook() {
+  local manifest="$1"
+  [[ -r "$manifest" ]] || return 1
+  awk '
+    { content = content $0 }
+    END {
+      if (content ~ /"UserPromptSubmit"[[:space:]]*:[[:space:]]*\[/ &&
+          content ~ /"UserPromptSubmit".*report-completions\.sh/) exit 0
+      exit 1
+    }
+  ' "$manifest"
+}
+
+completion_plugin="$(completion_plugin_state)"
+completion_settings_dir="${CLAUDE_CONFIG_DIR:-${HOME:-}/.claude}"
+completion_script="$REPO/hooks/report-completions.sh"
+completion_manifest="$REPO/hooks/hooks.json"
+completion_inbox="$OMNILANE_HOME/inbox"
+completion_plugin_ok=0
+completion_script_ok=0
+completion_manifest_ok=0
+completion_inbox_ok=1
+completion_pending=0
+completion_reason=""
+
+case "$completion_plugin" in
+  active)
+    completion_plugin_ok=1
+    report PASS completion-plugin "omnilane@omnilane is enabled according to Claude Code settings"
+    ;;
+  inactive)
+    completion_reason="omnilane@omnilane is missing or disabled"
+    report WARN completion-plugin "$completion_reason according to Claude Code settings"
+    ;;
+  *)
+    completion_reason="Claude Code plugin state is unknown"
+    report WARN completion-plugin "$completion_reason; settings files were absent, unreadable, or invalid"
+    ;;
+esac
+
+if [[ -x "$completion_script" ]]; then
+  completion_script_ok=1
+  report PASS completion-hook "$completion_script exists and is executable"
+elif [[ -e "$completion_script" ]]; then
+  completion_reason="${completion_reason:+$completion_reason; }$completion_script is not executable"
+  report WARN completion-hook "$completion_script exists but is not executable"
+else
+  completion_reason="${completion_reason:+$completion_reason; }$completion_script is missing"
+  report WARN completion-hook "$completion_script is missing"
+fi
+
+if completion_manifest_registers_hook "$completion_manifest"; then
+  completion_manifest_ok=1
+  report PASS completion-manifest "$completion_manifest from the current checkout registers UserPromptSubmit"
+else
+  completion_reason="${completion_reason:+$completion_reason; }$completion_manifest does not register UserPromptSubmit"
+  report WARN completion-manifest "$completion_manifest from the current checkout does not register UserPromptSubmit for report-completions.sh"
+fi
+
+if [[ -L "$completion_inbox" || ( -e "$completion_inbox" && ! -d "$completion_inbox" ) ]]; then
+  completion_inbox_ok=0
+  completion_reason="${completion_reason:+$completion_reason; }$completion_inbox is not a real directory"
+  report WARN completion-inbox "$completion_inbox must be a real directory"
+elif [[ -d "$completion_inbox" ]]; then
+  for completion_record in "$completion_inbox"/*.json; do
+    [[ -f "$completion_record" && ! -L "$completion_record" ]] || continue
+    completion_pending=$((completion_pending + 1))
+  done
+  report PASS completion-inbox "$completion_pending pending records in $completion_inbox"
+else
+  report PASS completion-inbox "0 pending records; $completion_inbox does not exist yet"
+fi
+
+if [[ "$completion_plugin_ok" -eq 1 && "$completion_script_ok" -eq 1 &&
+      "$completion_manifest_ok" -eq 1 && "$completion_inbox_ok" -eq 1 ]]; then
+  report PASS completion-notice "active; $completion_pending pending records; manifest read from $completion_manifest"
+else
+  if [[ "$completion_plugin" == inactive ]]; then
+    completion_reason="$completion_reason; run: claude plugin marketplace add \"$REPO\"; claude plugin install omnilane@omnilane"
+  elif [[ "$completion_plugin" == unknown ]]; then
+    completion_reason="$completion_reason; inspect $completion_settings_dir/settings.json and settings.local.json"
+  fi
+  report WARN completion-notice "inactive: $completion_reason; manifest read from $completion_manifest"
+fi
+
 if [[ -f "$OMNILANE_HOME/local.sh" ]]; then
   if /bin/bash -n "$OMNILANE_HOME/local.sh" 2>/dev/null; then
     report PASS local-config "$OMNILANE_HOME/local.sh syntax is valid"

package/scripts/jobs.sh

@@ -4,14 +4,19 @@ set -euo pipefail
 # Usage: jobs.sh [--json] list | status JOB_ID | result JOB_ID | stats [--last N]
 #        jobs.sh [--json] recommend [--last N] [--lane L] [--min-samples N]
 #        jobs.sh wait JOB_ID [--timeout N]
+#        jobs.sh send JOB_ID TEXT | watch JOB_ID | close JOB_ID
 #        jobs.sh audit [--last N] [--json] | prune [--keep N] [--apply]
 
+# Runtime-relative shared library.
+# shellcheck disable=SC1091
 source "$(dirname "${BASH_SOURCE[0]}")/lib/common.sh"
 JOBS="$OMNILANE_HOME/jobs"
 JOB_ID_PATTERN='^[0-9]{8}-[0-9]{6}-[0-9]+-[0-9]+$'
 JSON_MODE=0
 COMMAND="unknown"
 
+# 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
@@ -49,7 +54,7 @@ die() {
   exit "$rc"
 }
 
-USAGE_TEXT="usage: jobs.sh [--json] list [--lane L] [--vendor V] [--status running|done]|status ID|result ID|tail ID [--lines N]|retry ID [--background]|stats [--last N] [--lane L] [--vendor V]|recommend [--last N] [--lane L] [--min-samples N]|wait ID [--timeout N]|cancel ID|rm ID|audit [--last N]|prune [--keep N] [--older-than DAYS] [--apply]|help"
+USAGE_TEXT="usage: jobs.sh [--json] list [--lane L] [--vendor V] [--status running|done]|status ID|result ID|tail ID [--lines N]|send ID TEXT|watch ID|close ID|retry ID [--background]|stats [--last N] [--lane L] [--vendor V]|recommend [--last N] [--lane L] [--min-samples N]|wait ID [--timeout N]|cancel ID|rm ID|audit [--last N]|prune [--keep N] [--older-than DAYS] [--apply]|help"
 
 usage() {
   die 2 "$USAGE_TEXT"
@@ -108,6 +113,14 @@ read_public_metadata() {
   PUBLIC_METADATA="$value"
 }
 
+print_mode_notice() {
+  local path="$JOB_DIR/mode-notice.txt"
+  [[ -e "$path" || -L "$path" ]] || return 0
+  if read_public_metadata "$path"; then
+    printf '%s\n' "$PUBLIC_METADATA"
+  fi
+}
+
 valid_utf8() {
   command -v iconv >/dev/null 2>&1 || return 1
   printf '%s' "$1" | iconv -f UTF-8 -t UTF-8 >/dev/null 2>&1
@@ -131,6 +144,55 @@ read_job_pid() {
   RECORDED_PID="$value"
 }
 
+load_job_vendor() {
+  if ! read_public_metadata "$JOB_DIR/meta.json" || ! parse_stats_metadata "$PUBLIC_METADATA"; then
+    die 1 "job metadata is not safely readable"
+  fi
+  JOB_VENDOR="$STATS_VENDOR"
+}
+
+require_live_job() {
+  load_job_vendor
+  [[ "$JOB_VENDOR" == "claude" ]] || die 1 "job vendor '$JOB_VENDOR' is not live-capable; it runs in single-shot mode"
+}
+
+wait_for_live_ready() {
+  local deadline=$((SECONDS + 5))
+  while [[ ! -f "$JOB_DIR/inbox.ready" ]]; do
+    if [[ -e "$JOB_DIR/exit" || -L "$JOB_DIR/exit" ]]; then
+      die 1 "job is no longer accepting live messages"
+    fi
+    if [[ "$SECONDS" -ge "$deadline" ]]; then
+      die 124 "live inbox did not become ready within 5s"
+    fi
+    sleep 0.1
+  done
+  [[ ! -L "$JOB_DIR/inbox.ready" ]] || die 1 "unsafe live inbox readiness path"
+  [[ -p "$JOB_DIR/inbox.fifo" && ! -L "$JOB_DIR/inbox.fifo" ]] || die 1 "live inbox FIFO is unavailable"
+}
+
+write_fifo_with_timeout() {
+  local fifo="$1" payload="$2" writer_pid deadline rc
+  (
+    printf '%s\n' "$payload" > "$fifo"
+  ) &
+  writer_pid=$!
+  deadline=$((SECONDS + 5))
+  while kill -0 "$writer_pid" 2>/dev/null; do
+    if [[ "$SECONDS" -ge "$deadline" ]]; then
+      kill -TERM "$writer_pid" 2>/dev/null || true
+      wait "$writer_pid" 2>/dev/null || true
+      return 124
+    fi
+    sleep 0.1
+  done
+  set +e
+  wait "$writer_pid"
+  rc=$?
+  set -e
+  return "$rc"
+}
+
 parse_stats_metadata() {
   local value="$1"
   local metadata_re='^\{"lane":"([a-z][a-z0-9-]*)","vendor":"('"$OMNILANE_VENDOR_ALT"')"(,|})'
@@ -280,6 +342,76 @@ case "${1:-}" in
   help|--help|-h)
     [[ "$JSON_MODE" -eq 0 && $# -eq 1 ]] || usage
     echo "$USAGE_TEXT" ;;
+  send)
+    [[ "$JSON_MODE" -eq 0 && $# -eq 3 ]] || usage
+    select_job "$2"
+    require_live_job
+    wait_for_live_ready
+    if [[ "${FOREMAN_SESSION+x}" == "x" ]]; then
+      foreman_value="$FOREMAN_SESSION"
+    else
+      foreman_value="${foreman_session-}"
+    fi
+    payload="$(printf '{"type":"user","omnilane_job_id":"%s","foreman_session":"%s","message":{"role":"user","content":[{"type":"text","text":"%s"}]}}' \
+      "$(json_escape "$2")" "$(json_escape "$foreman_value")" "$(json_escape "$3")")"
+    set +e
+    write_fifo_with_timeout "$JOB_DIR/inbox.fifo" "$payload"
+    send_rc=$?
+    set -e
+    [[ "$send_rc" -eq 0 ]] || die "$send_rc" "send timed out or failed; the live worker may be gone"
+    echo "sent $2"
+    ;;
+  watch)
+    [[ "$JSON_MODE" -eq 0 && $# -eq 2 ]] || usage
+    select_job "$2"
+    require_live_job
+    events_path="$JOB_DIR/events.jsonl"
+    watch_deadline=$((SECONDS + 5))
+    while [[ ! -f "$events_path" ]]; do
+      if [[ -e "$JOB_DIR/exit" || -L "$JOB_DIR/exit" ]]; then
+        die 1 "job has no live event stream"
+      fi
+      [[ "$SECONDS" -lt "$watch_deadline" ]] || die 124 "live event stream did not appear within 5s"
+      sleep 0.1
+    done
+    [[ ! -L "$events_path" ]] || die 1 "unsafe live event path"
+    if [[ -e "$JOB_DIR/exit" || -L "$JOB_DIR/exit" ]]; then
+      cat "$events_path"
+    else
+      tail -n +1 -f -- "$events_path"
+    fi
+    ;;
+  close)
+    [[ "$JSON_MODE" -eq 0 && $# -eq 2 ]] || usage
+    select_job "$2"
+    require_live_job
+    if [[ -e "$JOB_DIR/exit" || -L "$JOB_DIR/exit" ]]; then
+      read_exit_code "$JOB_DIR/exit" || die 1 "invalid recorded exit status"
+      echo "already closed (exit $RECORDED_EXIT)"
+      exit "$RECORDED_EXIT"
+    fi
+    holder_path="$JOB_DIR/inbox.holder.pid"
+    read_job_pid "$holder_path" || die 1 "live inbox holder is unavailable"
+    holder_pid="$RECORDED_PID"
+    kill -0 "$holder_pid" 2>/dev/null || die 1 "live inbox holder is gone"
+    kill -USR1 "$holder_pid" 2>/dev/null || die 1 "could not signal live inbox holder"
+    close_deadline=$((SECONDS + 10))
+    while [[ ! -e "$JOB_DIR/exit" && ! -L "$JOB_DIR/exit" ]]; do
+      if [[ "$SECONDS" -ge "$close_deadline" ]]; then
+        die 124 "close signal sent, but the live worker did not terminate within 10s"
+      fi
+      sleep 0.1
+    done
+    read_exit_code "$JOB_DIR/exit" || die 1 "invalid recorded exit status"
+    events_path="$JOB_DIR/events.jsonl"
+    result_count=0
+    if [[ -f "$events_path" && ! -L "$events_path" ]]; then
+      result_count="$(grep -Ec '"type"[[:space:]]*:[[:space:]]*"result"' "$events_path" || true)"
+      [[ "$result_count" =~ ^[0-9]+$ ]] || result_count=0
+    fi
+    echo "closed $2 (result_events=$result_count exit=$RECORDED_EXIT)"
+    exit "$RECORDED_EXIT"
+    ;;
   tail)
     # Peek at the live public output stream of one job (running or done)
     # without touching its exit contract. Only out.txt is shown; stderr and
@@ -427,13 +559,19 @@ case "${1:-}" in
         fi
         for artifact in "$job_dir"/*; do
           [[ -e "$artifact" || -L "$artifact" ]] || continue
-          if [[ -L "$artifact" ]]; then
-            audit_emit "$id" symlink-artifact
-            findings=$((findings + 1)); job_failed=1
-          elif [[ -d "$artifact" ]]; then
-            audit_emit "$id" nested-directory
-            findings=$((findings + 1)); job_failed=1
-          elif [[ -f "$artifact" ]]; then
+      if [[ -L "$artifact" ]]; then
+        audit_emit "$id" symlink-artifact
+        findings=$((findings + 1)); job_failed=1
+      elif [[ -d "$artifact" ]]; then
+        audit_emit "$id" nested-directory
+        findings=$((findings + 1)); job_failed=1
+      elif [[ -p "$artifact" && "${artifact##*/}" == "inbox.fifo" ]]; then
+        mode="$(path_mode "$artifact" 2>/dev/null || true)"
+        if [[ "$mode" != "600" ]]; then
+          audit_emit "$id" unsafe-fifo-mode
+          findings=$((findings + 1)); job_failed=1
+        fi
+      elif [[ -f "$artifact" ]]; then
             mode="$(path_mode "$artifact" 2>/dev/null || true)"
             if [[ "$mode" != "600" ]]; then
               audit_emit "$id" unsafe-file-mode
@@ -821,6 +959,9 @@ case "${1:-}" in
       else
         echo "running"
       fi
+    fi
+    if [[ "$JSON_MODE" -eq 0 ]]; then
+      print_mode_notice
     fi ;;
   wait)
     [[ "$JSON_MODE" -eq 0 && $# -ge 2 ]] || usage

package/scripts/lib/common.sh

@@ -64,6 +64,94 @@ write_current_pid_file() {
   mv "$tmp" "$path"
 }
 
+process_start_time() { # pid -> stable ps(1) start timestamp
+  local pid="$1" value
+  [[ "$pid" =~ ^[1-9][0-9]{0,9}$ ]] || return 1
+  value="$(LC_ALL=C ps -o lstart= -p "$pid" 2>/dev/null)" || return 1
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  [[ -n "$value" ]] || return 1
+  printf '%s\n' "$value"
+}
+
+process_parent_pid() {
+  local pid="$1" value
+  [[ "$pid" =~ ^[1-9][0-9]{0,9}$ ]] || return 1
+  value="$(LC_ALL=C ps -o ppid= -p "$pid" 2>/dev/null)" || return 1
+  value="${value//[[:space:]]/}"
+  [[ "$value" =~ ^[1-9][0-9]{0,9}$ ]] || return 1
+  printf '%s\n' "$value"
+}
+
+read_session_entry() { # path -> SESSION_ENTRY_{PID,START,ID}
+  local path="$1" fields rest
+  SESSION_ENTRY_PID=""
+  SESSION_ENTRY_START=""
+  SESSION_ENTRY_ID=""
+  [[ -f "$path" && ! -L "$path" ]] || return 1
+  fields="$(perl -MJSON::PP -e '
+    use strict;
+    use warnings;
+    my ($path) = @ARGV;
+    my $size = -s $path;
+    die "invalid size\n" unless defined($size) && $size <= 4096;
+    open my $fh, "<", $path or die $!;
+    local $/;
+    my $entry = decode_json(<$fh>);
+    close $fh or die $!;
+    die "invalid entry\n" unless ref($entry) eq "HASH";
+    my ($pid, $start, $id) = @{$entry}{qw(pid start_time session_id)};
+    die "invalid pid\n" if ref($pid) || !defined($pid) || $pid !~ /\A[1-9][0-9]{0,9}\z/;
+    die "invalid start\n" if ref($start) || !defined($start) ||
+      $start !~ /\A[ -~]{1,128}\z/;
+    die "invalid session\n" if ref($id) || !defined($id) ||
+      $id !~ /\A[A-Za-z0-9._:-]{1,256}\z/;
+    print "$pid\t$start\t$id";
+  ' "$path" 2>/dev/null)" || return 1
+  SESSION_ENTRY_PID="${fields%%$'\t'*}"
+  rest="${fields#*$'\t'}"
+  [[ "$rest" != "$fields" ]] || return 1
+  SESSION_ENTRY_START="${rest%%$'\t'*}"
+  SESSION_ENTRY_ID="${rest#*$'\t'}"
+  [[ "$SESSION_ENTRY_ID" != "$rest" ]] || return 1
+}
+
+prune_stale_session_entries() {
+  local sessions="$OMNILANE_HOME/sessions" entry live_start
+  [[ -d "$sessions" && ! -L "$sessions" ]] || return 0
+  for entry in "$sessions"/*.json; do
+    [[ -f "$entry" && ! -L "$entry" ]] || continue
+    read_session_entry "$entry" || continue
+    if ! live_start="$(process_start_time "$SESSION_ENTRY_PID")" ||
+       [[ "$live_start" != "$SESSION_ENTRY_START" ]]; then
+      rm "$entry" 2>/dev/null || true
+    fi
+  done
+}
+
+find_foreman_session() { # dispatch pid -> nearest live Claude foreman session
+  local pid="$1" sessions="$OMNILANE_HOME/sessions"
+  local parent start entry hops=0
+  [[ "$pid" =~ ^[1-9][0-9]{0,9}$ ]] || return 1
+  [[ -d "$sessions" && ! -L "$sessions" ]] || return 1
+  prune_stale_session_entries
+
+  while [[ "$hops" -lt 128 ]]; do
+    parent="$(process_parent_pid "$pid")" || return 1
+    [[ "$parent" =~ ^[1-9][0-9]{0,9}$ && "$parent" != "$pid" ]] || return 1
+    start="$(process_start_time "$parent")" || return 1
+    entry="$sessions/$parent.json"
+    if read_session_entry "$entry" &&
+       [[ "$SESSION_ENTRY_PID" == "$parent" && "$SESSION_ENTRY_START" == "$start" ]]; then
+      printf '%s\n' "$SESSION_ENTRY_ID"
+      return 0
+    fi
+    pid="$parent"
+    hops=$((hops + 1))
+  done
+  return 1
+}
+
 # ---- Vendor registry (single source of truth) ---------------------------
 # Two vendor kinds. CLI-agent vendors run a local binary (see vendor_bin).
 # Direct-API vendors are OpenAI-compatible /chat/completions endpoints driven

package/scripts/lib/i18n.sh

@@ -28,6 +28,14 @@ msg() { # key -> localized string ({} = placeholder, see msgf)
       case "$L" in zh-TW) echo "已偵測到——請自行執行:";; zh-CN) echo "已检测到——请自行执行:";; ja) echo "検出——次を手動で実行:";; ko) echo "감지됨——직접 실행하세요:";; *) echo "found — run this yourself:";; esac ;;
     plugin_hint)
       case "$L" in zh-TW) echo "(選配:把本 repo 裝成 Claude Code 外掛,可用 /route 指令)";; zh-CN) echo "(可选:把本仓库装成 Claude Code 插件,获得 /route 命令)";; ja) echo "(任意:このリポジトリを Claude Code プラグインとして追加すると /route コマンドが使えます)";; ko) echo "(선택: 이 저장소를 Claude Code 플러그인으로 추가하면 /route 명령 사용 가능)";; *) echo "(optional: add this repo as a Claude Code plugin for /route commands)";; esac ;;
+    completion_notice_active)
+      case "$L" in zh-TW) echo "Claude Code 完成通知：已啟用（omnilane@omnilane 外掛已啟用）。";; zh-CN) echo "Claude Code 完成通知：已启用（omnilane@omnilane 插件已启用）。";; ja) echo "Claude Code 完了通知: 有効です（omnilane@omnilane プラグインが有効）。";; ko) echo "Claude Code 완료 알림: 활성 상태입니다(omnilane@omnilane 플러그인 활성화됨).";; *) echo "Claude Code completion notice: active (omnilane@omnilane is enabled).";; esac ;;
+    completion_notice_unknown)
+      case "$L" in zh-TW) echo "Claude Code 完成通知：狀態未知（查不到外掛狀態）。";; zh-CN) echo "Claude Code 完成通知：状态未知（无法查询插件状态）。";; ja) echo "Claude Code 完了通知: 状態不明（プラグイン状態を確認できません）。";; ko) echo "Claude Code 완료 알림: 상태를 알 수 없습니다(플러그인 상태 조회 실패).";; *) echo "Claude Code completion notice: unknown (plugin state could not be queried).";; esac ;;
+    completion_notice_inactive)
+      case "$L" in zh-TW) echo "Claude Code 完成通知：未啟用。這項功能需要安裝外掛；只有 skill symlink 不會送達通知。";; zh-CN) echo "Claude Code 完成通知：未启用。此功能需要安装插件；只有 skill symlink 不会送达通知。";; ja) echo "Claude Code 完了通知: 無効です。この機能にはプラグインのインストールが必要で、skill symlink だけでは通知されません。";; ko) echo "Claude Code 완료 알림: 비활성 상태입니다. 이 기능은 플러그인 설치가 필요하며 skill symlink만으로는 알림이 전달되지 않습니다.";; *) echo "Claude Code completion notice: inactive. This feature requires the plugin install; the skill symlink alone does not deliver notices.";; esac ;;
+    completion_notice_install)
+      case "$L" in zh-TW) echo "請執行：";; zh-CN) echo "请执行：";; ja) echo "次を実行してください:";; ko) echo "다음을 실행하세요:";; *) echo "Run:";; esac ;;
     linked)
       case "$L" in zh-TW) echo "已連結";; zh-CN) echo "已链接";; ja) echo "リンクしました";; ko) echo "링크됨";; *) echo "linked";; esac ;;
     removed)