@groundnuty/macf 0.2.0-rc.0

package/plugin/rules/coordination.md

@@ -0,0 +1,224 @@
+# Coordination Rules (canonical, shared)
+
+**This file is the single source of truth for cross-cutting coordination rules that apply to every MACF agent.** It is copied into each agent workspace's `.claude/rules/` by `macf init` and refreshed by `macf update`. Do not edit workspace copies directly — edit this file and re-run `macf update`.
+
+> **Workspaces without full `macf init`** (e.g. `groundnuty/macf` itself, or any Claude Code workspace operated by a bot that isn't a MACF-registered agent) can still get these canonical rules via `macf rules refresh --dir <workspace>`. Same copy, no App credentials or registry required.
+
+The rules here are topology-agnostic: they work whether the project uses a science-agent coordinator (like macf) or peer-to-peer agents with direct user oversight (like CV).
+
+---
+
+## Issue Lifecycle
+
+1. **The reporter owns the issue closure.** The agent who opened an issue is the only one who closes it. This rule has two failure modes — both costly, both silent. Check for both before posting a merge-handoff comment.
+
+   **Failure mode A — closing an issue you didn't open.** Two ways this happens:
+   - *Auto-close via PR keywords.* GitHub's auto-close keywords in a PR body or commit message close the referenced issue on merge, bypassing the reporter. **Never use any of these 9 variants when the issue was filed by someone else:** `Closes #N`, `Fixes #N`, `Resolves #N`, `Close #N`, `Fix #N`, `Resolve #N`, `Closed #N`, `Fixed #N`, `Resolved #N`. Use **`Refs #N`** instead.
+   - *Manual close via `gh issue close`.* Don't close someone else's issue even after merging the implementation. Post the handoff comment and stop.
+
+   **Failure mode B — waiting for yourself to close.** When the issue's reporter is YOU (you filed the issue during an audit, a follow-up split-off, or self-observed bug), there is no one else to close it. Don't post `@<other-agent> ready for you to close when verified` — no one is waiting to do that for you. After your PR merges, close the issue yourself with a verification comment. Silent stall otherwise: the queue fills with in-review issues that never clear.
+
+   **Self-check before posting any merge-handoff comment:**
+
+        gh issue view <N> --json author --jq '.author.login'
+
+   - Author is someone else (user or another agent) → post `@<author> PR #M merged, ready for you to close when verified.` and STOP.
+   - Author is YOU (your `app/<bot-name>` login) → close the issue yourself:
+
+            gh issue close <N> --reason completed --comment "Verified on main after PR #M merged. Closing as reporter."
+
+   Also self-check PR bodies before pushing:
+
+        git log -1 --pretty=%B  # or the PR body draft
+        # grep for any of: Closes Fixes Resolves Close Fix Resolve Closed Fixed Resolved
+
+   If any of those appear and the referenced issue was filed by someone else, replace with `Refs #N`.
+
+   **Why this rule matters:** Reporter-owns-closure gives the reporter a chance to verify the fix matches their intent before the issue disappears from their queue. In a multi-agent workflow, the reporter often has context the implementer doesn't (why it was filed at that priority, what the acceptance criteria really meant, what adjacent work it blocks). Auto-close strips that context; reflexive handoff on self-filed issues wastes it.
+
+2. **Work through the queue without prompting.** When an issue is complete, check your assigned-label queue and pick up the next one immediately. Do NOT ask the reporter to ping you or reply "continue" before starting. Only wait when (a) your PR is in review, or (b) the queue is empty. If an issue is ambiguous, ask clarifying questions on that issue and move to the next queued one while waiting.
+
+3. **Never remove your own agent label.** Status labels (`in-progress`, `in-review`, `blocked`) swap as work moves; assignment labels stay.
+
+4. **Issue body is frozen during active work.** Once an assignee has commented "picking up" / added an `in-progress` or `in-review` label / filed a PR referencing the issue, the body **is the assignee's working spec** and should not be edited. Scope corrections, additional requirements, clarifying details, regex fixes — all go as **follow-up comments** in the issue thread.
+
+   **Why:** editing the body mid-flight either changes the target under the assignee's feet (they started on spec v1, are now reading v2) or is silently lost (they don't re-fetch the body after starting). A thread comment is visible, acknowledged, and dated. Both silent failure modes are worse than the tiny friction of posting a comment.
+
+   **When body edits ARE fine:**
+
+   - Before anyone has engaged (issue just-filed, no `in-progress` label, no assignee comments)
+   - The assignee is the one editing their own issue body
+   - Fixing obvious typos or broken links (not scope)
+
+   **When body edits are NOT fine:**
+
+   - Assignee has commented "picking up" / is actively working
+   - An `in-progress` / `in-review` label is set
+   - A PR referencing the issue is open
+
+   If a correction is substantive enough that the assignee would want to re-read from scratch, consider closing the current issue and filing a replacement with a clear back-reference — rather than in-place body rewrite.
+
+5. **Auto-opened issues break the peer-agent-reporter assumptions.** When an issue is filed by `github-actions[bot]` or any other non-human/non-agent bot, the peer-reviewer-verifies-the-fix loop that rules 1-4 assume doesn't apply — the bot-reporter can't verify, can't be routed-to as a reviewer, and can't sanity-check closure. Three specific adaptations:
+
+   - **Use `Refs #N`, not `Closes #N`, in the fix PR body.** The auto-close keyword bypasses the verification step the bot-reporter can't perform. Prefer an explicit close after the next post-merge run independently confirms the fix worked — not the PR merge itself, which fires before verification.
+   - **Route the review ping to `@macf-science-agent[bot]`** (or whichever peer agent would normally review), **not by echoing the `@<bot-reporter>` mention from the auto-open body.** The auto-open's `@mention` addresses the agent who should FIX, not the one who should REVIEW. Self-mention loops don't fire the routing workflow — the PR sits unreviewed.
+   - **Wait for the next auto-run to confirm green, then close with a comment citing the green run's SHA + URL.** If the auto-opening workflow has a self-close-on-green step (e.g., `e2e.yml` has one per #166), trust it — don't pre-empt by closing manually or via PR auto-close keyword. For workflows without a self-close step, close manually only after observing the next run green.
+
+   **Why this rule matters:** lucky timing isn't a verification gate. If a fix is incomplete, auto-close on PR merge closes the issue 2 seconds before the next run fails anew — producing a misleading closure trail. The "stays open until green" contract the auto-open body sets needs to be honored on the machine-enforced side, not relied on operator-discipline.
+
+   **Example auto-opened issues in this repo:** E2E cadence failures on `main` (#149 workflow auto-opens a `code-agent`/`blocked` issue with title prefix `ci(e2e): post-merge suite failing on main`); dependency-drift alerts; future `/sign` / cert-rotation health alarms. The pattern generalizes to any workflow that files on failure.
+
+---
+
+## Communication
+
+1. **@mention in EVERY comment.** Routing depends on it. A comment without @mention is invisible to the recipient agent.
+
+2. **All discussion in issue comments, not PR comments.** Issue threads are visible on the Projects board and persist after PRs are merged or closed.
+
+3. **Verify your comment actually posted — describing ≠ doing.** Writing a review / LGTM / close-comment / status-update as prose in your response is NOT the same as posting it to GitHub. Only executed `gh issue comment` / `gh pr comment` / `gh issue close` tool calls reach the repo; chat output is invisible to other agents. Treat the verification step as a **mandatory tail**, not optional, on any review-producing turn.
+
+   **After any `gh ... comment` / `gh ... close`:**
+
+        gh issue view <N> --repo <owner>/<repo> --json comments \
+          --jq '.comments[-1].author.login'
+
+   Confirms (a) the comment exists, (b) attribution is correct (bot not user — see Token & Git Hygiene below).
+
+   **Signs you may have missed the tool call:**
+
+   - Your last action was describing a review / decision / close in prose
+   - The recipient's status comment says "waiting for review" or "ready for you to close" with no reply from you visible on the thread
+   - Time has passed since you "reviewed" but no downstream activity (merge, follow-up questions, re-review request) has happened
+
+   When in doubt, run the `gh issue view` check. Cheap to verify; costly to have the assignee wait on a review that never arrived.
+
+4. **Concise comments** — 1-3 sentences unless detail is needed.
+
+---
+
+## When You're Stuck — Escalation
+
+1. **Treat definitive GitHub states as action signals, not wait signals.** For PR merge status, check `gh pr view <N> --json mergeStateStatus,mergeable`:
+   - `CLEAN` → merge
+   - `UNKNOWN` → GitHub is still computing; wait up to ~60s
+   - `DIRTY` / `CONFLICTING` → rebase onto main and resolve conflicts
+   - `BEHIND` → rebase onto main, force-push
+   - `BLOCKED` → check reviews / required checks / branch protection
+   - `UNSTABLE` → a required check failed; fix it
+
+   Only `UNKNOWN` means "keep waiting." Anything else means your turn to act.
+
+   **Exception — CI-completion routing (macf-actions v1.3+).** When you receive a CI-completion routing notification (`PR #N: CI SUCCESS/FAILED ...`) and `gh pr view` returns `UNKNOWN` or `UNSTABLE` immediately after, the notification was fired by one workflow's `check_suite.completed` while another workflow on the same commit is still in-flight. The rollup hasn't resolved yet. Wait ~30s and re-query; don't force-merge until the full rollup goes `CLEAN`. See `groundnuty/macf-actions#6` for background.
+
+2. **Escalate to the issue reporter.** When you've tried to resolve and are still stuck, @mention the reporter of the issue you're working on:
+
+        GH_TOKEN=$GH_TOKEN gh issue comment <N> --repo <owner>/<repo> --body "@<reporter> blocked on <X> — tried <Y>, need <Z>."
+
+   Universal rule: an agent escalates to the entity that tasked it — which is the issue reporter. Same entity that owns closing the issue (see Issue Lifecycle rule 1). This holds across any topology:
+   - macf (code-agent → science-agent → user)
+   - CV (cv-agents → user directly)
+   - Experiments (workers → experiment orchestrator → science-agent)
+
+   The chain flows from who opened the issue. You don't need to know the topology — you just @mention the reporter.
+
+3. **The reporter decides the next step.** They may act directly, involve a coordinator, or bring in the user. Do not reach past the reporter to the user unless the reporter has explicitly said they can't help.
+
+---
+
+## Peer Dynamic
+
+You are a peer to the agents and humans you work with, not a subordinate and not a superior.
+
+- **Push back** when an issue has wrong scope, missing context, flawed design, or conflicts with prior decisions
+- **Ask clarifying questions** before proceeding on ambiguous requirements — wait for answers
+- **Defend your implementation choices** with concrete reasoning if the reviewer disagrees
+- **Accept valid feedback** and push fixes promptly
+- **Research before implementing** — your training data may be outdated. Look up current SDK/library/API docs (context7, WebSearch, WebFetch) before using them
+
+The goal is correctness through dialogue, not compliance.
+
+---
+
+## Submitting a Prompt to a Claude Code TUI (tmux)
+
+When a hook or script needs to programmatically submit a prompt to a Claude Code TUI running in tmux, **always use the canonical helper**:
+
+        .claude/scripts/tmux-send-to-claude.sh <session-or-empty> "<prompt text>"
+
+Pass `""` for the session to target the current pane.
+
+**Never** call `tmux send-keys "<prompt>" Enter` inline. Claude Code's TUI is in multi-line input mode by default, so a single Enter inserts a newline instead of submitting — the prompt sits in the buffer unsubmitted. The helper handles the submit-quirk correctly: clear existing input with `C-u`, send the text with a first Enter, sleep 1 second (load-bearing — without it tmux batches both Enters and Claude processes them atomically as "newline + newline"), then send a second Enter that actually submits.
+
+The helper is distributed to every agent workspace by `macf init` and refreshed by `macf update` (same mechanism as this rules file). If you're writing a new hook or automation that needs to prompt Claude, use the helper — do not re-implement the pattern.
+
+### Canonical tmux launch pattern
+
+**One session per agent, named `<project>@<agent>`.** For example:
+
+        tmux new-session -d -s "academic-resume@cv-architect" \
+          "cd /path/to/academic-resume && ./claude.sh"
+
+        tmux new-session -d -s "academic-resume@cv-project-archaeologist" \
+          "cd /path/to/academic-resume && ./claude.sh"
+
+**Why this matters:** when the channel server's `tmux-wake` path (macf#185) auto-detects its own tmux target via `$TMUX_PANE` or `tmux display-message`, a **shared session with one window per agent** produces ambiguous resolution — two server processes in different windows of the same session can end up with identical auto-detected targets, and wakes land on the wrong pane. Empirically observed during the 2026-04-21 bilateral e2e smoke (chain broke when archaeologist's wake delivered to cv-architect's pane).
+
+**One session per agent** gives each server process a deterministic `$TMUX_PANE` + one-window-per-session context where `display-message` can't be ambiguous.
+
+**Session-name convention `<project>@<agent>`** is parseable (both human + script-friendly) and collision-free across projects — two `cv-architect` agents on the same VM (one for `academic-resume`, one for `macf-paper`) stay on separate sessions.
+
+**Bonus**: separate sessions mean multiple terminals can attach to different agents independently — `tmux attach -t academic-resume@cv-architect` on one terminal, `...@cv-project-archaeologist` on another, without windows-switching interference.
+
+**Migration** from a single-session multi-window setup: `tmux rename-session -t <old-name> <new-name>` per agent.
+
+---
+
+## Token & Git Hygiene
+
+1. **Refresh GH_TOKEN before every `gh` or `git push`** — tokens are 1-hour installation tokens. Use the canonical helper, and **fail loud** if it doesn't work:
+
+        GH_TOKEN=$("$MACF_WORKSPACE_DIR/.claude/scripts/macf-gh-token.sh" \
+          --app-id "$APP_ID" --install-id "$INSTALL_ID" --key "$KEY_PATH") || exit 1
+        export GH_TOKEN
+
+   **Use `$MACF_WORKSPACE_DIR/` as the path prefix, not `./`.** The relative-path form (`./.claude/scripts/...`) breaks the moment you `cd` to another repo for cross-repo work — the `$(...)` substitution returns empty, `export GH_TOKEN=""` silently succeeds, and the next `gh` call falls back to stored user auth. `$MACF_WORKSPACE_DIR` is set by `claude.sh` to the agent's workspace absolute path and resolves regardless of cwd. Same principle for `KEY_PATH`: `claude.sh` rewrites relative key paths to absolute at launch so helper invocations from any cwd still find the key.
+
+   **Why this matters:** the `#140` PreToolUse hook catches this class at tool-call time (empty `GH_TOKEN` → blocks the `gh` call before it runs). But the hook adds friction — the command aborts, the operator retries with the correct pattern. Using absolute paths from the start avoids the abort-retry loop entirely.
+
+   **Never** use the naive `export GH_TOKEN=$(gh token generate ... | jq -r '.token')` pattern — if `gh token generate` fails, jq's success masks the error (no `pipefail`), `GH_TOKEN` becomes the string `"null"`, and every subsequent `gh` operation silently falls back to the stored `gh auth login` as the user. This is the attribution trap: your PRs and comments get written as the user, not the bot, and nothing surfaces the mismatch until cross-agent routing breaks.
+
+   The helper uses `--token-only`, `set -euo pipefail`, validates the `ghs_` prefix, and emits actionable diagnostics (clock drift, missing key, bad PEM, wrong App/installation ID) on failure.
+
+2. **Sanity-check your identity** at session start or when something feels off:
+
+        GH_TOKEN=$GH_TOKEN ./.claude/scripts/macf-whoami.sh
+
+   Bot tokens (`ghs_*`) print `bot installation token`. A user token (`ghp_*`, `gho_*`, `ghu_*`) prints the user login and exits non-zero with a warning — that's the attribution trap firing.
+
+3. **When token generation fails, diagnose — don't work around it.** Common causes observed in practice:
+
+   - **Clock drift** — "JWT could not be decoded" usually means this machine's clock is skewed beyond GitHub's JWT tolerance. Check `timedatectl status` (expect `System clock synchronized: yes`).
+   - **Key mismatch** — `.github-app-key.pem` on disk doesn't match the App's registered public key (typically after a key rotation on GitHub without syncing locally). Compare fingerprints:
+
+            openssl rsa -in "$KEY_PATH" -pubout -outform DER 2>/dev/null | openssl dgst -sha256
+
+     against the SHA256 shown on GitHub → App settings → Private keys.
+   - **Wrong App/installation ID** — double-check `$APP_ID` and `$INSTALL_ID` in `.claude/settings.local.json`.
+   - **Missing App permission** — a 401 on a specific endpoint (e.g. `gh run list` returns 401 while `gh issue list` works) typically means the App lacks the permission for that resource. Coordinator/review agents especially need `actions: read` to debug team workflow runs — see DR-019 for the full required permission set. A missing permission is another flavor of the attribution trap: the bot call 401s, `gh` falls through to stored user auth, operations run as the user without surfacing the issue.
+
+4. **Never bake tokens into `git remote set-url`** — use `-c url.insteadOf` for each push so tokens don't persist in remote URLs.
+
+5. **Never leave uncommitted changes** in the working tree at the end of a turn.
+
+6. **Never commit** `.github-app-key.pem`, tokens, or secrets. `.gitignore` should exclude them, but also verify untracked files before staging.
+
+7. **Structural enforcement: the PreToolUse hook.** Every workspace ships with `.claude/scripts/check-gh-token.sh`, wired into `.claude/settings.json` as a PreToolUse hook on `Bash`. It intercepts every `gh` and `git push` invocation (including wrapped forms like `sudo gh ...`, `GH_TOKEN=x gh ...`, `env FOO=bar gh ...`) and blocks with `exit 2` if `GH_TOKEN` is missing or doesn't have the `ghs_` prefix. This moves enforcement from operator discipline (rules 1-3 above) to the harness itself — without it, the attribution trap recurred 5 times in a single day (see #140). If you ever need to run a knowingly user-attributed op (e.g., `gh auth login` during onboarding), set `MACF_SKIP_TOKEN_CHECK=1` for that one call. The hook is installed by `macf init`, refreshed by `macf update` and `macf rules refresh`.
+
+---
+
+## When to Read vs. Modify These Rules
+
+- **Read:** Every session start. These rules define how you coordinate.
+- **Modify:** Never directly in workspace copies. Edit the canonical file at `plugin/rules/coordination.md` in `groundnuty/macf`, then run `macf update` in each affected workspace.
+- **Disagree with a rule?** Open an issue on `groundnuty/macf` proposing the change, with rationale. Peer-review applies.

package/scripts/check-gh-token.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+#
+# check-gh-token.sh — Claude Code PreToolUse hook that blocks `gh` and
+# `git push` invocations when GH_TOKEN isn't a bot installation token
+# (ghs_ prefix). Prevents the attribution trap documented in
+# plugin/rules/coordination.md (Token & Git Hygiene) and #140.
+#
+# Hook contract: JSON on stdin, exit 0 = allow, exit 2 = block (stderr
+# is fed back to Claude as the error). See groundnuty/macf#140 for
+# design rationale; 5 recurrences in a single day drove the move from
+# behavioral to structural enforcement.
+#
+# Override: MACF_SKIP_TOKEN_CHECK=1 bypasses (for intentional
+# user-attributed ops, e.g. `gh auth login` during onboarding).
+set -euo pipefail
+
+# Operator override first — cheapest exit. No stdin read needed.
+if [[ "${MACF_SKIP_TOKEN_CHECK:-}" == "1" ]]; then
+  exit 0
+fi
+
+# Read and parse the PreToolUse JSON payload. Fall through to allow on
+# parse error — a broken hook must not brick the harness. Claude Code
+# emits a well-formed payload in practice; this is defense-in-depth.
+INPUT_JSON="$(cat)"
+COMMAND="$(jq -r '.tool_input.command // ""' <<<"$INPUT_JSON" 2>/dev/null || echo "")"
+
+# Wrapper-aware regex: match `gh ` or `git push ` as the effective
+# command, allowing for zero or more of: sudo, env VAR=VAL..., watch,
+# ionice, setsid, nice, time. Also triggers when preceded by `;`, `&&`,
+# `||`, `|` so chained forms like `make && sudo gh ...` still match.
+# Designed per science-agent's #140 review — the naïve anchored regex
+# was trivially bypassable by wrappers.
+GH_PATTERN='(^|[[:space:];|&])(sudo[[:space:]]+|env[[:space:]]+([A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*|watch[[:space:]]+|ionice[[:space:]]+|setsid[[:space:]]+|nice[[:space:]]+|time[[:space:]]+|[A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*(gh[[:space:]]|git[[:space:]]+push([[:space:]]|$))'
+
+# Shell-wrapper bypass regex: catches `bash -c "gh ..."`, `sh -c '...'`,
+# `zsh -c`, and flag-prefixed forms like `bash -x -c`, `bash -xc`,
+# `bash -lc`. The shell's -c flag executes its quoted argument AS A
+# COMMAND, so `gh` inside it IS a real invocation — unlike
+# `echo "gh is cool"` where the same text is just literal data.
+# Without this branch, `bash -c "gh issue close"` was a trivial bypass:
+# `bash` isn't in the wrapper allowlist, and `gh` inside the quotes
+# isn't preceded by one of the allowed delimiters `[[:space:];|&]`.
+# Caught in the post-#140 audit pass, 2026-04-20.
+#
+# Flag handling: `(-[a-zA-Z]+[[:space:]]+)*` allows zero or more
+# separate flag groups like `-x ` or `-e `. Final flag uses
+# `-[a-zA-Z]*c` — must end in `c` (the `-c`-ness), optional letters
+# before it cover combined forms like `-xc`, `-lc`, `-exc`.
+SHELL_C_PATTERN='(^|[[:space:];|&])(sudo[[:space:]]+|env[[:space:]]+([A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*|[A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*(bash|sh|zsh)[[:space:]]+(-[a-zA-Z]+[[:space:]]+)*-[a-zA-Z]*c[[:space:]]+[^[:space:]].*(gh[[:space:]]|git[[:space:]]+push([[:space:]]|$))'
+
+if [[ ! "$COMMAND" =~ $GH_PATTERN ]] && [[ ! "$COMMAND" =~ $SHELL_C_PATTERN ]]; then
+  # Not a gh/git-push command — allow without checking token.
+  exit 0
+fi
+
+# `gh auth *` is identity-management (login, logout, status, token,
+# refresh, setup-git) — user-attribution is correct by design here.
+# Blanket-blocking this subcommand would put the hook directly in the
+# onboarding path (fresh workspace → first `gh auth login` → wall of
+# error text), which is exactly the wrong user experience. Carve it
+# out. Wrapper forms (`sudo gh auth ...`) also match because the regex
+# allows arbitrary wrapper prefix before `gh`.
+if [[ "$COMMAND" =~ (^|[[:space:];|&])(sudo[[:space:]]+|env[[:space:]]+([A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*|[A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*gh[[:space:]]+auth([[:space:]]|$) ]]; then
+  exit 0
+fi
+
+# Check GH_TOKEN: must be present AND start with ghs_ (bot token).
+# ghp_/gho_/ghu_ are user tokens; empty falls through to stored
+# `gh auth login` (user). Either case fires the trap.
+# Note: `${GH_TOKEN:-}` expansion is mandatory under `set -u`; a bare
+# `${GH_TOKEN:0:4}` errors with "unbound variable" when the env var
+# is unset, which is exactly the case we need to handle.
+GH_TOKEN_VALUE="${GH_TOKEN:-}"
+TOKEN_PREFIX="${GH_TOKEN_VALUE:0:4}"
+if [[ -z "$GH_TOKEN_VALUE" ]] || [[ "$TOKEN_PREFIX" != "ghs_" ]]; then
+  cat >&2 <<ERR
+BLOCKED by MACF attribution-trap hook: this command would post as the USER, not the BOT.
+
+Command: ${COMMAND}
+GH_TOKEN prefix: ${TOKEN_PREFIX:-(empty)}
+
+This hook exists because behavioral controls for the GH_TOKEN attribution
+trap recurred 5 times in a single day. See groundnuty/macf#140 and
+.claude/rules/coordination.md (Token & Git Hygiene).
+
+Fix — refresh the bot token via the fail-loud helper:
+
+  GH_TOKEN=\$(./.claude/scripts/macf-gh-token.sh \\
+    --app-id "\$APP_ID" --install-id "\$INSTALL_ID" --key "\$KEY_PATH") || exit 1
+  export GH_TOKEN
+
+If the helper is missing, restore it:
+  macf rules refresh --dir .
+
+Override (ONLY for intentional user-attributed ops like onboarding):
+  export MACF_SKIP_TOKEN_CHECK=1
+ERR
+  exit 2
+fi
+
+exit 0

package/scripts/macf-gh-token.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# Generate a fresh GitHub App installation token and emit it on stdout.
+#
+# Designed to fail LOUD — not fall back silently to `gh auth login` as the
+# user, which is what happens with the naive `$(gh token generate | jq)`
+# pattern when `gh token generate` fails (pipefail unset by default, so
+# jq's success masks gh's failure and GH_TOKEN ends up as "null").
+#
+# Callers should use `TOKEN=$(./.claude/scripts/macf-gh-token.sh ...) || exit 1`
+# or similar — on any failure this script writes the error reason to stderr
+# and exits non-zero, and prints NOTHING to stdout.
+#
+# Usage:
+#   macf-gh-token.sh --app-id <id> --install-id <id> --key <path> [--hostname <host>]
+#
+# On success: the installation token (starts with `ghs_`) is printed on
+# stdout with a trailing newline.
+# On failure: error goes to stderr, exit status is non-zero, stdout is empty.
+
+set -euo pipefail
+
+usage() {
+  cat <<USAGE >&2
+Usage: $0 --app-id <id> --install-id <id> --key <path> [--hostname <host>]
+
+Required:
+  --app-id <id>        GitHub App ID
+  --install-id <id>    GitHub App installation ID
+  --key <path>         Path to the App private key (.pem)
+
+Optional:
+  --hostname <host>    GitHub Enterprise hostname (default: api.github.com)
+
+On success the installation token (ghs_*) is printed to stdout.
+On failure, error details go to stderr and exit is non-zero.
+USAGE
+}
+
+app_id=""
+install_id=""
+key_path=""
+hostname=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --app-id)     app_id="${2:?--app-id requires value}";     shift 2 ;;
+    --install-id) install_id="${2:?--install-id requires value}"; shift 2 ;;
+    --key)        key_path="${2:?--key requires value}";      shift 2 ;;
+    --hostname)   hostname="${2:?--hostname requires value}"; shift 2 ;;
+    -h|--help)    usage; exit 0 ;;
+    *)            echo "Error: unknown argument: $1" >&2; usage; exit 2 ;;
+  esac
+done
+
+missing=()
+[ -z "$app_id" ]     && missing+=(--app-id)
+[ -z "$install_id" ] && missing+=(--install-id)
+[ -z "$key_path" ]   && missing+=(--key)
+if [ "${#missing[@]}" -gt 0 ]; then
+  echo "Error: missing required flag(s): ${missing[*]}" >&2
+  usage
+  exit 2
+fi
+
+if [ ! -f "$key_path" ]; then
+  echo "Error: key file not found: $key_path" >&2
+  echo "Hint: check that KEY_PATH in .claude/settings.local.json points at a valid .pem file." >&2
+  exit 1
+fi
+
+# Capture stderr so we can grep for known failure patterns and add
+# diagnostic hints, but keep it available to re-emit to the user.
+err_file="$(mktemp -t macf-gh-token-err.XXXXXX)"
+trap 'rm -f "$err_file"' EXIT
+
+gh_args=(gh token generate
+  --app-id "$app_id"
+  --installation-id "$install_id"
+  --key "$key_path"
+  --token-only
+)
+[ -n "$hostname" ] && gh_args+=(--hostname "$hostname")
+
+# Intentionally NOT piping through `jq` — --token-only gives us the bare
+# token, so we don't need to parse JSON, and we avoid the `$(gh | jq)`
+# exit-status-masking trap that started this whole issue.
+if ! token="$("${gh_args[@]}" 2>"$err_file")"; then
+  echo "Error: gh token generate failed." >&2
+  if [ -s "$err_file" ]; then
+    echo "--- gh token generate stderr ---" >&2
+    cat "$err_file" >&2
+    echo "--------------------------------" >&2
+  fi
+
+  # Hint the most common causes we've observed.
+  if grep -qi "JWT could not be decoded\|JWT" "$err_file" 2>/dev/null; then
+    echo "" >&2
+    echo "Hint: 'JWT could not be decoded' typically indicates **clock drift** on this host." >&2
+    echo "  Check:  timedatectl status        (expect: System clock synchronized: yes)" >&2
+    echo "          chronyc tracking          (expect: Leap status: Normal, small offset)" >&2
+  elif grep -qi "unable to read key" "$err_file" 2>/dev/null; then
+    echo "" >&2
+    echo "Hint: key file unreadable. Verify file permissions (should be user-readable)." >&2
+  elif grep -qi "unable to parse key\|PEM.*RSA" "$err_file" 2>/dev/null; then
+    echo "" >&2
+    echo "Hint: key file is not a valid PEM RSA key, or it does not match the App's registered key." >&2
+    echo "  Compare your local key fingerprint to the App settings page on GitHub:" >&2
+    echo "    openssl rsa -in \"$key_path\" -pubout -outform DER 2>/dev/null | openssl dgst -sha256" >&2
+    echo "    (then check GitHub → App settings → Private keys → SHA256 fingerprint)" >&2
+  elif grep -qi "404\|Not Found" "$err_file" 2>/dev/null; then
+    echo "" >&2
+    echo "Hint: App or installation not found. Verify --app-id and --install-id." >&2
+  fi
+  exit 1
+fi
+
+# Sanity-check the result. Installation tokens start with ghs_. Anything
+# else (ghp_ user PAT, gho_ OAuth, empty string) would be a footgun.
+token_prefix="${token:0:4}"
+if [ -z "$token" ]; then
+  echo "Error: gh token generate succeeded but returned an empty token." >&2
+  exit 1
+fi
+if [ "$token_prefix" != "ghs_" ]; then
+  echo "Error: generated token has prefix '${token_prefix}' — expected 'ghs_' (installation token)." >&2
+  echo "  Refusing to emit a non-installation token to avoid mis-attribution." >&2
+  exit 1
+fi
+
+printf '%s\n' "$token"

