fix(route): resume an existing ai/issue-N branch instead of losing re-triggered work

When an agent was re-triggered on an issue that already had a branch/open PR, route.sh created a
fresh branch from main (git checkout -b), so the push back was rejected non-fast-forward and the new
commits were silently dropped (|| true) -- the run reported success and re-announced the stale PR,
but the work was gone (observed on issue #17 run #88). Resume the existing branch when it exists, so
new commits fast-forward onto it and update its PR; only branch from main when none exists.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitea/workflows/ai-agent.yml

@@ -1,6 +1,9 @@
 name: ai-agent
-# Thin caller so the agents work on THIS repo too (their own workflow). Same shared logic.
-# New issues opened by ffaerber auto-start @pm; @mention an agent in a comment to route on replies.
+run-name: "ai-agent · #${{ github.event.issue.number }}"   # quotes required: bare # starts a YAML comment
+# Standard caller for the shared AI-agent workflow (ffaerber/agents). Copy this file VERBATIM into
+# any repo that should get the agents — it is identical in every repo. All logic + scripts live in
+# agents/.gitea/workflows/; scripts are fetched from @main at run time. The `jobs.agent` wrapper is
+# required: a reusable (workflow_call) workflow can only be invoked from a caller job, not top-level.
 on:
   issue_comment:
     types: [created]

.gitea/workflows/scripts/publish.sh

@@ -39,7 +39,6 @@ if [ "$MODE" != "pr" ]; then
   # 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
-  post "$(printf '🤖 **@%s**\n\n%s' "$NAME" "$msg")"
   # Close the issue if the agent flagged it (maintainer said it's not needed / duplicate).
   if grep -qiE '^[[:space:]]*CLOSE_ISSUE[[:space:]]*$' /tmp/agent_out.md; then
     echo "closing issue #$NUM"
@@ -48,6 +47,9 @@ if [ "$MODE" != "pr" ]; then
   fi
   # BREAKDOWN: from a BEGIN_SUBTASKS block, create a milestone + one sub-issue per line
   # (linked to this issue). Sub-issues are NOT auto-started — maintainer mentions agents later.
+  # Process subtasks first so we can append the created-issues list to the SAME comment as
+  # the reply (issue #38 — one comment per run).
+  subtext=""
   if grep -qiE '^[[:space:]]*BEGIN_SUBTASKS' /tmp/agent_out.md; then
     block=$(awk '/^[[:space:]]*BEGIN_SUBTASKS/{f=1;next} /^[[:space:]]*END_SUBTASKS/{f=0} f' /tmp/agent_out.md)
     ms=$(printf '%s\n' "$block" | sed -nE 's/^[[:space:]]*milestone:[[:space:]]*//Ip' | head -1)
@@ -75,8 +77,9 @@ if [ "$MODE" != "pr" ]; then
       echo "created sub-issue #${n:-?}: $title"
       [ -n "$n" ] && links="$links\n- #$n — $title"
     done < /tmp/subtasks.txt
-    post "$(printf '🤖 **@%s** — created sub-issues%s (mention an agent on each when ready):%b' "$NAME" "${ms:+ under milestone **$ms**}" "$links")"
+    subtext=$(printf '\n\n---\n🤖 **@%s** — created sub-issues%s (mention an agent on each when ready):%b' "$NAME" "${ms:+ under milestone **$ms**}" "$links")
   fi
+  post "$(printf '🤖 **@%s**\n\n%s%s' "$NAME" "$msg" "$subtext")"
   # Auto-delegate: if the plan names a teammate, trigger them via AGENT_TOKEN (a PAT, so it
   # fires a new workflow run — the built-in token cannot). Never targets @pm or self, so the
   # chain always terminates at a dev. The '🤖' guard on the trigger stops status-comment loops.
@@ -123,6 +126,16 @@ git fetch -q origin 2>/dev/null || true
 prbody=$(printf '%s\n\n---\nResolves #%s · 🤖 @%s' "$prdesc" "$NUM" "$NAME")
 owner=${GITHUB_REPOSITORY%%/*}
 
+# Post the agent's activity trail (tool calls + reasoning) inline in the same comment so
+# each run produces exactly ONE comment (issue #38). Computed once here so every dev-agent
+# exit path (no-changes, PR-open-failed, normal) appends it to the single reply comment.
+activity=""
+if [ -s /tmp/activity_log.md ]; then
+  entries=$(wc -l < /tmp/activity_log.md 2>/dev/null || echo 0)
+  log=$(cat /tmp/activity_log.md)
+  activity=$(printf '\n\n---\n🤖 **@%s** — activity log (%s entries):\n<details>\n<summary>tool calls & reasoning</summary>\n\n%s\n\n</details>' "$NAME" "$entries" "$log")
+fi
+
 # One PR per run: publish ONLY this run's own branch ($BRANCH), never sibling
 # ai/issue-N-* branches. This removes the multi-PR ambiguity that left the
 # activity log stranded on the triggering issue instead of the PR thread.
@@ -130,7 +143,7 @@ br="$BRANCH"
 ahead=$(git rev-list --count "origin/main..origin/$br" 2>/dev/null || echo 0)
 if [ "${ahead:-0}" -eq 0 ]; then
   # No changes on this branch — a plan / questions / analysis only.
-  post "$(printf '🤖 **@%s**\n\n%s' "$NAME" "$reply")"
+  post "$(printf '🤖 **@%s**\n\n%s%s' "$NAME" "$reply" "$activity")"
   exit 0
 fi
 
@@ -148,7 +161,7 @@ if [ -z "$url" ]; then
   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**\n\n%s' "$NAME" "$reply")"; exit 0; }
+[ -z "$url" ] && { echo "PR open/lookup failed for $br — posting reply on issue instead"; post "$(printf '🤖 **@%s**\n\n%s%s' "$NAME" "$reply" "$activity")"; exit 0; }
 
 # Posts to the PR thread when we have a PR number, else to the origin issue ($NUM).
 prpost() {
@@ -160,17 +173,8 @@ prpost() {
 }
 
 if [ "$NEW" = "true" ]; then
-  prpost "$prnum" "$(printf '🤖 **@%s** — ✅ PR ready for review — @ffaerber please review & merge:\n- %s' "$NAME" "$url")"
+  prpost "$prnum" "$(printf '🤖 **@%s** — ✅ PR ready for review — @ffaerber please review & merge:\n- %s%s' "$NAME" "$url" "$activity")"
 else
   # Resume (comment is on a PR thread): include the write-up here too.
-  prpost "$prnum" "$(printf '🤖 **@%s** — updated branch/PR:\n- %s\n\n%s' "$NAME" "$url" "$prdesc")"
-fi
-
-# Post the agent's activity trail (tool calls + reasoning) as a separate comment so
-# it is visible on the PR thread. Additive — kept here even when nothing changed, so a
-# follow-up run (re-trigger) can see what this run did via the fetched issue thread.
-if [ -s /tmp/activity_log.md ]; then
-  entries=$(wc -l < /tmp/activity_log.md 2>/dev/null || echo 0)
-  log=$(cat /tmp/activity_log.md)
-  prpost "$prnum" "$(printf '🤖 **@%s** — activity log (%s entries):\n<details>\n<summary>tool calls & reasoning</summary>\n\n%s\n\n</details>' "$NAME" "$entries" "$log")"
+  prpost "$prnum" "$(printf '🤖 **@%s** — updated branch/PR:\n- %s\n\n%s%s' "$NAME" "$url" "$prdesc" "$activity")"
 fi

.gitea/workflows/scripts/route.sh

@@ -55,7 +55,13 @@ if [ -n "$IS_PR" ]; then                     # comment on a PR -> resume its bra
   ref=$(curl -s -H "Authorization: token $GT" "$API/pulls/$NUM" | jq -r .head.ref)
   git fetch origin "$ref" && git checkout "$ref"
   { echo "branch=$ref"; echo "new=false"; } >> "$GITHUB_OUTPUT"
-else                                         # comment on an issue -> new branch
+elif git ls-remote --exit-code --heads origin "ai/issue-$NUM" >/dev/null 2>&1; then
+  # comment on an issue whose branch ALREADY exists (a prior run / open PR) -> RESUME it, so new
+  # commits fast-forward onto the same branch and update its PR. Branching fresh from main here would
+  # be rejected on push as non-fast-forward and the new work would be silently lost (see issue #17).
+  git fetch origin "ai/issue-$NUM" && git checkout "ai/issue-$NUM"
+  { echo "branch=ai/issue-$NUM"; echo "new=false"; } >> "$GITHUB_OUTPUT"
+else                                         # comment on an issue, no branch yet -> new branch
   git checkout -b "ai/issue-$NUM"
   { echo "branch=ai/issue-$NUM"; echo "new=true"; } >> "$GITHUB_OUTPUT"
   # For dev agents, publish the branch immediately and tell the maintainer where to watch.

README.md

@@ -29,10 +29,18 @@ detail out of agents that shouldn't act on it while still letting them know the
 
 ## Use it in a repo
 
-Add `.gitea/workflows/ai-agent.yml` to the consuming repo:
+**The standard caller is one file, identical in every repo.** Copy this repo's own
+[`.gitea/workflows/ai-agent.yml`](.gitea/workflows/ai-agent.yml) verbatim into the consuming repo —
+it is the source of truth, and `agents` itself uses the same file:
 
 ```yaml
 name: ai-agent
+run-name: "ai-agent · #${{ github.event.issue.number }}"   # quotes required: bare # starts a YAML comment
+# Standard caller for the shared AI-agent workflow (ffaerber/agents). Copy this file VERBATIM into
+# any repo that should get the agents — it is identical in every repo. All logic + scripts live in
+# agents/.gitea/workflows/; scripts are fetched from @main at run time. The `jobs.agent` wrapper is
+# required: a reusable (workflow_call) workflow can only be invoked from a caller job, not top-level.
+# `run-name` titles each run by the triggering issue (e.g. "ai-agent · #42") in the Actions list.
 on:
   issue_comment:
     types: [created]
@@ -44,7 +52,9 @@ jobs:
     secrets: inherit
 ```
 
-That's the whole per-repo footprint. All the logic (agent registry, routing, delegation,
+That's the whole per-repo footprint, and it's the minimum a caller can be: the `on:` triggers must
+live in each repo (a reusable workflow can't declare its callers' triggers) and the `jobs.agent`
+wrapper is mandatory for `workflow_call`. Everything else (agent registry, routing, delegation,
 reactions, PR/issue plumbing) lives here in `agent.yml`.
 
 ## Repo layout