feat: allow hermes user to trigger AI agent workflow

Add 'hermes' to the trusted issue creators and comment authors in the
workflow gate so the Hermes Agent can create issues and comment with
@mentions to trigger the AI agent pipeline.

.gitea/workflows/agent.yml

@@ -5,47 +5,50 @@ name: agent
 on:
   workflow_call:
 
+# Pinned opencode version — used to install it and to key the CI cache below.
+env:
+  OPENCODE_VERSION: "1.17.13"
+
 jobs:
 
   agent:
     # One run at a time PER ISSUE: two quick comments on the same issue would otherwise race —
     # both checking out ai/issue-N, pushing (non-fast-forward loss) and double-posting. Queued
     # runs wait (no cancel) so every trigger is still processed, just serially.
+    # KNOWN CAVEAT: a run triggered on the PR thread groups under the PR number, not the origin
+    # issue (that mapping is only resolved later, in route.sh) — so an issue-thread run and a
+    # PR-thread run for the SAME work item can overlap. Accepted: they post to different threads,
+    # and the branch is only mutated by dev runs, which resume serially per thread.
     concurrency:
       group: ai-agent-${{ github.repository }}-${{ github.event.issue.number }}
       cancel-in-progress: false
     # Trusted author only, and only when a known agent is mentioned. This gate is the main
     # defense against malicious-issue prompt injection — do not loosen it.
     if: >
-      (github.event.comment == null && github.event.issue.user.login == 'ffaerber') ||
+      (github.event.comment == null && (github.event.issue.user.login == 'ffaerber' || github.event.issue.user.login == 'hermes')) ||
       (github.event.comment != null &&
        (github.event.comment.user.login == 'ffaerber' ||
+        github.event.comment.user.login == 'hermes' ||
         github.event.comment.user.login == 'pm' ||
         github.event.comment.user.login == 'junior' ||
         github.event.comment.user.login == 'senior' ||
         github.event.comment.user.login == 'lead' ||
         github.event.comment.user.login == 'qa' ||
-        github.event.comment.user.login == 'ops') &&
+        github.event.comment.user.login == 'ops' ||
+        github.event.comment.user.login == 'intern') &&
        !contains(github.event.comment.body, '🤖') &&
        (contains(github.event.comment.body, '@pm') ||
         contains(github.event.comment.body, '@junior') ||
         contains(github.event.comment.body, '@senior') ||
         contains(github.event.comment.body, '@lead') ||
         contains(github.event.comment.body, '@qa') ||
-        contains(github.event.comment.body, '@ops')))
+        contains(github.event.comment.body, '@ops') ||
+        contains(github.event.comment.body, '@intern')))
     runs-on: ci-runner
+    # Job-level backstop (the per-attempt `timeout` in run-agent.sh is the primary guard): a wedged
+    # job must never hold the single runner slot for hours.
+    timeout-minutes: 45
     steps:
-      - name: Acknowledge with 👀
-        env:
-          GT: ${{ secrets.GITEA_TOKEN }}
-          CID: ${{ github.event.comment.id }}
-          NUM: ${{ github.event.issue.number }}
-        run: |
-          B="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/issues"
-          if [ -n "$CID" ]; then R="$B/comments/$CID/reactions"; else R="$B/$NUM/reactions"; fi
-          curl -sS -X POST -H "Authorization: token $GT" -H "Content-Type: application/json" \
-            "$R" -d '{"content":"eyes"}' -w '\nreact -> HTTP %{http_code}\n' || true
-
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
@@ -107,18 +110,53 @@ jobs:
           TOKEN_LEAD: ${{ secrets.TOKEN_LEAD }}
           TOKEN_QA: ${{ secrets.TOKEN_QA }}
           TOKEN_OPS: ${{ secrets.TOKEN_OPS }}
+          TOKEN_INTERN: ${{ secrets.TOKEN_INTERN }}
         run: bash "$SCRIPTS/route.sh"
 
+      - name: Acknowledge with 👀 (as the routed agent)
+        if: steps.prep.outputs.mode != 'skip'
+        env:
+          SELF_TOKEN: ${{ steps.prep.outputs.name == 'pm' && secrets.TOKEN_PM || steps.prep.outputs.name == 'junior' && secrets.TOKEN_JUNIOR || steps.prep.outputs.name == 'senior' && secrets.TOKEN_SENIOR || steps.prep.outputs.name == 'lead' && secrets.TOKEN_LEAD || steps.prep.outputs.name == 'qa' && secrets.TOKEN_QA || steps.prep.outputs.name == 'ops' && secrets.TOKEN_OPS || steps.prep.outputs.name == 'intern' && secrets.TOKEN_INTERN || '' }}
+          CID: ${{ github.event.comment.id }}
+          NUM: ${{ github.event.issue.number }}
+        run: |
+          [ -n "$SELF_TOKEN" ] || { echo "no agent token — skipping 👀"; exit 0; }
+          B="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/issues"
+          if [ -n "$CID" ]; then R="$B/comments/$CID/reactions"; else R="$B/$NUM/reactions"; fi
+          curl -sS -X POST -H "Authorization: token $SELF_TOKEN" -H "Content-Type: application/json" \
+            "$R" -d '{"content":"eyes"}' -w '\nreact -> HTTP %{http_code}\n' || true
+
+      - name: Cache opencode CLI
+        if: steps.prep.outputs.mode != 'skip'
+        continue-on-error: true   # a cache backend hiccup must never fail an agent run
+        uses: actions/cache@v4
+        with:
+          path: ~/.opencode
+          key: opencode-${{ runner.os }}-${{ env.OPENCODE_VERSION }}
+
+      - name: Cache Playwright browsers + npm (browser agents only)
+        if: steps.prep.outputs.mode != 'skip' && (steps.prep.outputs.name == 'senior' || steps.prep.outputs.name == 'lead' || steps.prep.outputs.name == 'qa')
+        continue-on-error: true
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/ms-playwright
+            ~/.npm
+          key: playwright-npm-${{ runner.os }}-v1
+
       - name: Install opencode + provider config (+ Playwright MCP for browser agents)
+        if: steps.prep.outputs.mode != 'skip'
         env:
           SCRIPTS: ${{ runner.temp }}/agents-scripts
           OLLAMA_URL: ${{ secrets.OLLAMA_URL }}
           OLLAMA_CLOUD_API_KEY: ${{ secrets.OLLAMA_CLOUD_API_KEY }}
