@nanocollective/roster 0.1.0-alpha.6 → 0.1.0-alpha.7

package/docs/prompts.md

@@ -58,12 +58,12 @@ ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","repo":"o/r"}' \
 `comment_id`; a mention typed into the body of a *new* issue does not, and there is no comment
 for the agent to fetch. So `compose.mjs` derives `event.no_comment` from the absence, and
 `prompts/mention.md` branches on it: one side points at the comment, the other at the issue
-body. Without that, the first instruction in the prompt was a `gh api .../issues/comments/`
+body. Without that, the first instruction in the prompt would be a `gh api .../issues/comments/`
 call with no id on the end, which 404s.
 
-The second route is the busier one now. It is what the portal's [Ask a staff
-member](portal.md#asking-for-a-change) produces, and those issues often carry a pull request
-that lives somewhere else and say to answer there instead.
+The second route is the busier one. It is what the portal produces when you [ask for a
+change](portal.md#asking-for-a-change), and those issues often carry a pull request that lives
+somewhere else and say to answer there instead.
 
 ## Syntax
 
@@ -108,10 +108,31 @@ than a hang.
 | `event` | trigger context, from `ROSTER_CONTEXT` |
 | `event.issue_number`, `event.comment_id`, `event.repo`, `event.actor` | |
 | `event.no_comment` | true when the ask is the issue body rather than a comment. There is no `{{#unless}}`, so the absence is a value |
+| `inflight` | the pull requests people have open on the product repos, as a markdown list. **Empty outside a run**, and when there are none. See below |
 
 Anything else in a manifest is reachable under `staff.`, so `staff.status_issue` and
 `staff.public_token_env` work without being listed here.
 
+## Human work in flight
+
+Before composing, a run looks at the staff member's product repos (their `works_in`, or every
+`role: product` repo) for open pull requests opened by people rather than by any App. Each one
+goes in as a line: title, author, age, branch, and the files it touches, capped at twenty with
+the top directories named when there are more.
+
+`prompts/_inflight.md` carries that list under a short instruction, inside `{{#if inflight}}`,
+and both kinds include it: do not open competing work on files a human branch is changing, and
+raise anything about it on that pull request instead.
+
+It exists because nothing else tells them. Without it, a person's long-running branch is
+invisible, and the staff open pull requests and issues chasing the same files, which the branch
+then overtakes.
+
+The list is a value, never a template. Titles are a person's words, and a `{{` in one must not
+be able to break composition, so `compose.mjs` reads `.roster-run/inflight.md` and substitutes it
+as it stands. Locally there is no such file, so `roster prompt` leaves the section out; pass
+`--inflight` to fetch the real list through your own `gh`.
+
 ## Guarding
 
 `{{staff.product}}` is null for a staff member with an empty `works_in`, and an unresolved

package/docs/security.md

@@ -45,6 +45,31 @@ whole organisation can reach anything in it.
 Install narrowly. The Staff card's **GitHub App** panel prints the list it actually needs, and
 so does `roster app`.
 
+## The review gate
+
+"Nothing goes out unread" is enforced by GitHub, not by the prompt. An App with
+`contents: write` on a product repo can push to its default branch, and with
+`pull_requests: write` it can merge its own PR, unless a rule on the branch says otherwise.
+
+The rule: **the default branch of every product repo requires a pull request with at least one
+approving review, and no staff App is on the list of who may bypass it.** A ruleset or classic
+branch protection both count.
+
+`roster doctor` reads it for every `role: product` repo in `org.yaml` and every repo a staff
+member `works_in`, as `review-gate`. It fails when nothing requires a PR or a staff App can
+bypass the rule, and warns when a PR is required with no approval, since then whoever opened
+it can merge it.
+
+`roster hire --apply` adds a ruleset named `roster: review before merge` to each product repo
+that does not already require an approving review, and leaves anything stricter alone. Pass
+`--no-review-gate` to skip it. The ruleset lets repository admins bypass it only by merging a
+pull request, so your own merge is still the approval (GitHub will not let you approve your
+own PR) and an App, which is never an admin, cannot merge at all.
+
+To set it by hand: repo **Settings -> Rules -> Rulesets -> New branch ruleset**, target the
+default branch, tick **Require a pull request before merging** with one required approval, and
+keep the staff Apps off the bypass list.
+
 ## Permissions a new App asks for
 
 ```
@@ -106,13 +131,12 @@ into a world-readable log.
 
 So a mention on a public pull request is decoration. It posts, it renders as a chip, and
 nothing happens, which is safe and also invisible. The portal is what makes it visible and what
-gets you out of it: replying with an `@handle` where nothing listens says so, and **Ask a staff
-member** opens the request on that person's own private tracker instead, carrying the pull
-request and the hunk. It writes through your own `gh`, as you, so no credential lives on the
+gets you out of it: replying with an `@handle` where nothing listens says so, and offers to
+open the request on that person's own private tracker as well, carrying the pull request and
+the hunk. It writes through your own `gh`, as you, so no credential lives on the
 public repo and nothing is dispatched across a boundary.
 
-There was once a forwarder in the product repo that bridged this automatically. It was removed;
-see [concepts](concepts.md#kinds-of-run). If you reinstate one, its author gate is
+If you add a workflow to a product repo that bridges this automatically, its author gate is
 load-bearing. Do not relax it.
 
 ## The loop guard

package/docs/session-workflow.md

@@ -14,8 +14,8 @@ A caller is about forty lines and does nothing but pass arguments.
 ## Why it lives in the tenant
 
 A reusable workflow in a **private** repo can only be called from inside its own organisation.
-A tenant therefore cannot call the framework's copy. That constraint is what forced the whole
-design, and it turned out better: the framework is never a runtime dependency, so nothing
+A tenant therefore cannot call the framework's copy. That constraint shapes the whole
+design, and it is the better one anyway: the framework is never a runtime dependency, so nothing
 breaks if it moves, goes private, or is deleted.
 
 This is also why `roster-ops` needs **Settings -> Actions -> General -> accessible from
@@ -28,7 +28,7 @@ repositories in this organisation**. Without it, callers fail with "workflow not
 | `staff` | string | required | Handle, as in `org.yaml`. |
 | `kind` | string | `daily` | `daily` or `mention`. |
 | `ops_repo` | string | required | `owner/name` of the ops repo. |
-| `model` | string | `claude-opus-5` | Passed to the agent, unless the agent resolves its own. |
+| `model` | string | `claude-opus-5-5` | Passed to the agent, unless the agent resolves its own. |
 | `timeout_minutes` | number | `90` | Job ceiling. |
 | `allowed_tools` | string | `Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch` | Tool permissions, for agents that take them. |
 | `issue_number` | string | `""` | Trigger context. |
@@ -51,23 +51,54 @@ authentication error forty lines into a log.
 
 ## What it does, in order
 
-1. **Mint the private-tracker token** from the staff member's App.
-2. **Mint the public-repo token**, if a public App was passed.
-3. **React to the request** with eyes, on a `mention` only. Before any checkout, so it lands in
+1. **Start the clock**, for the run record.
+2. **Mint the private-tracker token** from the staff member's App.
+3. **Mint the public-repo token**, if a public App was passed.
+4. **React to the request** with eyes, on a `mention` only. Before any checkout, so it lands in
    seconds. `continue-on-error`: a missing reaction must never cost the answer.
-4. **Check out the ops repo.** It is the only thing that can be cloned without having read a
+5. **Check out the ops repo.** It is the only thing that can be cloned without having read a
    manifest, so it goes first and then says what else to clone.
-5. **Work out what to check out**, by running `runner-plan.mjs`.
-6. **Check out the brain**, full history. The agent reads its own past.
-7. **Check out peers and product repos**, per the plan.
-8. **Set git identity** to the App.
-9. **Set up Node and pnpm**, if the plan found a `package.json`.
-10. **Compose the prompt**, to a step output and to `.roster-prompt.txt`.
-11. **Check the agent has a credential.**
-12. **Work out which agent runs this**, by running `agents.mjs`.
-13. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
+6. **Work out what to check out**, by running `runner-plan.mjs`.
+7. **Check out the brain**, full history. The agent reads its own past.
+8. **Check out peers and product repos**, per the plan.
+9. **Gather human work in flight**: open pull requests people have on the product repos, via
+   `inflight.mjs`, for the prompt. Never fatal. See [prompts](prompts.md#human-work-in-flight).
+10. **Set git identity** to the App.
+11. **Set up Node and pnpm**, if the plan found a `package.json`.
+12. **Compose the prompt**, to a step output and to `.roster-prompt.txt`.
+13. **Check the agent has a credential.**
+14. **Work out which agent runs this**, by running `agents.mjs`.
+15. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
     CLI one. See [choosing a coding agent](agents.md).
-14. **Say so if the run did not finish.**
+16. **Write down the run**, whatever happened: staff, kind, outcome, duration, and turns, cost
+    and tokens where the agent reports them. Into the job summary, and kept as an artifact
+    called `roster-run`. Never fatal. See [cost](cost.md#what-each-run-cost).
+17. **Say so if the run did not finish.** A comment on the status issue, or on the issue that
+    woke a mention, linking the run.
+
+## When the failure is the token
+
+The failure notice cannot rely on anything that might be what failed. A renamed repo, a rotated
+key or an uninstalled App breaks the App token first, and an alert that posts with that token
+says nothing at exactly the moment it is needed. So the notice uses the App token when there is
+one, and falls back to the job's own `github.token` when there is not or it is refused. It then
+posts as `github-actions`, and says to check the App.
+
+That needs `issues: write` on the job token. `session.yaml` asks for it, but a called workflow
+can only narrow what its caller grants, so both callers grant it too:
+
+```yaml
+jobs:
+  session:
+    permissions:
+      contents: read
+      issues: write
+    uses: acme/roster-ops/.github/workflows/session.yaml@main
+```
+
+Callers generated before this lack it, and their fallback cannot post. `roster upgrade --apply`
+regenerates them. `roster doctor` separately reports any other workflow in the ops or brain
+repos that has failed run after run, as `workflows.failing`.
 
 ## What `runner-plan.mjs` emits
 
@@ -92,6 +123,7 @@ Consumed by later steps as `steps.plan.outputs.*`.
 | `GH_TOKEN` | private-tracker token, already authenticated |
 | `PUBLIC_TOKEN` | public product repo token |
 | `AGENT_PROMPT_FILE` | absolute path to the composed prompt |
+| `AGENT_RESULT_FILE` | where to write the agent's own result JSON, if it has one. Optional; it is how cost gets into the run record |
 | `AGENT_MODEL` | resolved model |
 | `AGENT_TOOLS` | the `allowed_tools` string |
 | *the agent's own* | its credential, under whatever name it declares |

package/docs/staff-yaml.md

@@ -22,13 +22,13 @@ brain: acme/technology
 status_issue: 15
 
 schedule: "0 7 * * 1-5"
-model: claude-opus-5
+model: claude-opus-5-5
 timeout_minutes: 90
 mention_timeout_minutes: 90
 
 bot: acme-cto[bot]
 public_bot: acme-robot[bot]
-public_token_env: PIPWEB_TOKEN
+public_token_env: PUBLIC_TOKEN
 agent_secret: CLAUDE_CODE_OAUTH_TOKEN
 
 identities:
@@ -154,6 +154,17 @@ Labels this staff member expects to exist on its own tracker, grouped for readab
 value across every group is checked by `roster doctor`. An agent applying a label that does not
 exist gets an API error mid-run.
 
+## `memory`
+
+This staff member's own memory budgets, overriding the org's. Same three fields as
+[`memory` in org.yaml](org-yaml.md#memory); any left out fall back to the org, then to the
+defaults.
+
+```yaml
+memory:
+  max_index_kb: 32
+```
+
 ## What `roster upgrade` does to this file
 
 Nothing. It is `scaffold` class: written once by `roster hire`, and yours from that moment.

package/docs/troubleshooting.md

@@ -22,8 +22,10 @@ a coding agent, split into what an agent can fix and what only a person can. `ro
 
 **Is:** the ops repo's Actions access is not set to organisation-wide.
 
-Settings -> Actions -> General on `roster-ops`. The setup screen deep-links that exact page,
-which is the fastest way to fix it; Health and `roster doctor` both check it explicitly.
+`roster init --apply` sets it, and so does *Set it for me* on the setup screen. If GitHub
+refused (it needs admin on the ops repo), set it by hand: Settings -> Actions -> General ->
+Access on `roster-ops`, "accessible from repositories in the organisation". Health and `roster
+doctor` both check it explicitly.
 
 ---
 
@@ -90,11 +92,9 @@ constrains it is not a thing anybody wants.
 **Is:** you edited a framework-owned file. `compose.mjs`, `agents.mjs`, `runner-plan.mjs` and
 `session.yaml` are generated. The next `roster upgrade` reconciles them against the template.
 
-This happened here: a fix went into `roster-ops/.github/workflows/session.yaml` instead of
-`templates/ops/...`, and nothing noticed because the framework had not touched that file *yet*.
-
-`roster upgrade` now reports an edit to a framework-owned file whether or not anything has
-collided, and `roster upgrade --check` fails on it. Move the change upstream.
+Nothing notices until the framework next touches that file. `roster upgrade` reports an edit
+to a framework-owned file whether or not anything has collided, and `roster upgrade --check`
+fails on it. Move the change upstream.
 
 ---
 
@@ -181,7 +181,7 @@ landed on GitHub thirty seconds ago and the checkout is behind, that is what you
 
 ## `roster upgrade` says a file has no base
 
-A tenant created before the merge base was recorded has nothing to merge against. Reconstruct
+A tenant with no recorded merge base has nothing to merge against. Reconstruct
 one from the framework's history:
 
 ```bash

package/docs/upgrading.md

@@ -53,6 +53,12 @@ The diff is printed either way, so nothing goes quietly.
 If you want a caller to differ, change the thing it is generated from. Timeouts, schedule,
 model and identities all live in `staff.yaml`.
 
+**A caller the framework no longer generates is removed.** It would still dispatch into
+`session.yaml` with a kind that no longer composes, and fail at run time. The plan lists it.
+The one that has gone so far is `<handle>-pr-mention.yaml`; if your tenant is old enough to
+have one, a forwarding workflow in the product repo went with it, and that one is yours to
+delete, because `roster upgrade` never writes into product repos.
+
 ## Conflicts
 
 A conflict is never written into a live file. Agents read `org/voice.md` at every boot, and

package/docs/writing-a-charter.md

@@ -28,6 +28,13 @@ layer. That is the part that matters most, because without them the model writes
 of whoever it was shown. The brief then interviews you, drafts from your answers, and tells you
 what it cut and why.
 
+**So is a worked example, when one fits.** A staff member whose handle or role reads as a CTO, a
+CMO or support gets the matching [example](#worked-examples) inside the brief, labelled as a
+model for the shape and not content to copy. The copy-a-prompt panel has a picker to choose
+another or none; in a terminal it is `--example cto|cmo|support|none`. It is still a brief you
+answer: the interview comes first, and nothing in the charter should come from the example
+rather than from you.
+
 From a terminal, the same brief:
 
 ```bash
@@ -63,6 +70,14 @@ touches. Be specific. A vague boundary is one that gets crossed at 07:00 with no
 **Where the rest of it lives.** Point at `memory/INDEX.md`, `log/decisions.md`, the pinned
 status issue, and the surfaces the manifest declares.
 
+## Worked examples
+
+Three, for an invented company called Acme: a [CTO](charters/cto.md), a [CMO](charters/cmo.md)
+and a [Head of Support](charters/support.md). They are examples to adapt, not templates to fill
+in. Read them for what a finished charter covers and how specific it gets, then write your own
+about your business. A charter copied from one of these describes Acme. The brief carries the matching one for
+you; these links are for reading them first.
+
 ## Things worth being concrete about
 
 - **Escalation.** Name the label and the mechanism, not the sentiment. "Open an issue labelled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanocollective/roster",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "An agent-run org, powered by GitHub. Scaffold AI staff members whose brain is a repo.",
   "type": "module",
   "bin": {

package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml

@@ -18,6 +18,12 @@ concurrency:
 
 jobs:
   session:
+    # The ceiling on what session.yaml's job token may do: reading the checkout, and the one
+    # comment that says a run failed when the App that would normally say so is what broke.
+    # A called workflow cannot raise these, so they have to be granted here.
+    permissions:
+      contents: read
+      issues: write
     uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
     with:
       staff: %%STAFF%%

package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml

@@ -53,6 +53,12 @@ jobs:
         (github.event_name == 'issues' &&
          contains(github.event.issue.body, '%%MENTION%%'))
       )
+    # The ceiling on what session.yaml's job token may do: reading the checkout, and the one
+    # comment that says a run failed when the App that would normally say so is what broke.
+    # A called workflow cannot raise these, so they have to be granted here.
+    permissions:
+      contents: read
+      issues: write
     uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
     with:
       staff: %%STAFF%%

package/templates/brain/CHARTER.md

@@ -11,10 +11,10 @@ between %%MENTION%% and everyone else.
 Write it before the first unattended run. A generated charter would produce a generic agent,
 which is the failure this whole arrangement exists to avoid.
 
-Write it with your own AI:
+Write it with your own AI. This prints a brief to paste into whichever agent you use (in
+Claude Code it is also /charter, from inside this repo):
 
-    cd %%DIR%% && claude
-    /charter
+    roster brief charter %%STAFF%%
 
 Or write it by hand. The headings below are the shape that has worked; the words are yours.
 

package/templates/brain/README.md

@@ -10,6 +10,7 @@ on, and has decided.
 | `memory/INDEX.md` | One line per fact, read at every boot. |
 | `memory/notes/` | The argument behind a fact, read on demand. |
 | `log/decisions.md` | Why things were decided. Not boot context. |
+| `strategy/` | Longer role documents, and `ideas.md`: ideas parked here rather than filed as issues. |
 | `.github/workflows/` | Three callers. The body lives in `%%OPS_REPO%%`. |
 
 Scheduled runs and mentions are wired up by roster. To see what this staff member is actually

package/templates/brain/log/decisions.md

@@ -4,3 +4,6 @@ Why things were decided, newest first. Not boot context: this is read when a dec
 being revisited, not every morning.
 
 One entry per decision. What was decided, why, and what would change it back.
+
+This file holds the current month. Move anything older into `log/decisions/<YYYY-MM>.md`:
+`roster lint` warns past 24KB.

package/templates/brain/strategy/ideas.md

@@ -0,0 +1,7 @@
+# Ideas
+
+Speculative ideas, one line each, parked here rather than filed as issues. An issue is for
+something that needs a ruling; an idea that does not yet is noise on the tracker.
+
+Promote one to an issue when it serves a priority in `org/priorities.md` and needs a ruling.
+Delete one when it stops being interesting.

package/templates/ops/.github/workflows/session.yaml

@@ -25,7 +25,7 @@ on:
         type: string
       model:
         required: false
-        default: claude-opus-5
+        default: claude-opus-5-5
         type: string
       timeout_minutes:
         required: false
@@ -69,11 +69,22 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: ${{ inputs.timeout_minutes }}
 
+    # `issues: write` is for the failure notice alone, which falls back to this job's own token
+    # when the App's cannot be minted. A called workflow cannot raise what its caller granted, so
+    # the callers ask for the same.
+    permissions:
+      contents: read
+      issues: write
+
     # secrets are not usable in a step-level `if`, so the presence check is hoisted here.
     env:
       HAS_PUBLIC_APP: ${{ secrets.PUBLIC_APP_ID != '' }}
 
     steps:
+      # For the run record at the end. A job has no start time of its own to read back.
+      - name: Start the clock
+        run: echo "ROSTER_STARTED=$(date +%s)" >> "$GITHUB_ENV"
+
       - name: Mint the private-tracker token
         id: private
         uses: actions/create-github-app-token@v2
@@ -161,6 +172,36 @@ jobs:
             echo "product: $repo -> $dir"
           done
 
+      # What people have open on the product repos, so the agent does not open competing work
+      # on files a human branch is rewriting. Read by "Compose the prompt" below; never
+      # fatal, because without it the prompt just has no section about it.
+      - name: Gather human work in flight
+        if: steps.plan.outputs.products != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ steps.public.outputs.token || steps.private.outputs.token }}
+        run: node roster-ops/inflight.mjs --staff "${{ inputs.staff }}" --ops roster-ops --brains . --out .roster-run/inflight.md
+
+      # staff.yaml names the variable its prompts use for the public token (`public_token_env`),
+      # and an `env:` key cannot be an expression, so the name is exported here for every later
+      # step. PUBLIC_TOKEN is always set as well; this only adds the name the manifest chose.
+      - name: Export the public token under its manifest name
+        if: steps.public.outputs.token != ''
+        env:
+          BRAIN_DIR: ${{ steps.plan.outputs.brain_dir }}
+          TOKEN: ${{ steps.public.outputs.token }}
+        run: |
+          set -euo pipefail
+          name=$(sed -n 's/^public_token_env:[[:space:]]*//p' "$BRAIN_DIR/staff.yaml" | head -1 | tr -d "\"' ")
+          case "$name" in
+            ""|PUBLIC_TOKEN|GH_TOKEN|GITHUB_TOKEN) exit 0 ;;
+          esac
+          if ! [[ "$name" =~ ^[A-Z_][A-Z0-9_]*$ ]]; then
+            echo "::warning::public_token_env '$name' is not a variable name; only PUBLIC_TOKEN is set"
+            exit 0
+          fi
+          echo "$name=$TOKEN" >> "$GITHUB_ENV"
+
       # Commits read as the bot, not as a human, so the git history stays legible.
       - name: Set git identity
         env:
