acstack 0.49.0 → 0.49.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "acstack",
   "description": "Agentic coding stack where planning grows only as far as needed: a map of decisions, tasks, checks, and handoffs behind a pluggable tracker.",
-  "version": "0.49.0",
+  "version": "0.49.1",
   "author": {
     "name": "ac8318740"
   },

package/assets/terminal-workspace/helpers/acstack-bridge

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# Look at the Playwriter bridge from the dev machine, and fix it where that is
+# possible from here.
+#
+#   acstack-bridge status        what is up, on both machines
+#   acstack-bridge fix [what]    restart relay | tunnel | both (default both)
+#
+# Restarting either is a Windows scheduled task, so this machine cannot do it
+# directly. It asks the opener, which runs over there and can. When the opener
+# is not reachable either, it prints the handoff block to paste into a
+# PowerShell on the laptop instead - the same block the bridge skill defines.
+#
+# What it still cannot do is arm the extension. That is a click inside a
+# third-party extension and nothing on either machine can press it.
+# Installed by acstack.
+set -uo pipefail
+
+BRIDGE="${ACSTACK_BRIDGE_URL:-http://127.0.0.1:19988}"
+OPENER="${ACSTACK_OPENER_URL:-http://127.0.0.1:19989}"
+OPENER_TOKEN="${XDG_CONFIG_HOME:-$HOME/.config}/acstack/opener.token"
+FREE_PORT="${ACSTACK_FREE_PORT:-$HOME/.claude/acstack/bin/vm-free-port.sh}"
+
+CMD="${1:-status}"
+WHAT="${2:-both}"
+
+tok() { cat "$OPENER_TOKEN" 2>/dev/null; }
+
+clear_port() {  # clear_port <port> - let go of a forward this machine still holds
+  # A tunnel that will not rebind is usually held from this side: the VM's sshd
+  # still owns the forward channel of a session that dropped. Restarting the
+  # task on the laptop then fails exactly the way it failed before, because
+  # nothing here let go of the port. So this runs first.
+  #
+  # The clearer ships with acstack and may simply not be installed on a machine
+  # that got the terminal workspace some other way. Worth saying, but not a
+  # reason to refuse the restart, which may be all that was needed.
+  if [ ! -f "$FREE_PORT" ]; then
+    echo "no port clearer at $FREE_PORT - asking for the restart without freeing $1 first." >&2
+    return 0
+  fi
+  #
+  # A clearer that predates --port is the awkward case in between: it exists,
+  # so the missing-file warning never fires, but it only knows how to free
+  # 19988. Called bare it would clear the bridge port twice, never touch 19989,
+  # and hand back two successes - so the caller would believe both ports were
+  # freed. Report the version and clear nothing; guessing is worse than saying.
+  # It announces its age two ways: the flag is nowhere in its text, or it takes
+  # the flag, does not recognise the argument, and exits 64 - the usage code,
+  # which is not "the port is stuck" and is not worth a retry without the flag.
+  local older="is older than this branch, so it cannot free $1 on request."
+  local fix="Update acstack on this machine to refresh it. Asking for the restart anyway."
+  if ! grep -q -- '--port' "$FREE_PORT" 2>/dev/null; then
+    echo "$FREE_PORT $older It has no --port support at all. $fix" >&2
+    return 0
+  fi
+  local rc=0
+  bash "$FREE_PORT" --port "$1" >/dev/null 2>&1 || rc=$?
+  if [ "$rc" = "64" ]; then
+    echo "$FREE_PORT $older It refused --port with the usage code 64. $fix" >&2
+  elif [ "$rc" != "0" ]; then
+    echo "$FREE_PORT could not free $1 - asking for the restart anyway." >&2
+  fi
+}
+
+opener_call() {  # opener_call <method> <path> [data]
+  local t; t=$(tok) || return 1
+  [ -n "$t" ] || return 1
+  if [ "$1" = "POST" ]; then
+    curl -fsS --connect-timeout 2 -m 40 -X POST -H "X-ACStack-Token: $t" \
+      -H 'Content-Type: application/json' --data "${3:-{\}}" "$OPENER$2" 2>/dev/null
+  else
+    curl -fsS --connect-timeout 2 -m 10 -H "X-ACStack-Token: $t" "$OPENER$2" 2>/dev/null
+  fi
+}
+
+handoff() {  # what this machine cannot do, in the shape the other side expects
+  # Unquoted, because $1 names what is being asked for - so every PowerShell $
+  # inside has to be escaped or the shell eats it. A handoff block is pasted
+  # verbatim into a shell on the other machine, so a mangled one is worse than
+  # no block at all.
+  cat >&2 <<HANDOFF
+
+--- BEGIN VM-SIDE HANDOFF (to Windows agent) ---
+Context: the bridge needs $1 on the laptop, and the opener on 19989 is not
+reachable from this machine either, so nothing here can do it.
+
+Run on the Windows laptop:
+  Stop-ScheduledTask -TaskName 'Playwriter-*'
+  Start-ScheduledTask -TaskName 'Playwriter-Relay'
+  Start-ScheduledTask -TaskName 'Playwriter-Opener'
+  Get-ScheduledTask -TaskName 'Playwriter-Tunnel-*','Playwriter-OpenerTunnel-*' |
+    ForEach-Object { Start-ScheduledTask -TaskName \$_.TaskName }
+  .\doctor.ps1
+
+Expected result:
+  doctor.ps1 exits with all green rows, including "Relay listening on 19988"
+  and "Opener listening on 19989", and no tunnel-*.stuck markers.
+
+Report back:
+  The doctor.ps1 output (paste the table).
+--- END VM-SIDE HANDOFF ---
+HANDOFF
+}
+
+case "$CMD" in
+  status)
+    # This machine's own view first: these say whether the tunnels arrived,
+    # which is the half the laptop cannot see.
+    if curl -fsS --connect-timeout 1 -m 3 "$BRIDGE/json/version" >/dev/null 2>&1; then
+      armed=$(curl -fsS --connect-timeout 1 -m 3 "$BRIDGE/json/list" 2>/dev/null | tr -d '[:space:]')
+      case "$armed" in
+        ''|'[]') echo "relay:   reachable, but the extension is armed on no tab" ;;
+        *)       echo "relay:   reachable, extension armed" ;;
+      esac
+    else
+      echo "relay:   not reachable on $BRIDGE"
+    fi
+
+    if health=$(opener_call GET /health); then
+      echo "opener:  reachable - $(printf '%s' "$health" | tr -d '[:space:]')"
+    elif [ -z "$(tok)" ]; then
+      echo "opener:  no token at $OPENER_TOKEN (run register-tasks.ps1 on the laptop)"
+    else
+      echo "opener:  not reachable on $OPENER"
+    fi
+
+    # And the laptop's view, which only the opener can fetch.
+    if tasks=$(opener_call GET /bridge/health); then
+      echo "tasks:   $(printf '%s' "$tasks" | tr -d '[:space:]')"
+    else
+      echo "tasks:   unknown - the opener is the only way to see them from here"
+    fi
+    echo "route:   $(acstack-open --why 2>/dev/null || echo unknown)"
+    ;;
+  fix)
+    case "$WHAT" in
+      relay|tunnel|both) ;;
+      *) echo "usage: acstack-bridge fix [relay|tunnel|both]" >&2; exit 2 ;;
+    esac
+    # A tunnel restart is the only case where a port here is in the way. Both
+    # ports get cleared, because the opener's 19989 is forwarded by its own task
+    # and wedges on its own. fix relay touches no tunnel, so clearing a port
+    # there would be tearing down a working connection to fix something else.
+    if [ "$WHAT" != "relay" ]; then
+      clear_port 19988
+      clear_port 19989
+    fi
+    if out=$(opener_call POST /bridge/restart "$(printf '{"what":"%s"}' "$WHAT")"); then
+      echo "asked the laptop to restart: $WHAT"
+      printf '%s\n' "$out"
+      # Restarting is not recovering. Give the tunnels a moment to rebind, then
+      # say whether they actually came back rather than reporting the request.
+      sleep 5
+      rc=0
+      if curl -fsS --connect-timeout 1 -m 3 "$BRIDGE/json/version" >/dev/null 2>&1; then
+        echo "relay is answering again on $BRIDGE"
+      else
+        echo "the restart was accepted but the relay is still not answering here on 19988." >&2
+        echo "  if this persists the port may be wedged on this machine:" >&2
+        echo "  bash $FREE_PORT --port 19988" >&2
+        rc=1
+      fi
+      # Two tunnels, two verdicts. A relay that came back says nothing about
+      # the opener, and an opener that stayed down is the half that leaves this
+      # machine unable to reach a browser at all - so it is checked, and named.
+      if [ "$WHAT" != "relay" ]; then
+        if opener_call GET /health >/dev/null; then
+          echo "opener is answering again on $OPENER"
+        else
+          echo "the restart was accepted but the opener is still not answering here on 19989." >&2
+          echo "  if this persists the port may be wedged on this machine:" >&2
+          echo "  bash $FREE_PORT --port 19989" >&2
+          rc=1
+        fi
+      fi
+      exit $rc
+    fi
+    handoff "a restart of $WHAT"
+    exit 1
+    ;;
+  *)
+    echo "usage: acstack-bridge [status|fix [relay|tunnel|both]]" >&2
+    exit 2
+    ;;
+esac