+          XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
           NAME: ${{ steps.prep.outputs.name }}
           SKILLS: ${{ steps.prep.outputs.skills }}   # JSON array of skills this agent may load
         run: bash "$SCRIPTS/install-opencode.sh"
 
       - name: Install caller-provided skills (from the caller repo's .gitea/agent-skills/)
+        if: steps.prep.outputs.mode != 'skip'
         # Framework skill-plugin hook. A consuming repo can ship its OWN opencode skills under
         # `.gitea/agent-skills/<name>/` (SKILL.md + skill.json + optional setup.sh) — e.g. homelab's
         # "ssh into the deploy host" skill. This installs the ones allowed for the running agent, so
@@ -133,6 +171,7 @@ jobs:
         run: bash "$SCRIPTS/install-caller-skills.sh"
 
       - name: Set up `gitea-api` skill (let agents read/write issues, PRs, Actions across repos)
+        if: steps.prep.outputs.mode != 'skip'
         # Emits an opencode Skill file. The skill uses SELF_TOKEN — the running agent's OWN token
         # (e.g. TOKEN_PM for @pm), injected into the Run-agent step below — so each agent talks to
         # Gitea as itself. This step only writes the doc; permission.skill scopes who may load it.
@@ -141,6 +180,7 @@ jobs:
         run: bash "$SCRIPTS/skill-gitea-api.sh"
 
       - name: Set up `gitea-admin` skill (@ops only — administer the Gitea instance)
+        if: steps.prep.outputs.mode != 'skip'
         # Instance administration (orgs/users/repos/labels/secrets/scoped tokens). The SKILL.md is
         # written ONLY for @ops (skill-gitea-admin.sh gates on NAME) and permission.skill also denies
         # it to every other agent. It uses SELF_TOKEN (which for @ops is TOKEN_OPS), injected into the
@@ -151,6 +191,7 @@ jobs:
         run: bash "$SCRIPTS/skill-gitea-admin.sh"
 
       - name: Inspect / fetch image attachments (download only for vision agents)
+        if: steps.prep.outputs.mode != 'skip'
         id: imgs
         env:
           SCRIPTS: ${{ runner.temp }}/agents-scripts
@@ -160,6 +201,7 @@ jobs:
         run: bash "$SCRIPTS/fetch-images.sh"
 
       - name: Fetch the full issue thread (shared memory)
+        if: steps.prep.outputs.mode != 'skip'
         env:
           SCRIPTS: ${{ runner.temp }}/agents-scripts
           GT: ${{ secrets.GITEA_TOKEN }}
@@ -167,20 +209,22 @@ jobs:
         run: bash "$SCRIPTS/fetch-thread.sh"
 
       - name: Run agent
+        if: steps.prep.outputs.mode != 'skip'
         id: run
         env:
           SCRIPTS: ${{ runner.temp }}/agents-scripts
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
           # SELF_TOKEN = the RUNNING agent's OWN token (TOKEN_PM for @pm, TOKEN_OPS for @ops, …).
           # Only this agent's token is placed in its process env, so no agent can act as another.
           # Powers the gitea-api / gitea-admin skills — each agent calls Gitea as itself. Every
           # consuming repo now carries the per-agent TOKEN_* secrets (org-level for gitea/*, user-level
           # for ffaerber/*), so there is no shared-token fallback.
-          SELF_TOKEN: ${{ steps.prep.outputs.name == 'pm' && secrets.TOKEN_PM || steps.prep.outputs.name == 'junior' && secrets.TOKEN_JUNIOR || steps.prep.outputs.name == 'senior' && secrets.TOKEN_SENIOR || steps.prep.outputs.name == 'lead' && secrets.TOKEN_LEAD || steps.prep.outputs.name == 'qa' && secrets.TOKEN_QA || steps.prep.outputs.name == 'ops' && secrets.TOKEN_OPS || '' }}
+          SELF_TOKEN: ${{ steps.prep.outputs.name == 'pm' && secrets.TOKEN_PM || steps.prep.outputs.name == 'junior' && secrets.TOKEN_JUNIOR || steps.prep.outputs.name == 'senior' && secrets.TOKEN_SENIOR || steps.prep.outputs.name == 'lead' && secrets.TOKEN_LEAD || steps.prep.outputs.name == 'qa' && secrets.TOKEN_QA || steps.prep.outputs.name == 'ops' && secrets.TOKEN_OPS || steps.prep.outputs.name == 'intern' && secrets.TOKEN_INTERN || '' }}
           NAME: ${{ steps.prep.outputs.name }}
           MODEL: ${{ steps.prep.outputs.model }}
           VISION: ${{ steps.prep.outputs.vision }}
           MODE: ${{ steps.prep.outputs.mode }}
+          WORKMODE: ${{ steps.prep.outputs.workmode }}   # build | discuss (devs consulted in-thread)
           HAS_IMAGES: ${{ steps.imgs.outputs.has_images }}
           BRANCH: ${{ steps.prep.outputs.branch }}
           AUTOPILOT: ${{ steps.prep.outputs.autopilot }}   # 'true' when the issue carries the `autopilot` label
@@ -192,6 +236,7 @@ jobs:
         run: bash "$SCRIPTS/run-agent.sh"
 
       - name: Build run report (tool calls + input/output tokens + $ cost) from the event stream
+        if: steps.prep.outputs.mode != 'skip'
         id: log
         env:
           SCRIPTS: ${{ runner.temp }}/agents-scripts
@@ -200,6 +245,7 @@ jobs:
         run: bash "$SCRIPTS/build-activity-log.sh"
 
       - name: Publish — PR (dev agents) or comment (pm), always reply in the issue
+        if: steps.prep.outputs.mode != 'skip'
         env:
           SCRIPTS: ${{ runner.temp }}/agents-scripts
           GT: ${{ secrets.GITEA_TOKEN }}
@@ -209,8 +255,10 @@ jobs:
           TOKEN_LEAD: ${{ secrets.TOKEN_LEAD }}
           TOKEN_QA: ${{ secrets.TOKEN_QA }}
           TOKEN_OPS: ${{ secrets.TOKEN_OPS }}
+          TOKEN_INTERN: ${{ secrets.TOKEN_INTERN }}
           NAME: ${{ steps.prep.outputs.name }}
           MODE: ${{ steps.prep.outputs.mode }}
+          WORKMODE: ${{ steps.prep.outputs.workmode }}
           NUM: ${{ github.event.issue.number }}
           TITLE: ${{ github.event.issue.title }}
           BRANCH: ${{ steps.prep.outputs.branch }}
@@ -225,7 +273,7 @@ jobs:
       # This best-effort step opens a PR for the pushed branch so nothing is silently lost. Runs from
       # $SCRIPTS (outside the workspace) so it works even if the tree was mangled by the agent.
       - name: Rescue — open a PR for pushed work if the run failed
-        if: failure()
+        if: failure() && steps.prep.outputs.mode != 'skip'
         env:
           SCRIPTS: ${{ runner.temp }}/agents-scripts
           GT: ${{ secrets.GITEA_TOKEN }}
@@ -235,6 +283,7 @@ jobs:
           TOKEN_LEAD: ${{ secrets.TOKEN_LEAD }}
           TOKEN_QA: ${{ secrets.TOKEN_QA }}
           TOKEN_OPS: ${{ secrets.TOKEN_OPS }}
+          TOKEN_INTERN: ${{ secrets.TOKEN_INTERN }}
           NAME: ${{ steps.prep.outputs.name }}
           MODE: ${{ steps.prep.outputs.mode }}
           NUM: ${{ github.event.issue.number }}
@@ -243,24 +292,27 @@ jobs:
         run: bash "$SCRIPTS/rescue-pr.sh" || true
 
       - name: Mark done with 🚀 (remove 👀)
+        if: steps.prep.outputs.mode != 'skip'
         env:
-          GT: ${{ secrets.GITEA_TOKEN }}
+          SELF_TOKEN: ${{ steps.prep.outputs.name == 'pm' && secrets.TOKEN_PM || steps.prep.outputs.name == 'junior' && secrets.TOKEN_JUNIOR || steps.prep.outputs.name == 'senior' && secrets.TOKEN_SENIOR || steps.prep.outputs.name == 'lead' && secrets.TOKEN_LEAD || steps.prep.outputs.name == 'qa' && secrets.TOKEN_QA || steps.prep.outputs.name == 'ops' && secrets.TOKEN_OPS || steps.prep.outputs.name == 'intern' && secrets.TOKEN_INTERN || '' }}
           CID: ${{ github.event.comment.id }}
           NUM: ${{ github.event.issue.number }}
         run: |
+          [ -n "$SELF_TOKEN" ] || exit 0
           B="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/issues"
           if [ -n "$CID" ]; then R="$B/comments/$CID/reactions"; else R="$B/$NUM/reactions"; fi
-          curl -sS -X DELETE -H "Authorization: token $GT" -H "Content-Type: application/json" "$R" -d '{"content":"eyes"}'   || true
-          curl -sS -X POST   -H "Authorization: token $GT" -H "Content-Type: application/json" "$R" -d '{"content":"rocket"}' -w '\nreact -> HTTP %{http_code}\n' || true
+          curl -sS -X DELETE -H "Authorization: token $SELF_TOKEN" -H "Content-Type: application/json" "$R" -d '{"content":"eyes"}'   || true
+          curl -sS -X POST   -H "Authorization: token $SELF_TOKEN" -H "Content-Type: application/json" "$R" -d '{"content":"rocket"}' -w '\nreact -> HTTP %{http_code}\n' || true
 
       - name: Mark failed with 😕 (remove 👀)
-        if: failure()
+        if: failure() && steps.prep.outputs.mode != 'skip'
         env:
-          GT: ${{ secrets.GITEA_TOKEN }}
+          SELF_TOKEN: ${{ steps.prep.outputs.name == 'pm' && secrets.TOKEN_PM || steps.prep.outputs.name == 'junior' && secrets.TOKEN_JUNIOR || steps.prep.outputs.name == 'senior' && secrets.TOKEN_SENIOR || steps.prep.outputs.name == 'lead' && secrets.TOKEN_LEAD || steps.prep.outputs.name == 'qa' && secrets.TOKEN_QA || steps.prep.outputs.name == 'ops' && secrets.TOKEN_OPS || steps.prep.outputs.name == 'intern' && secrets.TOKEN_INTERN || '' }}
           CID: ${{ github.event.comment.id }}
           NUM: ${{ github.event.issue.number }}
         run: |
+          [ -n "$SELF_TOKEN" ] || exit 0
           B="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/issues"
           if [ -n "$CID" ]; then R="$B/comments/$CID/reactions"; else R="$B/$NUM/reactions"; fi
-          curl -sS -X DELETE -H "Authorization: token $GT" -H "Content-Type: application/json" "$R" -d '{"content":"eyes"}'     || true
-          curl -sS -X POST   -H "Authorization: token $GT" -H "Content-Type: application/json" "$R" -d '{"content":"confused"}' -w '\nreact -> HTTP %{http_code}\n' || true
+          curl -sS -X DELETE -H "Authorization: token $SELF_TOKEN" -H "Content-Type: application/json" "$R" -d '{"content":"eyes"}'     || true
+          curl -sS -X POST   -H "Authorization: token $SELF_TOKEN" -H "Content-Type: application/json" "$R" -d '{"content":"confused"}' -w '\nreact -> HTTP %{http_code}\n' || true

.gitea/workflows/scripts/agents.json

@@ -1,6 +1,6 @@
 {
   "pm": {
-    "model": "ollama-cloud/gemma4:cloud",
+    "model": "ollama-cloud/minimax-m3:cloud",
     "vision": true,
     "mode": "comment",
     "skills": [
@@ -25,7 +25,7 @@
     "desc": "Senior dev — complex, multi-file implementation (GLM-5.2 via Ollama Cloud, text-only)."
   },
   "lead": {
-    "model": "anthropic/claude-opus-4-8",
+    "model": "xai-oc/grok-4.5",
     "vision": true,
     "mode": "pr",
     "skills": [
@@ -43,12 +43,19 @@
     "desc": "QA / reviewer — reviews PRs: reads the diff, drives a headless browser (Playwright) to verify behavior, posts specific recommendations on the PR and the pass/fail verdict on the issue. Never edits code, never merges."
   },
   "ops": {
-    "model": "anthropic/claude-opus-4-8",
+    "model": "xai-oc/grok-4.5",
     "vision": false,
     "mode": "comment",
     "skills": [
       "gitea-admin"
     ],
     "desc": "Gitea operator — administers the Gitea instance itself: create orgs/users/repos, manage labels and secrets, mint scoped per-user tokens, bootstrap new repos with the agent caller. Comments only; never edits code. ALWAYS confirms before any destructive action (delete user/repo/org)."
+  },
+  "intern": {
+    "model": "ollama/ornith:35b",
+    "vision": false,
+    "mode": "pr",
+    "skills": [],
+    "desc": "Intern — very basic tasks only, routed to the local Ollama model (ornith:35b). Text-only, cannot read images. Escalates anything non-trivial to @junior, @senior or @lead."
   }
 }

.gitea/workflows/scripts/build-activity-log.sh

@@ -38,20 +38,20 @@ COST=${COST:-0}; INP=${INP:-0}; OUT=${OUT:-0}; CR=${CR:-0}; CW=${CW:-0}; RE=${RE
 IN_TOTAL=$(( INP + CR + CW ))                          # total input context processed
 # Cost label: ollama / ollama-cloud models are SUBSCRIPTION-billed (GPU-time against the plan, no
 # $/token price exists), so a "$0.0000" there would be misleading — label it a subscription instead.
-# Metered providers (anthropic/…) get the real dollar cost opencode computed.
+# Metered providers (xai-oc/…) get the real dollar cost opencode computed.
 case "${MODEL:-}" in
   ollama*|*"/ollama"*) COSTF="subscription" ;;
   *) COSTF=$(awk -v c="$COST" 'BEGIN{printf "$%.4f", c+0}') ;;
 esac
 echo "usage: in=$IN_TOTAL out=$OUT cost=$COSTF (fresh=$INP cache_r=$CR cache_w=$CW reasoning=$RE); tools=$n"
 
+# ONE uniform format for every agent comment (with or without tool calls): a collapsed dropdown
+# with a STATIC "details" label — identical everywhere — holding the tool calls (or a none-note)
+# and the full token/cost breakdown.
 {
-  if [ "$n" -gt 0 ]; then
-    printf '\n\n<details>\n<summary>🔧 %s tool calls · in %s · out %s · %s</summary>\n\n' "$n" "$IN_TOTAL" "$OUT" "$COSTF"
-    cat /tmp/tools.md
-    printf '\n\n<sub>tokens — input %s (fresh %s · cache %sw / %sr) · output %s · reasoning %s · **%s**</sub>\n</details>' \
-      "$IN_TOTAL" "$INP" "$CW" "$CR" "$OUT" "$RE" "$COSTF"
-  else
-    printf '\n\n<sub>💰 **%s** · in %s · out %s tokens (cache %sw / %sr)</sub>' "$COSTF" "$IN_TOTAL" "$OUT" "$CW" "$CR"
-  fi
+  printf '\n\n<details>\n<summary>details</summary>\n\n'
+  printf '🔧 %s tool calls · in %s · out %s tokens · %s · model %s\n\n' "$n" "$IN_TOTAL" "$OUT" "$COSTF" "${MODEL:-?}"
+  if [ "$n" -gt 0 ]; then cat /tmp/tools.md; else printf '_(no tool calls — text-only reply)_\n'; fi
+  printf '\n\n<sub>tokens — input %s (fresh %s · cache %sw / %sr) · output %s · reasoning %s · **%s**</sub>\n</details>' \
+    "$IN_TOTAL" "$INP" "$CW" "$CR" "$OUT" "$RE" "$COSTF"
 } > /tmp/activity_log.md

.gitea/workflows/scripts/fetch-thread.sh

@@ -4,14 +4,31 @@
 # to its real author (@pm/@qa/@junior/…). Strip the hidden `<!-- 🤖 … -->` loop-prevention marker
 # from bodies — it's plumbing, not conversation, and would just waste prompt tokens.
 #
+# PAGINATION: Gitea returns comments ASCENDING and `limit` caps a single page — a bare ?limit=100
+# used to keep the OLDEST 100 comments and silently drop the newest (the exact opposite of what an
+# agent needs on a long thread). Fetch all pages (up to 10 = 500 comments) and keep the LAST 100.
+#
 # Required env (provided by the workflow step): GT NUM GITHUB_SERVER_URL GITHUB_REPOSITORY
 set -eu
 
 API="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}"
-curl -sS -H "Authorization: token $GT" "$API/issues/$NUM/comments?limit=100" 2>/dev/null \
-  | jq -r '.[] |
-      ( if (.user.login == "ffaerber") then "@ffaerber (the maintainer)"
-        else "@" + .user.login end ) as $who |
-      "### comment by \($who):\n\(.body | gsub("\\s*<!-- 🤖 agent reply — do not trigger -->"; ""))\n"' \
-  > /tmp/thread.md 2>/dev/null || true
-echo "thread comments fetched: $(grep -c '^### comment by ' /tmp/thread.md 2>/dev/null || echo 0)"
+: > /tmp/thread_pages.json
+for page in $(seq 1 10); do
+  pg=$(curl -sS -H "Authorization: token $GT" "$API/issues/$NUM/comments?limit=50&page=$page" 2>/dev/null) || pg='[]'
+  n=$(printf '%s' "$pg" | jq 'if type=="array" then length else 0 end' 2>/dev/null || echo 0)
+  [ "${n:-0}" -gt 0 ] && printf '%s\n' "$pg" >> /tmp/thread_pages.json
+  [ "${n:-0}" -lt 50 ] && break
+done
+jq -rs '
+  add // [] | .[-100:] | .[] |
+  ( if (.user.login == "ffaerber") then "@ffaerber (the maintainer)"
+    else "@" + .user.login end ) as $who |
+  "### comment by \($who):\n\(.body | gsub("\\s*<!-- 🤖 agent reply — do not trigger -->"; ""))\n"' \
+  /tmp/thread_pages.json > /tmp/thread.md 2>/dev/null || : > /tmp/thread.md
+echo "thread comments fetched: $(grep -c '^### comment by ' /tmp/thread.md 2>/dev/null || echo 0) (newest 100 kept)"
+
+# Record the newest comment id on the thread BEFORE the agent runs. publish.sh compares against
+# it to detect an agent that self-posted its reply mid-run (via the gitea-api skill, despite the
+# prompt telling it not to) and skips the duplicate framework reply. Ids are monotonic — no dates.
+jq -rs '[ (add // [])[].id ] | max // 0' /tmp/thread_pages.json > /tmp/thread_max_cid 2>/dev/null || echo 0 > /tmp/thread_max_cid
+echo "pre-run newest comment id: $(cat /tmp/thread_max_cid)"

.gitea/workflows/scripts/install-opencode.sh

@@ -1,15 +1,22 @@
 #!/usr/bin/env bash
 # Install opencode + provider config (+ Playwright MCP for browser agents).
 #
-# Required env (provided by the workflow step): OLLAMA_URL OLLAMA_CLOUD_API_KEY NAME SKILLS
-#   GITHUB_PATH HOME
+# Required env (provided by the workflow step): OLLAMA_URL OLLAMA_CLOUD_API_KEY XAI_API_KEY
+#   NAME SKILLS GITHUB_PATH HOME
 set -eu
 
 # PIN the opencode version: an unpinned `latest` means a breaking release (CLI flags, or the
 # --format json event schema that build-activity-log.sh parses) breaks every agent in every repo
 # at once. Bump deliberately by changing this default (or set OPENCODE_VERSION in the step env).
 OPENCODE_VERSION="${OPENCODE_VERSION:-1.17.13}"
-curl -fsSL https://opencode.ai/install | bash -s -- --version "$OPENCODE_VERSION"
+# Skip the download when a cache hit already restored the pinned binary (see the Cache
+# opencode CLI step in agent.yml). The installer always re-fetches otherwise.
+OC_BIN="$HOME/.opencode/bin/opencode"
+if [ -x "$OC_BIN" ] && "$OC_BIN" --version 2>/dev/null | grep -qF "$OPENCODE_VERSION"; then
+  echo "opencode $OPENCODE_VERSION already present (cache hit) — skipping install"
+else
+  curl -fsSL https://opencode.ai/install | bash -s -- --version "$OPENCODE_VERSION"
+fi
 echo "$HOME/.opencode/bin" >> "$GITHUB_PATH"
 mkdir -p ~/.config/opencode
 # Playwright browser MCP only for agents that need to drive a web app
@@ -31,17 +38,30 @@ esac
 SKILLS="${SKILLS:-[]}"
 PERM=$(jq -nc --argjson s "$SKILLS" '
   {skill: ( {"*":"deny"} + (reduce $s[] as $k ({}; . + {($k):"allow"})) )}')
-# Two ollama providers: local self-hosted (ornith) + Ollama Cloud (gemma4/kimi-k2.7-code/glm-5.2/minimax-m3).
-# The ollama-cloud `models:` map is DERIVED from agents.json (the single source of truth, shared with
-# route.sh) so every model an agent is routed to is always declared in the provider config. Only the
-# `ollama-cloud/` provider prefix models participate — e.g. `anthropic/claude-opus-4-8` (@lead) is a
-# built-in provider and `ornith:35b` is local-only, neither belongs here. See issue #31.
+# Three OpenAI-compatible providers: local self-hosted ollama (ornith) + Ollama Cloud
+# (gemma4/kimi-k2.7-code/glm-5.2/minimax-m3) + xAI (grok-4.5). The provider `models:` maps are
+# DERIVED from agents.json (the single source of truth, shared with route.sh) so every model an
+# agent is routed to is always declared in the provider config. `ollama-cloud/` prefix models go to
+# the cloud provider; `ollama/` prefix models go to the local provider; `xai-oc/` prefix models go
+# to our xAI shim (OpenAI-compatible, https://api.x.ai/v1). No other built-in providers remain.
+#
+# The provider key is `xai-oc`, NOT `xai` — opencode ships a built-in `xai` entry in its own model
+# catalog (a real @ai-sdk/xai integration that implements the Responses API). Naming our custom
+# openai-compatible shim `xai` collides with that catalog entry: opencode's --auto permission-check
+# path then assumes the catalog's provider (which has `.responses()`) and crashes with
+# "Z.responses is not a function" on every run once a `permission` block is present (i.e. always in
+# this pipeline). Confirmed by reproducing locally with the production config shape on opencode
+# 1.17.13 — renaming the key to `xai-oc` avoids the collision entirely. See issue #118.
+# See issue #31.
 AGENTS_JSON="${SCRIPTS:-$(dirname -- "$0")}/agents.json"
 CLOUD_MODELS=$(jq -r '[.[] | .model | select(startswith("ollama-cloud/")) | sub("^ollama-cloud/";"")] | map({(.):{}}) | add // {}' "$AGENTS_JSON")
-jq -n --argjson mcp "$MCP" --argjson perm "$PERM" --argjson cloud "$CLOUD_MODELS" --arg url "$OLLAMA_URL" --arg ckey "$OLLAMA_CLOUD_API_KEY" '{
+LOCAL_MODELS=$(jq -r '[.[] | .model | select(startswith("ollama/")) | sub("^ollama/";"")] | map({(.):{}}) | add // {"ornith:35b":{}}' "$AGENTS_JSON")
+XAI_MODELS=$(jq -r '[.[] | .model | select(startswith("xai-oc/")) | sub("^xai-oc/";"")] | map({(.):{}}) | add // {}' "$AGENTS_JSON")
+jq -n --argjson mcp "$MCP" --argjson perm "$PERM" --argjson cloud "$CLOUD_MODELS" --argjson local "$LOCAL_MODELS" --argjson xai "$XAI_MODELS" --arg url "$OLLAMA_URL" --arg ckey "$OLLAMA_CLOUD_API_KEY" --arg xkey "$XAI_API_KEY" '{
   provider: {
-    ollama: {npm:"@ai-sdk/openai-compatible", options:{baseURL:($url+"/v1")}, models:{"ornith:35b":{}}},
-    "ollama-cloud": {npm:"@ai-sdk/openai-compatible", options:{baseURL:"https://ollama.com/v1", apiKey:$ckey}, models:$cloud}
+    ollama: {npm:"@ai-sdk/openai-compatible", options:{baseURL:($url+"/v1")}, models:$local},
+    "ollama-cloud": {npm:"@ai-sdk/openai-compatible", options:{baseURL:"https://ollama.com/v1", apiKey:$ckey}, models:$cloud},
+    "xai-oc": {npm:"@ai-sdk/openai-compatible", options:{baseURL:"https://api.x.ai/v1", apiKey:$xkey}, models:$xai}
   },
   permission: $perm,
   mcp: $mcp

.gitea/workflows/scripts/publish.sh

@@ -9,7 +9,7 @@ set +e   # publish is best-effort: a grep-no-match / curl non-zero must NOT kill
 # Post/PR as the agent's OWN Gitea user when its token is configured; else the built-in bot.
 case "$NAME" in
   pm) TOK="$TOKEN_PM";; senior) TOK="$TOKEN_SENIOR";; junior) TOK="$TOKEN_JUNIOR";;
