@trailkeep/cli 0.0.0-stage → 0.3.1

package/bin/trailkeep

@@ -0,0 +1,1456 @@
+#!/bin/sh
+# trailkeep: two-layer context (global knowledge + per-branch task files) for
+# Claude Code, Codex CLI and GitHub Copilot CLI. POSIX sh + git, no other deps.
+# https://github.com/msiric/trailkeep
+
+set -u
+
+VERSION="0.3.1"
+PKG="@trailkeep/cli"
+MARKER="managed by trailkeep"
+
+# ---------------------------------------------------------------- paths ----
+
+resolve_self() {
+  # Portable "readlink -f" for this script (macOS ships no -f before 12.3).
+  p=$0
+  while [ -L "$p" ]; do
+    d=$(cd "$(dirname "$p")" && pwd -P)
+    l=$(readlink "$p")
+    case $l in /*) p=$l ;; *) p=$d/$l ;; esac
+  done
+  d=$(cd "$(dirname "$p")" && pwd -P)
+  printf '%s/%s\n' "$d" "$(basename "$p")"
+}
+
+SELF=$(resolve_self)
+ROOT=$(cd "$(dirname "$SELF")/.." && pwd -P)
+
+TRAILKEEP_HOME=${TRAILKEEP_HOME:-$HOME/.agents}
+PERSONAL=$TRAILKEEP_HOME/AGENTS.md
+REPOS=$TRAILKEEP_HOME/repos
+SKILLS_DIR=$HOME/.agents/skills          # read by Codex and Copilot
+BIN_DIR=${TRAILKEEP_BIN_DIR:-$HOME/.local/bin}
+CLAUDE_DIR=${CLAUDE_CONFIG_DIR:-$HOME/.claude}
+CODEX_DIR=${CODEX_HOME:-$HOME/.codex}
+COPILOT_DIR=${COPILOT_HOME:-$HOME/.copilot}
+# install copies the tool here and points every hook, link and the plugin at
+# it, so moving the clone, npm upgrades or switching Node versions never break
+# hooks (or Codex's per-hook trust).
+RUNTIME=$TRAILKEEP_HOME/trailkeep
+RT_BIN=$RUNTIME/bin/trailkeep
+MAX_CHARS=${TRAILKEEP_MAX_CHARS:-9000}    # Claude caps hook text at 10,000 chars
+case $MAX_CHARS in ''|*[!0-9]*) MAX_CHARS=9000 ;; esac
+[ "$MAX_CHARS" -gt 9500 ] && MAX_CHARS=9500
+
+# --------------------------------------------------------------- output ----
+
+if [ -t 1 ]; then
+  C_OK=$(printf '\033[32m'); C_WARN=$(printf '\033[33m'); C_FAIL=$(printf '\033[31m'); C_DIM=$(printf '\033[2m'); C_OFF=$(printf '\033[0m')
+else
+  C_OK=; C_WARN=; C_FAIL=; C_DIM=; C_OFF=
+fi
+
+say()  { printf '%s\n' "$*"; }
+ok()   { printf '%s  ok%s    %s\n' "$C_OK" "$C_OFF" "$*"; }
+warn() { printf '%s  warn%s  %s\n' "$C_WARN" "$C_OFF" "$*"; WARNS=$((WARNS + 1)); }
+fail() { printf '%s  fail%s  %s\n' "$C_FAIL" "$C_OFF" "$*"; FAILS=$((FAILS + 1)); }
+info() { printf '%s  info%s  %s\n' "$C_DIM" "$C_OFF" "$*"; }
+hint() { printf '        %s-> %s%s\n' "$C_DIM" "$*" "$C_OFF"; }
+die()  { printf 'trailkeep: %s\n' "$*" >&2; exit 1; }
+WARNS=0; FAILS=0
+
+# Pretty-print a path with ~ for $HOME.
+tilde() { case $1 in "$HOME"/*) printf '~/%s\n' "${1#"$HOME"/}" ;; *) printf '%s\n' "$1" ;; esac; }
+
+has() { command -v "$1" >/dev/null 2>&1; }
+
+# --------------------------------------------------------- dry-run fs ops ----
+
+DRY=0
+act() { # describe + perform unless dry-run; failures are counted
+  printf '  %s\n' "$1"
+  [ "$DRY" -eq 1 ] && return 0
+  shift
+  if ! "$@"; then
+    printf '%s  fail%s  the step above did not complete\n' "$C_FAIL" "$C_OFF"
+    FAILS=$((FAILS + 1))
+    return 1
+  fi
+}
+
+write_file() { # write_file PATH CONTENT
+  mkdir -p "$(dirname "$1")" && printf '%s\n' "$2" > "$1"
+}
+
+make_link() { mkdir -p "$(dirname "$1")" && ln -s "$2" "$1"; }
+move_file() { mkdir -p "$(dirname "$2")" && mv "$1" "$2"; }
+quiet() { "$@" >/dev/null; }
+
+# Put the trailkeep block at the top of FILE (replacing any old block).
+put_block() { # FILE BLOCK
+  mkdir -p "$(dirname "$1")" || return 1
+  tmp=$(mktemp) || return 1
+  [ -f "$1" ] && strip_block "$1" > "$tmp"
+  { printf '%s\n' "$2"; if [ -s "$tmp" ]; then printf '\n'; awk 'NF { p = 1 } p' "$tmp"; fi; } > "$1"
+  st=$?; rm -f "$tmp"; return $st
+}
+
+drop_block() { # FILE
+  tmp=$(mktemp)
+  strip_block "$1" | awk 'NF { p = 1 } p' > "$tmp"
+  cat "$tmp" > "$1"
+  rm -f "$tmp"
+}
+
+# Move the user's own lines from ~/.claude/CLAUDE.md into the personal file.
+adopt_claude_md() { # CLAUDE_MD PERSONAL
+  mkdir -p "$(dirname "$2")"
+  strip_block "$1" | awk 'NF { p = 1 } p' > "$2"
+  : > "$1"
+}
+
+backup() { # copy a file (following symlinks) into the backup dir before changing it
+  [ -f "$1" ] || return 0
+  [ "$DRY" -eq 1 ] && return 0
+  mkdir -p "$BACKUP_DIR" && cp "$1" "$BACKUP_DIR/$(printf '%s' "$1" | sed 's#/#_#g')"
+}
+BACKUP_DIR=$TRAILKEEP_HOME/backups/$(date +%Y%m%d-%H%M%S)
+
+# ------------------------------------------------------------ git helpers ----
+
+in_repo() { git rev-parse --is-inside-work-tree >/dev/null 2>&1; }
+
+# The main checkout (shared by all worktrees of the repo).
+main_checkout() {
+  cd_=$(git rev-parse --git-common-dir 2>/dev/null) || return 1
+  cd_=$(cd "$cd_" && pwd -P) || return 1
+  case $cd_ in */.git) dirname "$cd_" ;; *) printf '%s\n' "$cd_" ;; esac
+}
+
+# Stable key per repository: from the origin URL when there is one, so every
+# clone and worktree of the same repo shares notes and efforts.
+repo_key() {
+  url=$(git config --get remote.origin.url 2>/dev/null || true)
+  if [ -n "$url" ]; then
+    printf '%s\n' "$url" | sed \
+      -e 's#^[A-Za-z][A-Za-z0-9+.-]*://##' \
+      -e 's#^[^@/]*@##' \
+      -e 's#:#/#' \
+      -e 's#/*$##' -e 's#\.git$##' \
+      | tr 'A-Z' 'a-z' | sed -e 's#/#__#g' -e 's#[^a-z0-9._-]#_#g'
+  else
+    mc=$(main_checkout) || return 1
+    sum=$(printf '%s' "$mc" | cksum | cut -d' ' -f1)
+    printf 'local__%s-%s\n' "$(basename "$mc" | tr 'A-Z' 'a-z' | sed 's#[^a-z0-9._-]#_#g')" "$sum"
+  fi
+}
+
+current_branch() {
+  if [ -n "${TRAILKEEP_EFFORT:-}" ]; then printf '%s\n' "$TRAILKEEP_EFFORT"; return 0; fi
+  git symbolic-ref --quiet --short HEAD 2>/dev/null
+}
+
+branch_file_id() { printf '%s\n' "$1" | sed 's#/#__#g'; }
+
+repo_dir()    { printf '%s/%s\n' "$REPOS" "$1"; }
+notes_path()  { printf '%s/%s/NOTES.md\n' "$REPOS" "$1"; }
+worktree_top() { git rev-parse --show-toplevel 2>/dev/null; }
+# Efforts live in the worktree (inside every agent's writable workspace) under
+# a self-ignoring .trailkeep/ folder, so the repo's own files never change.
+effort_dir()  { printf '%s/.trailkeep\n' "$(worktree_top)"; }
+effort_path() { printf '%s/%s.md\n' "$(effort_dir)" "$(branch_file_id "$2")"; }
+
+ensure_effort_dir() {
+  d=$(effort_dir)
+  [ -e "$d" ] && [ ! -d "$d" ] && die "$d exists and is not a directory"
+  mkdir -p "$d" || die "could not create $d"
+  [ -f "$d/.gitignore" ] || printf '# trailkeep: keep this folder out of git\n*\n' > "$d/.gitignore"
+}
+
+need_repo() {
+  in_repo || die "not inside a git repository"
+  KEY=$(repo_key) || die "could not identify this repository"
+}
+
+need_branch() {
+  BRANCH=$(current_branch) || die "detached HEAD: check out a branch or set TRAILKEEP_EFFORT=<name>"
+  [ -n "$BRANCH" ] || die "detached HEAD: check out a branch or set TRAILKEEP_EFFORT=<name>"
+}
+
+remember_repo() { # best effort: note this worktree so `list` can find it (may be sandboxed)
+  d=$(repo_dir "$KEY"); w=$(worktree_top)
+  { mkdir -p "$d" && touch "$d/worktrees" && { grep -qxF "$w" "$d/worktrees" || printf '%s\n' "$w" >> "$d/worktrees"; }; } 2>/dev/null || true
+}
+
+# ------------------------------------------------------------------ text ----
+
+json_escape() {
+  tr -d '\000-\010\013\014\016-\037' | awk 'BEGIN { ORS = "" }
+    { gsub(/\\/, "\\\\"); gsub(/"/, "\\\""); gsub(/\t/, "\\t"); gsub(/\r/, "\\r")
+      if (NR > 1) printf "\\n"; printf "%s", $0 }'
+}
+
+# Extract a top-level string field from a small JSON object on stdin.
+json_field() {
+  sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n 1 | sed -e 's#\\/#/#g' -e 's#\\\\#\\#g'
+}
+
+chars() { wc -c < "$1" | tr -d ' '; }
+lines() { wc -l < "$1" | tr -d ' '; }
+
+# Lines of a "## Heading" section.
+section() { # section FILE HEADING
+  awk -v h="## $2" '$0 == h { on = 1; next } /^## / { on = 0 } on' "$1"
+}
+
+today() { date +%Y-%m-%d; }
+
+# --------------------------------------------------------------- context ----
+# Called by each agent's SessionStart hook. Prints nothing when there is
+# nothing to add, so repos without notes or efforts cost zero tokens.
+
+piece() { # piece LABEL PATH BUDGET -> prints the block, or a pointer if too big
+  n=$(chars "$2")
+  if [ "$n" -le "$3" ]; then
+    printf '%s (%s):\n' "$1" "$2"
+    cat "$2"
+  else
+    printf '%s is at %s (%s chars, over the trailkeep budget). Read that file before starting work.\n' "$1" "$2" "$n"
+  fi
+}
+
+default_branch() {
+  d=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null) && { printf '%s\n' "${d#origin/}"; return 0; }
+  for d in main master trunk develop; do git show-ref --verify --quiet "refs/heads/$d" && { printf '%s\n' "$d"; return 0; }; done
+  return 1
+}
+
+build_context() {
+  in_repo || return 0
+  KEY=$(repo_key) || return 0
+  notes=$(notes_path "$KEY")
+  effort=
+  if b=$(current_branch) && [ -n "$b" ]; then effort=$(effort_path "$KEY" "$b"); fi
+
+  has_notes=0; has_effort=0
+  [ -s "$notes" ] && has_notes=1
+  [ -n "$effort" ] && [ -s "$effort" ] && has_effort=1
+
+  budget=$MAX_CHARS
+  if [ "$has_notes" -eq 1 ]; then
+    piece "trailkeep: private notes for this repository" "$notes" "$((budget / 3))"
+    budget=$((budget - $(chars "$notes")))
+    [ "$budget" -lt $((MAX_CHARS / 2)) ] && budget=$((MAX_CHARS / 2))
+    printf '\n'
+  fi
+  if [ "$has_effort" -eq 1 ]; then
+    printf 'trailkeep: this branch has an effort file. It is the source of truth for the current task. Keep it current as you work: tick Plan items, add one dated line under Progress before you stop, and record decisions and dead ends (start a line with "Dead end:" for approaches that failed).\n'
+    piece "trailkeep: effort file for branch $b" "$effort" "$budget"
+    printf '\n'
+  elif [ "${TRAILKEEP_HINT:-1}" != 0 ] && [ -n "$effort" ] && db=$(default_branch) && [ "$b" != "$db" ]; then
+    printf 'trailkeep: no effort file for branch %s. If this task spans more than one session, run `trailkeep new` and keep it current.\n' "$b"
+  fi
+  n=0
+  for f in "$(log_dir "$KEY")"/*.tsv; do [ -f "$f" ] && n=$((n + $(lines "$f"))); done
+  if [ "$n" -gt 0 ]; then
+    printf 'trailkeep: this repo has a decision log (%s entries). Before changing code with history, or to learn why something is the way it is, run `trailkeep log --path <file>` or `trailkeep log --grep <word>`; `trailkeep log show <id>` gives one entry in full.\n' "$n"
+  fi
+}
+
+cmd_context() {
+  target=text
+  while [ $# -gt 0 ]; do
+    case $1 in
+      --for) target=${2:-}; shift 2 ;;
+      --for=*) target=${1#--for=}; shift ;;
+      *) die "context: unknown option $1" ;;
+    esac
+  done
+  case $target in claude|codex|copilot|text) ;; *) die "context: --for must be claude, codex, copilot or text" ;; esac
+
+  input=
+  if [ "$target" != text ] && [ ! -t 0 ]; then input=$(cat); fi
+  if [ -n "$input" ]; then
+    src=$(printf '%s' "$input" | json_field source)
+    # Resumed sessions already contain the earlier injection.
+    [ "$src" = resume ] && exit 0
+    cwd=$(printf '%s' "$input" | json_field cwd)
+    if [ -n "$cwd" ] && [ -d "$cwd" ]; then cd "$cwd" || exit 0; fi
+  fi
+
+  out=$(build_context 2>/dev/null) || out=
+  if [ -n "$(printf '%s' "$out" | tr -d '[:space:]')" ]; then
+    if [ "$target" = copilot ]; then
+      # Copilot only reads {"additionalContext": "..."} from sessionStart hooks.
+      printf '{"additionalContext":"%s"}\n' "$(printf '%s\n' "$out" | json_escape)"
+    else
+      printf '%s\n' "$out"
+    fi
+  fi
+  # After the output: pick up what a killed session didn't log, credited to that
+  # session, and remember this one. In the background so startup stays instant.
+  if [ "$target" != text ]; then
+    startup_harvest "$(session_ref "$target" "$input")" </dev/null >/dev/null 2>&1 &
+    [ -n "${TRAILKEEP_SYNC:-}" ] && wait
+  fi
+  exit 0
+}
+
+startup_harvest() { # NEW_SESSION
+  in_repo || return 0
+  KEY=$(repo_key) || return 0
+  ld=$(log_dir "$KEY")
+  mkdir -p "$ld/.seen" 2>/dev/null || return 0
+  w=$ld/.seen/last-session-$(worktree_top | cksum | cut -d' ' -f1)
+  prev=$(cat "$w" 2>/dev/null) || prev=
+  harvest "${prev:-unknown}" ""
+  [ -n "$1" ] && printf '%s\n' "$1" > "$w"
+  return 0
+}
+
+# ------------------------------------------------------------------- log ----
+# Append-only decision log, one file per repo per month:
+#   ~/.agents/repos/<repo>/log/YYYY-MM.tsv
+# One event per line, tab-separated:
+#   id  time  type  branch  commit  paths  text  session  transcript
+# Agents never write it (sandboxes would block that). They write Decisions and
+# Progress in the effort file; the session hooks copy new lines in here.
+
+TAB=$(printf '\t')
+
+log_dir() { printf '%s/log\n' "$(repo_dir "$1")"; }
+
+one_line() { tr '\t\r\n' '   ' | sed 's/  */ /g; s/^ //; s/ $//'; }
+
+new_id() { od -An -N4 -tx1 /dev/urandom | tr -d ' \n' | cut -c1-7; }
+
+log_append() { # KEY TYPE BRANCH COMMIT PATHS TEXT SESSION TRANSCRIPT
+  d=$(log_dir "$1")
+  mkdir -p "$d" 2>/dev/null || return 1
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(new_id)" "$(date +%Y-%m-%dT%H:%M)" "$2" "$3" "${4:--}" "${5:--}" \
+    "$(printf '%s' "$6" | one_line)" "${7:--}" "${8:--}" >> "$d/$(date +%Y-%m).tsv"
+}
+
+# All events for a repo, newest first.
+log_events() { # KEY
+  d=$(log_dir "$1")
+  for f in "$d"/*.tsv; do [ -f "$f" ] && cat "$f"; done | awk '{ a[NR] = $0 } END { for (i = NR; i > 0; i--) print a[i] }'
+}
+
+# Files touched since the last harvest on this branch (committed + uncommitted).
+# Files a branch touched since LAST (or since it split from the default
+# branch), excluding upstream changes merged in; plus uncommitted changes when
+# it's the current branch. Up to 50 paths.
+changed_paths() { # BRANCH LAST_SHA
+  tip=refs/heads/$1
+  git show-ref --verify --quiet "$tip" || tip=HEAD
+  set --  "$tip" "${2:-}"
+  excl=
+  if [ -n "$2" ] && git cat-file -e "$2^{commit}" 2>/dev/null; then excl=$2; fi
+  db=$(default_branch 2>/dev/null) || db=
+  { if [ -n "$excl" ] || { [ -n "$db" ] && [ "refs/heads/$db" != "$1" ]; }; then
+      # shellcheck disable=SC2086
+      git --no-optional-locks log --format= --name-only "$1" --not $excl ${db:+"refs/heads/$db"} 2>/dev/null
+    fi
+    if [ "$1" = HEAD ] || [ "$1" = "refs/heads/$(current_branch 2>/dev/null)" ]; then
+      git --no-optional-locks diff --name-only HEAD 2>/dev/null
+    fi; } | awk 'NF && !seen[$0]++' |
+  awk 'NR <= 50 { printf "%s%s", (NR > 1 ? "," : ""), $0 } END { if (NR > 50) printf ",+%d more", NR - 50 }'
+}
+
+# Copy new Decisions/Progress lines from the current branch's effort file into
+# the log, and archive efforts whose branches were deleted. Silent, best effort.
+# Serialise harvests per repo (session end and session start can overlap).
+lock_log() { # DIR
+  l=$1/.lock; i=0
+  while ! mkdir "$l" 2>/dev/null; do
+    if [ -n "$(find "$l" -prune -mmin +1 2>/dev/null)" ]; then rmdir "$l" 2>/dev/null; continue; fi
+    i=$((i + 1)); [ "$i" -ge 30 ] && return 1
+    sleep 0.1 2>/dev/null || sleep 1
+  done
+}
+unlock_log() { rmdir "$1/.lock" 2>/dev/null; }
+
+# A deleted branch that was really renamed: git's reflog says where it went.
+renamed_to() { # OLD_BRANCH
+  gd=$(git rev-parse --git-common-dir 2>/dev/null) || return 1
+  [ -d "$gd/logs/refs/heads" ] || return 1
+  grep -rhF "renamed refs/heads/$1 to refs/heads/" "$gd/logs/refs/heads" 2>/dev/null | tail -n 1 |
+    awk -v m="renamed refs/heads/$1 to refs/heads/" '{ i = index($0, m); if (i) print substr($0, i + length(m)) }' | awk 'NF'
+}
+
+# Copy one effort file's new Decisions/Progress lines into the log (one awk pass).
+harvest_file() { # FILE BRANCH SESSION TRANSCRIPT
+  seen=$ld/.seen/$(branch_file_id "$2")
+  touch "$seen" 2>/dev/null || return 0
+  new=$(awk -v tab="$TAB" -v seenf="$seen" '
+    BEGIN { while ((getline x < seenf) > 0) seen[x] = 1; close(seenf) }
+    /^## / { sec = ($0 == "## Decisions and dead ends") ? "decision" : ($0 == "## Progress") ? "progress" : ""; next }
+    sec != "" {
+      l = $0; sub(/^[[:space:]]*[-*][[:space:]]*/, "", l); gsub(/[\t\r]/, " ", l); sub(/[[:space:]]+$/, "", l)
+      if (l == "" || l ~ /^\[[ xX]\]/ || (l in seen)) next
+      seen[l] = 1; t = sec
+      if (l ~ /^([Dd]ead[ -]end|[Tt]ried |[Rr]ejected|[Rr]everted)/) t = "dead-end"
+      print t tab l
+    }' "$1")
+  [ -n "$new" ] || return 0
+  last=$(cat "$seen.sha" 2>/dev/null)
+  sha=$(git rev-parse --short "refs/heads/$2" 2>/dev/null || git rev-parse --short HEAD 2>/dev/null) || sha=-
+  paths=$(changed_paths "$2" "$last")
+  base=$(od -An -N3 -tx1 /dev/urandom | tr -d ' \n')
+  mkdir -p "$ld" 2>/dev/null || return 0
+  printf '%s\n' "$new" | awk -F "$TAB" -v OFS="$TAB" -v base="$base" -v ts="$(date +%Y-%m-%dT%H:%M)" \
+    -v br="$2" -v sha="${sha:--}" -v paths="${paths:--}" -v ses="${3:--}" -v tr="${4:--}" \
+    '{ printf "%s%x%s%s%s%s%s%s%s%s%s%s%s%s%s%s%s%s\n", base, NR, OFS, ts, OFS, $1, OFS, br, OFS, sha, OFS, paths, OFS, $2, OFS, ses, OFS, tr }' \
+    >> "$ld/$(date +%Y-%m).tsv" || return 0
+  printf '%s\n' "$new" | cut -f2- >> "$seen"
+  printf '%s\n' "$sha" > "$seen.sha"
+}
+
+# Harvest every effort in this worktree, follow renamed branches, then
+# archive efforts whose branches are gone. Silent, best effort, locked.
+harvest() { # SESSION TRANSCRIPT
+  in_repo || return 0
+  KEY=$(repo_key) || return 0
+  ld=$(log_dir "$KEY")
+  mkdir -p "$ld/.seen" 2>/dev/null || return 0
+  lock_log "$ld" || return 0
+  ed=$(effort_dir)
+  gone_efforts | while IFS="$TAB" read -r br f; do
+    [ -n "$f" ] || continue
+    nb=$(renamed_to "$br") || nb=
+    if [ -z "$nb" ] || ! git show-ref --verify --quiet "refs/heads/$nb"; then continue; fi
+    nf=$ed/$(branch_file_id "$nb").md
+    [ -e "$nf" ] && continue
+    sed "s/^Branch: .* · Repo:/Branch: $(printf '%s' "$nb" | sed 's/[&/\]/\\&/g') · Repo:/" "$f" > "$nf" && rm -f "$f"
+    for x in "" .sha; do [ -f "$ld/.seen/$(branch_file_id "$br")$x" ] && mv "$ld/.seen/$(branch_file_id "$br")$x" "$ld/.seen/$(branch_file_id "$nb")$x"; done
+    log_append "$KEY" note "$nb" - - "effort followed branch rename from $br" "$1" "$2"
+  done
+  for f in "$ed"/*.md; do
+    [ -f "$f" ] || continue
+    br=$(effort_branch "$f"); [ -n "$br" ] || continue
+    harvest_file "$f" "$br" "$1" "$2"
+  done
+  gone_efforts | while IFS="$TAB" read -r br f; do
+    [ -n "$f" ] || continue
+    if dest=$(archive_effort "$f" "$KEY"); then
+      log_append "$KEY" closed "$br" - - "effort auto-archived: branch deleted ($(tilde "$dest"))" "$1" "$2"
+    fi
+  done
+  unlock_log "$ld"
+  return 0
+}
+
+session_ref() { # TOOL JSON -> tool:session-id
+  sid=$(printf '%s' "$2" | json_field session_id)
+  [ -n "$sid" ] || sid=$(printf '%s' "$2" | json_field sessionId)
+  [ -n "$sid" ] && printf '%s:%s\n' "$1" "$sid"
+}
+
+cmd_harvest() { # hook entry point (session end)
+  target=text
+  case ${1:-} in --for) target=${2:-text} ;; --for=*) target=${1#--for=} ;; esac
+  input=
+  if [ "$target" != text ] && [ ! -t 0 ]; then input=$(cat); fi
+  if [ -n "$input" ]; then
+    cwd=$(printf '%s' "$input" | json_field cwd)
+    if [ -n "$cwd" ] && [ -d "$cwd" ]; then cd "$cwd" || exit 0; fi
+  fi
+  harvest "$(session_ref "$target" "$input")" "$(printf '%s' "$input" | json_field transcript_path)" >/dev/null 2>&1
+  exit 0
+}
+
+log_usage() {
+  cat <<EOF
+trailkeep log [--path P] [--grep TEXT] [--type T] [--branch B] [--since YYYY-MM-DD] [-n N]
+trailkeep log show ID
+trailkeep log add TYPE TEXT       types: decision, dead-end, progress, note
+EOF
+}
+
+cmd_log() {
+  need_repo
+  case ${1:-} in
+    show) shift; log_show "$@"; return ;;
+    add) shift; [ $# -ge 2 ] || die "usage: trailkeep log add TYPE TEXT"
+         typ=$1; shift
+         b=$(current_branch 2>/dev/null) || b=-
+         log_append "$KEY" "$typ" "${b:--}" "$(git rev-parse --short HEAD 2>/dev/null || echo -)" - "$*" "manual" - || die "could not write the log"
+         say "Logged."; return ;;
+    -h|--help|help) log_usage; return ;;
+  esac
+  fpath=; fgrep=; ftype=; fbranch=; fsince=; limit=20
+  while [ $# -gt 0 ]; do
+    case $1 in
+      --path|--grep|--type|--branch|--since|-n)
+        [ $# -ge 2 ] || die "$1 needs a value"
+        case $1 in
+          --path) fpath=$2 ;; --grep) fgrep=$2 ;; --type) ftype=$2 ;;
+          --branch) fbranch=$2 ;; --since) fsince=$2 ;; -n) limit=$2 ;;
+        esac
+        shift 2 ;;
+      *) log_usage >&2; exit 2 ;;
+    esac
+  done
+  if [ -n "$fpath" ]; then
+    # make the path repo-relative, like the logged ones
+    case $fpath in /*) top=$(worktree_top); fpath=${fpath#"$top"/} ;; *) fpath=$(git rev-parse --show-prefix 2>/dev/null)${fpath#./} ;; esac
+    fpath=${fpath%/}
+  fi
+  case $limit in ''|*[!0-9]*) die "-n needs a number" ;; esac
+  out=$(log_events "$KEY" | awk -F "$TAB" -v p="$fpath" -v g="$fgrep" -v t="$ftype" -v b="$fbranch" -v s="$fsince" -v n="$limit" '
+    function has_path(list, want,   k, parts, i) {
+      k = split(list, parts, ",")
+      for (i = 1; i <= k; i++) if (parts[i] == want || index(parts[i], want "/") == 1) return 1
+      return 0
+    }
+    (p == "" || has_path($6, p)) && (g == "" || index(tolower($7), tolower(g)) > 0) &&
+    (t == "" || $3 == t) && (b == "" || $4 == b) && (s == "" || substr($2, 1, 10) >= s) {
+      txt = $7; if (length(txt) > 140) txt = substr(txt, 1, 137) "..."
+      printf "%s  %s  %-8s  %s  %s  %s\n", $1, substr($2, 1, 10), $3, $4, $5, txt
+      if (++c >= n) exit
+    }')
+  if [ -n "$out" ]; then printf '%s\n' "$out"; else say "No matching log entries."; fi
+}
+
+log_show() { # ID (prefix ok)
+  [ -n "${1:-}" ] || die "usage: trailkeep log show ID"
+  line=$(log_events "$KEY" | awk -F "$TAB" -v id="$1" 'index($1, id) == 1 { print; exit }')
+  [ -n "$line" ] || die "no log entry $1"
+  printf '%s\n' "$line" | awk -F "$TAB" '{
+    print "id:         " $1; print "time:       " $2; print "type:       " $3; print "branch:     " $4
+    print "commit:     " $5 (($5 != "-") ? "   (git show " $5 ")" : "")
+    print "paths:      " $6; print "session:    " $8
+    if ($9 != "-") print "transcript: " $9
+    print ""; print $7 }'
+}
+
+# ----------------------------------------------------------- effort cmds ----
+
+effort_template() { # NAME KEY KIND
+  cat <<EOF
+# $1
+
+Branch: $1 · Repo: $2 · Kind: $3 · Created: $(today)
+
+## Goal
+
+
+## Done when
+
+
+## Plan
+
+- [ ] 
+
+## Progress
+
+
+## Decisions and dead ends
+
+
+## Open questions
+
+EOF
+}
+
+cmd_new() {
+  need_repo; need_branch
+  f=$(effort_path "$KEY" "$BRANCH")
+  if [ -e "$f" ]; then
+    say "Effort already exists: $f"
+    return 0
+  fi
+  kind=branch; [ -n "${TRAILKEEP_EFFORT:-}" ] && kind=named
+  ensure_effort_dir
+  effort_template "$BRANCH" "$KEY" "$kind" > "$f" || die "could not write $f"
+  remember_repo
+  say "Created $f"
+  say "Fill in Goal, Done when and Plan (or ask your agent to, with the effort skill)."
+}
+
+cmd_path() {
+  need_repo
+  case ${1:-} in
+    --notes) notes_path "$KEY" ;;
+    --repo) repo_dir "$KEY" ;;
+    --dir) effort_dir ;;
+    "") need_branch; effort_path "$KEY" "$BRANCH" ;;
+    *) die "path: unknown option $1" ;;
+  esac
+}
+
+cmd_show() {
+  need_repo
+  out=$(build_context)
+  if [ -n "$out" ]; then printf '%s\n' "$out"; else say "Nothing to inject for this repo/branch (no notes, no effort)."; fi
+}
+
+open_editor() {
+  ed=${VISUAL:-${EDITOR:-vi}}
+  # shellcheck disable=SC2086
+  $ed "$1"
+}
+
+cmd_edit() {
+  need_repo; need_branch
+  f=$(effort_path "$KEY" "$BRANCH")
+  [ -e "$f" ] || die "no effort for branch $BRANCH (run: trailkeep new)"
+  open_editor "$f"
+}
+
+cmd_notes() {
+  need_repo
+  f=$(notes_path "$KEY")
+  if [ "${1:-}" = --path ]; then printf '%s\n' "$f"; return 0; fi
+  if [ ! -e "$f" ]; then
+    mkdir -p "$(dirname "$f")"
+    printf '# Private notes: %s\n\n' "$KEY" > "$f"
+    remember_repo
+  fi
+  if [ -t 0 ] && [ -t 1 ]; then open_editor "$f"; else printf '%s\n' "$f"; fi
+}
+
+last_progress() {
+  section "$1" Progress | awk 'NF { l = $0 } END { print l }'
+}
+
+list_dir() { # print efforts in one .trailkeep dir
+  for f in "$1"/*.md; do
+    [ -e "$f" ] || continue
+    br=$(effort_branch "$f"); [ -n "$br" ] || br=$(basename "$f" .md)
+    lp=$(last_progress "$f")
+    printf '%s  %s  %s\n' "$2" "$br" "$(tilde "$(dirname "$1")")"
+    printf '    %s\n' "${lp:-(no progress yet)}"
+    LISTED=1
+  done
+}
+
+cmd_list() {
+  LISTED=0; seen=
+  for reg in "$REPOS"/*/worktrees; do
+    [ -f "$reg" ] || continue
+    key=$(basename "$(dirname "$reg")")
+    while IFS= read -r w; do
+      [ -d "$w/.trailkeep" ] || continue
+      case "
+$seen
+" in *"
+$w
+"*) continue ;; esac
+      seen="$seen
+$w"
+      list_dir "$w/.trailkeep" "$key"
+    done < "$reg"
+  done
+  if in_repo && KEY=$(repo_key); then
+    w=$(worktree_top)
+    case "
+$seen
+" in *"
+$w
+"*) ;; *) [ -d "$w/.trailkeep" ] && list_dir "$w/.trailkeep" "$KEY" ;; esac
+  fi
+  [ "$LISTED" -eq 1 ] || say "No active efforts."
+}
+
+archive_effort() { # FILE KEY -> prints destination; archive lives in ~/.agents, kept after the worktree is gone
+  a=$(repo_dir "$2")/archive
+  mkdir -p "$a" 2>/dev/null || return 1
+  dest=$a/$(today)-$(basename "$1")
+  n=1
+  while [ -e "$dest" ]; do dest=$a/$(today)-$n-$(basename "$1"); n=$((n + 1)); done
+  cp "$1" "$dest" 2>/dev/null || return 1
+  rm -f "$1"
+  printf '%s\n' "$dest"
+}
+
+cmd_close() {
+  need_repo; need_branch
+  f=$(effort_path "$KEY" "$BRANCH")
+  [ -e "$f" ] || die "no effort for branch $BRANCH"
+  dec=$(section "$f" "Decisions and dead ends" | awk 'NF')
+  harvest manual - >/dev/null 2>&1
+  dest=$(archive_effort "$f" "$KEY") || die "could not write to $(tilde "$(repo_dir "$KEY")") (sandboxed agent?). Run 'trailkeep close' yourself in a terminal."
+  log_append "$KEY" closed "$BRANCH" "$(git rev-parse --short HEAD 2>/dev/null || echo -)" - "effort closed ($(tilde "$dest"))" manual -
+  say "Archived to $dest"
+  if [ -n "$dec" ]; then
+    say ""
+    say "Decisions recorded for this effort. Promote any that every future task needs:"
+    printf '%s\n' "$dec"
+    say ""
+    say "  team-wide, not derivable from code -> repo AGENTS.md"
+    say "  private to you, this repo          -> trailkeep notes"
+    say "  you, every repo                    -> $(tilde "$PERSONAL")"
+  fi
+}
+
+effort_branch() { # original branch/effort name from the header line
+  sed -n 's/^Branch: \([^·]*\) ·.*/\1/p' "$1" | head -n 1 | sed 's/ *$//'
+}
+
+effort_kind() { if grep -q '^Branch: .* · Kind: named ·' "$1"; then echo named; else echo branch; fi; }
+
+# Efforts in this worktree whose branch no longer exists (named efforts never count).
+gone_efforts() {
+  cur=$(current_branch 2>/dev/null) || cur=
+  for f in "$(effort_dir)"/*.md; do
+    [ -e "$f" ] || continue
+    [ "$(effort_kind "$f")" = named ] && continue
+    br=$(effort_branch "$f")
+    [ -n "$br" ] || continue
+    [ "$br" = "$cur" ] && continue   # the branch you're on (maybe with no commits yet)
+    git show-ref --verify --quiet "refs/heads/$br" && continue
+    # still on a remote: not gone yet (it disappears after fetch --prune)
+    [ -n "$(git for-each-ref --format='%(refname)' "refs/remotes/*/$br" 2>/dev/null)" ] && continue
+    printf '%s\t%s\n' "$br" "$f"
+  done
+}
+
+cmd_prune() {
+  need_repo
+  apply=0; [ "${1:-}" = --apply ] && apply=1
+  list=$(gone_efforts)
+  if [ -z "$list" ]; then say "No efforts for deleted branches."; return 0; fi
+  printf '%s\n' "$list" | while IFS="$(printf '\t')" read -r br f; do
+    if [ "$apply" -eq 1 ]; then
+      d=$(archive_effort "$f" "$KEY") || die "could not write to $(tilde "$(repo_dir "$KEY")")"
+      say "archived $d  (branch $br is gone)"
+    else
+      say "$br  (branch gone)  $f"
+    fi
+  done
+  [ "$apply" -eq 1 ] || say "Run 'trailkeep prune --apply' to archive them."
+}
+
+# --------------------------------------------------------------- install ----
+
+claude_import_line() {
+  case $PERSONAL in
+    "$HOME"/*) printf '@~/%s\n' "${PERSONAL#"$HOME"/}" ;;
+    *) printf '@%s\n' "$PERSONAL" ;;
+  esac
+}
+
+claude_block() {
+  printf '<!-- trailkeep:begin (%s; edit %s instead) -->\n%s\n<!-- trailkeep:end -->\n' "$MARKER" "$(tilde "$PERSONAL")" "$(claude_import_line)"
+}
+
+strip_block() { # print FILE without the trailkeep block
+  awk '/^<!-- trailkeep:begin/ { skip = 1; next } skip && /^<!-- trailkeep:end -->[[:space:]]*$/ { skip = 0; next } !skip' "$1"
+}
+
+block_ok() { # FILE has no block, or exactly one well-formed block
+  b=$(grep -c '^<!-- trailkeep:begin' "$1" 2>/dev/null); e=$(grep -c '^<!-- trailkeep:end -->[[:space:]]*$' "$1" 2>/dev/null)
+  [ "${b:-0}" -eq "${e:-0}" ] && [ "${b:-0}" -le 1 ]
+}
+
+block_body() { awk '/^<!-- trailkeep:begin/ { s = 1; next } /^<!-- trailkeep:end -->[[:space:]]*$/ { s = 0; next } s' "$1"; }
+
+has_content() { # non-blank, non-comment content
+  [ -f "$1" ] && grep -v '^[[:space:]]*$' "$1" | grep -qv '^[[:space:]]*<!--.*-->[[:space:]]*$'
+}
+
+is_link_to() { [ -L "$1" ] && [ "$(readlink "$1")" = "$2" ]; }
+
+codex_hook_group() {
+  printf '      {\n        "matcher": "startup|clear|compact",\n        "hooks": [\n          { "type": "command", "command": "%s context --for codex", "timeout": 10 }\n        ]\n      }\n' "'$RT_BIN'"
+}
+
+codex_end_group() {
+  printf '      {\n        "hooks": [\n          { "type": "command", "command": "%s harvest --for codex", "timeout": 3 }\n        ]\n      }\n' "'$RT_BIN'"
+}
+
+codex_hooks_json() {
+  printf '{\n  "description": "%s: injects private repo notes and the active effort file, logs decisions at session end",\n  "hooks": {\n    "SessionStart": [\n%s\n    ],\n    "SessionEnd": [\n%s\n    ]\n  }\n}\n' "$MARKER" "$(codex_hook_group)" "$(codex_end_group)"
+}
+
+copilot_hook_entry() {
+  printf '      { "type": "command", "bash": "%s context --for copilot", "timeoutSec": 10 }\n' "'$RT_BIN'"
+}
+
+copilot_end_entry() {
+  printf '      { "type": "command", "bash": "%s harvest --for copilot", "timeoutSec": 5 }\n' "'$RT_BIN'"
+}
+
+copilot_hooks_json() {
+  printf '{\n  "version": 1,\n  "description": "%s",\n  "hooks": {\n    "sessionStart": [\n%s\n    ],\n    "sessionEnd": [\n%s\n    ]\n  }\n}\n' "$MARKER" "$(copilot_hook_entry)" "$(copilot_end_entry)"
+}
+
+# We own a hook file only if its description carries our marker.
+owned() { [ -f "$1" ] && grep -q "\"description\": \"$MARKER" "$1"; }
+
+personal_template() {
+  cat <<'EOF'
+# Personal instructions
+EOF
+}
+
+# Link a tool's global instruction file to the personal file.
+link_global() { # TOOL PATH
+  t=$2
+  if is_link_to "$t" "$PERSONAL"; then
+    ok "$1 global instructions -> $(tilde "$PERSONAL")"
+    return 0
+  fi
+  if [ -L "$t" ]; then
+    warn "$1: $(tilde "$t") is a link to $(readlink "$t"), left untouched"
+    hint "point it at $(tilde "$PERSONAL") yourself if you want trailkeep to manage it"
+    return 0
+  fi
+  if [ -e "$t" ]; then
+    if has_content "$t"; then
+      warn "$1: $(tilde "$t") has its own content, left untouched"
+      hint "merge it into $(tilde "$PERSONAL"), then run: trailkeep install  (or use --adopt)"
+      return 0
+    fi
+    backup "$t"
+    act "replace $(tilde "$t") with a link to $(tilde "$PERSONAL")" rm -f "$t"
+  fi
+  act "link $(tilde "$t") -> $(tilde "$PERSONAL")" make_link "$t" "$PERSONAL"
+}
+
+# Write a hook file we own; never overwrite one we don't.
+own_file() { # LABEL PATH CONTENT SNIPPET
+  if [ -e "$2" ] && ! owned "$2"; then
+    warn "$1: $(tilde "$2") exists and is not managed by trailkeep, left untouched"
+    hint "add these entries to it by hand:"
+    printf '%s\n' "$4" | sed 's/^/    /'
+    return 0
+  fi
+  if [ -e "$2" ] && [ "$(cat "$2")" = "$3" ]; then ok "$1: $(tilde "$2")"; return 0; fi
+  act "write $(tilde "$2")" write_file "$2" "$3"
+}
+
+adopt_sources() { # list global files that hold instructions we could adopt
+  if [ -f "$CLAUDE_DIR/CLAUDE.md" ]; then
+    tmp=$(mktemp); strip_block "$CLAUDE_DIR/CLAUDE.md" > "$tmp"
+    has_content "$tmp" && printf '%s\n' "$CLAUDE_DIR/CLAUDE.md"
+    rm -f "$tmp"
+  fi
+  for f in "$CODEX_DIR/AGENTS.md" "$COPILOT_DIR/copilot-instructions.md"; do
+    [ -L "$f" ] && continue
+    has_content "$f" && printf '%s\n' "$f"
+  done
+}
+
+ensure_personal() {
+  if [ -e "$PERSONAL" ]; then ok "personal instructions: $(tilde "$PERSONAL")"; return 0; fi
+  srcs=$(adopt_sources)
+  count=$(printf '%s' "$srcs" | awk 'NF' | wc -l | tr -d ' ')
+  if [ "$ADOPT" -eq 1 ]; then
+    if [ "$count" -eq 1 ]; then
+      backup "$srcs"
+      if [ "$srcs" = "$CLAUDE_DIR/CLAUDE.md" ]; then
+        act "move your instructions from $(tilde "$srcs") into $(tilde "$PERSONAL")" adopt_claude_md "$srcs" "$PERSONAL"
+        if [ -f "$PERSONAL" ] && prose_only "$PERSONAL" | grep -qE '(^|[[:space:]])@[^[:space:]]'; then
+          warn "the adopted text has @imports: they now resolve from $(tilde "$TRAILKEEP_HOME"), and Codex/Copilot don't expand them"
+          hint "inline what they point to, or make the paths absolute for Claude"
+        fi
+      else
+        act "move $(tilde "$srcs") to $(tilde "$PERSONAL")" move_file "$srcs" "$PERSONAL"
+      fi
+      return 0
+    elif [ "$count" -gt 1 ]; then
+      fail "--adopt: more than one global file has content; merge them by hand into $(tilde "$PERSONAL"):"
+      printf '%s\n' "$srcs" | sed 's/^/          /'
+      return 1
+    fi
+  elif [ "$count" -eq 1 ] && [ "$DRY" -eq 0 ] && [ -t 0 ] && [ -t 1 ] && [ -z "${CLAUDECODE:-}${CODEX_SANDBOX:-}${COPILOT_AGENT:-}" ]; then
+    printf '  Found your instructions in %s.\n  Move them to %s so Claude Code, Codex and Copilot all use them? [y/N] ' "$(tilde "$srcs")" "$(tilde "$PERSONAL")"
+    ans=; read -r ans || ans=
+    case $ans in [Yy]*) ADOPT=1; ensure_personal; return $? ;; esac
+  fi
+  if [ "$ADOPT" -eq 0 ] && [ "$count" -gt 0 ]; then
+    info "existing global instructions found (Codex/Copilot/Claude don't share them yet):"
+    printf '%s\n' "$srcs" | sed 's/^/          /'
+    hint "rerun with --adopt to move a single one into $(tilde "$PERSONAL")"
+  fi
+  act "create $(tilde "$PERSONAL")" write_file "$PERSONAL" "$(personal_template)"
+}
+
+install_claude() {
+  say ""; say "Claude Code"
+  f=$CLAUDE_DIR/CLAUDE.md
+  if [ -f "$f" ] && ! block_ok "$f"; then
+    fail "$(tilde "$f") has a broken or duplicated trailkeep block; fix it by hand (keep one begin/end pair)"
+  elif [ -f "$f" ] && grep -q '^<!-- trailkeep:begin' "$f"; then
+    if [ "$(block_body "$f")" = "$(claude_import_line)" ]; then
+      ok "$(tilde "$f") imports $(tilde "$PERSONAL")"
+    else
+      backup "$f"
+      act "refresh the trailkeep block in $(tilde "$f")" put_block "$f" "$(claude_block)"
+    fi
+  else
+    backup "$f"
+    act "add an import of $(tilde "$PERSONAL") to $(tilde "$f")" put_block "$f" "$(claude_block)"
+  fi
+
+  if ! has claude; then
+    warn "claude not on PATH: the hook plugin was not installed"
+    hint "install Claude Code, then rerun: trailkeep install"
+    return 0
+  fi
+  if claude plugin marketplace list 2>/dev/null | grep -q 'trailkeep'; then
+    act "refresh the trailkeep plugin marketplace" quiet claude plugin marketplace update trailkeep
+  else
+    act "add the trailkeep plugin marketplace ($(tilde "$RUNTIME"))" quiet claude plugin marketplace add "$RUNTIME" --scope user
+  fi
+  if claude plugin list 2>/dev/null | grep -q 'trailkeep@trailkeep'; then
+    act "update the trailkeep plugin (SessionStart hook + effort skill)" quiet claude plugin update trailkeep@trailkeep --scope user
+  else
+    act "install the trailkeep plugin (SessionStart hook + effort skill)" quiet claude plugin install trailkeep@trailkeep --scope user
+  fi
+}
+
+install_codex() {
+  say ""; say "Codex CLI"
+  link_global "Codex" "$CODEX_DIR/AGENTS.md"
+  if has_content "$CODEX_DIR/AGENTS.override.md"; then
+    warn "Codex: $(tilde "$CODEX_DIR/AGENTS.override.md") exists and wins over AGENTS.md"
+    hint "move its content into $(tilde "$PERSONAL") and delete it"
+  fi
+  own_file "Codex hooks" "$CODEX_DIR/hooks.json" "$(codex_hooks_json)" "SessionStart:
+$(codex_hook_group)
+SessionEnd:
+$(codex_end_group)"
+  info "Codex runs new hooks only after you trust them: open codex, run /hooks, and trust both trailkeep hooks (once per machine)"
+}
+
+install_copilot() {
+  say ""; say "Copilot CLI"
+  link_global "Copilot" "$COPILOT_DIR/copilot-instructions.md"
+  own_file "Copilot hooks" "$COPILOT_DIR/hooks/trailkeep.json" "$(copilot_hooks_json)" "sessionStart:
+$(copilot_hook_entry)
+sessionEnd:
+$(copilot_end_entry)"
+}
+
+install_skill() {
+  say ""; say "Effort skill"
+  link_skill "$SKILLS_DIR/effort" "Codex and Copilot"
+  # Copilot stops reading ~/.agents/skills when COPILOT_HOME is set.
+  [ -n "${COPILOT_HOME:-}" ] && link_skill "$COPILOT_DIR/skills/effort" "Copilot (COPILOT_HOME)"
+  ok "Claude Code gets the skill from the plugin (as trailkeep:effort)"
+}
+
+link_skill() { # PATH LABEL
+  if is_link_to "$1" "$RUNTIME/skills/effort"; then ok "$2: $(tilde "$1")"; return 0; fi
+  if [ -e "$1" ] || [ -L "$1" ]; then
+    warn "$(tilde "$1") already exists, left untouched"
+    return 0
+  fi
+  act "link $(tilde "$1") -> $(tilde "$RUNTIME/skills/effort")" make_link "$1" "$RUNTIME/skills/effort"
+}
+
+# Copy the tool into $RUNTIME (atomically swapped), remembering where it came from.
+install_runtime() {
+  if [ -d "$RUNTIME" ] && [ "$ROOT" = "$(cd "$RUNTIME" && pwd -P)" ]; then ok "runtime: $(tilde "$RUNTIME")"; return 0; fi
+  act "copy trailkeep $VERSION to $(tilde "$RUNTIME")" copy_runtime
+}
+
+copy_runtime() {
+  new=$RUNTIME.new.$$
+  rm -rf "$new" && mkdir -p "$new" || return 1
+  for x in bin hooks skills .claude-plugin README.md LICENSE; do
+    [ -e "$ROOT/$x" ] && { cp -R "$ROOT/$x" "$new/" || return 1; }
+  done
+  chmod +x "$new/bin/trailkeep"
+  src=git; [ -d "$ROOT/.git" ] || src=npm
+  case $ROOT in */node_modules/*) src=npm ;; esac
+  printf 'version=%s\nsource=%s\npath=%s\n' "$VERSION" "$src" "$ROOT" > "$new/.trailkeep-runtime"
+  if [ -e "$RUNTIME" ]; then
+    [ -f "$RUNTIME/.trailkeep-runtime" ] || { rm -rf "$new"; printf '%s exists and is not an trailkeep runtime\n' "$RUNTIME" >&2; return 1; }
+    rm -rf "$RUNTIME.old.$$" && mv "$RUNTIME" "$RUNTIME.old.$$" && mv "$new" "$RUNTIME" && rm -rf "$RUNTIME.old.$$"
+  else
+    mkdir -p "$(dirname "$RUNTIME")" && mv "$new" "$RUNTIME"
+  fi
+}
+
+install_bin() {
+  t=$BIN_DIR/trailkeep
+  if is_link_to "$t" "$RT_BIN"; then ok "command: $(tilde "$t")"; else
+    if [ -e "$t" ] && ! [ -L "$t" ]; then warn "$(tilde "$t") exists and is not a link, left untouched"; else
+      [ -L "$t" ] && act "remove old link $(tilde "$t")" rm -f "$t"
+      act "link $(tilde "$t") -> $(tilde "$RT_BIN")" make_link "$t" "$RT_BIN"
+    fi
+  fi
+  case ":$PATH:" in *":$BIN_DIR:"*) ;; *) warn "$(tilde "$BIN_DIR") is not on your PATH"; hint "add it in your shell rc so agents can run trailkeep" ;; esac
+}
+
+want() { # TOOL DIR -> should we configure this tool?
+  case " $SKIP " in *" $1 "*) return 1 ;; esac
+  has "$1" || [ -d "$2" ]
+}
+
+cmd_install() {
+  SKIP=; ADOPT=0; NO_SKILL=0
+  while [ $# -gt 0 ]; do
+    case $1 in
+      --dry-run) DRY=1 ;;
+      --adopt) ADOPT=1 ;;
+      --no-claude) SKIP="$SKIP claude" ;;
+      --no-codex) SKIP="$SKIP codex" ;;
+      --no-copilot) SKIP="$SKIP copilot" ;;
+      --no-skill) NO_SKILL=1 ;;
+      *) die "install: unknown option $1" ;;
+    esac
+    shift
+  done
+  [ "$DRY" -eq 1 ] && say "Dry run: nothing will change."
+  say "trailkeep $VERSION install"
+  say ""; say "Shared"
+  ensure_personal || exit 1
+  [ "$DRY" -eq 1 ] || mkdir -p "$REPOS"
+  install_runtime || { say "Could not set up $(tilde "$RUNTIME")."; exit 1; }
+  install_bin
+  any=0
+  if want claude "$CLAUDE_DIR"; then install_claude; any=1; fi
+  if want codex "$CODEX_DIR"; then install_codex; any=1; fi
+  if want copilot "$COPILOT_DIR"; then install_copilot; any=1; fi
+  [ "$any" -eq 1 ] || warn "no supported agent found (claude, codex, copilot)"
+  [ "$NO_SKILL" -eq 1 ] || install_skill
+  [ -d "$BACKUP_DIR" ] && { say ""; say "Backups of changed files: $(tilde "$BACKUP_DIR")"; }
+  say ""
+  if [ "$FAILS" -gt 0 ]; then say "$FAILS step(s) failed; see above."; exit 1; fi
+  say "Next: trailkeep doctor   (checks the setup)   then   trailkeep verify   (live test with each agent)"
+}
+
+# Replace the CLAUDE.md block with a plain copy of the personal file.
+inline_block() { # FILE
+  tmp=$(mktemp) || return 1
+  strip_block "$1" | awk 'NF { p = 1 } p' > "$tmp"
+  { cat "$PERSONAL"; if [ -s "$tmp" ]; then printf '\n'; cat "$tmp"; fi; } > "$1"
+  st=$?; rm -f "$tmp"; return $st
+}
+
+copy_over_link() { rm -f "$1" && cp "$PERSONAL" "$1"; }
+
+cmd_uninstall() {
+  say "trailkeep uninstall"
+  [ "${1:-}" = --dry-run ] && { DRY=1; say "Dry run: nothing will change."; }
+  f=$CLAUDE_DIR/CLAUDE.md
+  if [ -f "$f" ] && grep -q '^<!-- trailkeep:begin' "$f"; then
+    if block_ok "$f"; then
+      backup "$f"
+      act "replace the import in $(tilde "$f") with a copy of your personal instructions" inline_block "$f"
+    else
+      fail "$(tilde "$f") has a broken trailkeep block; remove it by hand"
+    fi
+  fi
+  if has claude; then
+    if claude plugin list 2>/dev/null | grep -q 'trailkeep@trailkeep'; then act "uninstall the Claude Code plugin" quiet claude plugin uninstall trailkeep@trailkeep --scope user; fi
+    if claude plugin marketplace list 2>/dev/null | grep -q 'trailkeep'; then act "remove the plugin marketplace" quiet claude plugin marketplace remove trailkeep; fi
+  fi
+  for l in "$CODEX_DIR/AGENTS.md" "$COPILOT_DIR/copilot-instructions.md"; do
+    if is_link_to "$l" "$PERSONAL"; then act "replace link $(tilde "$l") with a copy of your personal instructions" copy_over_link "$l"; fi
+  done
+  for h in "$CODEX_DIR/hooks.json" "$COPILOT_DIR/hooks/trailkeep.json"; do
+    if owned "$h"; then act "remove $(tilde "$h")" rm -f "$h"; fi
+  done
+  for sk in "$SKILLS_DIR/effort" "$COPILOT_DIR/skills/effort"; do
+    if is_link_to "$sk" "$RUNTIME/skills/effort"; then act "remove link $(tilde "$sk")" rm -f "$sk"; fi
+  done
+  if is_link_to "$BIN_DIR/trailkeep" "$RT_BIN"; then act "remove $(tilde "$BIN_DIR/trailkeep")" rm -f "$BIN_DIR/trailkeep"; fi
+  if [ -f "$RUNTIME/.trailkeep-runtime" ]; then act "remove $(tilde "$RUNTIME")" rm -rf "$RUNTIME"; fi
+  say ""
+  say "Each agent keeps a plain copy of your personal instructions."
+  say "Kept: $(tilde "$TRAILKEEP_HOME") (personal file, notes, archive) and any .trailkeep/ folders in your worktrees."
+  [ "$FAILS" -eq 0 ] || exit 1
+}
+
+runtime_field() { sed -n "s/^$1=//p" "$RUNTIME/.trailkeep-runtime" 2>/dev/null; }
+
+cmd_update() {
+  src=$(runtime_field source); path=$(runtime_field path)
+  [ -n "$src" ] || { src=git; [ -d "$ROOT/.git" ] || src=npm; path=$ROOT; }
+  dry=0; case " $* " in *" --dry-run "*) dry=1 ;; esac
+  case $src in
+    git)
+      [ -d "$path/.git" ] || die "the clone at $path is gone; clone trailkeep again and run install"
+      if [ "$dry" -eq 1 ]; then say "Dry run: would git pull $(tilde "$path"), then:"
+      else say "Updating $(tilde "$path")"; git -C "$path" pull --ff-only || die "git pull failed (local changes?)"; fi
+      exec "$path/bin/trailkeep" install "$@" ;;
+    npm)
+      has npm || die "npm not found"
+      if [ "$dry" -eq 1 ]; then say "Dry run: would run npm install -g $PKG@latest, then install"; exec "$RT_BIN" install "$@"; fi
+      say "Updating with npm"
+      npm install -g "$PKG@latest" || die "npm install failed"
+      np=$(npm root -g)/$PKG/bin/trailkeep
+      [ -x "$np" ] || die "trailkeep not found in $(npm root -g)"
+      exec "$np" install "$@" ;;
+  esac
+}
+
+# ---------------------------------------------------------------- doctor ----
+
+# Strip fenced code blocks and inline code spans (Claude ignores imports there).
+prose_only() {
+  awk '/^[[:space:]]*(```|~~~)/ { f = !f; next } !f' "$1" | sed 's/`[^`]*`//g'
+}
+
+check_imports() { # FILE
+  dir=$(dirname "$1")
+  prose_only "$1" | grep -oE '(^|[[:space:]])@[^[:space:]]+' | sed 's/^[[:space:]]*@//' | while IFS= read -r p; do
+    case $p in */*|*.*) ;; *) continue ;; esac   # @mentions are not imports
+    p=${p%[),.;:]}
+    case $p in
+      "~/"*) full=$HOME/${p#"~/"} ;;
+      /*) full=$p ;;
+      *) full=$dir/$p ;;
+    esac
+    if [ -e "$full" ]; then :; else
+      printf '%s\n' "$p"
+    fi
+  done
+}
+
+check_size() { # LABEL FILE
+  n=$(lines "$2")
+  if [ "$n" -gt 200 ]; then
+    warn "$1 is $n lines; Anthropic's guidance is under 200 (longer files reduce adherence)"
+    hint "move area-specific parts to path-scoped rules / nested AGENTS.md, procedures to skills"
+  else
+    ok "$1: $n lines"
+  fi
+}
+
+doctor_personal() {
+  say "Personal layer"
+  if [ -f "$PERSONAL" ]; then
+    check_size "$(tilde "$PERSONAL")" "$PERSONAL"
+    check_imports "$PERSONAL" | while IFS= read -r p; do warn "$(tilde "$PERSONAL"): '@$p' looks like an import but the file doesn't exist"; done
+    if prose_only "$PERSONAL" | grep -qE '(^|[[:space:]])@[^[:space:]]*[/.]'; then
+      info "imports in $(tilde "$PERSONAL") work in Claude Code only; Codex and Copilot see them as plain text"
+    fi
+  else fail "missing $(tilde "$PERSONAL")"; hint "run: trailkeep install"; fi
+
+  f=$CLAUDE_DIR/CLAUDE.md
+  if [ -f "$f" ] && grep -qF "$(claude_import_line)" "$f"; then
+    ok "Claude Code imports it ($(tilde "$f"))"
+    rest=$(mktemp); strip_block "$f" > "$rest"
+    has_content "$rest" && info "$(tilde "$f") also has its own lines; Codex and Copilot don't see those"
+    rm -f "$rest"
+  elif has claude || [ -d "$CLAUDE_DIR" ]; then fail "Claude Code does not import it"; hint "run: trailkeep install"; fi
+
+  for pair in "Codex:$CODEX_DIR/AGENTS.md:codex:$CODEX_DIR" "Copilot:$COPILOT_DIR/copilot-instructions.md:copilot:$COPILOT_DIR"; do
+    label=${pair%%:*}; rest=${pair#*:}; path=${rest%%:*}; rest=${rest#*:}; bin=${rest%%:*}; dir=${rest#*:}
+    has "$bin" || [ -d "$dir" ] || continue
+    if is_link_to "$path" "$PERSONAL"; then ok "$label reads it ($(tilde "$path"))"
+    else fail "$label does not read it ($(tilde "$path") is not a link to it)"; hint "run: trailkeep install"; fi
+  done
+  has_content "$CODEX_DIR/AGENTS.override.md" && warn "$(tilde "$CODEX_DIR/AGENTS.override.md") overrides your personal file in Codex"
+  say ""
+}
+
+# The hook files call this script by absolute path; catch a moved clone.
+hook_target_ok() { # LABEL FILE
+  p=$(sed -n "s/.*\"'\([^']*\)' context --for.*/\1/p" "$2" | head -n 1)
+  if [ -n "$p" ] && [ ! -x "$p" ]; then
+    fail "$1 hook points at $p, which no longer exists"
+    hint "run trailkeep install from the clone's current location"
+  fi
+}
+
+doctor_hooks() {
+  say "Session hooks"
+  if [ -x "$RT_BIN" ]; then ok "runtime $(runtime_field version) at $(tilde "$RUNTIME") ($(runtime_field source))"
+  else fail "runtime missing at $(tilde "$RUNTIME"), so every hook fails"; hint "run: trailkeep install"; fi
+  if has claude; then
+    if claude plugin list 2>/dev/null | grep -q 'trailkeep@trailkeep'; then ok "Claude Code plugin installed"
+    else fail "Claude Code plugin not installed"; hint "run: trailkeep install"; fi
+  fi
+  if has codex || [ -d "$CODEX_DIR" ]; then
+    if [ -f "$CODEX_DIR/hooks.json" ] && grep -q "trailkeep' context --for codex" "$CODEX_DIR/hooks.json"; then
+      ok "Codex hook configured"
+      grep -q "trailkeep' harvest --for codex" "$CODEX_DIR/hooks.json" || { warn "Codex session-end hook missing, decisions won't be logged"; hint "run: trailkeep install"; }
+      hook_target_ok "Codex" "$CODEX_DIR/hooks.json"
+      # Trust is stored in config.toml under a key like "file:<dir>/hooks.json:session_start:0:0".
+      if [ -f "$CODEX_DIR/config.toml" ] && grep -qF 'hooks.json:session_start' "$CODEX_DIR/config.toml" && grep -qF 'hooks.json:session_end' "$CODEX_DIR/config.toml"; then
+        ok "Codex hook has a trust entry in config.toml"
+        hint "Codex re-checks trust against the hook's exact definition; after reinstalling from a new path, trust it again in /hooks"
+      else
+        warn "Codex hooks not trusted yet, so they will not run"
+        hint "open codex, run /hooks, and trust both trailkeep hooks"
+      fi
+    else fail "Codex hook missing"; hint "run: trailkeep install"; fi
+  fi
+  if has copilot || [ -d "$COPILOT_DIR" ]; then
+    if [ -f "$COPILOT_DIR/hooks/trailkeep.json" ]; then ok "Copilot hook configured"; hook_target_ok "Copilot" "$COPILOT_DIR/hooks/trailkeep.json"
+      grep -q "harvest --for copilot" "$COPILOT_DIR/hooks/trailkeep.json" || { warn "Copilot session-end hook missing"; hint "run: trailkeep install"; }
+    else fail "Copilot hook missing"; hint "run: trailkeep install"; fi
+  fi
+  if has trailkeep; then ok "trailkeep on PATH"; else warn "trailkeep is not on PATH (agents can't run it)"; fi
+  say ""
+}
+
+# Codex: global file + one file per directory from git root to cwd, combined
+# limit project_doc_max_bytes (default 32 KiB).
+# Codex: one file per directory from the git root down to cwd. The combined
+# project files share project_doc_max_bytes (32 KiB); the global file doesn't count.
+codex_chain() { # ROOT CWD -> prints project files in load order
+  d=$1
+  rel=${2#"$1"}
+  printf '%s\n' "$d"
+  printf '%s\n' "$rel" | tr '/' '\n' | while IFS= read -r part; do
+    [ -n "$part" ] || continue
+    d=$d/$part
+    printf '%s\n' "$d"
+  done
+}
+
+doctor_repo() {
+  in_repo || { info "not in a git repository: skipped repo checks"; say ""; return 0; }
+  top=$(cd "$(git rev-parse --show-toplevel)" && pwd -P)
+  here=$(pwd -P)
+  say "Repository layer ($(tilde "$top"))"
+
+  # Files Claude Code loads from cwd up to / (the user-level ~/.claude/CLAUDE.md
+  # doesn't count: it never blocks AGENTS.md). Newline-separated: paths may contain spaces.
+  claude_files=; agents_files=
+  d=$here
+  while :; do
+    for n in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do
+      f=$d/$n
+      [ -f "$f" ] || continue
+      [ "$f" = "$CLAUDE_DIR/CLAUDE.md" ] && continue
+      claude_files="$claude_files$f
+"
+    done
+    for n in AGENTS.md .claude/AGENTS.md; do [ -f "$d/$n" ] && agents_files="$agents_files$d/$n
+"; done
+    [ "$d" = / ] && break
+    d=$(dirname "$d")
+  done
+
+  if [ -z "$claude_files$agents_files" ]; then
+    info "no AGENTS.md or CLAUDE.md here; fine for small repos"
+    hint "if you add one, write only what an agent can't learn from the code: exact commands, gotchas, decisions"
+  fi
+
+  printf '%s' "$claude_files$agents_files" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    case $f in "$top"/*) rel=${f#"$top"/} ;; *) rel=$(tilde "$f") ;; esac
+    check_size "$rel" "$f"
+    check_imports "$f" | while IFS= read -r p; do warn "$rel: '@$p' looks like an import but the file doesn't exist"; done
+    if prose_only "$f" | grep -qE '(^|[[:space:]])@(~/|/)'; then
+      info "$rel imports a ~/ or absolute path; Copilot CLI ignores those"
+    fi
+  done
+
+  # Claude Code reads AGENTS.md only when no CLAUDE.md exists (v2.1.277+).
+  if [ -n "$claude_files" ] && [ -n "$agents_files" ]; then
+    imported=$(printf '%s' "$claude_files" | while IFS= read -r c; do
+      [ -n "$c" ] && prose_only "$c" | grep -qE '(^|[[:space:]])@(\./)?AGENTS\.md' && echo yes
+    done)
+    if [ -z "$imported" ]; then
+      first=$(printf '%s' "$claude_files" | head -n 1)
+      warn "$(tilde "$first") exists, so Claude Code ignores AGENTS.md here"
+      hint "add '@AGENTS.md' to it, or delete it if it holds nothing Claude-specific"
+    fi
+  fi
+  printf '%s' "$claude_files" | while IFS= read -r c; do
+    [ -n "$c" ] || continue
+    if [ "$(prose_only "$c" | awk 'NF' | grep -v '^[[:space:]]*<!--.*-->[[:space:]]*$')" = "@AGENTS.md" ]; then
+      info "$(tilde "$c") only imports AGENTS.md; Claude Code 2.1.277+ reads AGENTS.md itself, so it can go"
+    fi
+  done
+
+  total=0
+  chain=$(codex_chain "$top" "$here")
+  # (a subshell-free loop so $total survives)
+  oldifs=$IFS; IFS='
+'
+  for dir in $chain; do
+    for n in AGENTS.override.md AGENTS.md; do
+      if [ -s "$dir/$n" ]; then total=$((total + $(chars "$dir/$n"))); break; fi
+    done
+  done
+  IFS=$oldifs
+  if [ "$total" -gt 32768 ]; then
+    fail "Codex project instructions are $total bytes; Codex stops at 32768 (project_doc_max_bytes), the rest is dropped"
+  elif [ "$total" -gt 24576 ]; then
+    warn "Codex project instructions are $total bytes, close to the 32768 limit"
+  elif [ "$total" -gt 0 ]; then
+    ok "Codex project instructions: $total of 32768 bytes"
+  fi
+  say ""
+}
+
+doctor_task() {
+  in_repo || return 0
+  KEY=$(repo_key) || return 0
+  say "Task layer (key: $KEY)"
+  n=$(notes_path "$KEY")
+  if [ -s "$n" ]; then ok "private notes: $(chars "$n") chars"; else info "no private notes (trailkeep notes)"; fi
+  d=$(effort_dir)
+  if [ -d "$d" ] && [ -n "$(git -C "$(worktree_top)" status --porcelain --ignored=no -- .trailkeep 2>/dev/null)" ]; then
+    fail ".trailkeep/ is not ignored by git, so efforts could get committed"
+    hint "restore $(tilde "$d/.gitignore") with a single line: *"
+  fi
+  if b=$(current_branch) && [ -n "$b" ]; then
+    e=$(effort_path "$KEY" "$b")
+    if [ -s "$e" ]; then ok "effort for $b: $(lines "$e") lines, $(chars "$e") chars"
+    else info "no effort for branch $b (trailkeep new)"; fi
+  else info "detached HEAD: no effort lookup"; fi
+  out=$(build_context 2>/dev/null)
+  case $out in *"over the trailkeep budget"*)
+    warn "notes or effort are too big to inject, so agents only get a pointer to them"
+    hint "fold old Progress lines into a summary; notes get up to $((MAX_CHARS / 3)) chars, the effort the rest of $MAX_CHARS" ;;
+  esac
+  n=0; for f in "$(log_dir "$KEY")"/*.tsv; do [ -f "$f" ] && n=$((n + $(lines "$f"))); done
+  if [ "$n" -gt 0 ]; then ok "decision log: $n entries (trailkeep log)"; else info "decision log is empty (it fills from effort files at session end)"; fi
+  gone=$(gone_efforts | awk 'NF' | wc -l | tr -d ' ')
+  if [ "$gone" -gt 0 ]; then warn "$gone effort(s) belong to deleted branches"; hint "trailkeep prune --apply"; fi
+  say ""
+}
+
+cmd_doctor() {
+  say "trailkeep $VERSION doctor"
+  say ""
+  doctor_personal
+  doctor_hooks
+  doctor_repo
+  doctor_task
+  if [ "$FAILS" -gt 0 ]; then say "$FAILS problem(s), $WARNS warning(s)."; exit 1; fi
+  say "No problems. $WARNS warning(s)."
+}
+
+# ---------------------------------------------------------------- verify ----
+# Live end-to-end test: plants a random marker in each layer, asks each agent
+# which markers it can see without using tools, then restores everything.
+
+rand() { od -An -N4 -tu4 /dev/urandom | tr -d ' \n'; }
+
+cmd_verify() {
+  agents="claude codex copilot"
+  [ "${1:-}" = --agents ] && { agents=$(printf '%s' "${2:-}" | tr ',' ' '); }
+  [ -f "$PERSONAL" ] || die "no personal file yet: run trailkeep install"
+
+  id=$(rand)
+  P=ACX-P$id; R=ACX-R$id; N=ACX-N$id; E=ACX-E$id; D=ACX-D$id
+  work=$(mktemp -d) || die "mktemp failed"
+  repo=$work/trailkeep-verify-$id
+  personal_backup=$work/personal.bak
+  cp "$PERSONAL" "$personal_backup" || die "could not back up $PERSONAL"
+  vkey=
+
+  cleanup() {
+    trap - EXIT INT TERM HUP
+    # Restore only from a complete backup; never truncate the real file.
+    if [ -f "$personal_backup" ]; then cp "$personal_backup" "$PERSONAL"; fi
+    if [ -n "$vkey" ]; then rm -rf "${REPOS:?}/$vkey"; fi
+    rm -rf "$work"
+  }
+  trap cleanup EXIT
+  trap 'cleanup; exit 130' INT TERM HUP
+
+  mkdir -p "$repo"
+  ( cd "$repo" && git init -q && git symbolic-ref HEAD refs/heads/trailkeep-verify ) || die "git init failed"
+  printf '# Test repo\n\nVerification marker: %s\n' "$R" > "$repo/AGENTS.md"
+  printf '\nVerification marker: %s\n' "$P" >> "$PERSONAL"
+  vkey=$(cd "$repo" && repo_key)
+  mkdir -p "$REPOS/$vkey" "$repo/.trailkeep"
+  printf '*\n' > "$repo/.trailkeep/.gitignore"
+  printf '# Notes\n\nVerification marker: %s\n' "$N" > "$REPOS/$vkey/NOTES.md"
+  printf '# trailkeep-verify\n\nBranch: trailkeep-verify · Repo: %s · Kind: branch · Created: %s\n\n## Goal\n\nVerification marker: %s\n\n## Decisions and dead ends\n\n- verify decision %s\n' "$vkey" "$(today)" "$E" "$D" > "$repo/.trailkeep/trailkeep-verify.md"
+
+  q='Without using any tools, reading files or running commands, list every token that starts with "ACX-" that appears anywhere in your instructions or context. Reply with the tokens separated by spaces and nothing else. If there are none, reply NONE.'
+
+  say "trailkeep verify: asking each agent which layers it can see (a few hundred tokens each)"
+  say ""
+  printf '  %-9s %-10s %-10s %-10s %-10s %-10s\n' agent personal repo notes effort logged
+  for a in $agents; do
+    if ! has "$a"; then printf '  %-9s %s\n' "$a" "not installed, skipped"; continue; fi
+    out=$work/$a.out
+    case $a in
+      claude)  ( cd "$repo" && claude -p "$q" --tools "" --no-session-persistence ) > "$out" 2>&1 ;;
+      codex)   ( cd "$repo" && codex exec --ephemeral --skip-git-repo-check -s read-only "$q" ) > "$out" 2>&1 ;;
+      copilot) ( cd "$repo" && copilot -p "$q" -s --no-ask-user ) > "$out" 2>&1 ;;
+      *) printf '  %-9s %s\n' "$a" "unknown agent"; continue ;;
+    esac
+    row=
+    for m in "$P" "$R" "$N" "$E"; do
+      if grep -q "$m" "$out"; then row="$row$(printf '%-10s ' yes)"; else row="$row$(printf '%-10s ' NO)"; FAILS=$((FAILS + 1)); eval "miss_$a=1"; fi
+    done
+    # The session-end (or next session-start) hook should have logged the decision.
+    if cat "$REPOS/$vkey/log/"*.tsv 2>/dev/null | grep -q "$D"; then row="$row$(printf '%-10s ' yes)"
+    else row="$row$(printf '%-10s ' NO)"; FAILS=$((FAILS + 1)); eval "miss_$a=1"; fi
+    rm -rf "$REPOS/$vkey/log"
+    printf '  %-9s %s\n' "$a" "$row"
+  done
+  say ""
+  for a in $agents; do
+    eval "m=\${miss_$a:-0}"
+    [ "$m" -eq 1 ] || continue
+    say "$a missed something. Its reply:"
+    tail -n 5 "$work/$a.out" | sed 's/^/    /'
+    case $a in
+      claude) hint "notes/effort/logged missing: check 'claude plugin list' shows trailkeep@trailkeep enabled" ;;
+      codex) hint "notes/effort/logged missing: the hooks are probably untrusted; open codex, run /hooks, trust both" ;;
+      copilot) hint "personal missing: Copilot may not follow the symlink; set COPILOT_CUSTOM_INSTRUCTIONS_DIRS=$(tilde "$TRAILKEEP_HOME") in your shell rc" ;;
+    esac
+    say ""
+  done
+  if [ "$FAILS" -eq 0 ]; then say "Every agent sees every layer."; else exit 1; fi
+}
+
+# ------------------------------------------------------------------ main ----
+
+usage() {
+  cat <<EOF
+trailkeep $VERSION: global knowledge + per-branch task context for coding agents
+
+Setup
+  install [--adopt] [--dry-run] [--no-claude|--no-codex|--no-copilot] [--no-skill]
+  update            git pull this clone, then re-run install
+  uninstall [--dry-run]
+  doctor            check the setup and the current repo's instruction files
+  verify [--agents claude,codex,copilot]
+                    live test: ask each agent which layers it sees
+
+Per repo / branch (run inside a git repo)
+  new               create the effort file for the current branch
+  show              print what agents get at session start here
+  edit              open the effort file in \$EDITOR
+  path [--notes|--repo|--dir]
+  notes [--path]    open (or print the path of) your private notes for this repo
+  close             archive this branch's effort and list decisions to promote
+  prune [--apply]   archive efforts whose branches no longer exist
+  list              all active efforts across repos
+  log [--path P] [--grep TEXT] [--type T] [--branch B] [--since DATE] [-n N]
+  log show ID       one decision log entry in full
+  log add TYPE TEXT add an entry by hand
+
+Internal
+  context --for claude|codex|copilot|text   (session-start hook)
+  harvest --for claude|codex|copilot        (session-end hook)
+
+Data: $(tilde "$TRAILKEEP_HOME")  (override with TRAILKEEP_HOME)
+EOF
+}
+
+cmd=${1:-help}
+[ $# -gt 0 ] && shift
+case $cmd in
+  install) cmd_install "$@" ;;
+  uninstall) cmd_uninstall "$@" ;;
+  doctor) cmd_doctor "$@" ;;
+  verify) cmd_verify "$@" ;;
+  new) cmd_new "$@" ;;
+  show) cmd_show "$@" ;;
+  edit) cmd_edit "$@" ;;
+  path) cmd_path "$@" ;;
+  notes) cmd_notes "$@" ;;
+  close) cmd_close "$@" ;;
+  prune) cmd_prune "$@" ;;
+  list) cmd_list "$@" ;;
+  context) cmd_context "$@" ;;
+  harvest) cmd_harvest "$@" ;;
+  log) cmd_log "$@" ;;
+  update) cmd_update "$@" ;;
+  version|--version|-V) say "trailkeep $VERSION" ;;
+  help|--help|-h) usage ;;
+  *) usage >&2; exit 2 ;;
+esac