@nanocollective/roster 0.1.0-alpha.1 → 0.1.0-alpha.11

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/staff.yaml

@@ -13,7 +13,6 @@ schedule: "%%SCHEDULE%%"
 model: %%MODEL%%
 timeout_minutes: %%TIMEOUT%%
 mention_timeout_minutes: %%MENTION_TIMEOUT%%
-pr_mention_timeout_minutes: %%PR_MENTION_TIMEOUT%%
 
 bot: %%APP%%[bot]
 public_bot: %%PUBLIC_APP%%[bot]

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

@@ -15,7 +15,7 @@ on:
         required: true
         type: string
       kind:
-        description: "daily | mention | pr-mention"
+        description: "daily | mention"
         required: false
         default: daily
         type: string
@@ -25,17 +25,17 @@ on:
         type: string
       model:
         required: false
-        default: claude-opus-5
+        default: claude-opus-5-5
         type: string
       timeout_minutes:
         required: false
-        default: 60
+        default: 90
         type: number
       allowed_tools:
         required: false
         default: "Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch"
         type: string
-      # Trigger context. Empty on a scheduled run; set when a comment or a PR woke us.
+      # Trigger context. Empty on a scheduled run; set when a comment woke us.
       issue_number:
         required: false
         default: ""
@@ -44,10 +44,6 @@ on:
         required: false
         default: ""
         type: string
-      pr_number:
-        required: false
-        default: ""
-        type: string
     secrets:
       APP_ID:
         required: true
@@ -73,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
@@ -102,9 +109,7 @@ jobs:
       # missed". It sits here, before any checkout, so the eyes land in seconds rather than after
       # the clones.
       #
-      # `mention` only. A pr-mention is already acknowledged by the forwarder in the public product
-      # repo, on the comment the human actually left, and reacting again here would put two on it.
-      # A daily run has nothing to react to.
+      # `mention` only: a daily run has nothing to react to.
       #
       # An `issues` payload carries no comment, so the eyes go on the issue itself. That is the
       # route where a mention is typed straight into the body of a new issue.
@@ -167,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:
@@ -191,20 +226,6 @@ jobs:
             [ -d "$dir" ] && identify "$dir" "${PUBLIC_SLUG:-$PRIVATE_SLUG}"
           done
 
-      # A PR request is answered on the PR's own branch, never on a new one.
-      - name: Check out the PR branch
-        if: inputs.pr_number != ''
-        env:
-          GH_TOKEN: ${{ steps.public.outputs.token || steps.private.outputs.token }}
-          PRODUCT_DIR: ${{ steps.plan.outputs.product_dir }}
-          PRODUCT_REPO: ${{ steps.plan.outputs.product_repo }}
-        run: |
-          set -euo pipefail
-          [ -n "$PRODUCT_DIR" ] || { echo "no product repo to check a PR out of"; exit 1; }
-          cd "$PRODUCT_DIR"
-          gh pr checkout "${{ inputs.pr_number }}" --repo "$PRODUCT_REPO"
-          echo "on $(git branch --show-current)"
-
       - uses: pnpm/action-setup@v6
         if: steps.plan.outputs.needs_node == 'true'
         with:
@@ -226,7 +247,6 @@ jobs:
           ROSTER_CONTEXT: >-
             {"issue_number":"${{ inputs.issue_number }}",
              "comment_id":"${{ inputs.comment_id }}",
-             "pr_number":"${{ inputs.pr_number }}",
              "repo":"${{ github.repository }}",
              "actor":"${{ github.actor }}"}
         run: |
@@ -257,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
@@ -274,21 +293,25 @@ jobs:
           # No --max-turns. A run that legitimately needs more turns should get them: capping it
           # fails the action *after* the work is done and committed, which is a false red rather
           # than a saved penny. timeout-minutes is the real bound.
+          # The permission flags come from agents.mjs, which is the only thing that knows
+          # which agent is running and therefore how to say "may write" to it.
           claude_args: >-
             --model ${{ inputs.model }}
-            --allowedTools "${{ inputs.allowed_tools }}"
+            ${{ steps.agent.outputs.flags }}
           prompt: ${{ steps.compose.outputs.text }}
 
       # Any agent with a command line. The prompt is handed over as a file, never as an
       # 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.
           AGENT_TOOLS: ${{ inputs.allowed_tools }}
           AGENT_TOKEN: ${{ secrets.AGENT_TOKEN }}
           FALLBACK_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