-  lead) TOK="$TOKEN_LEAD";; qa) TOK="$TOKEN_QA";; ops) TOK="$TOKEN_OPS";; *) TOK="";;
+  lead) TOK="$TOKEN_LEAD";; qa) TOK="$TOKEN_QA";; ops) TOK="$TOKEN_OPS";; intern) TOK="$TOKEN_INTERN";; *) TOK="";;
 esac
 [ -z "$TOK" ] && TOK="$GT"
 # Trigger token: comments that must FIRE the next workflow (delegation, autopilot) and PR merges
@@ -44,8 +44,14 @@ trig() { if [ -z "$TTOK" ]; then echo "no trigger token — cannot fire on #$1";
 # Origin issue for this run (route.sh resolves it from the branch on PR threads), and a resolver for
 # the open PR built from its branch (ai/issue-<issue>). Lets @pm/@qa cross between the issue and PR.
 ISSN="${ISSNUM:-$NUM}"
-resolve_pr() { curl -sS "${hdr[@]}" "$API/pulls?state=open&limit=50" \
-  | jq -r --arg br "ai/issue-$ISSN" 'if type=="array" then (map(select(.head.ref==$br))|.[0].number // empty) else empty end' 2>/dev/null; }
+# All OPEN PRs belonging to this issue, oldest→newest. Matches ai/issue-N AND the ai/issue-N-<slug>
+# split branches AGENTS.md tells devs to use — an exact-only match silently stalled the flow on
+# slugged branches (DELEGATE:@qa found "no open PR"; autopilot MERGE_PR couldn't merge).
+resolve_prs() { curl -sS "${hdr[@]}" "$API/pulls?state=open&limit=50" \
+  | jq -r --arg br "ai/issue-$ISSN" 'if type=="array" then
+      ([ .[] | select(.head.ref==$br or (.head.ref|startswith($br+"-"))) | .number ] | sort | join(" "))
+    else "" end' 2>/dev/null; }
+resolve_pr() { resolve_prs | awk '{print $NF}'; }   # newest open PR (empty if none)
 # Remove the 'autopilot' label from an issue by resolving its ID first (Gitea's DELETE label
 # endpoint is by ID, not name). Arg $1 = issue number. Used as the autopilot kill switch.
 del_autopilot_label() {
@@ -60,15 +66,17 @@ del_autopilot_label() {
   fi
 }
 
-# drop machine-readable markers: DELEGATE / CLOSE_ISSUE / MERGE_PR / APPROVE / HALT / BOUNCE, and the
-# BEGIN_SUBTASKS..END_SUBTASKS and BEGIN_PR_DESCRIPTION..END_PR_DESCRIPTION blocks (the PR
+# drop machine-readable markers: DELEGATE / CLOSE_ISSUE / MERGE_PR / RETRO / APPROVE / HALT / BOUNCE,
+# and the BEGIN_SUBTASKS..END_SUBTASKS and BEGIN_PR_DESCRIPTION..END_PR_DESCRIPTION blocks (the PR
 # description is published separately).
 reply=$(awk '
   /^[[:space:]]*BEGIN_SUBTASKS/{s=1}
   /^[[:space:]]*BEGIN_PR_DESCRIPTION/{p=1}
   /^[[:space:]]*DELEGATE:[[:space:]]*@/{next}
+  /^[[:space:]]*ASK:[[:space:]]*@/{next}
   /^[[:space:]]*CLOSE_ISSUE[[:space:]]*$/{next}
   /^[[:space:]]*MERGE_PR[[:space:]]*$/{next}
+  /^[[:space:]]*RETRO[[:space:]]*$/{next}
   /^[[:space:]]*APPROVE[[:space:]]*$/{next}
   /^[[:space:]]*HALT([_ ]AUTOPILOT)?[[:space:]]*$/{next}
   /^[[:space:]]*BOUNCE:[[:space:]]*@/{next}
@@ -101,26 +109,37 @@ if [ "$MODE" != "pr" ]; then
   git clean -fd  2>/dev/null || true
 
   # ---------- @qa: reviewer only — never edits, never merges ----------
-  # Recommendations land ON THE PR (onsite the diff); the pass/fail verdict lands ON THE ISSUE so
-  # @pm (who never reads the PR) can act on it. Ends its reply with APPROVE / BOUNCE: @dev / HALT.
+  # ALL technical review detail lands ON THE PR (onsite the diff); the ISSUE gets only the terse
+  # pass/fail verdict so @pm (who never reads the PR) can act on it and the issue thread — which is
+  # for the creator/orchestration — stays free of review internals. APPROVE / BOUNCE: @dev / HALT.
   if [ "$NAME" = "qa" ]; then
     PRN=$(resolve_pr)
     if grep -qiE '^[[:space:]]*APPROVE[[:space:]]*$' /tmp/agent_out.md; then
-      post_to "$ISSN" "$(printf '✅ Reviewed PR #%s — looks good.\n\n%s%s' "${PRN:-?}" "$reply" "$activity")"
-      trig    "$ISSN" "@pm — @qa approved PR #${PRN:-?} (issue #$ISSN). Over to you."
-    elif grep -qiE '^[[:space:]]*BOUNCE:[[:space:]]*@(junior|senior|lead)' /tmp/agent_out.md; then
-      dev=$(grep -oiE 'BOUNCE:[[:space:]]*@(junior|senior|lead)' /tmp/agent_out.md | head -1 | grep -oiE '(junior|senior|lead)' | tr '[:upper:]' '[:lower:]')
+      if [ -n "$PRN" ]; then
+        post_to "$PRN"  "$reply$activity"            # the review detail belongs on the PR
+        post_to "$ISSN" "✅ Reviewed PR #$PRN — looks good."
+      else                                           # no PR resolved — nowhere better than the issue
+        post_to "$ISSN" "$(printf '✅ Reviewed — looks good.\n\n%s%s' "$reply" "$activity")"
+      fi
+      trig    "$ISSN" "@pm — I have reviewed and approved PR #${PRN:-?} (issue #$ISSN). Over to you."
+    elif grep -qiE '^[[:space:]]*BOUNCE:[[:space:]]*@(junior|senior|lead|intern)' /tmp/agent_out.md; then
+      dev=$(grep -oiE 'BOUNCE:[[:space:]]*@(junior|senior|lead|intern)' /tmp/agent_out.md | head -1 | grep -oiE '(junior|senior|lead|intern)' | tr '[:upper:]' '[:lower:]')
       [ -z "$dev" ] && [ -n "$PRN" ] && dev=$(curl -sS "${hdr[@]}" "$API/pulls/$PRN" | jq -r '.user.login // "junior"')
       dest="${PRN:-$NUM}"
       post_to "$dest" "$reply$activity"              # recommendations, on the PR
-      # Bounce budget: count prior "fix attempt" markers on the PR thread; stop after 3.
-      prior=$(curl -sS "${hdr[@]}" "$API/issues/$dest/comments?limit=100" | jq -r 'if type=="array" then [.[]|select(.body|test("fix attempt"))]|length else 0 end' 2>/dev/null); prior=${prior:-0}
+      # Bounce budget: count prior bounce TRIGGERS on the PR thread — only @qa-authored comments
+      # matching the exact "(fix attempt N/3)" template. A loose substring match would also count
+      # review text QUOTING our own templates (seen on PR #84: the counter jumped 1/3 → 3/3 because
+      # a qa review quoted publish.sh lines containing the phrase), halving the fix budget.
+      prior=$(curl -sS "${hdr[@]}" "$API/issues/$dest/comments?limit=100" | jq -r 'if type=="array" then [.[]|select(.user.login=="qa")|select(.body|test("^@[a-z]+ please address my review above and update PR #[0-9?]+ \\(fix attempt [0-9]+/3\\)\\.$"))]|length else 0 end' 2>/dev/null); prior=${prior:-0}
       if [ "$prior" -ge 3 ]; then
         [ "$AUTOPILOT" = "true" ] && del_autopilot_label "$ISSN"
         post_to "$ISSN" "🛑 Still not right after 3 fix attempts on PR #${PRN:-?} — handing to @ffaerber (details on the PR)."
       else
         n=$((prior + 1))
-        trig "$dest" "@${dev:-junior} please address @qa's review above and update PR #${PRN:-?} (fix attempt $n/3)."
+        # NOTE: this template and the counter regex above MUST stay in sync — if you reword one,
+        # reword the other, or the count resets to 0 and the 3-round cap stops working.
+        trig "$dest" "@${dev:-junior} please address my review above and update PR #${PRN:-?} (fix attempt $n/3)."
       fi
     elif grep -qiE '^[[:space:]]*HALT([_ ]AUTOPILOT)?[[:space:]]*$' /tmp/agent_out.md; then
       [ "$AUTOPILOT" = "true" ] && del_autopilot_label "$ISSN"
@@ -132,7 +151,7 @@ if [ "$MODE" != "pr" ]; then
   fi
 
   # ---------- @pm / @ops: issue-thread orchestration ----------
-  target=$(grep -oiE 'DELEGATE:[[:space:]]*@(junior|senior|lead|qa)' /tmp/agent_out.md 2>/dev/null | head -1 | grep -oiE '(junior|senior|lead|qa)' | tr '[:upper:]' '[:lower:]')
+  target=$(grep -oiE 'DELEGATE:[[:space:]]*@(junior|senior|lead|qa|intern)' /tmp/agent_out.md 2>/dev/null | head -1 | grep -oiE '(junior|senior|lead|qa|intern)' | tr '[:upper:]' '[:lower:]')
   # Visible comment: the reply text, or a sensible line if the agent only emitted a marker.
   msg="$reply"
   case "$msg" in ""|"_(Made changes"*) msg=$([ -n "$target" ] && echo "Handing off to @$target." || echo "_(no further comment)_") ;; esac
@@ -176,15 +195,43 @@ if [ "$MODE" != "pr" ]; then
     done < /tmp/subtasks.txt
     subtext=$(printf '\n\n---\nCreated sub-issues%s (mention an agent on each when ready):%b' "${ms:+ under milestone **$ms**}" "$links")
   fi
-  post "$(printf '%s%s%s' "$msg" "$subtext" "$activity")"
+  # DEDUP GUARD (issue: @pm double-posts its report). Prompt-level "do not self-post" is ignored
+  # by some models, so enforce it here: if the agent ALREADY posted a comment on this thread
+  # during the run (any comment by $NAME newer than the pre-run newest id from fetch-thread.sh),
+  # its self-post IS the reply — skip the duplicate framework comment. Markers (CLOSE_ISSUE,
+  # DELEGATE, MERGE_PR, subtasks) were already processed above and are unaffected.
+  # FAIL OPEN: if the pre-run marker is missing (fetch-thread hiccup), pre_cid=0 would make the
+  # agent's comments from PREVIOUS runs count as self-posts and wrongly suppress the reply.
+  # Without the marker, skip the guard and post normally.
+  pre_cid=$(cat /tmp/thread_max_cid 2>/dev/null || echo "")
+  selfposts=0
+  if [ -n "$pre_cid" ]; then
+  : > /tmp/all_comments.json
+  for pg in $(seq 1 10); do
+    cpg=$(curl -sS "${hdr[@]}" "$API/issues/$NUM/comments?limit=50&page=$pg" 2>/dev/null) || cpg='[]'
+    cn=$(printf '%s' "$cpg" | jq 'if type=="array" then length else 0 end' 2>/dev/null || echo 0)
+    [ "${cn:-0}" -gt 0 ] && printf '%s\n' "$cpg" >> /tmp/all_comments.json
+    [ "${cn:-0}" -lt 50 ] && break
+  done
+  selfposts=$(jq -rs --arg n "$NAME" --argjson c "${pre_cid:-0}" '[ (add // [])[] | select(.user.login==$n) | select(.id > $c) ] | length' /tmp/all_comments.json 2>/dev/null || echo 0)
+  fi
+  if [ "${selfposts:-0}" -gt 0 ]; then
+    echo "agent @$NAME already posted ${selfposts} comment(s) on #$NUM during this run — skipping duplicate framework reply"
+  else
+    post "$(printf '%s%s%s' "$msg" "$subtext" "$activity")"
+  fi
 
   # --- @pm autopilot merge: @pm is the ONLY agent that merges, and ONLY under the autopilot label ---
   # (@qa never merges — it approves and hands back here.) Merge with the PAT (TTOK), not the built-in
   # token, so the push to main fires the deploy. TOKEN_PM must carry write:repository.
   if [ "$NAME" = "pm" ] && [ "$AUTOPILOT" = "true" ] && grep -qiE '^[[:space:]]*MERGE_PR[[:space:]]*$' /tmp/agent_out.md; then
-    PRN=$(resolve_pr)
+    PRS=$(resolve_prs); PRN=${PRS##* }; CNT=$(echo "$PRS" | wc -w)
     if [ -z "$PRN" ]; then
       echo "MERGE_PR but no open PR found for issue #$ISSN"
+    elif [ "$CNT" -gt 1 ]; then
+      # Split-PR work: auto-merging just one of several open PRs is half a change deployed.
+      del_autopilot_label "$ISSN"
+      post_to "$ISSN" "⚠️ This issue has $CNT open PRs (#${PRS// /, #}) — autopilot only merges single-PR work. Removed the autopilot label; @ffaerber please review and merge them in order."
     else
       echo "@pm autopilot: merging PR #$PRN (issue #$ISSN)"
       mc=$(curl -sS -o /tmp/merge_resp.txt -w '%{http_code}' -X POST \
@@ -203,20 +250,55 @@ if [ "$MODE" != "pr" ]; then
     exit 0
   fi
 
+  # --- @pm RETRO: open a retrospective issue for this thread (maintainer asked for a retro) ---
+  # Creates a retro issue pointing at this issue + its PR and triggers @senior on it (has gitea-api
+  # to read both threads). The retro produces a LEARNINGS.md PR via the NORMAL choreography (senior →
+  # pm → qa → merge), and run-agent.sh injects LEARNINGS.md into every future prompt — closing the loop.
+  if [ "$NAME" = "pm" ] && grep -qiE '^[[:space:]]*RETRO[[:space:]]*$' /tmp/agent_out.md; then
+    PRN=$(curl -sS "${hdr[@]}" "$API/pulls?state=all&limit=50" \
+      | jq -r --arg br "ai/issue-$ISSN" 'if type=="array" then ([.[]|select(.head.ref==$br or (.head.ref|startswith($br+"-")))] | sort_by(.number) | last | .number // empty) else empty end' 2>/dev/null)
+    rbody=$(printf 'Retrospective for issue #%s%s.\n\nRead the FULL issue thread%s using the gitea-api skill (issue comments%s and the PR diff). Identify what went wrong, slow, or needed human correction — missed wiring, review misses, bounced rounds, unclear delegation, missing context.\n\nThen APPEND the distilled learnings to `LEARNINGS.md` at the repo root (create it with a short header if missing). Rules for entries:\n- 3 to 6 bullets max, each ONE line: `symptom -> rule for next time`.\n- Concrete and checkable (name the file/step/marker), not generic advice.\n- Do not repeat an existing bullet; refine it instead.\n- Do not rewrite unrelated parts of the file.\n\nThese learnings are injected into every future agent prompt, so quality over quantity.' \
+      "$ISSN" "${PRN:+ / PR #$PRN}" "${PRN:+ and PR #$PRN thread}" "${PRN:+, PR comments}")
+    rnum=$(curl -sS -X POST "${hdr[@]}" "$API/issues" \
+      -d "$(jq -nc --arg t "retro: issue #$ISSN" --arg b "$rbody" '{title:$t,body:$b}')" | jq -r '.number // empty')
+    if [ -n "$rnum" ]; then
+      echo "opened retro issue #$rnum"
+      post_to "$ISSN" "📝 Opened retro issue #$rnum."
+      trig "$rnum" "@senior please run this retrospective per the issue body."
+    else
+      echo "retro issue creation failed"
+    fi
+    exit 0
+  fi
+
+  # --- @pm ASK: consult a dev in the thread WITHOUT starting a build ---
+  # 'ASK: @<dev> <question>' fires the dev in DISCUSSION mode (route.sh: the trigger below does not
+  # match any build phrase, so the dev replies in-thread — no branch, no PR). @pm gathers input this
+  # way, then DELEGATEs when enough is known.
+  ask_line=$(grep -oiE '^[[:space:]]*ASK:[[:space:]]*@(junior|senior|lead|intern)[[:space:]]+.*$' /tmp/agent_out.md 2>/dev/null | head -1)
+  if [ "$NAME" = "pm" ] && [ -n "$ask_line" ]; then
+    ask_dev=$(printf '%s' "$ask_line" | grep -oiE '@(junior|senior|lead|intern)' | head -1 | tr -d '@' | tr '[:upper:]' '[:lower:]')
+    ask_q=$(printf '%s' "$ask_line" | sed -E 's/^[[:space:]]*ASK:[[:space:]]*@[A-Za-z]+[[:space:]]+//')
+    trig "$ISSN" "@$ask_dev $ask_q — this is a discussion: reply in this thread with your assessment; do not start any work."
+    exit 0
+  fi
+
   # --- @pm delegation: hand the build to a dev, or hand the finished PR to @qa for review ---
   # Only an explicit 'DELEGATE: @<agent>' line acts (never a prose mention). Fires via the PAT (TTOK)
   # so a new run starts; the built-in token cannot. Everything posts on the ISSUE — @pm never touches
   # the PR. Chain terminates: normal → @pm tells the creator (no marker); autopilot → @pm merges above.
   if [ -n "$target" ] && [ "$target" != "$NAME" ]; then
     if [ "$target" = "qa" ]; then
-      PRN=$(resolve_pr)
-      if [ -n "$PRN" ]; then
+      PRS=$(resolve_prs); PRN=${PRS##* }; CNT=$(echo "$PRS" | wc -w)
+      if [ -n "$PRN" ] && [ "$CNT" -gt 1 ]; then
+        trig "$ISSN" "@qa please review the $CNT open PRs for issue #$ISSN (#${PRS// /, #}) — put your recommendations on each PR; approve only when ALL are good."
+      elif [ -n "$PRN" ]; then
         trig "$ISSN" "@qa please review PR #$PRN for issue #$ISSN — put your recommendations on the PR, or approve."
       else
         echo "DELEGATE:@qa but no open PR yet for issue #$ISSN — not firing"
       fi
     else
-      trig "$ISSN" "@$target please proceed with issue #$ISSN per the plan above (delegated by $NAME)."
+      trig "$ISSN" "@$target please proceed with issue #$ISSN per my plan above."
     fi
   else
     echo "no DELEGATE marker — not delegating (agent is asking or finished)"
@@ -224,6 +306,15 @@ if [ "$MODE" != "pr" ]; then
   exit 0
 fi
 
+# --- dev DISCUSSION mode: consulted for expertise, no build (route.sh workmode=discuss) ---
+# The reply is a comment on the thread — discard any stray file edits, skip ALL git/PR machinery.
+if [ "${WORKMODE:-build}" = "discuss" ]; then
+  git checkout -- . 2>/dev/null || true
+  git clean -fd  2>/dev/null || true
+  post "$(printf '%s%s' "$reply" "$activity")"
+  exit 0
+fi
+
 # Scrub the runtime scripts checkout (.agents-workflow) from the tree so it never lands in a
 # commit/PR and never confuses the git ops below (issue #33). The scripts we run live outside the
 # workspace ($SCRIPTS -> runner.temp), so removing this in-tree copy is always safe. Handle every
@@ -243,7 +334,14 @@ if [ -n "$(git status --porcelain)" ]; then
   git add -A
   git commit -m "@$NAME: issue #$NUM"
 fi
-git push origin "HEAD:$BRANCH" || true
+if git push origin "HEAD:$BRANCH"; then
+  :
+else
+  status=$?
+  echo "git push failed for $BRANCH (exit $status)"
+  post "$(printf '⚠️ Push to branch `%s` failed (git exit %s). The PR will not open until the push succeeds. Please check the Actions log.%s' "$BRANCH" "$status" "$activity")"
+  exit 0
+fi
 git fetch -q origin 2>/dev/null || true
 
 prbody=$(printf '%s\n\n---\nResolves #%s' "$prdesc" "$NUM")
@@ -269,14 +367,21 @@ url=$(printf '%s' "$resp" | jq -r '.html_url // empty' 2>/dev/null)
 prnum=$(printf '%s' "$resp" | jq -r '.number // empty' 2>/dev/null)
 if [ -z "$url" ]; then
   title="@$NAME: $TITLE"
-  resp=$(curl -sS -X POST "${hdr[@]}" "$API/pulls" \
+  resp_body=/tmp/pr_create_resp.json
+  http_status=$(curl -sS -o "$resp_body" -w '%{http_code}' -X POST "${hdr[@]}" "$API/pulls" \
     -d "$(jq -nc --arg t "$title" --arg h "$br" --arg b "$prbody" \
           '{title:$t, head:$h, base:"main", body:$b}')")
-  echo "PR create ($br): $resp"
+  resp=$(cat "$resp_body" 2>/dev/null || true)
+  echo "PR create ($br): HTTP $http_status — $resp"
   url=$(printf '%s' "$resp" | jq -r '.html_url // empty' 2>/dev/null)
   prnum=$(printf '%s' "$resp" | jq -r '.number // empty' 2>/dev/null)
 fi
-[ -z "$url" ] && { echo "PR open/lookup failed for $br — posting reply on issue instead"; post "$(printf '%s%s' "$reply" "$activity")"; exit 0; }
+if [ -z "$url" ]; then
+  err_msg=$(printf '%s' "$resp" | jq -r 'if type=="object" and .message then .message else "(no error message in response)" end' 2>/dev/null)
+  echo "PR open/lookup failed for $br — HTTP $http_status — response: $resp"
+  post "$(printf '⚠️ Failed to open PR for branch `%s`.\n\nHTTP status: %s\nGitea message: %s%s' "$br" "$http_status" "$err_msg" "$activity")"
+  exit 0
+fi
 
 # Posts to the PR thread when we have a PR number, else to the origin issue ($NUM).
 prpost() {
@@ -297,6 +402,6 @@ else
   # on the PR thread. The qa↔dev loop is direct — it does NOT go back through @pm each round.
   prpost "$prnum" "$(printf 'Pushed an update to PR #%s.%s' "$prnum" "$activity")"
   case "$NAME" in
-    junior|senior|lead) trig "$prnum" "@qa please re-verify PR #$prnum — the dev has pushed an update." ;;
+    junior|senior|lead|intern) trig "$prnum" "@qa please re-verify PR #$prnum — I have pushed an update." ;;
   esac
 fi

.gitea/workflows/scripts/rescue-pr.sh

@@ -17,7 +17,7 @@ set +e
 # Post/PR as the agent's OWN Gitea user when its token is configured; else the built-in bot.
 case "$NAME" in
   pm) TOK="$TOKEN_PM";; senior) TOK="$TOKEN_SENIOR";; junior) TOK="$TOKEN_JUNIOR";;
-  lead) TOK="$TOKEN_LEAD";; qa) TOK="$TOKEN_QA";; ops) TOK="$TOKEN_OPS";; *) TOK="";;
+  lead) TOK="$TOKEN_LEAD";; qa) TOK="$TOKEN_QA";; ops) TOK="$TOKEN_OPS";; intern) TOK="$TOKEN_INTERN";; *) TOK="";;
 esac
 [ -z "$TOK" ] && TOK="$GT"
 # Trigger token: the @pm hand-back below must FIRE a new run, which the built-in token cannot.

