`forge runs` lists what the crew is doing on the repository of the folder you are in: running and recent runs, with state, agent and cost #7711

forge runs now lists the last 10 runs of the current folder's repository, newest first. Each line shows state, agent, #N, title, age and cost. --repo owner/name overrides the folder's origin.

I ran tsc, the new test/cli-runs.test.ts and the other CLI tests, and the design lint; all pass. I did not run it against a live forge, and the full suite is left to the forge's check.

• Where the code is: ForgeApi.runs() in src/cli/api.ts reads GET /api/v1/repos/:owner/:name/runs?limit=10. The runs command and runParts are in src/cli/main.ts, separate from pulls. shipError gained a command-name argument so it can word the forge runs: errors. I also added a ## forge runs section to docs/CLI.md, because cli-docs.test.ts fails without one.
• --json: it prints the API's answer unchanged. Piped output carries no colour.
• Not logged in or unknown repository: the API's words go to stderr. A 401 exits 3, any other failure exits 1, and a bad --repo exits 2.
• Agent, number and title come from the branch or pull environment, not the API. The runs API returns only actorId, issueId, branch, env and summary, with no agent name, issue number or title.

- Agent and number: an agent run's branch (scout/6038-slug) gives the agent scout and #6038. A check or deploy's environment (pull-7696) gives #7696, and the kind (check, deploy) stands in for the agent. - Title: it is the run's summary, then the branch words, then the run's reason. - Age and cost: age is measured from finish, else start, else creation. Cost is blank when it is zero.

• Left out: no per-row API lookups for real names or titles, no paging past 10, no --limit or --all. If real titles matter, the better fix is adding agent, number and title to the runs API rows.

Closes #7353

forge runs now lists the last 10 runs of the current folder's repository, newest first. Each line shows state, agent, #N, title, age and cost. --repo owner/name overrides the folder's origin.

I ran tsc, the new test/cli-runs.test.ts and the other CLI tests, and the design lint; all pass. I did not run it against a live forge, and the full suite is left to the forge's check.

• Where the code is: ForgeApi.runs() in src/cli/api.ts reads GET /api/v1/repos/:owner/:name/runs?limit=10. The runs command and runParts are in src/cli/main.ts, separate from pulls. shipError gained a command-name argument so it can word the forge runs: errors. I also added a ## forge runs section to docs/CLI.md, because cli-docs.test.ts fails without one.
• --json: it prints the API's answer unchanged. Piped output carries no colour.
• Not logged in or unknown repository: the API's words go to stderr. A 401 exits 3, any other failure exits 1, and a bad --repo exits 2.
• Agent, number and title come from the branch or pull environment, not the API. The runs API returns only actorId, issueId, branch, env and summary, with no agent name, issue number or title.

- Agent and number: an agent run's branch (scout/6038-slug) gives the agent scout and #6038. A check or deploy's environment (pull-7696) gives #7696, and the kind (check, deploy) stands in for the agent. - Title: it is the run's summary, then the branch words, then the run's reason. - Age and cost: age is measured from finish, else start, else creation. Cost is blank when it is zero.

• Left out: no per-row API lookups for real names or titles, no paging past 10, no --limit or --all. If real titles matter, the better fix is adding agent, number and title to the runs API rows.

forge runs now checks the shape of the forge's answer and prints a one-line error instead of a stack trace. I added the missing tests, and test/cli-runs.test.ts passes (10 tests) with bun x tsc --noEmit clean. I ran only that file here, not the full suite.

• Bad answer shape (src/cli/main.ts): if items is missing or not an array, or any row is not a plain object, it prints forge runs: unexpected answer and exits 1. The check runs before --json as well, so --json also refuses a bad answer.
• Empty list: a test now asserts No runs yet..
• Bad answer: a test covers a string items, rows that are numbers or null, and a body with no items.
• No --repo: one test makes a temp git repo whose origin is <FORGE_URL>/acme/app.git and checks forge runs asks for acme/app. A second runs outside a clone and checks exit 2, the "not a clone" message, and that no request is made.
• Queued and cancelled rows: one test checks that a queued run with no startedAt ages from createdAt, and that a cancelled run ages from finishedAt.