@@ -306,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 }}"
@@ -314,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

@@ -24,22 +24,43 @@ import { parseYaml } from "./compose.mjs";
  * `uses:` cannot be an expression. Only the reference Claude runner is one of these.
  * `cli` is everything else: install a package, run a command. That path is open-ended.
  */
+/* Claude says what an agent may do as a list of its own tool names. The three levels are the
+   same list narrowed: everything, everything but the network, and nothing that writes. */
+const CLAUDE_TOOLS = {
+  full: '--allowedTools "Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch"',
+  workspace: '--allowedTools "Bash,Read,Write,Edit,Glob,Grep"',
+  "read-only": '--allowedTools "Read,Glob,Grep,WebFetch,WebSearch"',
+};
+
+/** Single quotes, because every one of these ends up inside `eval` in the session. */
+function shellArg(v) {
+  return `'${String(v).replace(/'/g, "'\\''")}'`;
+}
+
 export const PRESETS = {
   // The reference runner, and the default. Uses Anthropic's own action, which handles tool
   // permissions and output for us.
   "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)}`,
   },
 
   // The same agent through its plain CLI, for anyone who would rather not depend on the action.
   claude: {
     kind: "cli",
     install: "npm install -g @anthropic-ai/claude-code",
-    run: 'claude -p --model "$AGENT_MODEL" --allowedTools "$AGENT_TOOLS" < "$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)}`,
   },
 
   codex: {
@@ -47,20 +68,66 @@ export const PRESETS = {
     install: "npm install -g @openai/codex",
     // `exec -` reads the prompt from stdin. The sandbox has to be opened up because the whole
     // point of a session is that it edits the checkout and pushes.
-    run: 'codex exec - --model "$AGENT_MODEL" --sandbox danger-full-access < "$AGENT_PROMPT_FILE"',
+    run: 'codex exec - --model "$AGENT_MODEL" $AGENT_FLAGS < "$AGENT_PROMPT_FILE"',
     token_env: "CODEX_API_KEY",
     model: "gpt-5-codex",
+    /* Codex spells freedom as a sandbox plus an approval policy, and both have to be said:
+       a sandbox that allows writes still stops to ask by default, and a run that stops to ask
+       at 07:00 is a run that times out having done nothing. */
+    permissions: {
+      full: '--sandbox danger-full-access -c approval_policy="never"',
+      workspace: '--sandbox workspace-write -c approval_policy="never"',
+      "read-only": '--sandbox read-only -c approval_policy="never"',
+    },
+    // `-c key=value` is its highest-precedence override, so anything else goes through it.
+    option: (k, v) => `-c ${k}=${shellArg(JSON.stringify(v))}`,
   },
 
   nanocoder: {
     kind: "cli",
     install: "npm install -g @nanocollective/nanocoder",
-    // `run` is its non-interactive mode; --trust-directory skips the first-run prompt that
-    // would otherwise hang a runner, and --plain avoids the TUI. The prompt is an argument
-    // here rather than stdin, so it is read out of the file.
-    run: 'nanocoder --model "$AGENT_MODEL" --mode yolo --trust-directory --plain run "$(cat "$AGENT_PROMPT_FILE")"',
+    /* `run` is its non-interactive mode; --trust-directory skips the first-run prompt that
+       would otherwise hang a runner, and --plain avoids the TUI. The prompt is an argument
+       here rather than stdin, so it is read out of the file.
+
+       NANOCODER_PROVIDERS_FILE is the part that makes it work unattended. Nanocoder is a
+       client, not a model: it reads its providers from `agents.config.json` found in the
+       working directory. In a session that directory is the workspace root — the place the
+       repos are checked out *into* — which belongs to no repo, so a committed config would
+       never be found. Pointing at the ops repo's copy gives every staff member the same
+       providers from a file that is version controlled. A missing file is ignored, so this is
+       safe when somebody has configured it another way. */
+    run:
+      'NANOCODER_PROVIDERS_FILE="${NANOCODER_PROVIDERS_FILE:-roster-ops/agents.config.json}" ' +
+      'nanocoder --model "$AGENT_MODEL" $AGENT_FLAGS --trust-directory --plain run "$(cat "$AGENT_PROMPT_FILE")"',
     token_env: "NANOCODER_API_KEY",
     model: "",
+    /* Its development modes. `plan` is genuinely read-only: it reasons and proposes and edits
+       nothing, which is the right answer for a staff member you are not ready to trust yet. */
+    permissions: {
+      full: "--mode yolo",
+      workspace: "--mode auto-accept",
+      "read-only": "--mode plan",
+    },
+    option: (k, v) => `--${k} ${shellArg(v)}`,
+    /* A client rather than a model, so it cannot run until it has been told whose model to
+       call. Written on init and reported by doctor when it is missing, because the failure
+       without it is a run that installs, starts, finds no provider and exits. */
+    config: {
+      path: "agents.config.json",
+      contents: {
+        nanocoder: {
+          providers: [
+            {
+              name: "openrouter",
+              baseUrl: "https://openrouter.ai/api/v1",
+              apiKey: "${NANOCODER_API_KEY}",
+              models: ["FILL IN: a model this provider serves, and set it as `model` in org.yaml"],
+            },
+          ],
+        },
+      },
+    },
   },
 };
 