.gitea/workflows/scripts/route.sh

@@ -31,24 +31,52 @@ name=""
 # load-bearing for the flow's trigger comments: "@pm — @qa approved …" must route to @pm (pm is
 # checked first), while "@junior please address @qa's review …" must route to the dev (devs are
 # checked before qa). If you add an agent or reword a trigger in publish.sh, re-check this order.
-for a in pm junior senior lead qa ops; do
-  case "$scan" in *"@$a"*) name=$a; break;; esac
+# WORD-BOUNDARY match, not substring: "@internal" or "x@internet.com" must NOT route to @intern
+# (the workflow gate can only do contains(), so this is where its false positives get filtered).
+for a in pm junior senior lead qa ops intern; do
+  if printf '%s' "$scan" | grep -qE "(^|[^[:alnum:]_])@$a([^[:alnum:]_-]|\$)"; then name=$a; break; fi
 done
 if [ -z "$name" ]; then
-  if [ -z "$CID" ]; then name=pm; else echo "no known agent mentioned"; exit 1; fi
+  if [ -z "$CID" ]; then
+    name=pm
+  else
+    # Not an agent task (e.g. the gate's contains() matched "@internal"). Skip GRACEFULLY: emit
+    # mode=skip so every later step no-ops — a red run for a non-agent comment is just noise.
+    echo "no known agent mentioned (word-boundary) — skipping run"
+    { echo "name=none"; echo "model=none"; echo "vision=false"; echo "mode=skip"; echo "skills=[]";
+      echo "branch=main"; echo "new=false"; echo "autopilot=false"; echo "issnum=$NUM"; } >> "$GITHUB_OUTPUT"
+    exit 0
+  fi
 fi
 model=$(jq -r --arg a "$name" '.[$a].model'  /tmp/agents.json)
 vision=$(jq -r --arg a "$name" '.[$a].vision' /tmp/agents.json)
 mode=$(jq -r --arg a "$name" '.[$a].mode'   /tmp/agents.json)
 # Compact JSON array of the skills this agent may load (scopes permission.skill in install-opencode.sh).
 skills=$(jq -c --arg a "$name" '.[$a].skills // []' /tmp/agents.json)