package/assets/terminal-workspace/helpers/acstack-clip

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Put text on the clipboard of the machine your terminal is on.
+#
+#   acstack-clip "text"      copy the arguments
+#   ... | acstack-clip       copy stdin
+#   acstack-clip --out       print what was copied last
+#
+# A VM reached over SSH has no display and no clipboard of its own, so
+# xclip and friends have nothing to talk to. OSC 52 is the escape sequence
+# that asks the terminal at the far end - Windows Terminal, iTerm2, kitty -
+# to put text on its own clipboard. It is only bytes in the terminal stream,
+# so it crosses SSH for free, and herdr forwards it from a pane to whatever
+# terminal is hosting it.
+#
+# Reading back is not symmetrical. Windows Terminal refuses OSC 52 reads on
+# purpose, so --out replays a local cache instead. Installed by acstack.
+set -uo pipefail
+
+CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/acstack/clipboard"
+
+# A real clipboard beats an escape sequence when one exists. Anything sitting
+# in this script's own directory is skipped, so the xclip shim installed
+# beside it can never call back into here in a loop.
+native() {  # native <tool>; prints the path of a real one, if any
+  local tool="$1" self candidate
+  self="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+  while IFS= read -r candidate; do
+    [ "$(cd "$(dirname "$candidate")" 2>/dev/null && pwd)" = "$self" ] && continue
+    printf '%s' "$candidate"; return 0
+  done < <(type -ap "$tool" 2>/dev/null)
+  return 1
+}
+
+has_display() { [ -n "${DISPLAY:-}${WAYLAND_DISPLAY:-}" ]; }
+
+if [ "${1:-}" = "--out" ] || [ "${1:-}" = "-o" ]; then
+  if has_display; then
+    for tool in wl-paste xclip xsel; do
+      real="$(native "$tool")" || continue
+      case "$tool" in
+        wl-paste) exec "$real" --no-newline ;;
+        xclip)    exec "$real" -out -selection clipboard ;;
+        xsel)     exec "$real" --output --clipboard ;;
+      esac
+    done
+  fi
+  [ -f "$CACHE" ] || { echo "acstack-clip: nothing copied yet" >&2; exit 1; }
+  cat "$CACHE"
+  exit 0
+fi
+
+if [ $# -gt 0 ]; then text="$*"; else text="$(cat)"; fi
+
+mkdir -p "$(dirname "$CACHE")"
+printf '%s' "$text" > "$CACHE"
+chmod 600 "$CACHE" 2>/dev/null
+
+if has_display; then
+  for tool in wl-copy xclip xsel; do
+    real="$(native "$tool")" || continue
+    case "$tool" in
+      wl-copy) printf '%s' "$text" | "$real" && exit 0 ;;
+      xclip)   printf '%s' "$text" | "$real" -in -selection clipboard && exit 0 ;;
+      xsel)    printf '%s' "$text" | "$real" --input --clipboard && exit 0 ;;
+    esac
+  done
+fi
+
+b64="$(printf '%s' "$text" | base64 | tr -d '\n')"
+# 74994 bytes is the ceiling tmux puts on an OSC 52 payload, and the lowest
+# of anything in this path. Past it the sequence is dropped without a word,
+# so say so rather than report a copy that did not happen.
+if [ ${#b64} -gt 74994 ]; then
+  echo "acstack-clip: too large for the terminal clipboard (${#b64} bytes encoded)" >&2
+  exit 1
+fi
+
+esc=$'\033]52;c;'"$b64"$'\a'
+# tmux drops escape sequences it does not recognise unless they are wrapped
+# for passthrough. herdr needs no wrapping - it forwards OSC 52 itself.
+if [ -n "${TMUX:-}" ]; then
+  esc=$'\033Ptmux;'"${esc//$'\033'/$'\033\033'}"$'\033\\'
+fi
+
+# The controlling terminal, not stdout. Callers are usually TUIs that have
+# redirected both streams, and OSC 52 has to reach the terminal itself.
+if { printf '%s' "$esc" > /dev/tty; } 2>/dev/null; then exit 0; fi
+printf '%s' "$esc" >&2

package/assets/terminal-workspace/helpers/acstack-dash

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# gh-dash with a section for the repo you are standing in. Installed by acstack.
+set -uo pipefail
+# Every action gh-dash takes shells out to gh and discards its stderr, so a
+# refusal from GitHub reaches you as "exit status 1" for two seconds. acstack-gh
+# goes in front of the real gh under that name and speaks the refusal aloud.
+# Its directory holds nothing else, so nothing else on PATH is shadowed.
+SHIM="$(mktemp -d)"; GEN=""
+trap 'rm -rf "$SHIM"; rm -f "$GEN"' EXIT
+ln -s "$(command -v acstack-gh)" "$SHIM/gh" 2>/dev/null && export PATH="$SHIM:$PATH"
+BASE="$HOME/.config/gh-dash/config.yml"
+REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null)"
+# Not exec, so the trap above still gets to clean up after the dashboard.
+[ -z "$REPO" ] && { gh dash "$@"; exit $?; }
+GEN="$(mktemp)"
+REPO="$REPO" python3 - "$BASE" "$GEN" <<'PY'
+import os, sys, yaml
+cfg = yaml.safe_load(open(sys.argv[1])) or {}
+repo = os.environ["REPO"]; short = repo.split("/")[-1]
+s = [x for x in cfg.get("prSections", []) if x.get("title") != short]
+s.insert(0, {"title": short, "filters": f"repo:{repo} is:open"})
+cfg["prSections"] = s
+yaml.safe_dump(cfg, open(sys.argv[2], "w"), sort_keys=False)
+PY
+gh dash --config "$GEN" "$@"

package/assets/terminal-workspace/helpers/acstack-db

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Open harlequin, the SQL editor, on one of your connection profiles.
+#
+#   acstack-db            one profile launches straight in, more than one opens a menu
+#   acstack-db <profile>  that profile, no menu
+#
+# Profiles live in a TOML file of your own. This writes a starter the first
+# time and never touches it again. Installed by acstack.
+set -uo pipefail
+# apply rewrites this line from harlequin.config_path. What ships here is the
+# default, so the helper is right even on a machine nothing rewrote it on.
+DB_CFG_DEFAULT="~/.config/acstack/harlequin.toml"  # acstack:config_path
+CFG="${ACSTACK_DB_CONFIG:-$DB_CFG_DEFAULT}"
+# A human writes ~ for home, and a human writes this config. Expanding it here
+# rather than at write time keeps the helper right on a machine whose HOME is
+# not the one apply ran under.
+case "$CFG" in
+  "~")   CFG="$HOME" ;;
+  "~/"*) CFG="$HOME/${CFG#\~/}" ;;
+esac
+
+command -v harlequin >/dev/null 2>&1 || {
+  echo "harlequin is not installed. Run: setup.sh apply"; exit 1; }
+
+if [ ! -f "$CFG" ]; then
+  mkdir -p "$(dirname "$CFG")"
+  cat > "$CFG" <<'T'
+# harlequin connection profiles. acstack wrote this once and will not write it
+# again. Edit it freely.
+default_profile = "local"
+
+[profiles.local]
+adapter = "postgres"
+conn_str = "postgres://localhost:5432/postgres"
+
+# Snowflake. Take the # marks off and fill in your own account.
+#
+# Put the credentials in ~/.snowflake/connections.toml and name the connection
+# here, rather than writing them into this file.
+#
+# externalbrowser authentication needs a browser on this machine. A dev machine
+# reached over SSH has none, so use a key pair or a password instead.
+#
+# [profiles.snowflake]
+# adapter = "snowflake"
+# connection_name = "default"
+T
+  echo "wrote a starter config at $CFG - edit it to reach your own database"
+fi
+
+launch() { exec harlequin --config-path "$CFG" -P "$1"; }
+[ $# -gt 0 ] && launch "$1"
+
+# Profile names, read with a regex rather than tomllib: tomllib needs python
+# 3.11 and nothing else this script writes has a floor that high. Names are all
+# that is wanted here, and a table header is the one line a regex reads safely.
+rows=$(python3 - "$CFG" <<'PY'
+import re, sys
+text = open(sys.argv[1]).read()
+d = re.search(r'(?m)^\s*default_profile\s*=\s*"([^"]+)"', text)
+default = d.group(1) if d else ""
+for m in re.finditer(r'(?m)^\s*\[profiles\.("?)([^\]"]+)\1\]\s*$', text):
+    name = m.group(2)
+    body = text[m.end():].split("\n[", 1)[0]
+    a = re.search(r'(?m)^\s*adapter\s*=\s*"([^"]+)"', body)
+    mark = "   (default)" if name == default else ""
+    print("%s\t%-24s %-12s%s" % (name, name, a.group(1) if a else "?", mark))
+PY
+)
+count=$(printf '%s\n' "$rows" | grep -c .)
+case "$count" in
+  0) echo "no profiles in $CFG"; exit 1 ;;
+  1) launch "$(printf '%s' "$rows" | cut -f1)" ;;
+esac
+
+command -v fzf >/dev/null 2>&1 || {
+  echo "fzf is not installed, so there is no menu. Naming a profile still works:"
+  printf '%s\n' "$rows" | cut -f1 | sed 's/.*/  acstack-db "&"/'
+  exit 1; }
+
+choice=$(printf '%s\n' "$rows" \
+  | fzf --delimiter=$'\t' --with-nth=2.. --no-multi --cycle \
+        --prompt="db > " --header="harlequin   ·   profile   adapter" \
+  | cut -f1)
+[ -n "$choice" ] || exit 0
+launch "$choice"