package/scripts/macf-whoami.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Print the identity associated with the current GH_TOKEN, and flag it
+# LOUDLY if the token is the wrong type (e.g., a user PAT where a bot
+# installation token is expected).
+#
+# This exists because of the silent-fallback trap: when `gh token generate`
+# fails, `gh` falls back to the locally stored `gh auth login` token,
+# and subsequent `gh` operations silently run as the user — but nothing
+# surfaces the identity mismatch until cross-agent routing breaks.
+#
+# Usage:
+#   macf-whoami.sh       # prints identity to stdout; non-zero exit on trouble
+#
+# Token prefixes (per GitHub docs):
+#   ghs_  — server-to-server (App installation token) → /user returns 403
+#   ghp_  — personal access token
+#   gho_  — OAuth user token
+#   ghu_  — user-to-server (GitHub App user-access) token
+
+set -euo pipefail
+
+if [ -z "${GH_TOKEN:-}" ]; then
+  echo "Error: GH_TOKEN is unset." >&2
+  exit 1
+fi
+
+prefix="${GH_TOKEN:0:4}"
+
+case "$prefix" in
+  ghs_)
+    # Installation token — /user is 403. This is the EXPECTED prefix for a
+    # healthy bot operation.
+    echo "bot installation token (prefix=ghs_)"
+    ;;
+  ghp_|gho_|ghu_)
+    user="$(gh api user --jq '.login' 2>/dev/null || echo '<unknown>')"
+    echo "user token: $user (prefix=$prefix)"
+    echo "" >&2
+    echo "WARNING: this is NOT a bot installation token. All gh/git-push" >&2
+    echo "operations will be attributed to '$user', not to the bot." >&2
+    echo "If you expected a bot token, run:" >&2
+    echo "  .claude/scripts/macf-gh-token.sh --app-id \$APP_ID --install-id \$INSTALL_ID --key \$KEY_PATH" >&2
+    echo "and look at its stderr diagnostics." >&2
+    exit 2
+    ;;
+  *)
+    echo "unknown token type (prefix=$prefix, first chars only shown)" >&2
+    echo "Expected ghs_ (bot installation), ghp_ (user PAT), gho_ (OAuth), or ghu_ (user-to-server)." >&2
+    exit 3
+    ;;
+esac