@@ -236,13 +277,12 @@ jobs:
       # `uses:` cannot be an expression, so an Action-based runner has to be written out
       # literally. This is the reference one; every other agent goes through the step below.
       - name: Run the session
+        id: session_action
         if: steps.agent.outputs.kind == 'action'
         uses: anthropics/claude-code-action@v1
         env:
           GH_TOKEN: ${{ steps.private.outputs.token }}
           PUBLIC_TOKEN: ${{ steps.public.outputs.token }}
-          # Kept as an alias while charters and memory still name it. Retire once they do not.
-          PIPWEB_TOKEN: ${{ steps.public.outputs.token }}
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN || secrets.AGENT_TOKEN }}
           # These repos are private and single-user, so the usual reason to hide a run's output does
@@ -264,11 +304,11 @@ jobs:
       # argument: it is thousands of words containing quotes and backticks, and argv limits and
       # shell quoting fail at 07:00 rather than in review.
       - name: Run the session
+        id: session_cli
         if: steps.agent.outputs.kind == 'cli'
         env:
           GH_TOKEN: ${{ steps.private.outputs.token }}
           PUBLIC_TOKEN: ${{ steps.public.outputs.token }}
-          PIPWEB_TOKEN: ${{ steps.public.outputs.token }}
           AGENT_MODEL: ${{ steps.agent.outputs.model || inputs.model }}
           AGENT_FLAGS: ${{ steps.agent.outputs.flags }}
           # Kept for a custom `run` written before permissions existed.
