overcodex 0.1.0__py3-none-any.whl

overcodex/payload/hooks/overcodex-handoff-inject.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# overcodex-handoff-inject.sh — Codex SessionStart hook.
+# Ported from overclaude's hooks/handoff-inject.sh. Injects a pending handoff
+# package for this cwd into the new session's context, then archives it.
+# Contract: always exit 0, silent on every error path, defensive jq parsing,
+# tolerate a missing state root.
+#
+# Schema notes (see config/hooks.json header for the full write-up):
+# session-start.command.input carries `source`: "startup"|"resume"|"clear"|
+# "compact". We act ONLY on "startup" — mirroring overclaude's Claude Code
+# matcher, which is also "startup"-only — so a mid-session /clear, a `codex
+# resume`, or the SessionStart that fires right after PreCompact's own
+# auto-compaction does not re-inject a stale package. This is a deliberate,
+# possibly-too-narrow choice: needs live validation that `codex resume` does
+# NOT also need this path (if handoff packages should survive a resume too,
+# widen to `startup|resume`).
+# session-start.command.output supports hookSpecificOutput.additionalContext
+# (hookEventName must echo "SessionStart") — that's how the package reaches
+# the new session; there is no plain-stdout passthrough the way Claude Code's
+# UserPromptSubmit works, so output MUST be well-formed JSON.
+exec 2>/dev/null
+set -u
+
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+STATE_ROOT="$CODEX_HOME/overcodex"
+ARCHIVE_DIR="$STATE_ROOT/handoff-archive"
+PENDING_TTL=600
+
+INPUT="$(cat)" || INPUT=""
+command -v jq >/dev/null 2>&1 || exit 0
+
+source_field="$(printf '%s' "$INPUT" | jq -r '.source // empty' 2>/dev/null)"
+[ "$source_field" = "startup" ] || exit 0
+
+cwd="$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)"
+[ -n "$cwd" ] || cwd="$PWD"
+
+# Pending-file path: codex-swap would be the canonical resolver if/when it
+# grows a `path handoff --cwd` subcommand (it does not, as of this writing —
+# it's an account-swap tool only); fall back to the shared hash convention
+# (identical result) unconditionally today. The probe is kept for forward
+# compatibility and is harmless: an unknown codex-swap subcommand prints usage
+# to stderr (redirected away) and exits non-zero, leaving P empty.
+P=""
+if command -v codex-swap >/dev/null 2>&1; then
+    P="$(codex-swap path handoff --cwd "$cwd" 2>/dev/null)"
+elif [ -x "$HOME/.local/bin/codex-swap" ]; then
+    P="$("$HOME/.local/bin/codex-swap" path handoff --cwd "$cwd" 2>/dev/null)"
+fi
+if [ -z "$P" ]; then
+    h="$(printf '%s' "$cwd" | /usr/bin/shasum -a 256 | awk '{print $1}' | cut -c1-12)"
+    [ -n "$h" ] || exit 0
+    P="$STATE_ROOT/handoff-pending-$h.md"
+fi
+
+[ -f "$P" ] || exit 0
+
+# Line 1 must be: <!-- handoff cwd="<abs>" created="<epoch-int>" -->
+header="$(head -n 1 "$P")"
+emb_cwd="$(printf '%s' "$header" | sed -n 's/^<!-- handoff cwd="\(.*\)" created="[0-9][0-9]*" -->[[:space:]]*$/\1/p')"
+emb_created="$(printf '%s' "$header" | sed -n 's/^<!-- handoff cwd=".*" created="\([0-9][0-9]*\)" -->[[:space:]]*$/\1/p')"
+
+# Malformed header -> leave file, silent.
+{ [ -n "$emb_cwd" ] && [ -n "$emb_created" ]; } || exit 0
+
+# cwd mismatch -> leave file, silent.
+[ "$emb_cwd" = "$cwd" ] || exit 0
+
+now="$(date +%s)"
+age=$(( now - emb_created ))
+
+# Archive name: <YYYYmmdd-HHMMSS>-<HASH>.md (UTC); hash taken from filename.
+base="${P##*/}"
+fhash="${base#handoff-pending-}"
+fhash="${fhash%.md}"
+ts="$(date -u +%Y%m%d-%H%M%S)"
+
+if [ "$age" -ge "$PENDING_TTL" ]; then
+    # Expired -> archive with -expired suffix, no output.
+    mkdir -p "$ARCHIVE_DIR" 2>/dev/null && mv -f "$P" "$ARCHIVE_DIR/$ts-$fhash-expired.md" 2>/dev/null
+    exit 0
+fi
+
+# Claim first (atomic mv), then read from the archived path — prevents a
+# concurrent same-cwd startup from injecting a dangling header after losing
+# the race for the pending file.
+A="$ARCHIVE_DIR/$ts-$fhash.md"
+{ mkdir -p "$ARCHIVE_DIR" && mv "$P" "$A"; } 2>/dev/null || exit 0
+
+body="$(tail -n +2 "$A" 2>/dev/null)"
+ctx="$(printf '%s\n\n%s' "## Handoff from previous session (loaded by handoff-inject)" "$body")"
+
+jq -n --arg ctx "$ctx" '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
+exit 0

