overclaude 1.0.0__py3-none-any.whl

overclaude/__init__.py

@@ -0,0 +1 @@
+"""overclaude — Claude Code, overclocked."""

overclaude/cli.py

@@ -0,0 +1,53 @@
+"""overclaude CLI — runs the bundled kit installer/uninstaller.
+
+The package wheel carries the same payload a git clone has (bin/, skills/,
+hooks/, statusline/, claude/, settings/, shell/, vendor/claude-swap, and the
+install/uninstall scripts). This CLI just locates that payload and runs the
+battle-tested bash scripts against it.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+from importlib.metadata import version as pkg_version
+from importlib.resources import files
+
+
+def _payload_dir():
+    p = files("overclaude").joinpath("payload")
+    path = str(p)
+    if not os.path.isdir(path) or not os.path.isfile(os.path.join(path, "install.sh")):
+        sys.exit("overclaude: bundled payload is missing — broken install; reinstall the package")
+    return path
+
+
+def _run_script(name):
+    return subprocess.call(["bash", os.path.join(_payload_dir(), name)])
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        prog="overclaude",
+        description="Claude Code, overclocked — /swap, /handoff, statusline, ULTRACODE model routing.",
+    )
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("install", help="install/refresh the kit into ~/.claude (idempotent, backs everything up)")
+    sub.add_parser("uninstall", help="remove exactly what install added (state in ~/.claude-swap-backup survives)")
+    sub.add_parser("path", help="print the bundled payload directory")
+    sub.add_parser("version", help="print the overclaude version")
+    args = ap.parse_args()
+
+    if args.cmd == "install":
+        sys.exit(_run_script("install.sh"))
+    if args.cmd == "uninstall":
+        sys.exit(_run_script("uninstall.sh"))
+    if args.cmd == "path":
+        print(_payload_dir())
+        return
+    if args.cmd == "version":
+        print(pkg_version("overclaude"))
+
+
+if __name__ == "__main__":
+    main()

overclaude/payload/bin/swap-guard

@@ -0,0 +1,352 @@
+#!/usr/bin/env bash
+# swap-guard — shared state/guard engine for the /swap + /handoff Claude Code integration.
+# Contract: section A of the binding interface contract.
+# Subcommands:
+#   whoami                          own session registry JSON (compact); exit 1 if not in a session
+#   sessions                        JSON array of OTHER live claude sessions (always exit 0)
+#   preflight <target>              switch-safety verdict JSON for slot number / alias / email (always exit 0)
+#   path flag|handoff [--cwd <dir>] print per-cwd state-file path
+#   flag <json>                     validate + fill + atomic-write relaunch flag; prints path (exit 1 on bad input)
+#   status                          own-session status JSON (always exit 0)
+#   cancel [--cwd <dir>]            remove pending handoff + flag for cwd (always exit 0)
+#   schedule-kill <pid>             v1 stub (exit 1)
+set -u
+
+STATE_ROOT="$HOME/.claude-swap-backup"
+CTX_DIR="$STATE_ROOT/ctx"
+ARCHIVE_DIR="$STATE_ROOT/handoff-archive"
+SESSIONS_DIR="$HOME/.claude/sessions"
+
+usage() {
+  cat >&2 <<'EOF'
+usage: swap-guard <subcommand> [args]
+  whoami                          own session registry JSON (compact)
+  sessions                        JSON array of other live claude sessions
+  preflight <target>              switch-safety verdict for slot / alias / email
+  path flag|handoff [--cwd <dir>] print per-cwd state-file path
+  flag <json>                     write relaunch flag ({"mode":"handoff"|"restart",...}); prints path
+  status                          own-session status JSON
+  cancel [--cwd <dir>]            remove pending handoff + flag for cwd
+  schedule-kill <pid>             phase-2 stub
+EOF
+  exit 2
+}
+
+# HASH(cwd) per shared constants: first 12 hex of sha256
+hash_cwd() { printf '%s' "$1" | /usr/bin/shasum -a 256 | awk '{print $1}' | cut -c1-12; }
+
+flag_path_for()    { printf '%s/relaunch-%s.json\n'      "$STATE_ROOT" "$(hash_cwd "$1")"; }
+pending_path_for() { printf '%s/handoff-pending-%s.md\n' "$STATE_ROOT" "$(hash_cwd "$1")"; }
+
+# whoami_json [start_pid] — walk the PPID chain from start_pid (default $$) up to pid 1;
+# print the first matching registry file's JSON (compact) and return 0, else return 1.
+whoami_json() {
+  local p="${1:-$$}"
+  while :; do
+    case "$p" in ''|*[!0-9]*) return 1;; esac
+    [ "$p" -gt 1 ] || return 1
+    if [ -f "$SESSIONS_DIR/$p.json" ]; then
+      jq -c . "$SESSIONS_DIR/$p.json" 2>/dev/null || cat "$SESSIONS_DIR/$p.json"
+      return 0
+    fi
+    p="$(ps -o ppid= -p "$p" 2>/dev/null | tr -d ' ')"
+  done
+}
+
+# session_live <pid> — true iff the process exists (kill -0) AND its comm contains "claude"
+session_live() {
+  local pid="${1:-}" comm
+  case "$pid" in ''|*[!0-9]*) return 1;; esac
+  kill -0 "$pid" 2>/dev/null || return 1
+  comm="$(ps -o comm= -p "$pid" 2>/dev/null)"
+  case "$comm" in *claude*) return 0;; *) return 1;; esac
+}
+
+# transcript_status <cwd> <sessionId> — activity fallback for sessions whose registry
+# file has no status field (clients < ~2.1.211 never publish one). An active session
+# appends to ~/.claude/projects/<flattened-cwd>/<sessionId>.jsonl on every turn, so:
+# mtime within TRANSCRIPT_ACTIVE_SECS -> "busy"; older -> "idle"; no transcript -> "unknown".
+TRANSCRIPT_ACTIVE_SECS=120
+transcript_status() {
+  local cwd="${1:-}" sid="${2:-}" t mtime now
+  [ -n "$cwd" ] && [ -n "$sid" ] || { printf 'unknown\n'; return 0; }
+  t="$HOME/.claude/projects/$(printf '%s' "$cwd" | sed 's/[^A-Za-z0-9]/-/g')/$sid.jsonl"
+  [ -f "$t" ] || { printf 'unknown\n'; return 0; }
+  mtime="$(stat -f %m "$t" 2>/dev/null)"
+  case "$mtime" in ''|*[!0-9]*) printf 'unknown\n'; return 0;; esac
+  now="$(date +%s)"
+  if [ $(( now - mtime )) -le "$TRANSCRIPT_ACTIVE_SECS" ]; then
+    printf 'busy\n'
+  else
+    printf 'idle\n'
+  fi
+}
+
+# sessions_json — JSON array of OTHER live sessions. status precedence: the value the
+# session itself reports (statusSource "reported") > transcript-mtime fallback
+# (statusSource "transcript-mtime") > "unknown" (statusSource "none").
+sessions_json() {
+  local own_pid="" out="[]" new_out f pid entry st
+  own_pid="$(whoami_json 2>/dev/null | jq -r '.pid // empty' 2>/dev/null)" || own_pid=""
+  for f in "$SESSIONS_DIR"/*.json; do
+    [ -f "$f" ] || continue
+    pid="$(jq -r '.pid // empty' "$f" 2>/dev/null)" || continue
+    [ -n "$pid" ] || continue
+    [ "$pid" = "$own_pid" ] && continue
+    session_live "$pid" || continue
+    entry="$(jq -c '{pid, sessionId, cwd, kind, entrypoint, status: (.status // "unknown"),
+      statusSource: (if .status then "reported" else "none" end)}' "$f" 2>/dev/null)" || continue
+    [ -n "$entry" ] || continue
+    if [ "$(printf '%s' "$entry" | jq -r '.statusSource' 2>/dev/null)" = "none" ]; then
+      st="$(transcript_status "$(printf '%s' "$entry" | jq -r '.cwd // empty')" \
+                              "$(printf '%s' "$entry" | jq -r '.sessionId // empty')")"
+      case "$st" in
+        busy|idle) entry="$(printf '%s' "$entry" | jq -c --arg s "$st" '.status = $s | .statusSource = "transcript-mtime"' 2>/dev/null)" || continue;;
+      esac
+    fi
+    new_out="$(printf '%s' "$out" | jq -c --argjson e "$entry" '. + [$e]' 2>/dev/null)" && [ -n "$new_out" ] && out="$new_out"
+  done
+  printf '%s\n' "$out"
+}
+
+# resolve_cwd [explicit] — precedence: explicit --cwd > whoami .cwd > $PWD
+resolve_cwd() {
+  local c="${1:-}"
+  if [ -z "$c" ]; then
+    c="$(whoami_json 2>/dev/null | jq -r '.cwd // empty' 2>/dev/null)" || c=""
+  fi
+  [ -n "$c" ] || c="$PWD"
+  printf '%s\n' "$c"
+}
+
+# parse_cwd_opt "$@" — echo value of --cwd/--cwd= if present; return 1 if absent
+parse_cwd_opt() {
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --cwd) shift; printf '%s\n' "${1:-}"; return 0;;
+      --cwd=*) printf '%s\n' "${1#--cwd=}"; return 0;;
+    esac
+    shift
+  done
+  return 1
+}
+
+cmd_whoami() {
+  local out
+  if out="$(whoami_json)"; then
+    printf '%s\n' "$out"
+    exit 0
+  fi
+  printf '%s\n' '{"error":"not-in-session"}'
+  exit 1
+}
+
+cmd_sessions() {
+  sessions_json
+  exit 0
+}
+
+cmd_preflight() {
+  local raw="${1:-}" busy busy_n list tgt slot="" verdict detail target_json number email us
+  busy="$(sessions_json | jq -c '[.[] | select(.status == "busy" or .status == "unknown")]' 2>/dev/null)" || busy="[]"
+  [ -n "$busy" ] || busy="[]"
+  busy_n="$(printf '%s' "$busy" | jq 'length' 2>/dev/null)" || busy_n=0
+
+  if [ -z "$raw" ]; then
+    jq -cn --argjson busy "$busy" \
+      '{verdict:"unknown-target",target:{number:null,email:null},busy:$busy,detail:"no target given"}'
+    exit 0
+  fi
+
+  list="$(cswap list --json 2>/dev/null)"
+  if [ -z "$list" ] || ! printf '%s' "$list" | jq -e . >/dev/null 2>&1; then
+    jq -cn --argjson busy "$busy" --arg t "$raw" \
+      '{verdict:"unknown-target",target:{number:null,email:null},busy:$busy,detail:("cswap list --json failed - cannot verify target " + ($t|tojson))}'
+    exit 0
+  fi
+
+  # Resolve target: digits -> slot number; else alias in sequence.json; else email
+  case "$raw" in
+    *[!0-9]*)
+      slot="$(jq -r --arg a "$raw" '.accounts | to_entries[] | select((.value.alias // "") == $a) | .key' \
+        "$STATE_ROOT/sequence.json" 2>/dev/null | head -n1)" || slot=""
+      ;;
+    *) slot="$raw";;
+  esac
+  if [ -n "$slot" ]; then
+    tgt="$(printf '%s' "$list" | jq -c --arg n "$slot" '[.accounts[]? | select((.number|tostring) == $n)] | first // empty' 2>/dev/null)"
+  else
+    tgt="$(printf '%s' "$list" | jq -c --arg e "$raw" '[.accounts[]? | select(((.email // "") | ascii_downcase) == ($e | ascii_downcase))] | first // empty' 2>/dev/null)"
+  fi
+
+  if [ -z "$tgt" ]; then
+    jq -cn --argjson busy "$busy" --arg t "$raw" \
+      '{verdict:"unknown-target",target:{number:null,email:null},busy:$busy,detail:("no account matches " + ($t|tojson) + " (not a slot number, alias, or email)")}'
+    exit 0
+  fi
+
+  target_json="$(printf '%s' "$tgt" | jq -c '{number, email}')"
+  number="$(printf '%s' "$tgt" | jq -r '.number')"
+  email="$(printf '%s' "$tgt" | jq -r '.email // ""')"
+  us="$(printf '%s' "$tgt" | jq -r '.usageStatus // ""' | tr '[:upper:]' '[:lower:]')"
+
+  case "$us" in
+    *login*|*quarantin*|*expired*|*invalid*|*revoked*)
+      verdict="relogin-required"
+      detail="account $number ($email) requires re-login (usageStatus: $us) - recover with /login then: cswap add --slot $number"
+      ;;
+    *)
+      if [ "$busy_n" -gt 0 ] 2>/dev/null; then
+        verdict="busy"
+        detail="account $number ($email) is healthy, but $busy_n other session(s) are busy or possibly-busy - a switch flips ALL sessions within ~30s"
+      else
+        verdict="ok"
+        detail="account $number ($email) is healthy and no other session is busy"
+      fi
+      ;;
+  esac
+
+  jq -cn --arg v "$verdict" --argjson t "$target_json" --argjson busy "$busy" --arg d "$detail" \
+    '{verdict:$v,target:$t,busy:$busy,detail:$d}'
+  exit 0
+}
+
+cmd_path() {
+  local kind="${1:-}"
+  [ $# -gt 0 ] && shift
+  local cwd_opt="" cwd
+  cwd_opt="$(parse_cwd_opt "$@")" || cwd_opt=""
+  cwd="$(resolve_cwd "$cwd_opt")"
+  case "$kind" in
+    flag)    flag_path_for "$cwd";;
+    handoff) pending_path_for "$cwd";;
+    *) usage;;
+  esac
+  exit 0
+}
+
+cmd_flag() {
+  local input="${1:-}"
+  if [ -z "$input" ] || ! printf '%s' "$input" | jq -e . >/dev/null 2>&1; then
+    echo "swap-guard flag: input is not valid JSON" >&2
+    exit 1
+  fi
+  local mode
+  mode="$(printf '%s' "$input" | jq -r '.mode // empty')"
+  case "$mode" in
+    handoff|restart) ;;
+    *) echo 'swap-guard flag: .mode must be "handoff" or "restart"' >&2; exit 1;;
+  esac
+  local sid cwd created out p tmp
+  sid="$(printf '%s' "$input" | jq -r '.sessionId // ""')"
+  cwd="$(printf '%s' "$input" | jq -r '.cwd // empty')"
+  cwd="$(resolve_cwd "$cwd")"
+  created="$(printf '%s' "$input" | jq -r '.created // empty' 2>/dev/null)"
+  case "$created" in ''|*[!0-9]*) created="$(date +%s)";; esac
+  out="$(jq -cn --arg m "$mode" --arg s "$sid" --arg c "$cwd" --argjson t "$created" \
+    '{mode:$m,sessionId:$s,cwd:$c,created:$t}')"
+  p="$(flag_path_for "$cwd")"
+  mkdir -p "$STATE_ROOT" 2>/dev/null || { echo "swap-guard flag: cannot create $STATE_ROOT" >&2; exit 1; }
+  tmp="$p.tmp.$$"
+  if printf '%s\n' "$out" > "$tmp" 2>/dev/null && mv "$tmp" "$p" 2>/dev/null; then
+    printf '%s\n' "$p"
+    exit 0
+  fi
+  rm -f "$tmp" 2>/dev/null
+  echo "swap-guard flag: write failed" >&2
+  exit 1
+}
+
+# _status_json <sessionId-or-empty> <cwd> — build the status JSON (factored for testability)
+_status_json() {
+  local sid="${1:-}" cwd="${2:-$PWD}"
+  local pct="" fired=0 bannered=0
+  if [ -n "$sid" ] && [ -f "$CTX_DIR/$sid.json" ]; then
+    pct="$(jq -r 'if (.pct|type) == "number" then (.pct|tostring) else "" end' "$CTX_DIR/$sid.json" 2>/dev/null)" || pct=""
+  fi
+  if [ -n "$sid" ] && [ -f "$CTX_DIR/$sid.state" ]; then
+    fired="$(jq -r '.fired // 0' "$CTX_DIR/$sid.state" 2>/dev/null)" || fired=0
+    bannered="$(jq -r '.bannered // 0' "$CTX_DIR/$sid.state" 2>/dev/null)" || bannered=0
+  fi
+  case "$fired" in ''|*[!0-9]*) fired=0;; esac
+  case "$bannered" in ''|*[!0-9]*) bannered=0;; esac
+
+  local h pending flagf pending_out="" page="" flag_out="" arch="" created
+  h="$(hash_cwd "$cwd")"
+  pending="$STATE_ROOT/handoff-pending-$h.md"
+  flagf="$STATE_ROOT/relaunch-$h.json"
+  if [ -f "$pending" ]; then
+    pending_out="$pending"
+    created="$(sed -n '1s/.*created="\([0-9][0-9]*\)".*/\1/p' "$pending" 2>/dev/null)"
+    [ -n "$created" ] || created="$(stat -f %m "$pending" 2>/dev/null)"
+    case "$created" in
+      ''|*[!0-9]*) page="";;
+      *) page="$(( $(date +%s) - created ))";;
+    esac
+  fi
+  [ -f "$flagf" ] && flag_out="$flagf"
+  if [ -d "$ARCHIVE_DIR" ]; then
+    arch="$(ls "$ARCHIVE_DIR" 2>/dev/null | grep -E -- "-$h(-expired)?\.md$" | sort | tail -n1)"
+    [ -n "$arch" ] && arch="$ARCHIVE_DIR/$arch"
+  fi
+
+  jq -cn --arg sid "$sid" --arg pct "$pct" --arg fired "$fired" --arg bannered "$bannered" \
+    --arg pending "$pending_out" --arg page "$page" --arg flagp "$flag_out" --arg arch "$arch" '
+    {sessionId: (if $sid == "" then null else $sid end),
+     pct: (if $pct == "" then null else ($pct|tonumber) end),
+     fired: ($fired|tonumber),
+     bannered: ($bannered|tonumber),
+     pendingHandoff: (if $pending == "" then null else $pending end),
+     pendingAgeSec: (if $page == "" then null else ($page|tonumber) end),
+     flag: (if $flagp == "" then null else $flagp end),
+     latestArchive: (if $arch == "" then null else $arch end)}'
+}
+
+cmd_status() {
+  local who sid="" cwd=""
+  if who="$(whoami_json 2>/dev/null)"; then
+    sid="$(printf '%s' "$who" | jq -r '.sessionId // empty' 2>/dev/null)" || sid=""
+    cwd="$(printf '%s' "$who" | jq -r '.cwd // empty' 2>/dev/null)" || cwd=""
+  fi
+  [ -n "$cwd" ] || cwd="$PWD"
+  _status_json "$sid" "$cwd"
+  exit 0
+}
+
+cmd_cancel() {
+  local cwd_opt="" cwd removed=0 f
+  cwd_opt="$(parse_cwd_opt "$@")" || cwd_opt=""
+  cwd="$(resolve_cwd "$cwd_opt")"
+  for f in "$(pending_path_for "$cwd")" "$(flag_path_for "$cwd")"; do
+    if [ -f "$f" ]; then
+      rm -f "$f" 2>/dev/null && { printf 'removed: %s\n' "$f"; removed=1; }
+    fi
+  done
+  [ "$removed" -eq 1 ] || printf 'nothing to remove for cwd %s\n' "$cwd"
+  exit 0
+}
+
+cmd_schedule_kill() {
+  echo "phase-2 feature not enabled" >&2
+  exit 1
+}
+
+main() {
+  local sub="${1:-}"
+  [ $# -gt 0 ] && shift
+  case "$sub" in
+    whoami)        cmd_whoami "$@";;
+    sessions)      cmd_sessions "$@";;
+    preflight)     cmd_preflight "$@";;
+    path)          cmd_path "$@";;
+    flag)          cmd_flag "$@";;
+    status)        cmd_status "$@";;
+    cancel)        cmd_cancel "$@";;
+    schedule-kill) cmd_schedule_kill "$@";;
+    *) usage;;
+  esac
+}
+
+if [ "${BASH_SOURCE[0]:-}" = "$0" ]; then
+  main "$@"
+fi

overclaude/payload/claude/ULTRACODE.md

@@ -0,0 +1,79 @@
+# ULTRACODE.md — Model & Effort Routing
+
+## 1. Core principle
+Spend fable only where judgment is the bottleneck, never where volume is: fable draws from a separate, much smaller rate-limit bucket, and omitting `opts.model` silently inherits it — every un-annotated `agent()` call is a fable spend.
+Explicit down-routing is your default posture, not an optimization.
+Route each agent by one question: "if this agent is quietly wrong, who catches it?" — a downstream agent means you may downgrade; nobody means top tier.
+
+## 2. Routing table
+| Task class | Model | Effort | Why |
+|---|---|---|---|
+| Scouting / file-listing | haiku | low | mechanical |
+| Bulk code reading / fact extraction | haiku (sonnet if dense) | low | extraction |
+| Mechanical transforms (rename, dedup, format) | haiku | low | deterministic |
+| Classify / extract into fixed `schema` | sonnet | low | ambiguity |
+| Finder sweeps (bug / perf) | sonnet | medium | recall |
+| Security sweeps | opus | high | asymmetry |
+| Implementation edits (well-scoped) | sonnet | medium | authorship |
+| Implementation edits (cross-cutting / tricky) | opus | high | judgment |
+| Adversarial verification / refutation votes | opus | high | precision |
+| Judge panel voters | opus | high | arbitration |
+| Judge chair / tie-break adjudicator | fable | xhigh | terminal |
+| Completeness critics | opus | high | gaps |
+| Final synthesis | fable (omit `model`) | xhigh | unrecoverable |
+
+Pairing rules:
+- Effort amplifies capability; it never substitutes. haiku@xhigh loses to sonnet@medium on judgment work; never pair xhigh with a fan-out stage.
+- Multiply tier by fan-out width BEFORE picking a model — fine at width 3 is a budget event at width 20. Any `parallel()` wider than ~5 gets an explicit haiku/sonnet.
+- Buy recall with width (more cheap finders over disjoint files); buy precision with tier (one strong verifier). Upstream misses get caught downstream; a false CONFIRM does not.
+- Width unknown until runtime? Route for the upper end of plausible width.
+
+## 3. Hard guardrails
+
+Never downgrade (floors, not targets):
+- Final synthesis, and ANY output the user sees without a downstream agent re-check: fable, never below opus. The trust boundary sets the floor, not the stage label.
+- Adversarial verification, judge panels, security verdicts, completeness critics: opus floor. A false CONFIRM ends scrutiny — nothing checks the checker.
+- Subtle-correctness verdicts (concurrency, auth/crypto, money math, data-loss migrations): fable. "Looks correct" and "is correct" diverge most here.
+
+Escalation rule (what makes cheap-first safe):
+- Give every finder/verifier a `schema` requiring `verdict` / `confidence` / `evidence`. Empty evidence IS low confidence, whatever number the agent reports.
+- Re-run once at a higher tier on: confidence < 0.7, UNSURE, empty/malformed output, or contradiction between parallel agents.
+- A CONFIRM/REFUTE split among voters escalates to one fable adjudicator — never majority-vote or average it; the split itself signals the question is hard.
+- Still UNSURE at the top tier? Surface it to the user. An honest "unresolved" is correct output; a manufactured verdict is a defect.
+
+Budget pressure (`budget.remaining()` thin, or fable bucket ~75%+ consumed):
+- Cut fan-out width and batch more files per agent FIRST; floors are the last thing to fall.
+- Treat fable as a read-only reserve: one highest-leverage call only (usually synthesis).
+- If the budget cannot cover the fable/opus terminal stages, say so and propose the cut — never silently ship a downgraded final answer.
+
+## 4. Example
+```js
+pipeline(files,
+  f  => agent(`List exports and structure of ${f}`,
+          { model: 'haiku', effort: 'low', label: 'scout (haiku/low)' }),
+  f  => agent(`Find bugs and perf issues in ${f}`,
+          { model: 'sonnet', effort: 'medium', schema: findingSchema,
+            label: 'find (sonnet/med)' }),                 // wide + cheap: recall
+  fs => agent(`Adversarially verify each finding; cite evidence; drop false positives`,
+          { model: 'opus', effort: 'high', schema: verdictSchema,
+            label: 'verify (opus/high)' })                 // narrow + strong: precision
+);
+// contested verdicts only — one strong judge beats five weak votes
+const ruling = await agent(`Adjudicate the CONFIRM/REFUTE splits`,
+  { model: 'fable', effort: 'xhigh', label: 'adjudicate (fable/xhigh)' });
+// model omitted DELIBERATELY: terminal stage inherits fable
+const report = await agent(`Synthesize the final review, ranked by severity`,
+  { effort: 'xhigh', label: 'synthesize (fable/xhigh)' });
+```
+A workflow that never touches fable is a valid — often good — outcome. Omission of `opts.model` should be rare, counted, and load-bearing.
+
+## 5. Routing lint (pre-flight — fix before dispatch, don't launch and patch)
+1. Every `agent()` call has an explicit `model`, or its omission is a deliberate apex spend. More than 2 omissions in one script = under-routing, not an apex-heavy task.
+2. No wide/parallel stage runs on opus or inherits fable; bulk stages sit at haiku/sonnet regardless of how the rest is routed.
+3. Verifiers, judges, and synthesis are at their floors — even under budget pressure.
+4. Every downgraded trusted-adjacent stage has a wired escalation trigger (confidence / UNSURE / contradiction → higher-tier re-run).
+5. `label` and `phase()` names embed the model tag (e.g. `verify (opus/high)`) — the user never opens the script to learn a stage ran on fable.
+
+## 6. Scope
+The same table binds the Agent tool's `model` param for one-off dispatches outside Workflow scripts: a lone bulk-reading agent is still a haiku job; a lone terminal judgment still earns opus or an intentional fable inheritance.
+The absence of a `pipeline()`/`parallel()` wrapper does not relax the discipline.

overclaude/payload/hooks/ctx-notify.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# ctx-notify.sh — Claude Code Stop hook.
+# Passive banner: when context usage sits in a threshold band that has not
+# been bannered yet, emit {"systemMessage": ...}. NEVER emits a "decision"
+# field. Contract: always exit 0, silent on every error path, defensive
+# jq parsing, no-op when stop_hook_active.
+exec 2>/dev/null
+
+# Thresholds.
+T1=60
+T2=75
+T3=85
+
+STATE_ROOT="$HOME/.claude-swap-backup"
+CTX_DIR="$STATE_ROOT/ctx"
+
+INPUT="$(cat)" || INPUT=""
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Never act on our own stop cycle.
+sha="$(jq -r '.stop_hook_active // false' <<<"$INPUT" 2>/dev/null)"
+[ "$sha" = "true" ] && exit 0
+
+session_id="$(jq -r '.session_id // empty' <<<"$INPUT" 2>/dev/null)"
+[ -n "$session_id" ] || exit 0
+
+# Relay pct (missing -> silent exit).
+relay="$CTX_DIR/$session_id.json"
+[ -f "$relay" ] || exit 0
+pct_raw="$(jq -r 'if (.pct|type) == "number" then .pct else empty end' "$relay" 2>/dev/null)"
+[ -n "$pct_raw" ] || exit 0
+pct="$(awk -v p="$pct_raw" 'BEGIN { printf "%d", p }')"
+case "$pct" in ''|*[!0-9]*) exit 0 ;; esac
+
+# State (missing/corrupt -> fired=0 bannered=0).
+state="$CTX_DIR/$session_id.state"
+fired=0
+bannered=0
+if [ -f "$state" ]; then
+    f="$(jq -r '.fired // 0' "$state" 2>/dev/null)"
+    b="$(jq -r '.bannered // 0' "$state" 2>/dev/null)"
+    case "$f" in 0|60|75|85) fired=$f ;; esac
+    case "$b" in 0|60|75|85) bannered=$b ;; esac
+fi
+
+# band = highest threshold <= pct (0 if < 60).
+band=0
+for t in "$T1" "$T2" "$T3"; do
+    [ "$pct" -ge "$t" ] && band=$t
+done
+
+if [ "$pct" -ge "$T1" ] && [ "$band" -gt "$bannered" ]; then
+    printf '{"systemMessage":"context %d%% — /handoff available"}\n' "$pct"
+    mkdir -p "$CTX_DIR" || exit 0
+    tmp="$state.tmp.$$"
+    printf '{"fired":%d,"bannered":%d}\n' "$fired" "$band" > "$tmp" && mv -f "$tmp" "$state"
+fi
+exit 0

overclaude/payload/hooks/ctx-watch.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# ctx-watch.sh — Claude Code UserPromptSubmit hook.
+# Reads the statusline relay for this session and, when context usage
+# crosses a new threshold, injects the handoff-offer note into the turn.
+# Contract: always exit 0, silent on every error path, defensive jq
+# parsing, no state writes on the /handoff | /swap skip path.
+exec 2>/dev/null
+
+# Thresholds (contract: variables at top).
+T1=60
+T2=75
+T3=85
+
+STATE_ROOT="$HOME/.claude-swap-backup"
+CTX_DIR="$STATE_ROOT/ctx"
+
+INPUT="$(cat)" || INPUT=""
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Skip path FIRST — before any state read/write.
+prompt="$(jq -r '.prompt // empty' <<<"$INPUT" 2>/dev/null)"
+case "$prompt" in
+    "/handoff"*|"/swap"*) exit 0 ;;
+esac
+
+session_id="$(jq -r '.session_id // empty' <<<"$INPUT" 2>/dev/null)"
+[ -n "$session_id" ] || exit 0
+
+# Relay pct (missing file / null / non-number -> silent exit).
+relay="$CTX_DIR/$session_id.json"
+[ -f "$relay" ] || exit 0
+pct_raw="$(jq -r 'if (.pct|type) == "number" then .pct else empty end' "$relay" 2>/dev/null)"
+[ -n "$pct_raw" ] || exit 0
+pct="$(awk -v p="$pct_raw" 'BEGIN { printf "%d", p }')"
+case "$pct" in ''|*[!0-9]*) exit 0 ;; esac
+
+# State (missing/corrupt -> fired=0 bannered=0).
+state="$CTX_DIR/$session_id.state"
+fired=0
+bannered=0
+if [ -f "$state" ]; then
+    f="$(jq -r '.fired // 0' "$state" 2>/dev/null)"
+    b="$(jq -r '.bannered // 0' "$state" 2>/dev/null)"
+    case "$f" in 0|60|75|85) fired=$f ;; esac
+    case "$b" in 0|60|75|85) bannered=$b ;; esac
+fi
+
+changed=0
+
+# Re-arm rule: if pct < fired-10 -> fired = highest threshold <= pct
+# (else 0), and bannered = min(bannered, fired).
+if [ "$pct" -lt $(( fired - 10 )) ]; then
+    new_fired=0
+    for t in "$T1" "$T2" "$T3"; do
+        [ "$pct" -ge "$t" ] && new_fired=$t
+    done
+    fired=$new_fired
+    [ "$bannered" -gt "$fired" ] && bannered=$fired
+    changed=1
+fi
+
+# Fire: highest threshold T with pct >= T and T > fired.
+T=0
+for t in "$T1" "$T2" "$T3"; do
+    [ "$pct" -ge "$t" ] && T=$t
+done
+if [ "$T" -gt "$fired" ]; then
+    printf '%s\n' "[context-watch] Context is at ${pct}%. After fully completing the user's current request, tell them context is filling up and OFFER /handoff to continue in a fresh session. Do NOT invoke the handoff skill yourself unless the user explicitly accepts in their own message — an offer you made is not acceptance. If they decline or ignore the offer, drop the subject; this notice will re-appear at the next threshold."
+    fired=$T
+    changed=1
+fi
+
+# Persist only when something changed (atomic write).
+if [ "$changed" -eq 1 ]; then
+    mkdir -p "$CTX_DIR" || exit 0
+    tmp="$state.tmp.$$"
+    printf '{"fired":%d,"bannered":%d}\n' "$fired" "$bannered" > "$tmp" && mv -f "$tmp" "$state"
+fi
+exit 0