package/assets/terminal-workspace/helpers/acstack-diff

@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+# Show a git diff in diffnav, with a banner naming what is being compared.
+#
+#   acstack-diff        this branch against dev, committed work only (alt+f)
+#   acstack-diff pick   choose the comparison from a menu (alt+x)
+#   acstack-diff auto   first non-empty of working tree, staged, last commit
+#
+# Every launch prepends a COMPARING block to the diff. diffnav renders whatever
+# precedes the first "diff --git" line, which is how git show's commit header
+# reaches the screen, so the block lands at the top of the content pane.
+#
+# diffnav's "o" key opens the file under the cursor with $EDITOR, in diffnav's
+# own pane. That pane is a herdr popup for alt+f and alt+x, and a popup cannot
+# host a second full-screen app, so the editor never draws there. acstack-edit
+# gives the file its own herdr tab instead, and both diff keys then match.
+set -uo pipefail
+if command -v acstack-edit >/dev/null 2>&1; then
+  case "${EDITOR:-}" in *acstack-edit) EDITOR=nvim ;; esac   # never nest
+  export ACSTACK_EDIT_EDITOR="${EDITOR:-nvim}"
+  export EDITOR=acstack-edit
+fi
+pick_checkout() {
+  # herdr groups worktrees as <root>/<repo>/<branch-slug>, so a pane often
+  # sits in the parent of several checkouts rather than in one.
+  local -a repos=()
+  while IFS= read -r d; do repos+=("$d"); done < <(
+    find . -mindepth 1 -maxdepth 1 -type d -exec test -e '{}/.git' \; -print 2>/dev/null | sort)
+  case ${#repos[@]} in
+    0) return 1 ;;
+    1) cd "${repos[0]}" && return 0 ;;
+    *) echo "Not a repo, but it holds ${#repos[@]} checkouts:"; echo
+       local i=1
+       for d in "${repos[@]}"; do
+         printf '  %d) %-34s %s\n' "$i" "${d#./}" "$(git -C "$d" branch --show-current 2>/dev/null)"
+         i=$((i+1))
+       done
+       echo; read -rp "Which one? [1-${#repos[@]}, q to quit] " choice
+       [[ "$choice" =~ ^[0-9]+$ ]] && [ "$choice" -ge 1 ] && [ "$choice" -le ${#repos[@]} ] \
+         && cd "${repos[$((choice-1))]}" && return 0
+       return 1 ;;
+  esac
+}
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  pick_checkout || { echo "No git checkout here: $PWD"; echo "Press any key..."; read -rsn1; exit 0; }
+fi
+
+BRANCH=$(git branch --show-current 2>/dev/null) || BRANCH=""
+[ -n "$BRANCH" ] || BRANCH="HEAD (detached)"
+
+# ---- refs -----------------------------------------------------------------
+ref_exists() { git rev-parse --verify --quiet "$1" >/dev/null 2>&1; }
+first_ref() { local r; for r in "$@"; do ref_exists "$r" && { echo "$r"; return 0; }; done; return 1; }
+dev_ref()     { first_ref origin/dev dev; }          # the server's dev wins over a stale local one
+              # default_compare falls back to the default branch only where no dev branch exists
+default_ref() {
+  local d; d=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null)
+  [ -n "$d" ] && { echo "$d"; return 0; }
+  first_ref origin/main main origin/master master
+}
+tip() {  # tip <ref> -> "1b298bd . 4 hours ago . Merge pull request ..."
+  # kept short: diffnav's content pane is narrower than the popup, so a long
+  # line wraps and the banner stops looking like a banner.
+  git log -1 --format='%h  %ar  %s' "$1" 2>/dev/null | cut -c1-70
+}
+
+# ---- what diffnav cannot draw ---------------------------------------------
+# diffnav hands each file to delta, and delta dies on SIGABRT when one line
+# runs to hundreds of kilobytes. diffnav reports the child's death as
+# "FATA signal: aborted (core dumped)" and quits, so one such file takes the
+# whole diff down with it. A committed build artifact is what does it: this
+# project's own cli/dist/index.js.map holds a single 982,428-character line,
+# and the merge commit touching it aborted diffnav in 1.7 seconds.
+#
+# So the file goes, not the diff. Any file whose patch holds a line over the
+# limit is dropped and named in the banner, and the rest is drawn as usual.
+# 20000 is far above any line a person writes and far below where delta gives
+# out. Raise or lower it with ACSTACK_DIFF_LINE_LIMIT.
+LINE_LIMIT_DEFAULT=20000
+LINE_LIMIT="${ACSTACK_DIFF_LINE_LIMIT:-$LINE_LIMIT_DEFAULT}"
+# awk compares a length against whatever this holds. Hand it "abc" and every
+# comparison is a string comparison that is never true, so the guard turns
+# itself off and the abort comes back with nothing on screen to explain it.
+# Hand it 0 and every file is dropped instead. Refuse both, out loud.
+case "$LINE_LIMIT" in
+  ''|0|*[!0-9]*)
+    echo "acstack-diff: ACSTACK_DIFF_LINE_LIMIT is \"$LINE_LIMIT\", which is not a" >&2
+    echo "  positive whole number. Using $LINE_LIMIT_DEFAULT." >&2
+    LINE_LIMIT=$LINE_LIMIT_DEFAULT ;;
+esac
+drop_unrenderable() {  # drop_unrenderable <skipped-file>  ; diff in, diff out
+  # One file at a time: a patch has to be held whole before its longest line
+  # is known. Everything before the first "diff --git" is a header, so it goes
+  # straight through. Written for gawk, mawk and busybox awk alike.
+  awk -v lim="$LINE_LIMIT" -v skip="$1" '
+    function flush() {
+      if (path == "") return
+      # A tab between the two fields. banner reads this file back and splits
+      # on the same tab, so the two have to move together.
+      if (long) printf "%s\t%d\n", path, maxlen > skip
+      else for (i = 1; i <= n; i++) print buf[i]
+    }
+    /^diff --git / {
+      flush()
+      split("", buf); n = 0; long = 0; maxlen = 0
+      path = $0; sub(/^diff --git a\//, "", path); sub(/ b\/.*$/, "", path)
+      if (path == "") path = "?"
+    }
+    {
+      if (path == "") { print; next }
+      if (length($0) > maxlen) maxlen = length($0)
+      if (length($0) > lim) long = 1
+      buf[++n] = $0
+    }
+    END { flush() }'
+}
+
+# ---- banner ---------------------------------------------------------------
+banner() {  # banner <source-label> <change-label> <what> <command>
+  # No line may start with a space: diffnav strips leading whitespace, so any
+  # indentation collapses and columns stop lining up.
+  printf 'COMPARING  %s  ==>  %s\n' "$1" "$2"
+  # base and compare repeat their ref so each row ties back to the first line.
+  [ -n "${SRC_TIP:-}" ] && printf 'base     %s\n' "$(printf '%s  %s' "$1" "$SRC_TIP" | cut -c1-70)"
+  [ -n "${CHG_TIP:-}" ] && printf 'compare  %s\n' "$(printf '%s  %s' "$2" "$CHG_TIP" | cut -c1-70)"
+  printf 'showing  %s\n' "$3"
+  printf 'command  %s\n' "$4"
+  # A dropped file is named here rather than left to be noticed as missing.
+  # The tab is what drop_unrenderable writes between the two fields.
+  [ -s "${SKIP:-}" ] && while IFS="$(printf '\t')" read -r p len; do
+    printf 'skipped  %s  (one line is %s chars, and diffnav aborts on it)\n' "$p" "$len"
+  done < "$SKIP"
+  return 0
+}
+launch() {  # launch <source> <change> <what> <git-args...>
+  local src="$1" chg="$2" what="$3"; shift 3
+  local cmd="git $*"
+  local tmp; tmp=$(mktemp); SKIP=$(mktemp)
+  git "$@" 2>/dev/null | drop_unrenderable "$SKIP" > "$tmp"
+  if grep -q '^diff --git' "$tmp"; then
+    # diffnav puts the line after "commit <sha>" in its status bar, and the bar
+    # stays put while you walk the file tree. A git show stream carries its own
+    # header, so only a plain diff needs one synthesised.
+    { [ "${1:-}" = diff ] && printf 'commit %s\n' "$(git rev-parse HEAD 2>/dev/null)"
+      banner "$src" "$chg" "$what" "$cmd"; echo; cat "$tmp"; } | diffnav
+  else
+    # Nothing for diffnav to draw, for one of two different reasons. The
+    # banner and the wait for a keypress are the same either way, so only the
+    # explanation sits inside the branch.
+    banner "$src" "$chg" "$what" "$cmd"
+    echo
+    if [ -s "$SKIP" ]; then
+      echo "  Every file that changed carries a line too long for diffnav."
+      echo "  They are named above, and nothing else differs between these two."
+    else
+      echo "  No difference between these two. Nothing to show."
+      local dirty; dirty=$(git status --porcelain 2>/dev/null | grep -cv '^??')
+      if [ "${dirty:-0}" -gt 0 ]; then
+        echo "  You do have $dirty file(s) changed but not committed."
+        echo "  Press alt+x and pick \"my uncommitted changes\" to see them."
+      else
+        echo "  Press alt+x to compare something else."
+      fi
+    fi
+    echo; echo "Press any key..."; read -rsn1
+  fi
+  rm -f "$tmp" "$SKIP"
+}
+
+# ---- comparisons ----------------------------------------------------------
+against() {  # against <base-ref> <committed|everything>
+  local base="$1" mode="$2" mb
+  SRC_TIP=$(tip "$base")
+  mb=$(git merge-base "$base" HEAD 2>/dev/null); mb=${mb:0:9}
+  [ -n "$mb" ] || { echo "No common history between $base and $BRANCH."
+                    echo; echo "Press any key..."; read -rsn1; return 1; }
+  if [ "$mode" = committed ]; then
+    CHG_TIP=$(tip HEAD)
+    launch "$base" "$BRANCH" \
+      "commits on $BRANCH that $base does not have" \
+      diff "$base...HEAD"
+  else
+    CHG_TIP="the files as they sit on disk right now"
+    launch "$base" "$BRANCH plus my uncommitted changes" \
+      "everything $BRANCH has since it left $base, committed or not" \
+      diff "$mb"
+  fi
+}
+local_only() {
+  SRC_TIP=$(tip HEAD); CHG_TIP="the files as they sit on disk right now"
+  launch "the newest commit on $BRANCH" "my uncommitted changes" \
+    "edits I have made but not committed, staged or not" diff HEAD
+}
+one_commit() {  # one_commit <sha>
+  SRC_TIP=$(tip "$1^" 2>/dev/null); CHG_TIP=$(tip "$1")
+  launch "the commit just before $1" "commit $1" "what this one commit changed" \
+    show "$1" -m --first-parent
+}
+auto() {  # fallback when there is no branch comparison to make; $1 says why
+  local why="${1:-nothing new to compare against another branch}"
+  if ! git diff --quiet || ! git diff --cached --quiet; then local_only
+  else SRC_TIP=$(tip HEAD^ 2>/dev/null); CHG_TIP=$(tip HEAD)
+       launch "$BRANCH one commit back" "$BRANCH at its newest commit" \
+         "$why, and nothing is uncommitted, so here is that commit alone" \
+         show HEAD -m --first-parent; fi
+}
+
+# ---- picker ---------------------------------------------------------------
+strip_ansi() { sed 's/\x1b\[[0-9;]*m//g'; }
+pick_ref() {  # pick_ref <prompt> -> a branch name
+  git for-each-ref --sort=-committerdate --format='%(refname:short)' \
+      refs/heads refs/remotes 2>/dev/null | grep -v '^origin/HEAD$' \
+    | fzf --prompt="$1 > " --no-multi --cycle --preview-window='right,60%' \
+          --preview='git log --oneline --decorate --color=always -20 {}'
+}
+pick_commit() {  # pick_commit -> a short sha
+  git log --oneline --decorate --color=always -300 2>/dev/null \
+    | fzf --ansi --prompt="commit > " --no-multi --cycle --preview-window='right,60%' \
+          --preview='git show --stat --color=always {1}' \
+    | strip_ansi | awk '{print $1}'
+}
+pick() {
+  command -v fzf >/dev/null 2>&1 || { echo "fzf is not installed."; echo; auto; return; }
+  local dev def choice a b
+  dev=$(dev_ref); def=$(default_ref)
+  local -a rows=()
+  row() { rows+=("$(printf '%s\t%-24s ==>  %-30s %s' "$1" "$2" "$3" "$4")"); }
+  [ -n "$dev" ] && [ "$dev" != "$BRANCH" ] && {
+    row dev-committed  "$dev" "$BRANCH"                "committed work only"
+    row dev-everything "$dev" "$BRANCH + uncommitted"  "committed work plus what is not committed"; }
+  [ -n "$def" ] && [ "$def" != "$BRANCH" ] && [ "$def" != "$dev" ] && {
+    row def-committed  "$def" "$BRANCH"                "committed work only"
+    row def-everything "$def" "$BRANCH + uncommitted"  "committed work plus what is not committed"; }
+  row local  "HEAD"        "my uncommitted work" "staged and unstaged changes only"
+  row commit "its parent"  "one commit"          "pick a commit from this branch's history"
+  row branch "any branch"  "any branch"          "pick the source, then the branch to compare"
+  choice=$(printf '%s\n' "${rows[@]}" \
+    | fzf --delimiter=$'\t' --with-nth=2.. --no-multi --cycle \
+          --prompt="diff > " --header="on $BRANCH   ·   source ==> change" \
+    | cut -f1)
+  case "$choice" in
+    dev-committed)  against "$dev" committed ;;
+    dev-everything) against "$dev" everything ;;
+    def-committed)  against "$def" committed ;;
+    def-everything) against "$def" everything ;;
+    local)          local_only ;;
+    commit)         a=$(pick_commit); [ -n "$a" ] && one_commit "$a" ;;
+    branch)         a=$(pick_ref "source (compare against)") ; [ -z "$a" ] && exit 0
+                    b=$(pick_ref "change (the new work)")    ; [ -z "$b" ] && exit 0
+                    SRC_TIP=$(tip "$a"); CHG_TIP=$(tip "$b")
+                    launch "$a" "$b" "commits on $b that $a does not have" diff "$a...$b" ;;
+    *)              exit 0 ;;
+  esac
+}
+
+# ---- entry ----------------------------------------------------------------
+default_compare() {  # alt+f: the newest commit on this branch, against origin/dev
+  local base; base=$(dev_ref) || base=$(default_ref)
+  # Only when this checkout IS the base branch is there nothing to compare.
+  if [ -z "$base" ] || [ "$base" = "$BRANCH" ] || [ "origin/$BRANCH" = "$base" ]; then
+    auto "$BRANCH is the branch everything else compares against"; return; fi
+  against "$base" committed
+}
+case "${1:-}" in
+  "")   default_compare ;;
+  pick) pick ;;
+  auto) auto ;;
+  *)    echo "usage: acstack-diff [pick|auto]"; exit 2 ;;
+esac