package/scripts/tmux-send-to-claude.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Send a prompt to a Claude Code TUI running in a tmux session.
+#
+# Claude Code's TUI is in multi-line input mode by default, so a single
+# Enter inserts a newline instead of submitting. Sending the prompt and
+# a single Enter leaves the text stuck in the input buffer until someone
+# manually presses Enter again.
+#
+# The correct pattern is:
+#   1. C-u                  — clear any stale input
+#   2. "<prompt>" + Enter   — type the prompt and a first Enter
+#   3. sleep 1              — let tmux deliver those as one read event
+#                             (without the sleep, tmux may batch both
+#                             Enters together and Claude processes them
+#                             atomically as "newline + newline", never
+#                             submitting)
+#   4. Enter                — the second Enter that actually submits
+#
+# Usage:
+#   tmux-send-to-claude.sh <session> <prompt>
+#
+#   <session> — tmux target session/window/pane (e.g. "agent:0"), or
+#               empty string "" to send to the current pane (useful
+#               when the caller is already inside the target tmux).
+#   <prompt>  — the prompt text to submit.
+#
+# This script is the ONLY sanctioned way to programmatically submit a
+# prompt to a Claude Code TUI. Never inline `tmux send-keys ... Enter`
+# for prompt submission — the quirk above is easy to forget.
+
+set -euo pipefail
+
+if [ "$#" -lt 2 ]; then
+  echo "usage: $0 <session-or-empty> <prompt>" >&2
+  exit 2
+fi
+
+session="$1"
+prompt="$2"
+
+if [ -n "$session" ]; then
+  tmux send-keys -t "$session" C-u
+  tmux send-keys -t "$session" "$prompt" Enter
+  sleep 1
+  tmux send-keys -t "$session" Enter
+else
+  tmux send-keys C-u
+  tmux send-keys "$prompt" Enter
+  sleep 1
+  tmux send-keys Enter
+fi