@@ -96,9 +163,60 @@ export function resolveAgent(org, staff = {}) {
     token_env: merged.token_env,
     // The staff member's own model wins; then the agent's default. Empty means "the agent's".
     model: staff.model ?? merged.model ?? "",
+    flags: flagsFor(merged, spec, org, staff),
+    config: merged.config ?? null,
   };
 }
 
+/** The three levels, in the order a person would climb them. */
+export const LEVELS = ["read-only", "workspace", "full"];
+
+/**
+ * What the agent is allowed to do, in its own words.
+ *
+ * org.yaml says `permissions: full` and every agent hears something different: Claude a list
+ * of tool names, Codex a sandbox and an approval policy, nanocoder a development mode. The
+ * translation lives here because it is the only place that knows which agent is running, and
+ * because the alternative is a config file written in one tool's vocabulary that quietly means
+ * nothing to the other two.
+ *
+ * `options` is the escape hatch, in that agent's own vocabulary, spelled onto its command line
+ * by the preset. Anything roster does not model is still reachable without waiting for us.
+ */
+function flagsFor(merged, spec, org, staff) {
+  const out = [];
+  const asked = staff.permissions ?? spec.permissions ?? org.permissions ?? "full";
+  if (!LEVELS.includes(asked)) {
+    throw new Error(`unknown permissions "${asked}". One of: ${LEVELS.join(", ")}`);
+  }
+
+  /* `allowed_tools` predates the levels and is Claude's own vocabulary, so it still wins for
+     an agent that takes a tool list. Nothing translates it for the others: a list written for
+     one tool is not a permission level for another, and guessing would be worse than saying so. */
+  const tools = staff.allowed_tools ?? org.defaults?.allowed_tools;
+  const table = merged.permissions;
+  if (tools && table === CLAUDE_TOOLS) {
+    const list = Array.isArray(tools) ? tools.join(",") : String(tools);
+    out.push(`--allowedTools "${list.replace(/\s+/g, "")}"`);
+  } else if (table) {
+    out.push(table[asked]);
+  }
+
+  const options = { ...(spec.options ?? {}), ...(staff.options ?? {}) };
+  const speller = merged.option;
+  for (const [k, v] of Object.entries(options)) {
+    if (v === undefined || v === null || v === "") continue;
+    if (!speller) {
+      throw new Error(
+        `agent "${merged.id ?? "custom"}" has options but no way to spell them.\n` +
+          "  A custom agent takes its options in its own `run` command.",
+      );
+    }
+    out.push(speller(k, v));
+  }
+  return out.filter(Boolean).join(" ");
+}
+
 function strip(o) {
   const out = {};
   for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== "") out[k] = v;
@@ -138,6 +256,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     `model=${agent.model}`,
     `install<<AGENT_EOF_9c1f\n${agent.install}\nAGENT_EOF_9c1f`,
     `run<<AGENT_EOF_9c1f\n${agent.run}\nAGENT_EOF_9c1f`,
+    `flags<<AGENT_EOF_9c1f\n${agent.flags}\nAGENT_EOF_9c1f`,
   ].join("\n");
   process.stdout.write(out + "\n");
 }

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");
 