overcodex/payload/hooks/overcodex-notify.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# overcodex-notify.sh — Codex Stop hook.
+# Ported from overclaude's hooks/ctx-notify.sh. Passive banner: when context
+# usage (derived from the rollout transcript — see overcodex-ctx-lib.sh) sits
+# in a threshold band that has not been bannered yet, emit
+# {"systemMessage": ...}. NEVER emits a "decision" field (stop.command.output
+# supports one, but we deliberately never touch it — this hook only informs,
+# it never blocks the turn). Contract: always exit 0, silent on every error
+# path, defensive jq parsing, no-op when stop_hook_active.
+exec 2>/dev/null
+set -u
+
+HOOKS_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)" || exit 0
+# shellcheck source=./overcodex-ctx-lib.sh
+. "$HOOKS_DIR/overcodex-ctx-lib.sh" 2>/dev/null || exit 0
+
+# Thresholds.
+T1=60
+T2=75
+T3=85
+
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+CTX_DIR="$CODEX_HOME/overcodex/ctx"
+
+INPUT="$(cat)" || INPUT=""
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Never act on our own stop cycle.
+sha="$(printf '%s' "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null)"
+[ "$sha" = "true" ] && exit 0
+
+session_id="$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)"
+[ -n "$session_id" ] || exit 0
+
+transcript_path="$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)"
+
+pct="$(ctx_pct_from_transcript "$transcript_path")" || exit 0
+case "$pct" in ''|*[!0-9]*) exit 0 ;; esac
+
+# State (missing/corrupt -> fired=0 bannered=0). Shared state file with
+# overcodex-ctx-watch.sh; see that script's header for the sharing contract.
+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
+    jq -n --arg msg "context ${pct}% - /prompts:handoff available" '{systemMessage: $msg}'
+    mkdir -p "$CTX_DIR" 2>/dev/null || exit 0
+    tmp="$state.tmp.$$"
+    printf '{"fired":%d,"bannered":%d}\n' "$fired" "$band" > "$tmp" 2>/dev/null && mv -f "$tmp" "$state" 2>/dev/null
+fi
+exit 0