package/scripts/write-build-info.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Postbuild: write `dist/.build-info.json` so the installed CLI can
+ * detect a stale-dist situation at runtime (per #144).
+ *
+ * The file records the git HEAD at build time + an ISO timestamp.
+ * `macf update` + `macf self-update` compare this against the source
+ * repo's current HEAD to decide whether the operator's linked CLI is
+ * behind main.
+ *
+ * Fail-soft on `git` errors: on a shallow clone or npm tarball
+ * install where `.git/` isn't available, write `commit: "unknown"`
+ * so the CLI still ships cleanly. The stale-detect path treats
+ * `unknown` as "don't know, don't warn."
+ */
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = dirname(SCRIPT_DIR);
+const DIST_DIR = join(REPO_ROOT, 'dist');
+const TARGET = join(DIST_DIR, '.build-info.json');
+
+function gitCommit() {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: REPO_ROOT,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+if (!existsSync(DIST_DIR)) {
+  mkdirSync(DIST_DIR, { recursive: true });
+}
+
+const info = {
+  commit: gitCommit(),
+  built_at: new Date().toISOString(),
+};
+
+writeFileSync(TARGET, JSON.stringify(info, null, 2) + '\n');
+console.log(`Wrote ${TARGET}: commit=${info.commit.slice(0, 7)} built_at=${info.built_at}`);