-echo "Routing to @$name (model=$model vision=$vision mode=$mode skills=$skills)"
-{ echo "name=$name"; echo "model=$model"; echo "vision=$vision"; echo "mode=$mode"; echo "skills=$skills"; } >> "$GITHUB_OUTPUT"
+
+# --- WORKMODE for dev (mode=pr) agents: build vs DISCUSS. ---
+# Mentioning a dev is a CONVERSATION by default — it replies in the thread without creating a
+# branch or PR. Actual building starts ONLY on the explicit signals:
+#   - a comment on a PR thread (resuming existing work), or
+#   - the pm delegation template ".. please proceed with issue .." (also usable by a human), or
+#   - the qa bounce template ".. please address my review ..".
+# This lets @pm (via its ASK marker) and the maintainer consult devs to gather information first,
+# and explicitly start the build later — see publish.sh / run-agent.sh.
+workmode=build
+if [ "$mode" = "pr" ] && [ -z "$IS_PR" ]; then
+  if printf '%s' "$scan" | grep -qiE 'please (proceed with issue|address my review)'; then
+    workmode=build
+  else
+    workmode=discuss
+  fi
+fi
+echo "Routing to @$name (model=$model vision=$vision mode=$mode workmode=$workmode skills=$skills)"
+{ echo "name=$name"; echo "model=$model"; echo "vision=$vision"; echo "mode=$mode"; echo "workmode=$workmode"; echo "skills=$skills"; } >> "$GITHUB_OUTPUT"
 
 # Act as the agent's own Gitea user when its token is set; else the built-in bot.
 case "$name" in
   pm) TOK="$TOKEN_PM";; senior) TOK="$TOKEN_SENIOR";; junior) TOK="$TOKEN_JUNIOR";;