overcodex/payload/hooks/overcodex-precompact-offer.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# overcodex-precompact-offer.sh — Codex PreCompact hook. No overclaude
+# equivalent (Claude Code has no PreCompact-shaped hook Claude actually
+# exposes on this axis the same way); added per spec because PreCompact is
+# the ONE moment we know for certain context is about to be destroyed:
+# pre-compact.command.input's `trigger` field is "auto" when Codex's OWN
+# model_auto_compact_token_limit was just crossed, or "manual" on an explicit
+# /compact. Since PreCompact fires only when compaction is actually about to
+# happen, this is inherently a rare, always-worth-surfacing event — no
+# threshold/hysteresis state is kept here (unlike ctx-watch/notify), and it
+# fires every time.
+#
+# pre-compact.command.output has NO hookSpecificOutput/additionalContext
+# field (confirmed against the embedded JSON Schema: only continue,
+# stopReason, suppressOutput, systemMessage) — unlike SessionStart/
+# UserPromptSubmit/PostToolUse/SubagentStart, PreCompact cannot inject
+# context into the turn (compaction is about to happen regardless). So this
+# is a passive systemMessage banner only, same mechanism as
+# overcodex-notify.sh's Stop banner — it is shown to the user, not fed to the
+# model as an instruction, so its wording addresses the human reading the
+# transcript rather than telling the model what to say.
+#
+# Contract: always exit 0, silent on every error path, defensive jq parsing,
+# never sets "decision" or "continue":false — this hook only informs.
+exec 2>/dev/null
+set -u
+
+INPUT="$(cat)" || INPUT=""
+command -v jq >/dev/null 2>&1 || exit 0
+
+trigger="$(printf '%s' "$INPUT" | jq -r '.trigger // empty' 2>/dev/null)"
+case "$trigger" in
+    auto)   why="Codex's auto-compact token limit was just reached" ;;
+    manual) why="a manual compact was requested" ;;
+    *)      exit 0 ;;
+esac
+
+jq -n --arg msg "context precompact (${trigger}) - ${why}; older turns are about to be summarized. This is the last chance to /prompts:handoff before that detail is gone." \
+    '{systemMessage: $msg}'
+exit 0

overcodex/payload/install.sh

