@freibergergarcia/phone-a-friend 2.3.1 → 2.6.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "phone-a-friend",
   "description": "CLI relay that lets AI coding agents collaborate by sending prompts and repository context to backend agents.",
-  "version": "2.3.1",
+  "version": "2.6.3",
   "author": {
     "name": "Bruno Freiberger"
   }

package/README.md

@@ -11,7 +11,6 @@
   [![CI](https://github.com/freibergergarcia/phone-a-friend/actions/workflows/ci.yml/badge.svg)](https://github.com/freibergergarcia/phone-a-friend/actions/workflows/ci.yml)
   [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
   ![Node.js 22.13+](https://img.shields.io/badge/node-%E2%89%A522.13-green)
-  [![Website](https://img.shields.io/badge/website-phone--a--friend-blue)](https://freibergergarcia.github.io/phone-a-friend/)
 
 </div>
 
@@ -136,7 +135,7 @@ phone-a-friend --to codex --prompt "List files that need refactoring" \
   --schema '{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}}},"required":["files"],"additionalProperties":false}'
 ```
 
-Claude and Codex enforce the schema natively. Gemini, Ollama, and OpenCode use prompt injection (best-effort).
+Claude, Codex, and Ollama enforce the schema through their native structured-output surfaces. Gemini and OpenCode CLI use prompt injection (best-effort), with PaF validating built-in verdict envelopes before returning them.
 
 ### Sessions
 
@@ -201,6 +200,40 @@ phone-a-friend config edit     # Open in $EDITOR
 
 `doctor` reports CLI backends, local backends (Ollama), host integration status (Claude / OpenCode plugin install state), and a summary count. The OpenCode CLI is treated as optional: if you only use Claude Code and don't have OpenCode installed, doctor will not flag that as a degraded state.
 
+### Update notifications
+
+phone-a-friend checks the npm registry for newer stable releases at most once
+every 24 hours and prints a one-time stderr banner the next time it runs in an
+interactive terminal. The current invocation is never slowed down: the registry
+fetch happens in the background, with results applied on the next run.
+
+Sample banner:
+
+```
+  ↑ phone-a-friend X.Y.Z available (current: A.B.C)
+    Run: npm install -g @freibergergarcia/phone-a-friend@latest
+```
+
+The banner is suppressed automatically when:
+- stdout or stderr is not a TTY (piped or redirected output)
+- `CI` is set, or `TERM=dumb`
+- the command uses `--quiet`, `--schema`, `--verdict-json`, or any subcommand-level `--json` flag
+- the same version was already shown within the last 7 days
+
+To disable update checks entirely:
+
+```bash
+# One-off
+PHONE_A_FRIEND_UPDATE_CHECK=false phone-a-friend ...
+
+# Permanent
+phone-a-friend config set defaults.update_check false
+```
+
+The cache lives at `~/.config/phone-a-friend/update-check.json` (or under
+`$XDG_CONFIG_HOME` if set). Run `phone-a-friend doctor` to inspect the current
+state.
+
 ## Backends
 
 | Backend | Type | Streaming |

package/commands/curiosity-engine.md

@@ -62,12 +62,12 @@ When `RELAY_MODE = direct`, call backend CLIs directly instead of using the
 
 | Backend | Direct command |
 |---------|---------------|
-| **Codex** | `codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "<combined-prompt>" < /dev/null` |
-| **Gemini** | `gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "<combined-prompt>"` |
-| **Ollama** | `curl -s http://localhost:11434/api/chat -H "Content-Type: application/json" -d '{"model":"<model>","messages":[{"role":"user","content":"<combined-prompt>"}],"stream":false}' \| jq -r '.message.content'` |
+| **Codex** | `codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "$(cat "$PROMPT_FILE")" < /dev/null` |
+| **Gemini** | `gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "$(cat "$PROMPT_FILE")"` |
+| **Ollama** | `PROMPT_JSON="$(jq -Rs . < "$PROMPT_FILE")"; curl -s http://localhost:11434/api/chat -H "Content-Type: application/json" -d "{\"model\":\"<model>\",\"messages\":[{\"role\":\"user\",\"content\":${PROMPT_JSON}}],\"stream\":false}" \| jq -r '.message.content'` |
 
-In direct mode, combine the relay prompt into a single string using this
-template:
+In direct mode, build `PROMPT_FILE` from the relay prompt using this
+template and the quoted-heredoc rule:
 
 ```
 You are helping another coding agent by reviewing or advising on work in a local repository.
@@ -123,6 +123,7 @@ If `--backend` value is not `codex`, `gemini`, or `ollama`: report error and sto
 
 Set:
 - TOPIC = parsed topic string
+- TOPIC_SAFE = TOPIC (untrusted text; never splice it into an inline shell command)
 - MAX_ROUNDS = parsed rounds (default 3, clamped [1, 6])
 - BACKEND = parsed backend (default `codex`)
 - ROUND = 1
@@ -179,43 +180,48 @@ Display to user:
 Claude Code, the OpenCode model name in OpenCode). Pick one that the user
 will recognize.
 
-Then relay to backend:
+Then relay to backend. First build `PROMPT_FILE` so untrusted text such as
+TOPIC and QUESTION is passed as data, not spliced into an inline shell
+command:
+
+```bash
+PROMPT_FILE="$(mktemp)"
+trap 'rm -f "$PROMPT_FILE" "${REPROMPT_FILE:-}"' EXIT
+{
+  printf '%s\n' 'You are playing The Curiosity Engine — a structured Q&A rally with another agent.'
+  printf 'Topic: %s\n' "$TOPIC_SAFE"
+  printf 'Round: 1 of %s\n\n' "$MAX_ROUNDS"
+  printf '%s\n' "The orchestrating agent's question for you:"
+  printf '%s\n\n' "$QUESTION"
+  cat <<'PAF_CURIOSITY_PROMPT_EOF'
+You MUST respond in EXACTLY this format — no exceptions, no extra text:
+
+ANSWER: <your answer to the orchestrator's question, 2-4 sentences>
+QUESTION: <a new question for the orchestrator on the same topic, that you are genuinely curious about>
+
+Do not add any text before ANSWER: or after the QUESTION line.
+PAF_CURIOSITY_PROMPT_EOF
+} > "$PROMPT_FILE"
+```
 
 **Binary mode** (`RELAY_MODE = binary`):
 ```bash
-phone-a-friend --to <BACKEND> --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF [--model <model>] --prompt "<relay-prompt>"
+phone-a-friend --to <BACKEND> --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF [--model <model>] --prompt "$(cat "$PROMPT_FILE")"
 ```
 
 **Direct mode** (`RELAY_MODE = direct`):
 ```bash
 # Codex:
-codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "<relay-prompt>" < /dev/null
+codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "$(cat "$PROMPT_FILE")" < /dev/null
 # Gemini (always include -m):
-gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "<relay-prompt>"
+gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "$(cat "$PROMPT_FILE")"
 # Ollama (use OLLAMA_SELECTED_MODEL from Step 2):
+PROMPT_JSON="$(jq -Rs . < "$PROMPT_FILE")"
 curl -s http://localhost:11434/api/chat -H "Content-Type: application/json" \
-  -d '{"model":"<OLLAMA_SELECTED_MODEL>","messages":[{"role":"user","content":"<relay-prompt>"}],"stream":false}' \
+  -d "{\"model\":\"<OLLAMA_SELECTED_MODEL>\",\"messages\":[{\"role\":\"user\",\"content\":${PROMPT_JSON}}],\"stream\":false}" \
   | jq -r '.message.content'
 ```
 
-Where `<relay-prompt>` is:
-
-```
-You are playing The Curiosity Engine — a structured Q&A rally with another agent.
-Topic: <TOPIC>
-Round: 1 of <MAX_ROUNDS>
-
-The orchestrating agent's question for you:
-<QUESTION>
-
-You MUST respond in EXACTLY this format — no exceptions, no extra text:
-
-ANSWER: <your answer to the orchestrator's question, 2-4 sentences>
-QUESTION: <a new question for the orchestrator on the same topic, that you are genuinely curious about>
-
-Do not add any text before ANSWER: or after the QUESTION line.
-```
-
 ## Step 4 — Parse Backend Response
 
 If the relay call (binary or direct) produces no output, empty stdout, or a
@@ -237,35 +243,39 @@ After each relay call, parse the response for `ANSWER:` and `QUESTION:` fields.
 
 Send one correction relay if `ANSWER:` or `QUESTION:` is missing:
 
+First create `REPROMPT_FILE` with a quoted heredoc:
+
+```bash
+REPROMPT_FILE="$(mktemp)"
+cat > "$REPROMPT_FILE" <<'PAF_CURIOSITY_REPROMPT_EOF'
+Your previous response did not follow the required format.
+You MUST respond with EXACTLY this structure:
+
+ANSWER: <your answer>
+QUESTION: <your question for the orchestrator>
+
+No other text. Try again.
+PAF_CURIOSITY_REPROMPT_EOF
+```
+
 **Binary mode** (`RELAY_MODE = binary`):
 ```bash
-phone-a-friend --to <BACKEND> --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF [--model <model>] --prompt "<re-prompt>"
+phone-a-friend --to <BACKEND> --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF [--model <model>] --prompt "$(cat "$REPROMPT_FILE")"
 ```
 
 **Direct mode** (`RELAY_MODE = direct`):
 ```bash
 # Codex:
-codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "<re-prompt>" < /dev/null
+codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "$(cat "$REPROMPT_FILE")" < /dev/null
 # Gemini:
-gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "<re-prompt>"
+gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "$(cat "$REPROMPT_FILE")"
 # Ollama:
+REPROMPT_JSON="$(jq -Rs . < "$REPROMPT_FILE")"
 curl -s http://localhost:11434/api/chat -H "Content-Type: application/json" \
-  -d '{"model":"<OLLAMA_SELECTED_MODEL>","messages":[{"role":"user","content":"<re-prompt>"}],"stream":false}' \
+  -d "{\"model\":\"<OLLAMA_SELECTED_MODEL>\",\"messages\":[{\"role\":\"user\",\"content\":${REPROMPT_JSON}}],\"stream\":false}" \
   | jq -r '.message.content'
 ```
 
-Where `<re-prompt>` is:
-
-```
-Your previous response did not follow the required format.
-You MUST respond with EXACTLY this structure:
-
-ANSWER: <your answer>
-QUESTION: <your question for the orchestrator>
-
-No other text. Try again.
-```
-
 Parse again. If still missing `QUESTION:` → end game early. Display:
 ```
 ⚠️  <BACKEND> broke the chain on round <N> (missing QUESTION: after re-prompt).
@@ -363,7 +373,7 @@ capability, or debugging requires a pin.
 with cache path, expiry, and bypass instructions; no auto-substitution):
 
 ```bash
-phone-a-friend --to gemini --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF --prompt "<relay-prompt>"
+phone-a-friend --to gemini --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF --prompt "$(cat "$PROMPT_FILE")"
 ```
 
 To bypass the cache: `PHONE_A_FRIEND_GEMINI_DEAD_CACHE=false`. Or delete the
@@ -371,7 +381,7 @@ cache file to clear it.
 
 **Direct mode** (no PaF wrapper — orchestrator handles retry):
 ```bash
-gemini --sandbox --yolo --include-directories "$PWD" --output-format text --prompt "<relay-prompt>"
+gemini --sandbox --yolo --include-directories "$PWD" --output-format text --prompt "$(cat "$PROMPT_FILE")"
 ```
 
 In direct mode, on capacity/transient errors (429, 500, 503), retry with a

package/commands/phone-a-friend.md

@@ -35,6 +35,9 @@ into the current conversation.
   subcommands (e.g. `phone-a-friend phone-a-team`).
 - `--backend` is a `/phone-a-team` skill argument, not a PaF CLI flag. Do
   not pass `--backend` to `phone-a-friend`.
+- When materializing relay commands, write dynamic prompt/context text into
+  temp files using single-quoted heredocs. Do not splice user text, prior
+  model output, or conversation context into double-quoted shell arguments.
 - Do NOT dump repo files or git output into `--context-file` or
   `--context-text`. Repo-aware backends read files via `--repo "$PWD"`
   using their own tools. See "Context hygiene" below.
@@ -61,11 +64,11 @@ When `RELAY_MODE = direct`, call backend CLIs directly instead of using the
 
 | Backend | Direct command |
 |---------|---------------|
-| **Codex** | `codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "<combined-prompt>" < /dev/null` |
-| **Gemini** | `gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "<combined-prompt>"` |
+| **Codex** | `codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "$(cat "$PROMPT_FILE")" < /dev/null` |
+| **Gemini** | `gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "$(cat "$PROMPT_FILE")"` |
 
-In direct mode, combine prompt + context into a single string using this
-template:
+In direct mode, build `PROMPT_FILE` from prompt + context using this
+template and the quoted-heredoc rule:
 
 ```
 You are helping another coding agent by reviewing or advising on work in a local repository.
@@ -168,12 +171,29 @@ I'm working on this task and got the above response. Please review it and return
 
    **Binary mode** (`RELAY_MODE = binary`):
    ```bash
-   phone-a-friend --to codex --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" $PAF_NO_DIFF [--fast] [--session <id>]
+   RELAY_BIN="$(command -v phone-a-friend)"
+   PROMPT_FILE="$(mktemp)"
+   CONTEXT_FILE="$(mktemp)"
+   trap 'rm -f "$PROMPT_FILE" "$CONTEXT_FILE"' EXIT
+
+   cat > "$PROMPT_FILE" <<'PAF_PROMPT_EOF'
+<relay-prompt>
+PAF_PROMPT_EOF
+
+   cat > "$CONTEXT_FILE" <<'PAF_CONTEXT_EOF'
+<context-payload>
+PAF_CONTEXT_EOF
+
+   "$RELAY_BIN" --to codex --repo "$PWD" --prompt "$(cat "$PROMPT_FILE")" --context-file "$CONTEXT_FILE" $PAF_NO_DIFF [--fast] [--session <id>]
    # For gemini, omit --model by default (let auto-routing pick); see "Gemini model selection" below.
    # Do NOT pass --session to gemini — it will error (see "Session continuity" below):
-   phone-a-friend --to gemini --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" $PAF_NO_DIFF [--fast]
+   "$RELAY_BIN" --to gemini --repo "$PWD" --prompt "$(cat "$PROMPT_FILE")" --context-file "$CONTEXT_FILE" $PAF_NO_DIFF [--fast]
    ```
 
+   Use delimiter names that do not appear in the payload. The quoted heredoc
+   marker (`<<'PAF_PROMPT_EOF'`) is intentional: it makes shell treat the
+   body as data, not executable text.
+
    `$PAF_NO_DIFF` comes from the probe in "Diff suppression" above. It
    resolves to `--no-include-diff` on new binaries and an empty string on
    stale binaries (with `PHONE_A_FRIEND_INCLUDE_DIFF=false` exported as
@@ -185,14 +205,14 @@ I'm working on this task and got the above response. Please review it and return
    **Direct mode** (`RELAY_MODE = direct`):
    ```bash
    # Codex:
-   codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "<combined-prompt>" < /dev/null
+   codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "$(cat "$PROMPT_FILE")" < /dev/null
    # Gemini (omit -m for auto-routing; pin only when reproducibility/capability is needed):
-   gemini --sandbox --yolo --include-directories "$PWD" --output-format text --prompt "<combined-prompt>"
+   gemini --sandbox --yolo --include-directories "$PWD" --output-format text --prompt "$(cat "$PROMPT_FILE")"
    ```
 
-   In direct mode, build `<combined-prompt>` using the template from the
-   "Direct call reference" section, substituting `<relay-prompt>` and
-   `<context-payload>` into the template.
+   In direct mode, build `PROMPT_FILE` from the template in the "Direct call
+   reference" section using the same quoted-heredoc rule, substituting
+   `<relay-prompt>` and `<context-payload>` into the file body.
 
    Note: `--fast`, `--session`, and `--no-include-diff` are PaF CLI flags
    only available in binary mode. Do not append them to direct-mode

package/commands/phone-a-team.md

@@ -37,19 +37,20 @@ When `RELAY_MODE = direct`, call backend CLIs directly instead of using the
 
 | Backend | Direct command |
 |---------|---------------|
-| **Codex** | `codex exec -C "$PWD" --skip-git-repo-check --sandbox <mode> "<combined-prompt>" < /dev/null` |
-| **Gemini** | `gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "<combined-prompt>"` |
-| **Ollama** | `curl -s http://localhost:11434/api/chat -H "Content-Type: application/json" -d '{"model":"<model>","messages":[{"role":"user","content":"<combined-prompt>"}],"stream":false}' \| jq -r '.message.content'` |
+| **Codex** | `codex exec -C "$PWD" --skip-git-repo-check --sandbox <mode> "$(cat "$PROMPT_FILE")" < /dev/null` |
+| **Gemini** | `gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "$(cat "$PROMPT_FILE")"` |
+| **Ollama** | `PROMPT_JSON="$(jq -Rs . < "$PROMPT_FILE")"; curl -s http://localhost:11434/api/chat -H "Content-Type: application/json" -d "{\"model\":\"<model>\",\"messages\":[{\"role\":\"user\",\"content\":${PROMPT_JSON}}],\"stream\":false}" \| jq -r '.message.content'` |
 
 Sandbox mapping for direct mode:
 - **Codex**: pass the mode string directly (`--sandbox read-only` or
   `--sandbox workspace-write`)
 - **Gemini**: `--sandbox` flag is boolean. Present = sandboxed (read-only).
-  For workspace-write, omit `--sandbox`.
+  Use `--sandbox` for both read-only and workspace-write; omit it only for
+  `danger-full-access`.
 - **Ollama**: no sandbox support. All context must be in the prompt.
 
-In direct mode, combine prompt + context + diff into a single string using
-this template:
+In direct mode, build `PROMPT_FILE` from prompt + context + diff using this
+template and the quoted-heredoc rule:
 
 ```
 You are helping another coding agent by reviewing or advising on work in a local repository.
@@ -113,9 +114,13 @@ matrix and skip rules).
 Extract a model name from the task arguments.
 
 **Explicit flag (highest priority, all backends):**
-- If `$ARGUMENTS` contains `--model <name>`: set `MODEL_OVERRIDE = <name>`.
-  Remove the `--model <name>` pair from TASK_DESCRIPTION.
-- This applies to all backends (codex, gemini, ollama, both).
+- If `$ARGUMENTS` contains `--model <name>`: validate `<name>` against
+  `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`.
+- If invalid (spaces, quotes, backticks, shell metacharacters, or a leading
+  punctuation character): abort and ask the user for a safe model name.
+- If valid: set `MODEL_OVERRIDE = <name>` and remove the `--model <name>`
+  pair from TASK_DESCRIPTION.
+- This applies to all backends (codex, gemini, ollama, both, all).
 
 **Natural language extraction (Ollama only, lower priority):**
 - Only attempt NL extraction when BACKEND is exactly `ollama` and no
@@ -129,6 +134,9 @@ Extract a model name from the task arguments.
   TASK_DESCRIPTION.
 - If the candidate appears inside quotes, backticks, or code blocks, do
   NOT extract (it's an example or reference, not a meta-instruction).
+- Validate extracted names with `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`. If
+  the extracted candidate fails validation, abort and ask the user for a
+  safe model name.
 
 **Examples:**
 - "review this code, use deepseek" (backend=ollama) → extract "deepseek" ✓
@@ -227,13 +235,14 @@ server has nothing to run — proceeding would always fail.
 If models are available, select using this precedence:
 1. If `MODEL_OVERRIDE` is set (from `--model` flag or NL extraction in
    Step 1): set `OLLAMA_SELECTED_MODEL = MODEL_OVERRIDE`. Check if it exists
-   in `OLLAMA_AVAILABLE_MODELS`. If not found, **warn** (e.g., "Model 'foo'
-   not found in local models: [bar, baz]. Proceeding anyway — it may be a
-   tag variant.") but proceed.
+   in `OLLAMA_AVAILABLE_MODELS`. If not found, **abort** and ask the user
+   to choose one of the discovered local models.
 2. If no override and `RELAY_MODE = binary`: check config by running
    `phone-a-friend config get backends.ollama.model`. If a value is
-   returned, set `OLLAMA_SELECTED_MODEL` to that value. Validate against
-   `OLLAMA_AVAILABLE_MODELS` — warn if not found but proceed.
+   returned, validate it against `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`,
+   then set `OLLAMA_SELECTED_MODEL` to that value. Validate against
+   `OLLAMA_AVAILABLE_MODELS` — if not found, abort and ask the user to
+   choose one of the discovered local models.
    If `RELAY_MODE = direct`: skip this step (the binary is not available to
    query config). Fall through to option 3.
 3. If neither override nor config: set `OLLAMA_SELECTED_MODEL` to the first
@@ -342,6 +351,12 @@ command:
 
 3. **Each teammate's prompt** must use this template:
 
+   Shell safety rule: every dynamic prompt/context payload must be written
+   to a temp file with a single-quoted heredoc before invoking Bash. Do not
+   splice user text, prior model output, or conversation context into
+   double-quoted shell arguments. Model names still go through the safe
+   model-name validation from Step 1.
+
    **Binary mode** (`RELAY_MODE = binary`):
    ```
    You are a relay worker. Your ONLY job: run the command below via Bash,
@@ -350,8 +365,20 @@ command:
 
    Run this now:
 
-   phone-a-friend --to <backend> --repo "$PWD" --prompt "<prompt>" \
-     [--context-text "<context>"] $PAF_NO_DIFF \
+   PROMPT_FILE="$(mktemp)"
+   CONTEXT_FILE="$(mktemp)"
+   trap 'rm -f "$PROMPT_FILE" "$CONTEXT_FILE"' EXIT
+
+   cat > "$PROMPT_FILE" <<'PAF_TEAM_PROMPT_EOF'
+   <prompt>
+   PAF_TEAM_PROMPT_EOF
+
+   cat > "$CONTEXT_FILE" <<'PAF_TEAM_CONTEXT_EOF'
+   <context>
+   PAF_TEAM_CONTEXT_EOF
+
+   phone-a-friend --to <backend> --repo "$PWD" --prompt "$(cat "$PROMPT_FILE")" \
+     [--context-file "$CONTEXT_FILE"] $PAF_NO_DIFF \
      [--sandbox <mode>] [--model <model>] --fast [--session <SESSION_ID>]
 
    Note: for `--to claude`, `--fast` has no effect.
@@ -439,6 +466,61 @@ is identical — only the execution mechanism changes.
 Execute a do-review-decide loop. Maximum MAX_ROUNDS rounds. Stop early if
 converged.
 
+### Convergence trace
+
+Before the loop starts, initialize an in-memory `CONVERGENCE_TRACE` array.
+This trace is local to the current command run; it is not analytics, tracking,
+or persisted product telemetry.
+
+After the REVIEW phase of each round, append a verdict envelope (the exact
+same shape used by `phone-a-friend --verdict-json`). The array index is the
+round number minus one, so do not add a separate `round` property to the
+envelope:
+
+```
+CONVERGENCE_TRACE = []  # index = round - 1
+
+# Each entry is a verdict envelope:
+{
+  "schema_version": 1,
+  "verdict": "ship" | "iterate" | "abstain",
+  "summary": "<one-sentence synthesis>",
+  "findings": [
+    { "severity": "blocker" | "important" | "nit",
+      "title": "<headline>",
+      "rationale": "<why it matters>",
+      "location": "<file or file:line> or null" }
+  ]
+}
+```
+
+The verdict is **derived from severities**: any `blocker` or `important`
+finding => `iterate`; empty findings or only `nit` findings => `ship`;
+`abstain` only when the reviewer cannot make a confident call AND findings
+is empty. This matches `parseVerdict()` in PaF's `src/verdict.ts`. Do not
+contradict the rule (e.g. do not record verdict=ship while listing a
+blocker — that is a malformed envelope).
+
+Two ways to source the verdict envelope per round:
+
+1. **Lead-judged (default)**: the lead orchestrator runs the rubric in
+   Phase 2 REVIEW and emits the envelope based on its own judgment. No
+   extra relay call. Cheap, fits text-output rounds, suitable for most
+   tasks.
+2. **Backend-judged (optional, file-change rounds)**: when the round
+   produced file changes that exist as a git diff, the lead MAY also
+   run `phone-a-friend --to <backend> --review --verdict-json` for an
+   independent third-party verdict. If used, merge it conservatively with
+   the lead-judged envelope: any blocker or important finding from either
+   source makes the trace verdict `iterate`, and a backend `ship` verdict
+   MUST NOT erase blocker or important findings the lead already found.
+   Prefer the backend envelope only when it is stricter than the lead, or
+   when the lead abstained and the backend produced a concrete verdict.
+   Cap at one verdict-json relay call per round.
+
+Both sources produce the same envelope shape, so CONVERGENCE_TRACE is uniform
+either way.
+
 ### Timing Expectations
 
 Different backends have different response times:
@@ -487,7 +569,19 @@ Delegate the task to the backend via the relay. The lead's job is to
 
   **Binary mode** (`RELAY_MODE = binary`):
   ```bash
-  phone-a-friend --to <backend> --repo "$PWD" --prompt "<prompt>" [--context-text "<context>"] $PAF_NO_DIFF [--sandbox <mode>] [--model <model>] --fast [--session <SESSION_ID>]
+  PROMPT_FILE="$(mktemp)"
+  CONTEXT_FILE="$(mktemp)"
+  trap 'rm -f "$PROMPT_FILE" "$CONTEXT_FILE"' EXIT
+
+  cat > "$PROMPT_FILE" <<'PAF_TEAM_PROMPT_EOF'
+<prompt>
+PAF_TEAM_PROMPT_EOF
+
+  cat > "$CONTEXT_FILE" <<'PAF_TEAM_CONTEXT_EOF'
+<context>
+PAF_TEAM_CONTEXT_EOF
+
+  phone-a-friend --to <backend> --repo "$PWD" --prompt "$(cat "$PROMPT_FILE")" [--context-file "$CONTEXT_FILE"] $PAF_NO_DIFF [--sandbox <mode>] [--model <model>] --fast [--session <SESSION_ID>]
   ```
 
   Diff inclusion: `$PAF_NO_DIFF` is set by the probe in "Diff inclusion
@@ -509,21 +603,23 @@ Delegate the task to the backend via the relay. The lead's job is to
   **Direct mode** (`RELAY_MODE = direct`):
   ```bash
   # Codex:
-  codex exec -C "$PWD" --skip-git-repo-check --sandbox <mode> "<combined-prompt>" < /dev/null
-  # Gemini (omit --sandbox for workspace-write):
-  gemini [--sandbox] --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "<combined-prompt>"
+  codex exec -C "$PWD" --skip-git-repo-check --sandbox <mode> "$(cat "$PROMPT_FILE")" < /dev/null
+  # Gemini (`--sandbox` for read-only/workspace-write; omit only for danger-full-access):
+  gemini [--sandbox] --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "$(cat "$PROMPT_FILE")"
   # Ollama:
+  PROMPT_JSON="$(jq -Rs . < "$PROMPT_FILE")"
   curl -s http://localhost:11434/api/chat -H "Content-Type: application/json" \
-    -d '{"model":"<OLLAMA_SELECTED_MODEL>","messages":[{"role":"user","content":"<combined-prompt>"}],"stream":false}' \
+    -d "{\"model\":\"<OLLAMA_SELECTED_MODEL>\",\"messages\":[{\"role\":\"user\",\"content\":${PROMPT_JSON}}],\"stream\":false}" \
     | jq -r '.message.content'
   ```
 
   Note: `--fast` and `--session` are not available in direct mode. Direct
   mode relay calls are always stateless (each round starts fresh).
 
-  In direct mode, build `<combined-prompt>` using the template from the
-  "Direct call reference" section. If `--include-diff` is used, run
-  `git diff HEAD` and append the output to the template's "Git Diff" section.
+  In direct mode, build `PROMPT_FILE` using the template from the "Direct call
+  reference" section and the quoted-heredoc rule. If `--include-diff` is used,
+  run `git diff HEAD` and append the output to the template's "Git Diff"
+  section inside that file.
 
   For gemini, omit `--model` by default and let auto-routing pick (see "Gemini model selection" section).
   For ollama, always include `--model` / model field using `OLLAMA_SELECTED_MODEL` from preflight.
@@ -562,16 +658,47 @@ round 1" on tasks that deserve iteration.
   the better output, note the disagreement and rationale for selection.
 - If one backend fails → continue with the successful one, note the failure.
 
+#### Phase 2.5: Convergence trace snapshot
+
+After REVIEW, append the verdict envelope for this round to
+`CONVERGENCE_TRACE` (see "Convergence trace" above). Display a one-line
+summary to the user before moving to DECIDE:
+
+```
+Round N: verdict=<ship|iterate|abstain> | catches: B blocker, I important, X nits
+```
+
+(omit zero-count categories: `Round 2: verdict=iterate | catches: 1 important, 2 nits`).
+
+**Diminishing-returns warning** (only when comparing round N to round N-1,
+both with verdict=iterate): if round N has equal-or-more findings than
+round N-1 AND blocker+important counts did not decrease, surface a single
+stderr-style line BEFORE the DECIDE phase:
+
+```
+Round N may not be making progress: same/more catches than round N-1, no severity decrease. Consider stopping.
+```
+
+This is a hint, not a hard stop. The lead may still continue if there is a
+reason (e.g. the round addressed a blocker but introduced an important
+finding). When continuing past the warning, briefly note the rationale in
+the next-round feedback.
+
 #### Phase 3: DECIDE
 
-Based on the review:
+Based on CONVERGENCE_TRACE[round-1].verdict and the review:
 
-- **Converged** (all rubric items pass): Stop the loop. Execute Step 8
+- **Converged** (verdict = `ship`): Stop the loop. Execute Step 8
   (Cleanup), then Step 9 (Final Synthesis). Do not iterate further — no
   iterating for its own sake.
-- **Issues found** (one or more rubric items fail): Formulate specific,
-  actionable feedback. Start the next round with this feedback incorporated
-  into the prompt.
+- **Issues found** (verdict = `iterate`): Formulate specific, actionable
+  feedback derived from the round's findings (use the `title` and
+  `rationale` of each blocker/important entry). Start the next round
+  with this feedback incorporated into the prompt.
+- **Inconclusive** (verdict = `abstain`): The reviewer could not make
+  a confident call. Surface what's missing (in `summary`) and either
+  request that information from the user OR run one more round with a
+  more focused prompt. Do not declare convergence on `abstain`.
 - **Backend error** (timeout, crash, unexpected failure): Note the failure.
   If another backend is available, try it. If no backend produced a
   successful result this round: if a previous round had a usable result,
@@ -753,6 +880,18 @@ a clear synthesis to the user. Include ALL of the following:
      convergence.
 5. **Sandbox note**: If `--sandbox workspace-write` was used at any point,
    note it here.
+6. **Convergence retrospective** (from `CONVERGENCE_TRACE`):
+   - Find the first round whose verdict is `ship`. Call that one-based round
+     number `K` (`CONVERGENCE_TRACE` array index + 1).
+   - If `K` exists and `K < MAX_ROUNDS`, append:
+     `Hint: this run reached "ship" at round K. Try --max-rounds K next time for a similar task.`
+   - If `K` does not exist (no ship-verdict in any round), append:
+     `Hint: no round reached "ship" — task may need decomposition, more context, or out-of-band work before re-running.`
+   - If a diminishing-returns warning fired during the run, mention it
+     here too: `Round X did not show progress over round X-1; if you see
+     this pattern again, consider --max-rounds (X-1).`
+   - Skip the retrospective when only a single round ran (insufficient
+     data to make any recommendation).
 
 Format the synthesis clearly. The user should understand at a glance what
 happened and whether the result is complete.
@@ -861,10 +1000,10 @@ The following precedence determines `OLLAMA_SELECTED_MODEL` during preflight:
 
 1. **`MODEL_OVERRIDE`** (from `--model` flag or NL extraction in Step 1) —
    highest priority. Validate against `OLLAMA_AVAILABLE_MODELS`. If not
-   found, warn but proceed.
+   found, abort and ask the user to choose one of the discovered models.
 2. **Config `backends.ollama.model`** — set via TUI model picker or
-   `phone-a-friend config set`. Validate against available models, warn if
-   not found.
+   `phone-a-friend config set`. Validate against the safe model-name pattern
+   and available models; abort if invalid or unavailable.
 3. **First model from `/api/tags`** — fallback auto-selection.
 
 - **Do NOT maintain a model priority list** for Ollama. Unlike Gemini, Ollama