-  lead) TOK="$TOKEN_LEAD";; qa) TOK="$TOKEN_QA";; ops) TOK="$TOKEN_OPS";; *) TOK="";;
+  lead) TOK="$TOKEN_LEAD";; qa) TOK="$TOKEN_QA";; ops) TOK="$TOKEN_OPS";; intern) TOK="$TOKEN_INTERN";; *) TOK="";;
 esac
 [ -z "$TOK" ] && TOK="$GT"
 git config user.name "$name"
@@ -56,7 +84,10 @@ git config user.email "$name@ffaerber.duckdns.org"
 API="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}"
 hdr=(-H "Authorization: token $TOK" -H "Content-Type: application/json")
 branch_ref=""
-if [ -n "$IS_PR" ]; then                     # comment on a PR -> resume its branch
+if [ "$workmode" = "discuss" ]; then         # conversation only — no branch, no PR machinery
+  echo "discussion mode — staying on main, no branch prep"
+  { echo "branch=main"; echo "new=false"; } >> "$GITHUB_OUTPUT"
+elif [ -n "$IS_PR" ]; then                   # comment on a PR -> resume its branch
   ref=$(curl -s -H "Authorization: token $GT" "$API/pulls/$NUM" | jq -r .head.ref)
   branch_ref="$ref"
   git fetch origin "$ref" && git checkout "$ref"