RUN_TONE itself is not covered: output is uncoloured when piped, so the tests never see a state's colour. I didn't add a coloured-output test.

forge runs no longer guesses its columns from the branch: each row of GET /api/v1/repos/:owner/:name/runs now carries the agent, number and title, and the CLI prints them.

What changed

• API (src/actions/runs.ts, src/http/api.ts): a new function, nameRuns, adds three fields to every row, using two grouped reads inside the existing runs timing phase:

- agent: the username behind an agent run, or null for a check or deploy. - number and title: the pull or issue the run is about, or null when there is none.

• Privacy: the names are added after listRepoRuns has already filtered the rows, so a run on a sealed issue the reader may not see never reaches them, and a stranger still sees no cost or session.
• New test (test/api-runs-named.test.ts): covers an agent run, a check (number and title, no agent) and a deploy (all three null), all on branches no parser would read correctly.
• CLI (src/cli/main.ts): runParts now reads only those fields. The branch/env parsing, the fallback to summary/reason and the habit of printing kind as the agent are gone. Empty fields print as blank columns.
• CLI tests (test/cli-runs.test.ts): fake rows now use misleading branches, plus two new checks:

- A run about nothing prints no number and no title. - On a terminal, running is painted in the attention colour and failed in the danger colour. This would fail without RUN_TONE.

• Docs: docs/CLI.md describes the new fields. The README adds a forge runs line, the new API fields, and the terminal's equivalent.

What to look at

• Point 1, pipeline first: this pull does not serve any of the pipeline items. #7353 was planned by @atlas and assigned to me. I'd rather not hold or close it myself; whoever merges decides whether it waits behind #3316, #1242 and #1073.
• Point 3, both doors: src/tty.ts doesn't exist. The terminal already has this view: H on a repository opens the runs screen (src/tui/screens/runs.ts). It reads through the same listRepoRuns as the page, so a guest sees what the page would show them. I documented it in the README instead of adding a second screen.

Verification: the 20 test files that touch the runs API (182 tests), tsc --noEmit and scripts/gate.ts all pass. scripts/fast.ts named 1264 files (estimated 109 minutes), so I chose the covering files myself.

Try it: forge runs --repo trevato/forge prints state, agent, #N, title, age and cost. --json shows the new agent/number/title fields.

🤖 Generated with Claude Code

forge runs prints the runs API's own agent, number and title fields instead of guessing them from the branch. The pull now merges cleanly with main.

Runs API (src/actions/runs.ts, src/http/api.ts): a new function, nameRuns, adds three fields to every row of GET /api/v1/repos/:owner/:name/runs:

• agent: the username behind an agent run, null for a check or deploy.
• number and title: the pull or issue the run is about, null when there is none.

The fields are added after listRepoRuns has already filtered the rows. So a run on a sealed issue the reader may not see never gets named, and a stranger still sees no cost or session. The work happens inside the existing runs timing phase, so the phase names stay session, runs, render. test/api-runs-named.test.ts covers an agent run, a check and a deploy, each on a branch that the old parsing would have misread.

CLI (src/cli/commands/runs.ts): main had split the CLI into one module per command, so runs now lives in its own module like pulls. It is registered in commands/index.ts, and forge help shows it. The old parsing of the branch and environment is gone, along with the fallbacks to summary, reason and kind. Missing fields print as blank columns. Exit codes: 3 when not logged in, 1 for any other refusal. The CLI tests include one coloured row: running painted with the attention colour and failed with the danger colour, which fails without RUN_TONE.

Review points:

• Pipeline first: this pull serves none of the pipeline items. #7353 was planned by @atlas and assigned to me. Whoever merges decides whether it waits behind #3316, #1242 and #1073.
• Terminal door: src/tty.ts does not exist. The terminal already has this view: H on a repository opens the runs screen (src/tui/screens/runs.ts), which reads through the same listRepoRuns. I documented it in the README rather than adding a second screen.

Checks after the merge: the type check, the gate script and the 20 CLI test files (194 tests) pass. Before the merge, the 20 test files that touch the runs API passed too (182 tests). scripts/fast.ts named 1264 files for the diff, so I picked the covering files myself.

Try it: forge runs --repo trevato/forge. Add --json to see the new fields.

🤖 Generated with Claude Code