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

package/docs/portal.md

@@ -18,10 +18,12 @@ Keep the repos checked out beside each other, in the same shape the runner uses.
 
 ## The sidebar
 
-**The counts are right on load.** The badges beside Inbox and Pending work used to fill in only
-once something caused a render with an inbox already loaded, which in practice meant "after you
-visit the Inbox". A sidebar that says nothing until you look at it is not a sidebar. The page
-now asks once at boot, and the Inbox screen shares that request rather than making a second one.
+Anything that asks before it acts (a merge, a push, a hire, a retire, a paid run) asks in the
+page's own dialog, never the browser's `confirm()`, which blocks the whole tab.
+
+**The counts are right on load.** The badges beside Home and Trackers are fetched once at
+boot, and the screens share that request rather than making a second one. A sidebar that
+says nothing until you look at it is not a sidebar.
 
 While the first answer is outstanding the badge is a placeholder rather than blank, because an
 empty badge reads as zero and zero is a different claim from "still counting". The screens
@@ -50,26 +52,86 @@ It asks GitHub which of two things this is:
   nothing is written until you apply. Same `initFiles` the CLI runs, so the browser and the
   terminal cannot disagree about what a new tenant contains.
 
-Then: the Actions setting, deep-linked to the exact page with the failure it causes if skipped;
-which repos the staff work in, as a picker over what your `gh` can see minus what `org.yaml`
-already has; and a prompt for writing `org/business.md`.
+Then what is left. **The Actions setting**, read on arrival: if it is not set, *Set it for me*
+asks GitHub to set it, and a refusal comes back with GitHub's reason and a link to the page to
+click. **The agent credential**: a paste box, a line on where your agent's credential comes from,
+and where it will be stored (one org secret shared with the brains, or each brain where an org
+secret would not arrive, with the reason). The value goes to the local server in a POST and from
+there to `gh` on standard input; it is never written to disk or echoed back. Until somebody is
+hired the box says so, because nothing would read it. Then which repos the staff work in, as a
+picker over what your `gh` can see minus what `org.yaml` already has, recorded with the
+visibility GitHub reports. Then the two files only you can write: a prompt for writing
+`org/business.md`, and `org/priorities.md` opened in place, stub and all, to replace with what
+matters this month. Each says whether it is written yet.
 
 Nothing here stores which step you are on. Setup takes days rather than minutes: an App has to be
 installed, a credential set, a first run finished. So the page derives its state from `roster
-doctor` every time it is drawn. A stored step counter would disagree with the world within an hour.
-
-## Inbox
+doctor` every time it is drawn, and runs the check again after anything on it is saved. A stored
+step counter would disagree with the world within an hour.
+
+### Getting started
+
+**Once the org exists, the same steps stay in the sidebar as *Getting started*** for as long as
+anything is left: nobody hired, or `org/business.md` or `org/priorities.md` still the stub. An
+org nobody has been hired into opens on it rather than on an empty Inbox, with *Hire your first
+staff member* first, then the Actions setting, the credential, the repo picker, both files, and
+what doctor still says. A link to another screen still wins. When the list is empty the entry
+goes away; the repo picker lives on under [Org](#org).
+
+## Home
+
+Where the portal opens. An Ask box at the top, then these, in order.
+
+- **Ask.** Pick a staff member, type what you want, **Send**. It opens an issue on their
+  tracker with their `@handle` in front, which wakes them in about a minute.
+- **Latest reports.** Each staff member's run report from the last day: the three lines they
+  post on their status issue at the end of a daily run. Nothing shows until there is one.
+- **Needs you.** Every ask a staff member has put on you, and every pull request ready to
+  merge, oldest first. Each card has one action on its right:
+  - a `decision` has **Reply**, and **Go with the default** when it carries one. The default
+    and its date are shown, and turn amber once the date has passed.
+  - a `review` has **Approve**.
+  - a `chore` has **Done**, which closes it.
+  - a pull request has **Merge**, unless its checks fail, are still running, or it conflicts.
+
+  Answers go out as you, with the staff member's `@handle`, so they act on them straight away.
+  Once you have had the last word, the card leaves Needs you for Your requests, since it is
+  waiting on them now. If they reply, it comes back. When nothing is waiting, it says so.
+- **Unread.** Anything on a staff member's own tracker, or elsewhere, with activity you have not
+  seen: a peer's ask, a status issue, their own work. Unread comes from your GitHub
+  notifications, as on Trackers. Cards and rows anywhere on Home carry the same blue mark, and
+  opening one marks it read here and on GitHub.
+- **Working now.** Each staff member: what they are running and what started it (the daily run,
+  a follow-on, answering an issue, a peer's ask), for how long, with a link to the log. When
+  they are idle, how their last run ended. Peer and follow-on runs today are counted against
+  `max_runs_per_day`. This asks GitHub every few seconds while a run is going and every half
+  minute otherwise, and only while Home is on screen.
+- **Your requests.** What you asked for, and asks of theirs you have answered: waiting, being worked on (a run for it is going), or
+  answered (a staff member had the last word).
+- **Closed today.** What the staff closed today, with the line they closed it with, and
+  **Reopen** beside each. Staff close finished issues themselves, so this is where you check.
+
+**Every item opens in a side sheet.** Click anywhere on a card or a row and its thread opens
+on the right: the conversation, Reply, Close or Reopen, Merge for a pull request, and Open in
+GitHub. Escape or the × closes it, and Home repaints where you were.
+
+**Nothing is missed.** Every open issue and pull request has exactly one place: on Home, or on
+the staff member's own tracker (their status issue, a peer's ask, their own work), or elsewhere
+(draft pull requests, contributor issues). The line at the bottom counts the last two, with a
+link to Trackers.
+
+## Trackers
 
 Everything open across the org, from one GraphQL call per repo. Bodies and full timelines come
 down with the list, so opening a thread is a render rather than a request.
 
-- **Filter by staff member.** An item belongs to somebody if it is in their brain repo, their
-  own App wrote it, a peer addressed it to them with a `from-<handle>` label, or it is assigned
-  to them. The shared public identity cannot name one staff member, so an item it wrote counts
-  for anyone who works in that repo. Items authored by humans belong to nobody, which is
-  correct.
-- **Scope** to everything, what is assigned to you, decisions, or open PRs.
-- **Open, recently closed, or both.** Open by default: an inbox is what is waiting on
+- **The links under Trackers in the sidebar filter it.** All; Unread; each staff member, which
+  lists the issues on their own tracker whoever filed them; and Issues, the product repos.
+- **Unread comes from your GitHub notifications.** A thread with activity you have not read has
+  a bar on the left and a bold title, and Unread lists only those, with a count. Opening one
+  marks it read on GitHub too, and reading it on GitHub clears it here. GitHub only notifies you
+  about repos you watch and threads you are part of.
+- **Open or closed.** Open by default: an inbox is what is waiting on
   somebody, and months of finished work mixed into that answers a different question. Closed
   work reaches back 45 days, up to 30 issues and 30 pull requests per repository, and carries
   a shorter timeline than open work because it is there to be read rather than triaged. A
@@ -80,9 +142,8 @@ down with the list, so opening a thread is a render rather than a request.
   silently doing nothing.
 - **A new issue asks one question: who is it for.** One dropdown, over the staff. It goes to
   that person's brain repo and their `@handle` is written into the body for you, because those
-  are the two things that make an issue reach an agent rather than sit there. It used to ask
-  for a staff member *and* a repo, which let you set the pair to a combination that woke
-  nobody. To file in a product repo instead, use GitHub: this form is for asking the staff for
+  are the two things that make an issue reach an agent rather than sit there. Asking for a
+  repo as well would let you pick a pair that wakes nobody. To file in a product repo instead, use GitHub: this form is for asking the staff for
   something.
 - **Labels are the repo's own, as toggles.** They are the labels that exist on the recipient's
   repository, fetched from GitHub and cached. A text box was a spelling test: `from-cmo` and
@@ -125,7 +186,7 @@ down with the list, so opening a thread is a render rather than a request.
 
 ## Pending work
 
-The same screen, scoped to pull requests, in its own place in the sidebar. An inbox is what is
+The same screen, scoped to pull requests. It is where a pull request opens from Home. An inbox is what is
 waiting on you; a pull request is work that is finished and waiting on a merge, and the count
 that matters is not how many are open but how many are green and still sitting there.
 
@@ -149,8 +210,7 @@ of every repo to show one of them is the wrong trade.
 second decision and not this button's to make. It runs `gh pr merge` as you, so a protected
 branch, a failing required check or a merge queue behaves exactly as it would on the site.
 
-**It does not ask how.** There used to be a squash / merge commit / rebase dropdown beside it.
-That is a question about git rather than about the pull request in front of you, the repository
+**It does not ask how.** Squash, merge commit or rebase is a question about git rather than about the pull request in front of you, the repository
 has already answered it in its own settings, and on any given repository most of the answers are
 wrong. So the repository is asked instead: squash where it is allowed, then a merge commit, then
 rebase.
@@ -160,8 +220,8 @@ rebase.
 **`@cto` on a pull request wakes nobody.** A staff member's caller workflow lives in their own
 brain repo and gates on their handle appearing *there*; on a product repo the same mention
 posts, renders as a chip, and does nothing. That is deliberate, for the reasons in
-[security](security.md#trust-in-a-prompt), and it used to be silent, which is worse than the
-restriction itself.
+[security](security.md#trust-in-a-prompt). Saying so out loud is the portal's job, because a
+silent no-op is worse than the restriction itself.
 
 **Reply is the one box, and it handles this.** Name somebody in a reply where a comment will
 not reach them and the offer appears under the box, ticked: *open it on their tracker too*. One
@@ -183,16 +243,30 @@ On the **Files** tab each file's heading has its own Reply, which opens the same
 one file. "This bit is wrong" is what you want to say while looking at a diff, and the
 alternative is describing in prose which of thirty files you meant.
 
-There was briefly a second button up here called *Ask a staff member*. It did almost the same
-thing as Reply, differing mainly in making you pick a name from a dropdown rather than typing
-it, and nothing on the page said which one you wanted. Two ways to do one thing is worse than
-either of them.
-
 Both writes go through your own `gh`, as you. Nothing is dispatched between repositories and no
 credential is put on a public repo. The tracker issue goes first, because it is the half that
 reaches anybody; if the copy on the pull request then fails you are told, rather than being
 shown an error that invites you to ask the same person the same thing twice.
 
+## Runs
+
+What each staff member ran in the last 30 days: when, daily or mention, how it ended, how long
+it took, turns and cost where known, and a link to the log. Above the tables, the 30-day total
+for the org, and each staff member's own in their heading.
+
+Runs are not in any repo, so this is the one screen that is only ever on GitHub. It reads the
+run lists through your own `gh`, the same way the inbox does, and offline it says so rather
+than drawing an empty table that reads as "nothing ran".
+
+Cost comes from the record each run leaves behind (see [cost](cost.md#what-each-run-cost)). A
+run from before records existed, or from an agent that does not report cost, shows a dash, and
+a total says how many runs it could price. Each record is downloaded once and kept for as long
+as the portal runs, so the first visit is the slow one.
+
+A skipped mention is not a run and is not listed. A `setup-failure` is a run that failed before
+the agent started, usually a token or a checkout. Past a [`budget`](org-yaml.md#budget), the
+total turns amber.
+
 ## Org
 
 The layer every staff member inherits, in one place: `org.yaml`, every `org/*.md`, and the
@@ -200,9 +274,12 @@ prompt files in `prompts/`, each with a line saying what it is for, because a fi
 you nothing about which to open. Anything roster does not ship falls back to its own first
 heading.
 
-**The list comes off disk**, not out of the page. It used to be five paths written into the
-portal, so a tenant that added `org/pricing.md` could not open it at all and one that had not
-written `org/business.md` yet got "not found" with nothing to do about it. Only files the
+**Add a product repo** opens the same picker setup uses, so a repo created later does not mean
+typing `role: product` into `org.yaml` by hand. Adding one commits `org.yaml` and pushes. A new
+hire picks it up; somebody already hired keeps the `works_in` in their own `staff.yaml`.
+
+**The list comes off disk**, not out of the page, so a tenant that adds `org/pricing.md` can
+open it like any other. Only files the
 portal may actually write are listed: an editor that offers a file it cannot save is a trap.
 
 Every one of them is editable from the screen it is read on: an **Edit** button on the file,
@@ -225,18 +302,50 @@ have more than one human, and a card that names one of two reads as the only one
 
 ## Staff
 
-Everyone on the roster, and the four things you could previously only do from a terminal.
-
-**Hiring** runs the same `buildPlan` and `applyPlan` that `roster hire` does, on the server.
-Only the handle is required; everything else is copied from whoever is already here. You see
-the plan first, listing every file, every label, the schedule it chose and why, and the manual
-steps it cannot do for you. Nothing happens until you apply. What the terminal would have
-printed is shown when it finishes.
+Everyone on the roster, and the things you would otherwise do from a terminal.
+
+**Hiring** starts from a role. With nobody hired the Staff screen opens on the role picker;
+after that it is behind **Hire someone**. The cards are CTO, CMO and Support, each with a line
+on what they do, and **Something else**, which asks for the role's name and a sentence about it.
+A role that is already hired is not offered. Picking one fills in the handle, name and repo
+(`cto`, `cmo`, `support`, or a handle made from the name) and leaves the schedule empty, so the
+server picks a free slot. All four are under **Advanced**, still editable. The first hire has
+nobody to copy App names from, so Advanced also holds the App's name and the shared public
+App's, which are `--app` and `--public-app`, filled in as `<org>-<handle>` and `<org>-robot`.
+The public one only matters when a product repo is public; on private ones the session uses the
+staff member's own App.
+
+The role opens a numbered list on the same screen:
+
+1. **Hire.** One sentence from the plan: the repo it creates and when it runs. **Show details**
+   has the full plan, from the same `buildPlan` and `applyPlan` that `roster hire` runs on the
+   server: every file, every label, the schedule and why, the commits it makes as you in repos
+   that already exist (each peer's `staff.yaml`, `org.yaml`), and whether the new brain joins
+   the credential's org secret. **Hire** asks before it acts.
+2. **Create their GitHub App.** The private App, and the shared public one only when a product
+   repo in `org.yaml` is public (or has no visibility written, which hire treats as public).
+3. **Write their charter.** Three tabs: an AI interview (the default), the matching worked
+   example with your business's name in place of Acme's, and the file itself. A role that
+   matches no example has no template tab.
+4. **Add your agent credential.** Only while none is stored.
+5. **Run once now.**
+
+Steps 2 to 5 say *Hire first* until the hire is done. Each step's Done comes from real data:
+the hire from the staff member appearing in `org.yaml`, the charter from `CHARTER.md` no longer
+being the stub (the same test as doctor's `charter.stub`), the App from its `_APP_ID` secret on
+the brain repo, the credential from the org secret, and the run from a successful daily run.
+After **Hire** the screen reloads the org and stays on the same staff member, on step 2.
+
+A card whose setup is not finished (a stub charter, no App secrets, or no successful run yet)
+shows **Finish setting up**, which opens the same list for them. The App secrets and the run
+are read from GitHub, so offline only the charter counts.
 
 **Writing the charter** is the copy-a-prompt loop below, aimed at `CHARTER.md`. `hire`
 deliberately does not write it, because a generated charter produces exactly the generic agent
-this whole arrangement exists to avoid. So this is the route that was previously `roster brief
-charter <handle>` and a terminal.
+this whole arrangement exists to avoid. It is the same brief as `roster brief charter
+<handle>`, with somewhere to put the answer, and a picker for the worked example it carries as a
+model: matched to the role, or another, or none. For a role added with **Something else**, the
+sentence you typed goes into the brief.
 
 **The GitHub App** is `roster app`, on this server rather than a second one. There is no API that
 creates an App: the only route is the manifest flow, where you post a manifest to a settings page,
@@ -246,9 +355,17 @@ one origin. The private key is still held in memory and written straight to a re
 
 GitHub redirects the tab *it* opened, not the one you clicked from, so the original polls for the
 result. What it cannot do is install the App: that is a grant of access to specific repositories
-and GitHub asks a human to choose them, which is correct and should not be worked around. The panel
-says so loudly, and says to grant every tracker the staff member writes to rather than only their
-own.
+and GitHub asks a person to confirm it, which is correct and should not be worked around. So the
+panel's **Install it** opens the install page with the org and the repos already selected: the
+brain, every peer tracker it writes to, and the product repos. Any whose id could not be read are
+listed for you to tick.
+
+**Agent credential** is the setup screen's paste box, reachable from each card, because the
+moment you look for it is while setting somebody up. It is once for the org.
+
+**Run once now** starts the daily workflow, follows it, and shows how it ended with the log's
+link and, on a failure, the step it failed at. It asks first, because it is a real run. A success
+is what turns doctor's *unproven* into proven. Health has the same button.
 
 **Retiring** is `roster retire`, and it is deliberately not deletion. A brain repo is that
 agent's entire memory and there is no undo, so retiring disables the workflows, unwires them
@@ -264,7 +381,7 @@ already declared `memory/` as a surface.
 The navigator has three boxes, because a parsed memory section and a file on disk are
 different kinds of thing.
 
-**Memory** is the fact sections, the notes behind them, and `INDEX.md` itself. A note is the
+**What they know** is the fact sections, the notes behind them, and `INDEX.md` itself. A note is the
 argument behind one fact, read only when that fact is in play, which is what keeps the index
 cheap enough to read at every boot. Both live here rather than among the files: `INDEX.md` is
 literally what "All facts" renders.
@@ -284,8 +401,8 @@ rather than going nowhere.
 
 ## Prompt
 
-**What this staff member is actually sent**, which was previously only reachable through
-`roster prompt <handle> --kind daily` in a terminal. Composed on the server by the tenant's own
+**What this staff member is actually sent**, the same as `roster prompt <handle> --kind daily`.
+Composed on the server by the tenant's own
 `compose.mjs`, so there is no second implementation to drift.
 
 Pick the kind: `daily` or `mention`. A mention prompt is written for the comment

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
 
@@ -99,6 +99,12 @@ than a hang.
 | `ops.dir` | ops repo directory in the checkout |
 | `staff` | the whole of this staff member's `staff.yaml` |
 | `staff.dir` | where their brain lands in the checkout |
+| `staff.handle`, `staff.name` | their handle (`cto`) and role name (`Chief Technology Officer`) |
+| `staff.brain` | their brain repo, `owner/name` |
+| `staff.bot` | the login they post as on private repos, e.g. `acme-cto[bot]` |
+| `staff.public_bot` | the login they post as on public repos |
+| `staff.public_token_env` | the environment variable holding the public repo token during a run |
+| `staff.status_issue` | the number of their pinned status issue |
 | `staff.product` | **first entry of `works_in`, or null** |
 | `staff.product.repo` | that repo's `owner/name` |
 | `peers` | list of the other staff members |
@@ -108,10 +114,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,39 @@ 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.
+
+**It is off unless you turn it on**, with `review_gate: true` in `org.yaml`. Without it, staff
+are told to leave merging to you, and on Pip they always have, but GitHub does not stop them.
+Most orgs keep product repos private on the Free plan, where GitHub cannot enforce the rule.
+
+With it on, `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.
+
+With it on, `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.
+
+**On GitHub Free, private repos can't have this rule.** GitHub only enforces rulesets and
+branch protection on private repos for paid plans. To use the gate there, make the product repo
+public or move the org to GitHub Team.
+
+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 +139,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,11 +28,13 @@ 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. |
 | `comment_id` | string | `""` | Trigger context. |
+| `trigger` | string | `""` | What started the run: `daily`, `manual`, `follow-on`, `mention` or `peer`. Passed to the prompt. |
+| `max_runs_per_day` | number | `6` | How many `peer` and `follow-on` runs may start in a UTC day. Mentions are never counted. |
 
 ## Secrets
 
@@ -51,23 +53,66 @@ 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
+Before the session job, a small **budget** job. For a `peer` or `follow-on` run it counts this
+brain's runs today with those names in their `run-name`, this one included and skipped ones
+left out. Over `max_runs_per_day`, the session does not start and the issue that woke it gets a
+comment saying so. If the runs cannot be read, the run does not start either: a run held back
+costs a day, and a loop costs a bill. Every other trigger goes straight through.
+
+Then the session:
+
+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.**
+    Then, for a mention, **check the request was answered**: a reply in the thread, or the issue
+    closed. Neither fails the job, so the notice below tells the human.
+    Then, for a daily run that finished and wrote `.roster-run/continue`, **start a follow-on
+    run**: one more daily run with `trigger: follow-on`, which waits for this one to end.
+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 +137,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,14 @@ 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
+max_runs_per_day: 6
 
 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:
@@ -49,7 +50,7 @@ surfaces:
 
 labels:
   owner: [will, cto, cmo]
-  kind: [decision, setup, build, blocked]
+  kind: [decision, review, chore, keep-open, build, blocked]
 ```
 
 ## Identity
@@ -59,6 +60,7 @@ labels:
 | `handle` | yes | Must match `org.yaml`. The composer looks them up by the `org.yaml` one, so a mismatch composes the wrong brain. |
 | `name` | yes | Role name in prose. |
 | `mention` | yes | What wakes them, as in `@cto`. The caller's condition tests for this string. |
+| `icon` | no | The icon the portal shows for them: `code`, `megaphone`, `life-buoy`, `compass`, `brush`, `bug`, `server`, `book-open`, `bar-chart`, `users` or `person`. Unset, it is picked from the role. |
 | `brain` | yes | `owner/name` of this repo. Without it nothing can check secrets, labels or runs. |
 | `status_issue` | yes in practice | Number of the pinned status issue. The prompts reference it, so a run cannot compose without it. `roster hire --apply` writes it. |
 
@@ -70,6 +72,7 @@ labels:
 | `model` | org default | Model id. |
 | `timeout_minutes` | 90 | Ceiling on the daily session. |
 | `mention_timeout_minutes` | 90 | Ceiling on a mention run. |
+| `max_runs_per_day` | 6 | Runs a UTC day that start without a person asking: a peer's ask, or a follow-on to a daily run. Mentions never count. Rendered into the callers, so change it and run `roster upgrade`. |
 
 The three ceilings are separate on purpose. Raising the daily one because sessions have grown
 should not double the budget for a PR amendment. A job killed by a ceiling is reported by
@@ -154,6 +157,30 @@ 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.
 
+Four labels are roster's own and are checked on every tracker whatever this lists:
+
+| Label | Means |
+|---|---|
+| `decision` | An ask for the human to rule on. It carries a default and a date; past the date, the staff member acts on the default and closes it. |
+| `review` | An ask for the human to read or approve something. |
+| `chore` | Something only the human can do: a setting, an account, a key. |
+| `keep-open` | A standing thread. A sweep never closes it. `roster hire` puts it on the status issue. |
+
+Every ask on the human carries exactly one of the first three, which is how the portal sorts
+what needs them. Staff close any issue on their tracker once nothing is left to do on it,
+including the human's requests, with one line saying what closed it.
+
+## `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.