.gitea/workflows/scripts/run-agent.sh

@@ -3,7 +3,7 @@
 # plain-text reply (/tmp/agent_out.md) plus the raw event stream (/tmp/events.jsonl).
 #
 # Required env (provided by the workflow step):
-#   ANTHROPIC_API_KEY SELF_TOKEN NAME MODEL VISION MODE HAS_IMAGES BRANCH AUTOPILOT NUM TITLE
+#   XAI_API_KEY SELF_TOKEN NAME MODEL VISION MODE HAS_IMAGES BRANCH AUTOPILOT NUM TITLE
 #   IBODY CMT
 #   FILES   (the opencode -f image flags, from the imgs step output)
 #   AUTOPILOT is 'true' when the issue carries the `autopilot` label (label-gated autopilot mode).
@@ -26,7 +26,7 @@ if [ "$MODE" = "comment" ]; then
   ACTION="You do NOT edit files, create branches, or write a PR description. Respond with your analysis,
    plan, research, or clarifying questions — your reply becomes a comment on the issue.
    To hand work to a teammate, end your reply with EXACTLY one line: 'DELEGATE: @<agent>' (one of
-   @junior @senior @lead @qa) — but ONLY when you are ready to hand off AND need nothing further from the
+   @junior @senior @lead @qa @intern) — but ONLY when you are ready to hand off AND need nothing further from the
    maintainer. If you are asking @ffaerber to confirm or decide ANYTHING, do NOT include a DELEGATE line;
    just ask and wait. Never ask for confirmation and delegate in the same reply. Mentioning a teammate in
    prose does NOT delegate — only the DELEGATE line does.
@@ -54,7 +54,15 @@ if [ "$MODE" = "comment" ]; then
 
    If anything is unclear or needs a decision at any phase, START your reply with '@ffaerber', ask
    specific questions, and do NOT emit a marker. Mentioning a teammate in prose does NOT act — only a
-   DELEGATE line does.
+   marker line does.
+   ASK — to CONSULT a dev before (or instead of) planning, end your reply with EXACTLY one line:
+   'ASK: @<dev> <one concrete question>'. The dev replies in this thread WITHOUT starting any work —
+   use it to gather feasibility/effort/approach input, then present your plan (and later DELEGATE)
+   once you know enough. One ASK per reply; never ASK and DELEGATE in the same reply.
+   RETRO — when the maintainer asks for a retrospective on this issue (e.g. 'run a retro',
+   '@pm retro'), briefly acknowledge and end your reply with EXACTLY one line: 'RETRO'. The
+   automation opens a retro issue (read this issue + its PR, distill learnings into LEARNINGS.md)
+   and assigns it. Emit RETRO only when explicitly asked.
    BREAKDOWN (a feature too big for one PR): in PHASE 1, propose a milestone name and the sub-task
    list, then ask '@ffaerber create these N sub-issues? reply yes.' ONLY after approval, end with:
    BEGIN_SUBTASKS
@@ -86,13 +94,22 @@ if [ "$MODE" = "comment" ]; then
      issue and hands back to @pm (who tells the creator, or in autopilot merges). You do NOT merge.
    - 'BOUNCE: @<dev>' — something needs changing. FIRST spell out, specifically and actionably, exactly
      what to change (file, label, value, hostname, …), THEN end with the BOUNCE line naming who fixes
-     it (@junior / @senior / @lead — usually whoever built it). The automation sends the PR back and
+     it (@junior / @senior / @lead / @intern — usually whoever built it). The automation sends the PR back and
      re-verifies with you. After 3 rounds it stops and hands to @ffaerber — so list ALL problems at
      once, not one at a time.
    - 'HALT' — the problem is NOT something a dev can fix (the request is ambiguous / needs a human
      decision). Hands back to @ffaerber.
    Emit AT MOST one marker, and only after you have actually verified."
   fi
+elif [ "${WORKMODE:-build}" = "discuss" ]; then
+  # A dev agent consulted for its EXPERTISE — conversation only, no build. Building starts later,
+  # explicitly ('please proceed with issue …'). See route.sh workmode.
+  ACTION="You are being CONSULTED in this thread — this is a DISCUSSION, not a build task. Answer the
+   question you were asked: read whatever files/logs you need (read-only), give your assessment,
+   approach, effort estimate, risks, or answer — concise and concrete. Your reply becomes a comment.
+   Do NOT modify files, do NOT commit or push, do NOT create branches, do NOT open PRs. Do not
+   emit any marker. When the team has enough information, @pm (or the maintainer) will explicitly
+   tell a dev to start building."
 else
   ACTION="You start on git branch '${BRANCH}', with git and push credentials already configured.
    FIRST read AGENTS.md at the repo root and FOLLOW IT EXACTLY — it defines the golden rules,
@@ -102,15 +119,42 @@ else
    open pull requests yourself — that is automated for every branch you push.
    If the task is genuinely unclear, make NO changes and reply with specific questions instead."
 fi
+# TEAM LEARNINGS — distilled from past retros (see the RETRO flow in publish.sh). Lives at the
+# CALLER repo root as LEARNINGS.md, maintained by retro PRs. Injected into EVERY agent's prompt
+# (capped) so past mistakes actually change future behavior — this is the feedback loop.
+# Cap is LINE-aware and keeps the NEWEST entries: retros append at the bottom, so a byte-cap from
+# the top would silently drop the latest lessons first (and cut mid-bullet).
+LEARN=""
+if [ -s LEARNINGS.md ]; then
+  if [ "$(wc -l < LEARNINGS.md)" -gt 80 ]; then
+    LEARN=$(printf '%s\n_(older learnings truncated — full list in LEARNINGS.md)_\n%s' \
+      "$(head -n 3 LEARNINGS.md)" "$(tail -n 70 LEARNINGS.md)")
+  else
+    LEARN=$(cat LEARNINGS.md)
+  fi
+  LEARN=$(printf '%s' "$LEARN" | head -c 8000)
+fi
+[ -n "$LEARN" ] && LEARN="
+   TEAM LEARNINGS (distilled from past retros in this repo — APPLY them; they exist because a
+   previous task went wrong without them):
+   ${LEARN}
+"
 PROMPT="You are @${NAME}, a member of an AI dev team working on this Gitea repository.
    YOUR ROLE: ${DESC}
    YOUR CAPABILITIES: model ${MODEL}. ${CAP}
    ${NOTE}
+${LEARN}
 
    Your reply is posted as a comment already attributed to you (@${NAME}) — your name and avatar are
    shown by Gitea. Do NOT begin your reply with your own name, an '@${NAME}' header, or a '🤖/🔨 @you'
    line; just write the content directly.
 