@@ -289,6 +329,10 @@ jobs:
           # an `env:` key cannot be an expression.
           export "$TOKEN_ENV=$TOKEN"
           export AGENT_PROMPT_FILE="$PWD/.roster-prompt.txt"
+          # Where an agent that can report its own turns and cost writes them. Optional: the
+          # run record reads it if it is there and records what it cannot know as unknown.
+          mkdir -p .roster-run
+          export AGENT_RESULT_FILE="$PWD/.roster-run/agent-result.json"
 
           if [ -n "$INSTALL" ]; then
             echo "::group::install ${{ steps.agent.outputs.id }}"
@@ -297,20 +341,70 @@ jobs:
           fi
           eval "$RUN"
 
-      # A failed unattended run is otherwise a red X in a tab nobody opens. New in the roster
-      # migration, and deliberate: every failure path should end somewhere a human reads.
+      # What this run was and what it cost, in the job summary and as an artifact with a stable
+      # name, which is what the portal's Runs screen and `roster doctor` read back. Never fatal:
+      # a missing record costs a row in a table, and failing the job over it would cost the run.
+      - name: Write down the run
+        if: always()
+        continue-on-error: true
+        env:
+          STAFF: ${{ inputs.staff }}
+          KIND: ${{ inputs.kind }}
+          AGENT_ID: ${{ steps.agent.outputs.id }}
+          MODEL: ${{ steps.agent.outputs.model || inputs.model }}
+          AGENT_OUTCOME: ${{ steps.session_action.outcome != 'skipped' && steps.session_action.outcome || steps.session_cli.outcome }}
+          JOB_STATUS: ${{ job.status }}
+          RESULT_FILE: ${{ steps.session_action.outputs.execution_file || format('{0}/.roster-run/agent-result.json', github.workspace) }}
+        run: node roster-ops/run-record.mjs --out .roster-run/run.json
+
+      - name: Keep the run record
+        if: always()
+        continue-on-error: true
+        uses: actions/upload-artifact@v6
+        with:
+          name: roster-run
+          path: .roster-run/run.json
+          if-no-files-found: ignore
+
+      # A failed unattended run is otherwise a red X in a tab nobody opens, so every failure path
+      # has to end somewhere a human reads.
+      #
+      # It cannot lean on anything that might be what failed. The App token is the first thing a
+      # renamed repo, a rotated key or an uninstalled App breaks, and a canary sat red for twelve
+      # days because its alert used exactly that token. So: the App token when there is one, and
+      # this job's own token when there is not or it is refused. The plan may not have run
+      # either, so the brain repo falls back to the caller's, which is the same repo, and
+      # staff.yaml is read over the API when it was never checked out.
       - name: Say so if the run did not finish
         if: failure() || cancelled()
         env:
-          GH_TOKEN: ${{ steps.private.outputs.token }}
+          APP_TOKEN: ${{ steps.private.outputs.token }}
+          JOB_TOKEN: ${{ github.token }}
           BRAIN_DIR: ${{ steps.plan.outputs.brain_dir }}
-          BRAIN_REPO: ${{ steps.plan.outputs.brain_repo }}
+          BRAIN_REPO: ${{ steps.plan.outputs.brain_repo || github.repository }}
+          ISSUE: ${{ inputs.issue_number }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
         run: |
-          set -euo pipefail
-          issue="${{ inputs.issue_number }}"
+          set -uo pipefail
+          issue="$ISSUE"
+          if [ -z "$issue" ] && [ -n "$BRAIN_DIR" ] && [ -f "$BRAIN_DIR/staff.yaml" ]; then
+            issue=$(sed -n 's/^status_issue:[[:space:]]*//p' "$BRAIN_DIR/staff.yaml" | head -1)
+          fi
+          if [ -z "$issue" ]; then
+            issue=$(GH_TOKEN="${APP_TOKEN:-$JOB_TOKEN}" gh api "repos/$BRAIN_REPO/contents/staff.yaml" \
+              -H "Accept: application/vnd.github.raw" 2>/dev/null \
+              | sed -n 's/^status_issue:[[:space:]]*//p' | head -1)
+          fi
+          issue="${issue%%[[:space:]#]*}"
           if [ -z "$issue" ]; then
-            issue=$(sed -n 's/^status_issue:[[:space:]]*//p' "$BRAIN_DIR/staff.yaml" | head -1 || true)
+            echo "::error::no status_issue in staff.yaml and no issue in the trigger, so nobody was told"
+            exit 1
+          fi
+
+          body="This run did not finish, so there is no answer coming. [Run ${GITHUB_RUN_ID}]($RUN_URL) has the error."
+          if [ -n "$APP_TOKEN" ] && GH_TOKEN="$APP_TOKEN" gh issue comment "$issue" --repo "$BRAIN_REPO" --body "$body"; then
+            exit 0
           fi
-          [ -n "$issue" ] || { echo "no status_issue in staff.yaml; nothing to comment on"; exit 0; }
-          gh issue comment "$issue" --repo "$BRAIN_REPO" --body \
-            "This run did not finish, so there is no answer coming. [Run ${{ github.run_id }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) has the error."
+          # Posted as github-actions rather than as the staff member, which is itself the clue.
+          GH_TOKEN="$JOB_TOKEN" gh issue comment "$issue" --repo "$BRAIN_REPO" --body \
+            "$body The staff member's own App could not post it, so check the App is installed on this repo and its APP_ID and APP_PRIVATE_KEY secrets are current."

package/templates/ops/agents.mjs

@@ -43,7 +43,7 @@ export const PRESETS = {
   "claude-code-action": {
     kind: "action",
     token_env: "CLAUDE_CODE_OAUTH_TOKEN",
-    model: "claude-opus-5",
+    model: "claude-opus-5-5",
     permissions: CLAUDE_TOOLS,
     option: (k, v) => `--${k} ${shellArg(v)}`,
   },
@@ -52,9 +52,13 @@ export const PRESETS = {
   claude: {
     kind: "cli",
     install: "npm install -g @anthropic-ai/claude-code",
-    run: 'claude -p --model "$AGENT_MODEL" $AGENT_FLAGS < "$AGENT_PROMPT_FILE"',
+    // JSON rather than text so the run record can read turns and cost off it. The log still
+    // carries the answer, inside the `result` field.
+    run:
+      'claude -p --model "$AGENT_MODEL" $AGENT_FLAGS --output-format json < "$AGENT_PROMPT_FILE"' +
+      ' | tee "$AGENT_RESULT_FILE"',
     token_env: "CLAUDE_CODE_OAUTH_TOKEN",
-    model: "claude-opus-5",
+    model: "claude-opus-5-5",
     permissions: CLAUDE_TOOLS,
     option: (k, v) => `--${k} ${shellArg(v)}`,
   },