@@ -0,0 +1,448 @@
+#!/bin/bash
+# install.sh — overcodex installer.
+# macOS /bin/bash 3.2 compatible. set -u; errors handled explicitly.
+# Reproduces the overcodex multi-account / ultracode setup for the Codex CLI.
+#
+# Never rewrites config.toml wholesale: top-level `hooks` and `[tui].status_line`
+# are only ADDED when absent (detected with python3+tomllib, grep fallback),
+# never overwritten. AGENTS.md and ~/.zshrc use begin/end marker blocks.
+
+set -u
+
+# ---------------------------------------------------------------------------
+# Locate the kit (this script lives at the repo root).
+# ---------------------------------------------------------------------------
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+
+# CODEX_HOME: honor the env var (relocatable state dir), else ~/.codex.
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+LOCALBIN="$HOME/.local/bin"
+ZSHRC="$HOME/.zshrc"
+
+CONFIG_TOML="$CODEX_HOME/config.toml"
+AGENTS_MD="$CODEX_HOME/AGENTS.md"
+
+# Kit sources.
+SRC_SWAP="$SCRIPT_DIR/bin/codex-swap"
+SRC_HOOKS_TPL="$SCRIPT_DIR/config/hooks-block.toml.tpl"
+SRC_AGENTS="$SCRIPT_DIR/codex/AGENTS-ULTRACODE.md"
+SRC_ZSNIPPET="$SCRIPT_DIR/shell/zshrc-snippet.sh"
+
+# Statusline TOML fragment (owned by the config builder). Optional; either name.
+SRC_STATUSLINE=""
+for c in "$SCRIPT_DIR/config/statusline.toml" "$SCRIPT_DIR/config/statusline"; do
+  [ -f "$c" ] && [ -s "$c" ] && { SRC_STATUSLINE="$c"; break; }
+done
+
+# Marker strings (must match uninstall.sh exactly).
+AGENTS_BEGIN='# --- overcodex ultracode (begin) ---'
+AGENTS_END='# --- overcodex ultracode (end) ---'
+ZSH_BEGIN='# --- overcodex integration (begin) ---'
+ZSH_END='# --- overcodex integration (end) ---'
+HOOKS_BEGIN='# --- overcodex hooks (begin) ---'
+HOOKS_END='# --- overcodex hooks (end) ---'
+SL_BEGIN='# --- overcodex statusline (begin) ---'
+SL_END='# --- overcodex statusline (end) ---'
+
+EPOCH=$(date +%s)
+
+# Summary accumulators (bash 3.2: plain indexed arrays).
+DID=()
+SKIPPED=()
+WARNED=()
+note_did()  { DID[${#DID[@]}]="$1";     echo "  [+] $1"; }
+note_skip() { SKIPPED[${#SKIPPED[@]}]="$1"; echo "  [=] $1"; }
+note_warn() { WARNED[${#WARNED[@]}]="$1";   echo "  [!] $1" >&2; }
+die()       { echo "install: ERROR: $1" >&2; exit 1; }
+
+echo "== overcodex installer =="
+echo "   kit:        $SCRIPT_DIR"
+echo "   CODEX_HOME: $CODEX_HOME"
+echo "   epoch:      $EPOCH"
+echo
+
+# ---------------------------------------------------------------------------
+# 0. Sanity: required kit files present.
+# ---------------------------------------------------------------------------
+for f in "$SRC_SWAP" "$SRC_HOOKS_TPL" "$SRC_AGENTS" "$SRC_ZSNIPPET"; do
+  [ -f "$f" ] || die "kit file missing: $f (run from the repo root)"
+done
+# At least one hook script.
+HOOK_SCRIPTS=$(ls "$SCRIPT_DIR"/hooks/*.sh 2>/dev/null)
+[ -n "$HOOK_SCRIPTS" ] || die "no hook scripts found under $SCRIPT_DIR/hooks/*.sh"
+
+# ---------------------------------------------------------------------------
+# 1. Dependency preflight.
+# ---------------------------------------------------------------------------
+echo "-- preflight --"
+
+# jq is required.
+if ! command -v jq >/dev/null 2>&1; then
+  die "jq is required but not found. Install it: brew install jq"
+fi
+echo "  [ok] jq: $(command -v jq)"
+
+# codex CLI: warn only (do not fail).
+if command -v codex >/dev/null 2>&1; then
+  echo "  [ok] codex: $(command -v codex)"
+else
+  note_warn "codex CLI not found on PATH. Install it, e.g.:"
+  note_warn "    brew install codex        (or)   npm install -g @openai/codex"
+  note_warn "  The kit installs fine without it, but codex must be present to use it."
+fi
+
+# python3 is preferred for TOML read/decide; grep is the fallback.
+PYTHON=""
+if command -v python3 >/dev/null 2>&1 && python3 -c 'import tomllib' >/dev/null 2>&1; then
+  PYTHON="python3"
+  echo "  [ok] python3 + tomllib: $(command -v python3)"
+else
+  note_warn "python3 with tomllib not found — using grep-based config.toml detection (best effort)."
+fi
+
+# CODEX_HOME: create if missing.
+if [ -d "$CODEX_HOME" ]; then
+  echo "  [ok] CODEX_HOME exists: $CODEX_HOME"
+else
+  mkdir -p "$CODEX_HOME" || die "could not create CODEX_HOME: $CODEX_HOME"
+  note_did "created CODEX_HOME: $CODEX_HOME"
+fi
+
+# PATH check for ~/.local/bin (where codex-swap lands).
+case ":$PATH:" in
+  *":$LOCALBIN:"*) echo "  [ok] $LOCALBIN is on PATH" ;;
+  *) note_warn "$LOCALBIN is not on your PATH. Add it so codex-swap is found:"
+     note_warn "    export PATH=\"\$HOME/.local/bin:\$PATH\"" ;;
+esac
+echo
+
+# ---------------------------------------------------------------------------
+# Helpers.
+# ---------------------------------------------------------------------------
+
+# backup_file <path> — timestamped backup if the file exists. Prints backup path.
+backup_file() {
+  bf_path="$1"
+  if [ -f "$bf_path" ]; then
+    cp -p "$bf_path" "$bf_path.bak-$EPOCH" || die "backup failed: $bf_path"
+    echo "$bf_path.bak-$EPOCH"
+  fi
+}
+
+# install_file <src> <dest> <mode|-> — copy with backup-on-change, chmod.
+# No backup, no copy when the destination is already identical (idempotent).
+install_file() {
+  if_src="$1"; if_dest="$2"; if_mode="$3"
+  mkdir -p "$(dirname "$if_dest")" || die "mkdir failed for $if_dest"
+  if [ -f "$if_dest" ]; then
+    if cmp -s "$if_src" "$if_dest"; then
+      [ "$if_mode" != "-" ] && chmod "$if_mode" "$if_dest" 2>/dev/null
+      note_skip "up-to-date: $if_dest"
+      return 0
+    fi
+    b=$(backup_file "$if_dest")
+    cp "$if_src" "$if_dest" || die "copy failed: $if_dest"
+    [ "$if_mode" != "-" ] && chmod "$if_mode" "$if_dest"
+    note_did "updated: $if_dest (backup: $b)"
+  else
+    cp "$if_src" "$if_dest" || die "copy failed: $if_dest"
+    [ "$if_mode" != "-" ] && chmod "$if_mode" "$if_dest"
+    note_did "installed: $if_dest"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# 2. File copies (per the FIXED DESTINATIONS contract).
+# ---------------------------------------------------------------------------
+echo "-- files --"
+
+install_file "$SRC_SWAP" "$LOCALBIN/codex-swap" 755
+
+# hooks/*.sh -> $CODEX_HOME/hooks/ (755)
+mkdir -p "$CODEX_HOME/hooks" || die "mkdir failed: $CODEX_HOME/hooks"
+for h in "$SCRIPT_DIR"/hooks/*.sh; do
+  [ -f "$h" ] || continue
+  install_file "$h" "$CODEX_HOME/hooks/$(basename "$h")" 755
+done
+
+# prompts/*.md -> $CODEX_HOME/prompts/  (optional)
+PROMPTS=$(ls "$SCRIPT_DIR"/prompts/*.md 2>/dev/null)
+if [ -n "$PROMPTS" ]; then
+  mkdir -p "$CODEX_HOME/prompts" || die "mkdir failed: $CODEX_HOME/prompts"
+  for p in "$SCRIPT_DIR"/prompts/*.md; do
+    [ -f "$p" ] || continue
+    install_file "$p" "$CODEX_HOME/prompts/$(basename "$p")" -
+  done
+else
+  note_skip "no prompts/*.md in kit (nothing to install)"
+fi
+echo
+
+# ---------------------------------------------------------------------------
+# 3. config.toml — add the inline [hooks] table and [tui].status_line IF ABSENT.
+#    Never rewrites the file: python3+tomllib decides presence; the hooks block
+#    is APPENDED at EOF between markers (a [hooks] table prepended at the top
+#    would capture every top-level key after it); status_line is a [tui] insert.
+# ---------------------------------------------------------------------------
+echo "-- config.toml --"
+
+# toml_present <config> -> prints "hooks=present|absent" and "sl=present|absent"
+# on stdout. Exits 3 on a parse error (caller then leaves the file untouched).
+toml_present() {
+  tp_cfg="$1"
+  if [ -n "$PYTHON" ]; then
+    "$PYTHON" - "$tp_cfg" <<'PY'
+import sys, tomllib
+p = sys.argv[1]
+try:
+    with open(p, "rb") as f:
+        d = tomllib.load(f)
+except FileNotFoundError:
+    d = {}
+except Exception as e:
+    sys.stderr.write("parse-error: %s\n" % e)
+    sys.exit(3)
+tui = d.get("tui")
+tui = tui if isinstance(tui, dict) else {}
+print("hooks=%s" % ("present" if "hooks" in d else "absent"))
+print("sl=%s" % ("present" if "status_line" in tui else "absent"))
+PY
+    return $?
+  fi
+  # grep fallback (heuristic: matches a top-level-looking key line).
+  if [ -f "$tp_cfg" ]; then
+    if grep -Eq '^[[:space:]]*hooks[[:space:]]*=' "$tp_cfg"; then
+      echo "hooks=present"; else echo "hooks=absent"; fi
+    if grep -Eq '^[[:space:]]*status_line[[:space:]]*=' "$tp_cfg"; then
+      echo "sl=present"; else echo "sl=absent"; fi
+  else
+    echo "hooks=absent"; echo "sl=absent"
+  fi
+  return 0
+}
+
+CFG_OK=1
+DET=$(toml_present "$CONFIG_TOML")
+if [ $? -eq 3 ]; then
+  CFG_OK=0
+  note_warn "config.toml is not valid TOML; leaving it completely untouched."
+  note_warn "  Fix $CONFIG_TOML, then re-run ./install.sh to wire hooks/status_line."
+fi
+
+if [ "$CFG_OK" = 1 ]; then
+  HOOKS_STATE=$(printf '%s\n' "$DET" | sed -n 's/^hooks=//p')
+  SL_STATE=$(printf '%s\n' "$DET" | sed -n 's/^sl=//p')
+
+  NEED_HOOKS=0
+  [ "$HOOKS_STATE" = absent ] && NEED_HOOKS=1
+
+  NEED_SL=0
+  if [ "$SL_STATE" = absent ]; then
+    if [ -n "$SRC_STATUSLINE" ]; then
+      NEED_SL=1
+    else
+      note_skip "no statusline fragment in kit — leaving [tui].status_line alone"
+    fi
+  fi
+
+  # Report the never-overwrite decisions.
+  if [ "$HOOKS_STATE" = present ]; then
+    if [ -f "$CONFIG_TOML" ] && grep -qF "$HOOKS_BEGIN" "$CONFIG_TOML"; then
+      note_skip "config.toml hooks key already wired by overcodex"
+    else
+      note_warn "config.toml already defines a 'hooks' key — leaving it untouched."
+      note_warn "  Merge the handlers from config/hooks-block.toml.tpl into your [hooks] table"
+      note_warn "  manually (substitute @HOOKS_DIR@ with $CODEX_HOME/hooks)."
+    fi
+  fi
+  if [ "$SL_STATE" = present ]; then
+    if [ -f "$CONFIG_TOML" ] && grep -qF "$SL_BEGIN" "$CONFIG_TOML"; then
+      note_skip "config.toml [tui].status_line already set by overcodex"
+    else
+      note_warn "config.toml already defines [tui].status_line — leaving it untouched."
+    fi
+  fi
+
+  if [ "$NEED_HOOKS" = 1 ] || [ "$NEED_SL" = 1 ]; then
+    b=""
+    [ -f "$CONFIG_TOML" ] && b=$(backup_file "$CONFIG_TOML")
+    TMP="$CONFIG_TOML.tmp-$EPOCH"
+    : > "$TMP" || die "cannot write $TMP"
+
+    # the existing file first, verbatim.
+    [ -f "$CONFIG_TOML" ] && cat "$CONFIG_TOML" >> "$TMP"
+
+    # hooks: APPEND the inline [hooks] table at EOF between markers, with
+    # @HOOKS_DIR@ resolved. (EOF is the only safe spot for a table block —
+    # prepended, it would capture the file's top-level keys.)
+    if [ "$NEED_HOOKS" = 1 ]; then
+      if [ -s "$TMP" ]; then
+        [ -n "$(tail -c1 "$TMP")" ] && printf '\n' >> "$TMP"
+        printf '\n' >> "$TMP"
+      fi
+      {
+        printf '%s\n' "$HOOKS_BEGIN"
+        sed "s|@HOOKS_DIR@|$CODEX_HOME/hooks|g" "$SRC_HOOKS_TPL"
+        printf '%s\n' "$HOOKS_END"
+      } >> "$TMP"
+    fi
+
+    # status_line: insert our keys just after an existing [tui] header, else
+    # append a fresh [tui] table at EOF. Fragment header/comment/blank lines are
+    # dropped so only the key lines land inside our markers.
+    if [ "$NEED_SL" = 1 ]; then
+      TMP2="$CONFIG_TOML.tmp2-$EPOCH"
+      awk -v sb="$SL_BEGIN" -v se="$SL_END" -v kf="$SRC_STATUSLINE" '
+        function emitkeys(   line) {
+          while ((getline line < kf) > 0) {
+            if (line == "" || line == "[tui]") continue
+            if (line ~ /^[ \t]*#/) continue
+            print line
+          }
+          close(kf)
+        }
+        { print }
+        /^[ \t]*\[tui\][ \t]*(#.*)?$/ && done != 1 {
+          print sb; emitkeys(); print se; done = 1
+        }
+        END {
+          if (done != 1) { print ""; print sb; print "[tui]"; emitkeys(); print se }
+        }
+      ' "$TMP" > "$TMP2" || die "awk failed inserting status_line"
+      mv "$TMP2" "$TMP" || die "could not stage status_line insert"
+    fi
+
+    # Validate before committing (python3 only; grep path trusts the insert).
+    if [ -n "$PYTHON" ]; then
+      "$PYTHON" - "$TMP" <<'PY' || { rm -f "$TMP"; die "generated config.toml is not valid TOML; original left untouched (backup: kept)"; }
+import sys, tomllib
+with open(sys.argv[1], "rb") as f:
+    tomllib.load(f)
+PY
+    fi
+
+    mv "$TMP" "$CONFIG_TOML" || die "could not write $CONFIG_TOML"
+    _bmsg=""
+    [ -n "$b" ] && _bmsg=" (backup: $b)"
+    [ "$NEED_HOOKS" = 1 ] && note_did "wired the inline [hooks] table into config.toml$_bmsg"
+    [ "$NEED_SL" = 1 ]    && note_did "set [tui].status_line in config.toml$_bmsg"
+  else
+    [ "$HOOKS_STATE" = absent ] || [ "$NEED_HOOKS" = 1 ] || true
+    note_skip "config.toml: no changes needed"
+  fi
+fi
+echo
+
+# ---------------------------------------------------------------------------
+# append_marked <target> <begin> <end> <src> <label>
+#   Append a marker-wrapped block only if the begin marker is absent. Any
+#   pre-existing overcodex marker lines in <src> are stripped so we never nest.
+# ---------------------------------------------------------------------------
+append_marked() {
+  am_target="$1"; am_begin="$2"; am_end="$3"; am_src="$4"; am_label="$5"
+  if [ -f "$am_target" ] && grep -qF "$am_begin" "$am_target"; then
+    note_skip "$am_label already present in $am_target"
+    return 0
+  fi
+  mkdir -p "$(dirname "$am_target")" || die "mkdir failed for $am_target"
+  b=""
+  [ -f "$am_target" ] && b=$(backup_file "$am_target")
+  # Separator blank line before our block when the file has content.
+  if [ -f "$am_target" ] && [ -s "$am_target" ]; then
+    [ -n "$(tail -c1 "$am_target")" ] && printf '\n' >> "$am_target"
+    printf '\n' >> "$am_target"
+  fi
+  {
+    printf '%s\n' "$am_begin"
+    # Drop any stray marker lines already in the source to avoid nesting.
+    grep -vxF "$am_begin" "$am_src" | grep -vxF "$am_end"
+    printf '%s\n' "$am_end"
+  } >> "$am_target" || die "could not append to $am_target"
+  if [ -n "$b" ]; then
+    note_did "appended $am_label to $am_target (backup: $b)"
+  else
+    note_did "created $am_target with $am_label"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# 4. AGENTS.md — append the ultracode block between markers (if absent).
+# ---------------------------------------------------------------------------
+echo "-- AGENTS.md --"
+append_marked "$AGENTS_MD" "$AGENTS_BEGIN" "$AGENTS_END" "$SRC_AGENTS" "overcodex ultracode block"
+echo
+
+# ---------------------------------------------------------------------------
+# 5. .zshrc — append the integration snippet between markers (if absent).
+# ---------------------------------------------------------------------------
+echo "-- .zshrc --"
+ZBEFORE_EXISTS=no
+[ -f "$ZSHRC" ] && grep -qF "$ZSH_BEGIN" "$ZSHRC" && ZBEFORE_EXISTS=yes
+append_marked "$ZSHRC" "$ZSH_BEGIN" "$ZSH_END" "$SRC_ZSNIPPET" "overcodex integration block"
+[ "$ZBEFORE_EXISTS" = no ] && note_warn "Open a new shell or run: source $ZSHRC"
+echo
+
+# ---------------------------------------------------------------------------
+# 6. Verify.
+# ---------------------------------------------------------------------------
+echo "-- verify --"
+
+# codex-swap resolves.
+if command -v codex-swap >/dev/null 2>&1 || [ -x "$LOCALBIN/codex-swap" ]; then
+  echo "  [ok] codex-swap resolves"
+else
+  note_warn "codex-swap does NOT resolve — is $LOCALBIN on PATH? (exec zsh, then re-check)"
+fi
+
+# hooks dir populated.
+if ls "$CODEX_HOME"/hooks/*.sh >/dev/null 2>&1; then
+  echo "  [ok] hooks dir populated: $CODEX_HOME/hooks/"
+else
+  note_warn "no hook scripts found under $CODEX_HOME/hooks/"
+fi
+
+# hooks key wired.
+HOOKS_WIRED=no
+if [ -n "$PYTHON" ] && [ -f "$CONFIG_TOML" ]; then
+  if "$PYTHON" - "$CONFIG_TOML" <<'PY' >/dev/null 2>&1
+import sys, tomllib
+with open(sys.argv[1], "rb") as f:
+    d = tomllib.load(f)
+sys.exit(0 if "hooks" in d else 1)
+PY
+  then HOOKS_WIRED=yes; fi
+elif [ -f "$CONFIG_TOML" ] && grep -Eq '^[[:space:]]*hooks[[:space:]]*=' "$CONFIG_TOML"; then
+  HOOKS_WIRED=yes
+fi
+if [ "$HOOKS_WIRED" = yes ]; then
+  echo "  [ok] config.toml hooks key wired"
+else
+  note_warn "config.toml has no hooks key — hooks will not load."
+fi
+
+# AGENTS marker present.
+if [ -f "$AGENTS_MD" ] && grep -qF "$AGENTS_BEGIN" "$AGENTS_MD"; then
+  echo "  [ok] AGENTS.md ultracode marker present"
+else
+  note_warn "AGENTS.md ultracode marker missing."
+fi
+echo
+
+# ---------------------------------------------------------------------------
+# Summary.
+# ---------------------------------------------------------------------------
+echo "== summary =="
+echo "  changed:  ${#DID[@]}"
+echo "  skipped:  ${#SKIPPED[@]}"
+echo "  warnings: ${#WARNED[@]}"
+if [ "${#WARNED[@]}" -gt 0 ]; then
+  echo "  -- warnings --"
+  i=0
+  while [ "$i" -lt "${#WARNED[@]}" ]; do
+    echo "    ! ${WARNED[$i]}"
+    i=$((i + 1))
+  done
+fi
+echo
+echo "Switch accounts with:  codex-swap  (isolated CODEX_HOME per account)."
+echo "Done."

overcodex/payload/prompts/handoff-cancel.md

@@ -0,0 +1,23 @@
+---
+description: "Remove a pending handoff package for this directory."
+argument-hint: ""
+---
+
+# /prompts:handoff-cancel — cancel a pending handoff
+
+## 1. Compute the state path
+
+Run exactly this (macOS /bin/bash 3.2 compatible):
+
+```bash
+HASH=$(printf '%s' "$PWD" | /usr/bin/shasum -a 256 | awk '{print $1}' | cut -c1-12)
+STATE_DIR="${CODEX_HOME:-$HOME/.codex}/overcodex"
+PENDING="$STATE_DIR/handoff-pending-$HASH.md"
+```
+
+## 2. Cancel
+
+- If `$PENDING` does not exist: report "no handoff pending for this directory — nothing to cancel."
+- If it exists: read line 1 for the `created` timestamp and line 2 for the goal, report them to the user ("removing pending handoff from <age> ago: '<goal>'"), then delete it: `rm "$PENDING"`.
+
+Only ever remove the single file for this cwd's hash — never glob-delete other pending packages under `$STATE_DIR`, they belong to other working directories.