@@ -212,18 +218,18 @@ export function render(template, ctx, readPartial, depth = 0) {
       if (path.startsWith("event.")) {
         throw new Error(
           `{{${path}}} needs trigger context, which arrives as ROSTER_CONTEXT.\n` +
-            `  A "mention" or "pr-mention" prompt is written for a comment that woke it, so it cannot\n` +
+            `  A "mention" prompt is written for the comment that woke it, so it cannot\n` +
             `  be composed without one. To see it locally:\n` +
-            `    ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","pr_number":"1","repo":"o/r"}' \\\n` +
+            `    ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","repo":"o/r"}' \\\n` +
             `      node compose.mjs --staff <handle> --kind <kind>`,
         );
       }
       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) {
@@ -234,11 +240,55 @@ function truthy(v) {
   return !(v === undefined || v === null || v === false || v === "" || (Array.isArray(v) && v.length === 0));
 }
 
+// ---------------------------------------------------------------------------
+// Who the staff answer to
+//
+// One person was written as `human:`. More than one is a `humans:` list. Both are read, the
+// singular still works, and the first entry is the one the prose addresses. Duplicated in
+// roster's own src/lib/humans.ts rather than imported, for the same reason the YAML parser
+// above is: a run must not depend on npm or on a network call.
+// ---------------------------------------------------------------------------
+
+export function readHumans(org) {
+  const listed = Array.isArray(org?.humans) ? org.humans : org?.humans ? [org.humans] : [];
+  const out = [];
+  for (const entry of [...listed, org?.human].filter(Boolean)) {
+    const github = String(entry.github ?? entry.login ?? "").trim();
+    const name = String(entry.name ?? github).trim();
+    if (!github && !name) continue;
+    if (github && out.some((h) => h.github.toLowerCase() === github.toLowerCase())) continue;
+    out.push({
+      github,
+      name: name || github,
+      marker: String(entry.marker ?? "").trim() || defaultMarker(name || github),
+      role: entry.role ?? undefined,
+    });
+  }
+  return out;
+}
+
+/** "Will (@will-lamerton) and Sam (@sam)", for a sentence in a prompt. */
+export function humanSentence(humans) {
+  const parts = humans.map((h) => (h.github ? `${h.name} (@${h.github})` : h.name));
+  if (parts.length < 2) return parts[0] ?? "";
+  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+
+function defaultMarker(name) {
+  return (
+    String(name)
+      .trim()
+      .split(/[\s-]+/)[0]
+      .toLowerCase()
+      .replace(/[^a-z0-9]/g, "") || "human"
+  );
+}
+
 // ---------------------------------------------------------------------------
 // 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);
@@ -268,10 +318,24 @@ export function compose({ opsDir, brainsDir, staff, kind }) {
     }
   }
 
+  // The `issues` route carries no comment: the ask is the body of a new issue. There is no
+  // `{{#unless}}`, and a prompt that tells an agent to read comment `` as its first instruction
+  // 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 };
+
+  // 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,
     event,
-    human: org.human,
+    // The first is who the prose addresses; `humans` is everybody the mention gate accepts.
+    human: humans[0] ?? org.human,
+    humans,
     ops: { dir: org.ops_dir ?? "roster-ops" },
     // `dir` lives in the org registry (it is where the checkout lands), everything
     // else lives in the staff member's own manifest.
@@ -288,6 +352,12 @@ export function compose({ opsDir, brainsDir, staff, kind }) {
     // Convenience strings the fragments lean on, computed once here so a
     // fragment never has to do string work.
     peer_list: peers.map((p) => `- \`${p.dir}/\` - the ${p.name}'s brain`).join("\n"),
+    // Everybody who can wake this staff member and rule on their work, and the same list
+    // 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)),
   };
 
   // "staff:foo.md" resolves inside the staff member's own brain repo, which is how a
@@ -315,7 +385,7 @@ function main(argv) {
     args[argv[i].slice(2)] = argv[i + 1];
   }
   if (!args.staff || !args.kind) {
-    console.error("usage: node compose.mjs --staff <handle> --kind <daily|mention|pr-mention> [--ops DIR] [--brains DIR]");
+    console.error("usage: node compose.mjs --staff <handle> --kind <daily|mention> [--ops DIR] [--brains DIR]");
     process.exit(2);
   }
   const opsDir = resolve(args.ops ?? HERE);