+   Do NOT use the gitea-api skill to post your reply, report, or any comment on THIS thread
+   yourself. The automation already posts your reply exactly once — self-posting it too is what
+   creates the duplicate comments you must avoid. On this thread, use gitea-api only to READ, or to
+   take an explicit action you were asked for (add/remove a label, close the issue, merge the PR).
+   Your report or answer IS your reply text — write it as your reply; do not post it via the API.
+
    TEAM ROSTER (who does what — hand off if a task isn't yours):
    ${ROSTER}
 
@@ -137,14 +181,21 @@ echo "opencode version: $(opencode --version 2>&1)"
 # keeps reading agent_out.md exactly as before. Success is exit code 0: the agent may
 # make tool-only changes with no text summary, so DO NOT treat empty output as failure.
 rc=1
+# HARD per-attempt timeout: there is exactly ONE runner slot, and a hung model (a stalled local
+# ollama generate on a trivial @intern question) once held it for ~1h, queueing every agent run
+# instance-wide. 20 min is far above any legitimate attempt. timeout SIGTERMs, then SIGKILLs 30s
+# later. rc=124 (timed out) is NOT retried — a hung backend stays hung; fail fast, free the runner.
+AGENT_TIMEOUT="${AGENT_TIMEOUT:-1200}"
 for attempt in 1 2 3; do
-  echo "opencode attempt $attempt/3 for @$NAME ($MODEL)"
+  echo "opencode attempt $attempt/3 for @$NAME ($MODEL, timeout ${AGENT_TIMEOUT}s)"
   rc=0
-  opencode run --model "$MODEL" --auto --format json "$PROMPT" ${FILES:-} \
+  timeout -k 30 "$AGENT_TIMEOUT" \
+    opencode run --model "$MODEL" --auto --format json "$PROMPT" ${FILES:-} \
     >/tmp/events.jsonl 2>/tmp/agent_err.log || rc=$?
   echo "rc=$rc"; echo "--- events ($(wc -l < /tmp/events.jsonl 2>/dev/null || echo 0) lines) ---"
   echo "--- stderr (trace) ---"; cat /tmp/agent_err.log
   [ $rc -eq 0 ] && break
+  if [ $rc -eq 124 ]; then echo "attempt timed out after ${AGENT_TIMEOUT}s — backend hung, not retrying"; break; fi
   if grep -qiE 'overloaded|429|529|rate.?limit|timeout|ETIMEDOUT|ECONNRESET|EAI_AGAIN' /tmp/events.jsonl /tmp/agent_err.log; then
     echo "transient error — backing off $((attempt*20))s"; sleep $((attempt * 20)); continue
   fi

.gitea/workflows/scripts/skill-gitea-admin.sh

@@ -107,9 +107,22 @@ curl -sS -X POST -H "Authorization: token $SELF_TOKEN" "$API/orgs/{org}/labels"
 3. Commit the standard caller so it gets the agents — `PUT /repos/{owner}/{repo}/contents/.gitea/workflows/ai-agent.yml`
    with base64 `content`, `message`, `branch:"main"` (copy the exact caller from the `agents` repo README).
 4. Add the agent bot users as collaborators: `PUT /repos/{owner}/{repo}/collaborators/{username}` (`{"permission":"write"}`).
-5. Ensure the repo can run agents — the org must hold the runtime secrets (ANTHROPIC_API_KEY, SELF_TOKEN,
+5. Ensure the repo can run agents — the org must hold the runtime secrets (XAI_API_KEY, SELF_TOKEN,
    TOKEN_* , OLLAMA_URL, OLLAMA_CLOUD_API_KEY); set any missing via the secrets calls above.
 
+## Packages / container registry
+Container images pushed by CI land in the **owner's** package namespace (e.g. `ffaerber/-/packages`)
+and are NOT automatically shown on the repo's Packages page — link once after the first push:
+```
+curl -sS -X POST -H "Authorization: token $SELF_TOKEN" "$API/packages/{owner}/container/{name}/-/link/{repo}"
+curl -sS -X POST -H "Authorization: token $SELF_TOKEN" "$API/packages/{owner}/container/{name}/-/unlink"
+```
+Registry auth facts (for wiring CI): the internal Actions token (`GITHUB_TOKEN`) is REJECTED by the
+container registry — a real PAT is required. A **user**-namespace package is writable only by that
+user or a site admin, so CI pushing to `<user>/<image>` needs a PAT minted BY that user with scope
+`write:package` only (stored as a repo/user secret, e.g. `REGISTRY_TOKEN`). Your own token carries
+`write:package`, so you can link/unlink and (if ever needed) push to any namespace.
+
 ## Admin user management
 - Create: `POST /admin/users`. Edit: `PATCH /admin/users/{username}`. Delete: `DELETE /admin/users/{username}` (**confirm first**).
 - List: `GET /admin/users`.

LEARNINGS.md

@@ -0,0 +1,9 @@
+# LEARNINGS — distilled from retros
+
+Rules for the team. Each line: `symptom -> rule for next time`. Keep concrete and checkable.
+
+- New agent added without the `agent.yml` trigger gate, breaking all `@intern` comments until round 3 -> adding an agent means editing BOTH the trusted-author list and the mention list in `agent.yml` (lines ~28 and ~37) in the same commit; @qa grep the gate for the new name.
+- Two of the 8 files an agent touches were missed on the first PR -> when adding an agent, touch all of `agents.json`, `install-opencode.sh`, `route.sh`, `agent.yml`, `publish.sh`, `rescue-pr.sh`, `run-agent.sh`, `README.md`; @qa diff-stat the PR and confirm the name appears in each.
+- Stray leading-space edits to `run-agent.sh` prompt heredoc bounced 2 review rounds -> only edit the exact token (the agent name) inside prompt heredocs, never re-indent surrounding lines; verify with `cat -A` against `main` before pushing.
+- @qa quoted the `@${dev} ... (fix attempt $n/3)` trigger string from the diff, inflating the bounce counter 1/3 -> 3/3 -> @qa paraphrase the fix-attempt line, never reproduce it verbatim; the publish.sh template+regex must stay pinned together.
+- @qa found whitespace and the gate miss in separate rounds, hitting the 3-round cap -> on a BOUNCE, list ALL problems (every file/line) in one round; the 3-round cap is hard.

README.md

@@ -7,12 +7,13 @@ Shared **AI dev-team** workflow for Gitea Actions, reusable across repos. It giv
 
 | Agent | Model | Vision | Mode | Skills | Role |
 |-------|-------|:------:|------|--------|------|
-| `@pm` | `ollama-cloud/gemma4:cloud` | yes | comment | `gitea-api` | Product manager & orchestrator — plans, picks the dev, hands finished PRs to `@qa`, reports back to the issue creator (autopilot: merges approved PRs itself). Issue thread only; never edits files, never reads the PR diff. |
+| `@pm` | `ollama-cloud/minimax-m3:cloud` | yes | comment | `gitea-api` | Product manager & orchestrator — plans, picks the dev, hands finished PRs to `@qa`, reports back to the issue creator (autopilot: merges approved PRs itself). Issue thread only; never edits files, never reads the PR diff. |
 | `@junior` | `ollama-cloud/kimi-k2.7-code:cloud` | no | pr | — | Junior dev — small, low-risk changes (mostly YAML/compose/config). Text-only, cannot read images. Defers complex or image tasks to `@senior` or `@lead`. |
 | `@senior` | `ollama-cloud/glm-5.2:cloud` | no | pr | `gitea-api` | Senior dev — complex, multi-file implementation (GLM-5.2 via Ollama Cloud, text-only). |
-| `@lead` | `anthropic/claude-opus-4-8` | yes | pr | `gitea-api` | Tech lead — the hardest problems, architecture, and final calls. |
+| `@lead` | `xai-oc/grok-4.5` | yes | pr | `gitea-api` | Tech lead — the hardest problems, architecture, and final calls. |
 | `@qa` | `ollama-cloud/minimax-m3:cloud` | yes | comment | `gitea-api` | QA / reviewer — reads the PR diff, drives a headless browser (Playwright) to verify behavior; recommendations on the PR, pass/fail verdict on the issue. Never edits code, never merges. |
-| `@ops` | `anthropic/claude-opus-4-8` | no | comment | `gitea-admin` | Gitea operator — administers the instance itself (create orgs/users/repos, labels, secrets, scoped per-user tokens, bootstrap repos). Comments only; never edits code. Confirms before destructive actions. |
+| `@ops` | `xai-oc/grok-4.5` | no | comment | `gitea-admin` | Gitea operator — administers the instance itself (create orgs/users/repos, labels, secrets, scoped per-user tokens, bootstrap repos). Comments only; never edits code. Confirms before destructive actions. |
+| `@intern` | `ollama/ornith:35b` | no | pr | — | Intern — very basic tasks only, routed to the local Ollama model (`ornith:35b`). Text-only, cannot read images. Escalates anything non-trivial to `@junior`, `@senior` or `@lead`. |
 
 The registry `.gitea/workflows/scripts/agents.json` is the source of truth for this mapping — if you
 change a model or an agent's skills there, update this table too. (Repo-specific skills, e.g. a
@@ -35,6 +36,24 @@ deploy-host SSH skill, live in the consuming repo under `.gitea/agent-skills/`
 `@pm` is the only agent that ever merges, and only under the `autopilot` label (its kill switch:
 remove the label mid-flight and the next step reverts to human control).
 
+### Discussion vs building
+
+Mentioning a dev agent is a **conversation by default**: it reads what it needs and replies in the
+thread — no branch, no PR. `@pm` can consult devs the same way with an `ASK: @<dev> <question>`
+marker (gather feasibility/effort input before planning). **Building starts only on the explicit
+signals**: `@pm`'s delegation (*"please proceed with issue …"* — a human can write the same phrase
+to start a build directly), a `@qa` bounce (*"please address my review …"*), or any comment on the
+PR thread itself (resuming existing work).
+
+### Retros — the learning loop
+
+Ask `@pm` for a retrospective on any issue (e.g. **"@pm run a retro"**, typically when merging). The
+automation opens a `retro: issue #N` issue and assigns `@senior`, who reads the full issue + PR
+threads (via the `gitea-api` skill), distills what went wrong or slow, and appends one-line
+`symptom → rule` bullets to **`LEARNINGS.md`** at the repo root — through the normal PR choreography,
+so the retro itself gets reviewed. `LEARNINGS.md` is injected into **every agent's prompt** on every
+run, so the lessons actually change future behavior (better delegation, fewer repeated misses).
+
 ### Per-agent skill scoping
 
 Skills load **on-demand**: only a skill's one-line `description` ever appears in an agent's
@@ -92,7 +111,7 @@ points `$SCRIPTS` at it. Keep the workflow and its scripts moving together on `m
 
 | Secret | For |
 |--------|-----|
-| `ANTHROPIC_API_KEY` | `@lead` (and `@pm`/`@senior`/`@qa` if on Claude) |
+| `XAI_API_KEY` | `@lead`, `@ops` (and any other agent switched to a `xai-oc/…` model) |
 | `OLLAMA_URL`, `OLLAMA_CLOUD_API_KEY` | local ornith / Ollama Cloud (gemma4, kimi-k2.7-code, glm-5.2, minimax-m3) |
 | `TOKEN_PM`,`TOKEN_SENIOR`,`TOKEN_JUNIOR`,`TOKEN_LEAD`,`TOKEN_QA` | **primary** — each agent's own Gitea-user PAT. The running agent gets *only its own* token (as `SELF_TOKEN`) so it posts, commits and comments as itself, and its `gitea-api` skill acts with its own scopes. Scopes: devs + `TOKEN_PM` carry `write:repository` (`@pm` is the only agent that merges, autopilot only); `TOKEN_QA` is `read:repository` + `write:issue` (reviews, never merges). |
 | `TOKEN_OPS` | `@ops` only — the admin PAT behind the `gitea-admin` skill (create orgs/users/repos, manage labels & secrets, mint scoped tokens). Injected into the agent process only when the agent is `@ops`. |