@nanocollective/roster 0.1.0-alpha.5 → 0.1.0-alpha.50

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

@@ -19,13 +19,23 @@ on:
         required: false
         default: daily
         type: string
+      # What started the run: daily | manual | follow-on | mention | peer. Peer and follow-on
+      # runs start without a person asking, so they are the ones held to max_runs_per_day.
+      trigger:
+        required: false
+        default: ""
+        type: string
+      max_runs_per_day:
+        required: false
+        default: 6
+        type: number
       ops_repo:
         description: "owner/name of the ops repo holding org.yaml and the prompts"
         required: true
         type: string
       model:
         required: false
-        default: claude-opus-5
+        default: claude-opus-5-5
         type: string
       timeout_minutes:
         required: false
@@ -65,15 +75,87 @@ permissions:
   contents: read
 
 jobs:
+  # Two staff can ask each other things, and a daily run can start a follow-on, so runs can start
+  # runs. This is what stops that at max_runs_per_day. A mention is a person asking and is never
+  # held back, so only peer and follow-on runs are counted, and only the ones that ran: a caller
+  # whose condition did not match leaves a skipped run behind under the same name.
+  budget:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      issues: write
+    outputs:
+      go: ${{ steps.count.outputs.go }}
+    steps:
+      - name: Count today's runs nobody asked for
+        id: count
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TRIGGER: ${{ inputs.trigger }}
+          STAFF: ${{ inputs.staff }}
+          LIMIT: ${{ inputs.max_runs_per_day }}
+          ISSUE: ${{ inputs.issue_number }}
+        run: |
+          set -uo pipefail
+          case "$TRIGGER" in
+            peer|follow-on) ;;
+            *) echo "go=true" >> "$GITHUB_OUTPUT"; exit 0 ;;
+          esac
+          today=$(date -u +%F)
+          # Includes this run, which is in progress and named like the rest.
+          filter="[.workflow_runs[]
+            | select(.display_title | test(\"^$STAFF (peer|follow-on)( |\$)\"))
+            | select(.conclusion != \"skipped\")] | length"
+          # One count per page, summed. pipefail makes a failed read fail the whole line.
+          if ! n=$(gh api --paginate "repos/${{ github.repository }}/actions/runs?created=>=$today&per_page=100" \
+              --jq "$filter" | awk '{s += $1} END {print s + 0}'); then
+            # Unknown is not under the limit. A run held back costs a day; a loop costs a bill.
+            echo "::warning::could not count today's runs, so this one does not start"
+            n=999999
+          fi
+          echo "$n of $LIMIT runs today that nobody asked for, this one included"
+          if [ "$n" -le "$LIMIT" ]; then
+            echo "go=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "go=false" >> "$GITHUB_OUTPUT"
+          msg="Not started: $STAFF has had $LIMIT runs today that nobody asked for, which is max_runs_per_day. The next daily run picks this up, or mention them to start one now."
+          echo "$msg" >> "$GITHUB_STEP_SUMMARY"
+          if [ -n "$ISSUE" ]; then
+            gh issue comment "$ISSUE" --repo "${{ github.repository }}" --body "$msg" || true
+          fi
+
   session:
+    needs: budget
+    if: needs.budget.outputs.go == 'true'
     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. `actions: write` starts a follow-on run. A called workflow
+    # cannot raise what its caller granted, so the callers ask for the same.
+    permissions:
+      contents: read
+      issues: write
+      actions: 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 != '' }}
+      # Nothing is listening once the agent ends its turn: the session is over and a background
+      # job dies with the runner. Claude Code moves any command past its timeout (ten minutes by
+      # default) into the background, and an agent told "you will be notified" ends its turn to
+      # wait, so a slow test suite cost the whole run, unpushed, reported as a success. With
+      # background tasks off a slow command stays in the foreground, and the higher cap lets a
+      # long gate finish inside the turn. timeout-minutes is still the real bound.
+      CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1"
+      BASH_MAX_TIMEOUT_MS: "2700000"
 
     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 +243,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:
@@ -207,7 +319,8 @@ jobs:
             {"issue_number":"${{ inputs.issue_number }}",
              "comment_id":"${{ inputs.comment_id }}",
              "repo":"${{ github.repository }}",
-             "actor":"${{ github.actor }}"}
+             "actor":"${{ github.actor }}",
+             "trigger":"${{ inputs.trigger }}"}
         run: |
           node roster-ops/compose.mjs --staff "${{ inputs.staff }}" --kind "${{ inputs.kind }}" --ops roster-ops --brains . > .roster-prompt.txt
           {
@@ -236,13 +349,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 +376,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 +401,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 +413,125 @@ 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.
+      # A session can exit cleanly without doing what it was asked: the success above only means
+      # the agent stopped. A mention is answered by a reply in its thread, or by the issue being
+      # closed when the request said to answer somewhere else. When neither happened the job
+      # fails, so the notice below tells the human instead of leaving them waiting.
+      #
+      # Never fails on its own account: if the issue cannot be read, nothing is claimed.
+      - name: Check the request was answered
+        id: answered
+        if: >-
+          inputs.kind == 'mention' && inputs.issue_number != ''
+          && (steps.session_action.outcome == 'success' || steps.session_cli.outcome == 'success')
+        env:
+          GH_TOKEN: ${{ steps.private.outputs.token }}
+          BOT: ${{ steps.private.outputs.app-slug }}[bot]
+          ISSUE: ${{ inputs.issue_number }}
+        run: |
+          set -uo pipefail
+          since=$(date -u -d "@$ROSTER_STARTED" +%Y-%m-%dT%H:%M:%SZ)
+          if ! state=$(gh api "repos/${{ github.repository }}/issues/$ISSUE" --jq .state) ||
+             ! replies=$(gh api --paginate "repos/${{ github.repository }}/issues/$ISSUE/comments?since=$since" \
+               --jq ".[] | select(.user.login == \"$BOT\" and .created_at >= \"$since\") | .id"); then
+            echo "::warning::could not read #$ISSUE, so whether it was answered is unknown"
+            exit 0
+          fi
+          if [ "$state" = "closed" ] || [ -n "$replies" ]; then
+            exit 0
+          fi
+          echo "unanswered=true" >> "$GITHUB_OUTPUT"
+          echo "::error::the session ended without replying on #$ISSUE or closing it"
+          exit 1
+
+      # A daily run that ended with the next step ready says so in .roster-run/continue, and one
+      # more run starts once this one ends: it waits on the caller's concurrency group. Only
+      # after a run that finished, and the budget job above holds the chain to the day's limit.
+      # The job token can do this: a workflow_dispatch it sends still starts a run.
+      - name: Start a follow-on run
+        if: >-
+          inputs.kind == 'daily' && success()
+          && (steps.session_action.outcome == 'success' || steps.session_cli.outcome == 'success')
+          && hashFiles('.roster-run/continue') != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CALLER: ${{ github.workflow_ref }}
+        run: |
+          set -uo pipefail
+          file=$(basename "${CALLER%@*}")
+          gh workflow run "$file" --repo "${{ github.repository }}" -f trigger=follow-on
+          { echo "Started a follow-on run:"; head -c 300 .roster-run/continue; echo; } >> "$GITHUB_STEP_SUMMARY"
+
+      # 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 }}
+          UNANSWERED: ${{ steps.answered.outputs.unanswered }}
+          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 }}
+          UNANSWERED: ${{ steps.answered.outputs.unanswered }}
+          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=$(sed -n 's/^status_issue:[[:space:]]*//p' "$BRAIN_DIR/staff.yaml" | head -1 || true)
+            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
+            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 [ "$UNANSWERED" = "true" ]; then
+            body="This run stopped without replying here or closing the issue, so there is no answer coming. [Run ${GITHUB_RUN_ID}]($RUN_URL) shows where it stopped."
+          fi
+          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)}`,
   },

package/templates/ops/compose.mjs

@@ -186,6 +186,12 @@ function parseScalar(raw, line) {
 
 const MAX_INCLUDE_DEPTH = 8;
 
+/* A partial's output is scanned again by the template that included it, so a value containing
+   `{{` would be rendered as though somebody had written it into a prompt: a PR title saying
+   `{{nope}}` failed the run, and one saying `{{> some/file}}` read that file in. Values are
+   fenced off with a character no template can contain, and let back out once, at the end. */
+const FENCE = "\u0000";
+
 export function render(template, ctx, readPartial, depth = 0) {
   if (depth > MAX_INCLUDE_DEPTH) throw new Error("include depth exceeded; a partial probably includes itself");
 
@@ -220,10 +226,10 @@ export function render(template, ctx, readPartial, depth = 0) {
       }
       throw new Error(`unknown or empty placeholder: {{${path}}}`);
     }
-    return String(v);
+    return String(v).replace(/\{\{/g, FENCE);
   });
 
-  return out;
+  return depth === 0 ? out.replaceAll(FENCE, "{{") : out;
 }
 
 function lookup(ctx, path) {
@@ -282,7 +288,7 @@ function defaultMarker(name) {
 // Composition
 // ---------------------------------------------------------------------------
 
-export function compose({ opsDir, brainsDir, staff, kind }) {
+export function compose({ opsDir, brainsDir, staff, kind, runDir }) {
   const org = parseYaml(readFileSync(join(opsDir, "org.yaml"), "utf8"), "org.yaml");
 
   const entry = (org.staff ?? []).find((s) => s.handle === staff);
@@ -317,6 +323,22 @@ export function compose({ opsDir, brainsDir, staff, kind }) {
   // sends it to a 404 before it has read anything. So the absence is a value of its own.
   if (Object.keys(event).length) event = { ...event, no_comment: !event.comment_id };
 
+  // Who started this run, as flags: the prompt language has `{{#if}}` and nothing to compare
+  // with. A peer's ask reads differently from a person's, and a follow-on picks up mid-task.
+  const trigger = String(event.trigger ?? "");
+  event = {
+    ...event,
+    from_peer: trigger === "peer",
+    from_human: trigger !== "peer",
+    follow_on: trigger === "follow-on",
+  };
+
+  // What people have open on the product repos, gathered by inflight.mjs just before this runs.
+  // Read as a value and never rendered as a template: it is PR titles, which are a person's
+  // words, and a `{{` in one must not be able to break composition.
+  const inflightFile = join(runDir ?? join(brainsDir, ".roster-run"), "inflight.md");
+  const inflight = existsSync(inflightFile) ? readFileSync(inflightFile, "utf8").trim() : "";
+
   const humans = readHumans(org);
   const ctx = {
     org,
@@ -333,6 +355,11 @@ export function compose({ opsDir, brainsDir, staff, kind }) {
       // The repo this role contributes to but does not own. Named explicitly in the
       // prompt because "a repo you do not own" is vaguer than an agent needs.
       product: (self.works_in ?? [])[0] ?? null,
+      // Absent from manifests written before it existed; the callers fall back to the same.
+      max_runs_per_day: self.max_runs_per_day ?? 6,
+      // One staff member drafts next month's org/priorities.md, so there is one draft rather
+      // than one per person: whoever org.yaml lists first.
+      drafts_priorities: (org.staff ?? [])[0]?.handle === staff,
     },
     peers,
     peer: peers[0] ?? null,
@@ -344,6 +371,7 @@ export function compose({ opsDir, brainsDir, staff, kind }) {
     // without the one the prose already names. Empty when there is only one, which is what
     // makes `{{#if humans_extra}}` the right way to mention the others at all.
     human_list: humanSentence(humans),
+    inflight,
     humans_extra: humanSentence(humans.slice(1)),
   };
 

package/templates/ops/inflight.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// Finds the pull requests people have open on a staff member's product repos, before the prompt
+// is composed, so the agent knows what a human is in the middle of changing.
+//
+// Written because nothing told them. While a person had a long branch open rewriting a product's
+// copy, the staff opened five pull requests and nine issues chasing that same copy, and four of
+// those pull requests were overtaken by the branch. Each one was reasonable on its own; none of
+// them could see the branch.
+//
+// Vendored alongside compose.mjs for the same reason: it runs on the runner, and must not depend
+// on npm. It asks GitHub through `gh`, which every runner has, and it never fails a run: with no
+// answer the prompt simply has no section about it.
+//
+// Usage:  node roster-ops/inflight.mjs --staff cto --ops roster-ops --brains . --out .roster-run/inflight.md
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseYaml } from "./compose.mjs";
+
+/** Enough to see an overlap without reading a 37,000-line branch into the prompt. */
+const MAX_PRS = 10;
+const MAX_FILES = 20;
+const MAX_DIRS = 6;
+
+/**
+ * A person, rather than one of this org's Apps or anybody else's automation.
+ *
+ * `gh` marks an App author as a bot and names it `app/<slug>`; a bot's own login ends `[bot]`.
+ * A machine user is none of those, which is why the org's own bot logins are passed in too.
+ */
+export function isHuman(author, bots = []) {
+  if (!author) return false;
+  const login = String(author.login ?? "");
+  if (!login || author.is_bot) return false;
+  if (login.startsWith("app/") || /\[bot\]$/i.test(login)) return false;
+  const bare = (s) => String(s).toLowerCase().replace(/\[bot\]$/, "").replace(/^app\//, "");
+  return !bots.some((b) => bare(b) === bare(login));
+}
+
+/** The repos a staff member works in: their own `works_in`, or else every product repo. */
+export function productRepos(org, manifest) {
+  const own = (manifest?.works_in ?? []).map((w) => String(w?.repo ?? "")).filter(Boolean);
+  if (own.length) return own;
+  return (org.repos ?? []).filter((r) => r.role === "product").map((r) => `${org.org}/${r.name}`);
+}
+
+/** The top directories a change touches, so a wide one reads as "the copy" rather than a list. */
+function directories(paths) {
+  const counts = new Map();
+  for (const p of paths) {
+    const parts = p.split("/");
+    const dir = parts.length === 1 ? "(root)" : parts.slice(0, Math.min(2, parts.length - 1)).join("/") + "/";
+    counts.set(dir, (counts.get(dir) ?? 0) + 1);
+  }
+  return [...counts].sort((a, b) => b[1] - a[1]).slice(0, MAX_DIRS);
+}
+
+function days(iso, now) {
+  const d = Math.floor((now - new Date(iso).getTime()) / 86400_000);
+  return d <= 0 ? "today" : d === 1 ? "1 day" : `${d} days`;
+}
+
+/**
+ * The markdown the prompt carries, or "" for nothing in flight.
+ *
+ * Titles are a person's words and go in as data: compose.mjs substitutes this file as a value,
+ * never renders it as a template, so a `{{` in a title cannot break a run.
+ */
+export function describe(found, now = Date.now()) {
+  const lines = [];
+  for (const { repo, prs } of found) {
+    for (const pr of prs.slice(0, MAX_PRS)) {
+      const paths = (pr.files ?? []).map((f) => f.path).filter(Boolean);
+      const total = Math.max(pr.changedFiles ?? 0, paths.length);
+      const title = String(pr.title ?? "").replace(/\s+/g, " ").trim();
+      lines.push(
+        `- **${repo}#${pr.number}** "${title}" by @${pr.author.login}, open ${days(pr.createdAt, now)}` +
+          `, branch \`${pr.headRefName}\`${pr.isDraft ? ", draft" : ""}, ${total} file${total === 1 ? "" : "s"}`,
+      );
+      if (!paths.length) continue;
+      if (total > MAX_FILES) {
+        lines.push(`  - mostly under ${directories(paths).map(([d, n]) => `\`${d}\` (${n})`).join(", ")}`);
+      }
+      const shown = paths.slice(0, MAX_FILES).map((p) => `\`${p}\``).join(", ");
+      const more = total - Math.min(paths.length, MAX_FILES);
+      lines.push(`  - ${shown}${more > 0 ? `, and ${more} more` : ""}`);
+    }
+    if (prs.length > MAX_PRS) lines.push(`- and ${prs.length - MAX_PRS} more open on ${repo}`);
+  }
+  return lines.length ? lines.join("\n") + "\n" : "";
+}
+
+/** Everything open by a person, per repo. `gh` is passed in so a test never needs the network. */
+export function gather({ org, manifest, gh }) {
+  const bots = [manifest?.bot, manifest?.public_bot].filter(Boolean);
+  const out = [];
+  for (const repo of productRepos(org, manifest)) {
+    let raw;
+    try {
+      raw = gh([
+        "pr",
+        "list",
+        "--repo",
+        repo,
+        "--state",
+        "open",
+        "--limit",
+        "50",
+        "--json",
+        "number,title,author,createdAt,headRefName,isDraft,changedFiles,files",
+      ]);
+    } catch (err) {
+      // One unreadable repo is not a reason to say nothing about the others.
+      console.error(`::warning::inflight: ${repo}: ${String(err.message).split("\n")[0]}`);
+      continue;
+    }
+    const prs = JSON.parse(raw || "[]")
+      .filter((pr) => isHuman(pr.author, bots))
+      // Oldest first: the long-lived branch is the one most likely to be overtaking everybody.
+      .sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+    if (prs.length) out.push({ repo, prs });
+  }
+  return out;
+}
+
+function main(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 2) args[argv[i].replace(/^--/, "")] = argv[i + 1];
+  if (!args.staff) throw new Error("--staff is required");
+  const opsDir = resolve(args.ops ?? ".");
+  const org = parseYaml(readFileSync(join(opsDir, "org.yaml"), "utf8"), "org.yaml");
+  const entry = (org.staff ?? []).find((s) => s.handle === args.staff);
+  if (!entry) throw new Error(`org.yaml has no staff member "${args.staff}"`);
+  const manifestPath = join(resolve(args.brains ?? ".."), entry.dir ?? entry.handle, "staff.yaml");
+  const manifest = existsSync(manifestPath)
+    ? parseYaml(readFileSync(manifestPath, "utf8"), "staff.yaml")
+    : {};
+
+  const gh = (a) => execFileSync("gh", a, { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
+  const text = describe(gather({ org, manifest, gh }));
+  const out = resolve(args.out ?? ".roster-run/inflight.md");
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, text);
+  process.stdout.write(text || "no human pull requests open on the product repos\n");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  try {
+    main(process.argv.slice(2));
+  } catch (err) {
+    // Never the reason a run fails. Without it the prompt has no section, which is how every
+    // run went before this existed.
+    console.error(`::warning::inflight: ${err.message}`);
+  }
+}