guide.md

# thirdshift

Read this manual [on thirdshift.app](https://thirdshift.app/docs/) or return to the [brief README](../README.md).

A factory that turns a GitHub issue into a ready-for-review pull request, or on request a merged one, by running unattended agent sessions against it. The humans are the day shift; the agents work the third shift, overnight, on any server, while you do something else.

Quality over quantity: a pull request marked ready for review is one the factory stands behind. When it can't stand behind the work, the **Ticket run** is a **Failed ticket run**: the work is pushed so nothing is lost, and the pull request goes back to a draft.

Terms in **bold** are defined in [`GLOSSARY.md`](../GLOSSARY.md).

## Workflows

A [Ticket run](#what-a-ticket-run-does), one issue in and one pull request out, is the factory's first workflow. It can leave its pull request for review or Self-merge it when asked with `thirdshift merge <Issue URL>` (see [Usage](#usage)). Other workflows handle larger plans, discovery, investigation and measurement:

- **[Spec run](#spec-runs)**, `thirdshift <Issue URL>` on an issue with sub-issues: works through its **Tickets** in dependency order, each merged into a **Spec branch**, then leaves one **Spec PR** ready for review.
- **[Architect run](#architect-runs)**, `thirdshift architect`: reviews the codebase's architecture, publishes a plan for its top Strong recommendation and builds it, or leaves an **Architect idea** for the **Day shift**.
- **[Pickup run](#pickup-runs)**, `thirdshift pickup`: takes the lowest-numbered **Ready issue** by default, the highest-numbered with `pickup.order = "highest-first"` or `highest-first` on the command, and runs it.
- **[Security run](#security-runs)**, `thirdshift secure`: audits the **Base branch** and records each **Security finding** privately. It is report-only by default; with fixing allowed, it fixes one finding it reproduced.
- **[Review run](#review-runs)**, `thirdshift review <PR URL>`: reviews an existing pull request, addresses its Standards and Spec findings and posts one comment. Add `--recommend-only` to get findings without fixes.
- **[Fix run](#fix-runs)**, `thirdshift fix [<PR URL or number>]`: takes an existing pull request through Delivery and the Repair loop against its own Base branch, without repeating implementation or initial code review. With no target, a Pass first checks Base branch CI unless scoped by author, then selects the lowest-numbered eligible non-draft PR with a Merge conflict or CI red.
- **[Triage run](#triage-runs)**, `thirdshift triage`: investigates a **Report** and files shaped issues, or recommends them with `--recommend-only`.

Architect, Pickup and Security runs, `review --author <login>`, and `fix` with no PR target are **Passes**, as is a Custom process started with no issue and no Issue-branch worktree: they take no Issue URL, so your operating system's scheduler can start them. A Custom process started with an issue is not a Pass. A file that declares an Issue-branch worktree is refused when no issue is given, before any session, rather than skipped. See [A Pickup run on a schedule](#a-pickup-run-on-a-schedule), [Architect runs every few minutes](#architect-runs-every-few-minutes) for Architect runs, and [Security runs on a schedule, with fixing allowed](#security-runs-on-a-schedule-with-fixing-allowed) for Security runs.

Every session runs on the **Harness** you choose: Claude Code by default, or Codex, Antigravity CLI, Grok Build, Muse Code, OpenCode or Kimi Code. See [Harness, Model and Effort](#harness-model-and-effort).

## What a Ticket run does

<a name="what-a-run-does" id="what-a-run-does"></a>

From a clone of the issue's repository, `thirdshift <Issue URL>`:

1. Checks that the Ticket run makes sense, before creating anything:
   - the **Origin match**: the **Issue URL** must belong to the same GitHub repository as the `origin` remote of the directory you run it from, and a mismatch says to start it from a clone of the issue's repository instead;
   - the issue is open;
   - the **Base branch** is well defined: HEAD is not detached, the branch exists on `origin`, and your local copy is not ahead of it, so unpushed commits can't leak into the pull request;
   - a local Issue branch, if you have one, points at the same commit as its copy on `origin`, so local-only commits are never destroyed.

   Any failed check stops the Ticket run before any work happens.
2. Picks the **Issue branch** (`issue-<n>`, or `issue-<n>-branch-<k>` once earlier ones are finished) and the **Base branch**, normally the branch you have checked out. Then it makes the [Claim](#the-claim): it labels the issue `in-progress`, in place of `ready-for-agent` if it has that.
3. Creates a git worktree next to your clone, named `<repo>-<Issue branch>`, so your own checkout is never touched.
4. Runs a headless agent session in that worktree on the **Harness**, Claude Code unless you [choose another](#harness-model-and-effort), with the **Factory skills** in [`skills/`](../skills) linked into its `.claude/skills/`, or `.agents/skills/` on the other Harnesses, as `thirdshift-<skill>` and kept out of git by a `.git/info/exclude` entry ([ADR-0012](adr/0012-factory-skills-linked-into-the-worktree-codex-unsandboxed.md)), started with one of the **Session prompts** in [`prompts/`](../prompts). The agent implements the issue, reviews its work against the Base branch, addresses the **Standards findings** and **Spec findings** it agrees with, and opens a ready-for-review pull request that lists every **Unaddressed finding** with a reason and closes the issue. With a [Security review](#security-review) asked for, a second session then reviews the change for vulnerabilities.
5. Takes over deterministically: pushes the Issue branch, skipping your repo's git hooks since the session runs the tests and CI gates the pull request, checks through `gh` that the pull request exists, is open and targets the Base branch, and marks it ready for review (`gh pr ready`) if the agent left it as a draft.
6. Keeps the pull request mergeable and green: merges the Base branch in and watches CI, starting a **Repair** session for a merge conflict or failing checks, at most 5 per Ticket run. A failed check that also failed, under the same name, on the Base branch commit the head last merged in is an **Inherited failure**, not the branch's to fix: the CI-fix Repair is given only the branch's own failures, with the Inherited failures listed as not to fix. If every failed check is an Inherited failure, no Repair starts: the Ticket run merges the Base branch again if it has moved since, and otherwise ends as a [Failed ticket run](#failed-ticket-runs) that says to fix the Base branch first, unless it was given `base-fix` or the [User config](#user-config) sets `base.fix`, when it starts a [Base fix](#base-fix) first. A check that is pending, passed or missing on that Base branch commit is the branch's own, and thirdshift never triggers or waits for the Base branch's CI. If a CI-fix Repair leaves the head unchanged, with no commit of its own and no Base branch move to merge, thirdshift does a **Check re-run**, once for that head: it asks GitHub to re-run the branch's own failed checks (`gh run rerun <run-id> --failed`, once per workflow run), says so on stderr as `re-running the failed checks on <short sha>: <check>[, <check>…]`, and watches CI on that head again, from the new attempt on. A check that failed for a reason that does not repeat, such as a flaky test or a runner fault, then passes, and the Ticket run goes on as for any green head. If CI is red again, the Ticket run ends as a Failed ticket run, with no second Repair or re-run for that head. It ends the same way, with nothing re-run, if one of those checks can't be re-run (a commit status, or a check run that is not a GitHub Actions job), since the head could not go green. When GitHub refuses a re-run, stderr shows the refusal and thirdshift reads all checks on that head again: a Repair may already have re-run them. Green continues the Ticket run, pending checks are watched, and the branch's own checks still red fail as before, without another Repair or request for that head. Checks that cannot be read or disappear after known failures cannot establish green CI. Any earlier successful workflow request still waits for its new attempt before the whole head is assessed. What the Repair concluded is never read, Inherited failures are never re-run on their own account, and a Check re-run is no Repair, so it counts against no budget ([ADR-0010](adr/0010-one-check-re-run-before-a-declined-ci-fix.md)). Before any Repair, a head whose own failed checks are all **Abandoned jobs**, GitHub Actions jobs GitHub ended as failed with no failed step and a step not completed, as when a runner is lost, has them re-run once, saying `<check> lost its runner on <short sha>; re-running it`, and CI watched again the same way: green goes on, and red again, or a refused or unseen re-run, gets the CI-fix Repair as before. This too is no Repair and counts against no budget ([ADR-0020](adr/0020-an-abandoned-job-is-re-run-before-any-repair.md)). If the Base branch moves while CI runs, it merges it again and goes round, at most 5 times per Ticket run. In a Ticket run that Self-merges, each round also takes in **Foreign commits** first: see [Foreign commits in a Ticket run that Self-merges](#foreign-commits-in-a-ticket-run-that-self-merges).
7. In a **Ticket run** that Self-merges (`thirdshift merge <Issue URL>`), does the **Self-merge**: once the pull request is open, ready for review, mergeable and green, thirdshift merges it into the Base branch with a merge commit, on exactly the head commit whose CI it watched (`gh pr merge --merge --match-head-commit <sha>`). Just before each attempt, it reads the PR's `reviewDecision`: `REVIEW_REQUIRED` or `CHANGES_REQUESTED` ends the Ticket run as **review required**, a policy refusal, without attempting the merge or taking another Repair round. An empty or `APPROVED` decision, or a failed read, keeps the existing merge behavior. It never uses GitHub's auto-merge ([ADR-0004](adr/0004-self-merge-by-thirdshift-not-github-auto-merge.md)). A merge that fails goes back round step 6, within the same budgets, and is tried again on the new green head. If that round finds nothing to fix, the refusal is a **policy refusal**, such as merge commits being disallowed or a review being required. After the merge, thirdshift deletes the Issue branch on `origin`, and closes the issue if it is still open, with the comment `Closed by #<pr>, merged into <base> by a thirdshift Ticket run with Self-merge.` GitHub closes it on its own only for a merge into the repository's default branch, and then thirdshift leaves it alone. Once the issue is closed, either way, thirdshift takes `in-progress` off it, [removing the Claim](#when-the-claim-ends).
8. Cleans up: removes the worktree, the local Issue branch and the temporary directory the Factory skills were written out to, whether the Ticket run succeeded or not. The one exception is a **Failed ticket run** whose work could not be pushed: see below.

### Worktree ownership and cleanup

A factory-owned checkout, on an **Issue branch** for a **Ticket run** or detached for an **Architecture review**.

Acquisition accounts for partial local effects: failed-acquisition recovery rechecks clean-only, instance-specific authority before and after every destructive attempt, including retries, advances only on verified transitions, and retains and names remaining work or uncertain partial effects. Failed-acquisition retention survives later Architecture review attempts.

Successful acquisition carries checkout and registration identity through its lifetime; ordinary synchronization, observations and Failed ticket run preservation share acquired-instance checks before and after every Git subprocess attempt, including retries, acting only on that acquired checkout and selected Issue branch and refusing changed or uncertain ownership. Failed ticket run preservation retains work when ownership has changed or is uncertain and finishes after Command interruption without clearing it; ordinary synchronization remains interruptible. Confirmed Self-merge branch deletion uses the captured Launch repository independently of checkout validity.

Cleanup checks stage-specific disposal authority before and after every destructive Git attempt, including retries: acquired identity and the captured cleanup head for checkout removal, removed-path absence and an unused expected head for local branch removal, then ref absence and the exact original local subsection for branch configuration removal. Only successful, verified transitions advance disposal; partial failures retain and name every remaining or uncertain resource. Live cleanup finishes after Command interruption without clearing it; stale disposal stays interruptible.

Stale Architecture review scratch is disposable only with evidence of successful detached acquisition and unchanged ownership; unmarked or uncertain checkouts are retained.

See [ADR-0014](adr/0014-successful-review-acquisition-authorizes-stale-disposal.md) for the ownership evidence that authorizes stale review disposal.

### Delivery and pull request identity

What a **Ticket run**, or a **Spec run** for its **Spec PR**, does from its worktree once its work begins. It runs the opening session (the implement session, or the **Spec review**), pushes, marks the pull request ready, keeps it mergeable and green through the **Repair loop**, and, in a **Ticket run** that Self-merges, does the **Self-merge**.

For a Spec PR, Delivery ends Ticket accounting's capture before the Spec review, allowing that session to replace the PR. The first successful observation after the opening session, or during Failed ticket run completion after an opening failure, captures one pull request number and URL in the issue's repository; all later observations and transitions use that identity. Readiness and every mergeability poll validate its expected **Issue branch** and **Base branch**, open state and readiness where required. A missing, closed or retargeted captured PR fails Delivery; a replacement from the same branch is never substituted.

A Delivery that fails takes the **Failed ticket run** path, drafting that same captured open PR after preserving work. Spec PR checklist restoration uses that Delivery capture before readiness and for final accounting after failure.

If a Delivery gate observes that its pull request has already merged into the expected Base branch, and its merged head includes all local work (the exact local head, with no uncommitted changes), the Ticket run ends as merged, even when it originally asked only for ready for review. Delivery stops further publication, PR edits and Self-merge work. A merged PR that leaves local work out still fails and retains that work; a merged state alone never establishes completion.

### Check re-run allowance

A **Check re-run** is allowed once per full head commit across one **Delivery**. The allowance is consumed before the request and stays consumed through green CI, **Inherited failures**, a **Base fix**, upstream moves, later Repair rounds and refused **Self-merge** reconciliation, even after visiting another head and returning.

Later watches still obtain fresh CI facts. If the branch's own checks are red on a head whose allowance has been consumed, the Ticket run ends as a **Declined CI fix** without another CI-fix Repair or Check re-run. A different head has its own allowance, and a separately started **Continuation** begins a new Delivery with fresh allowances. Inherited-only failures keep their usual handling.

The trigger, eligible GitHub Actions checks, refusal handling and CI watching are described in step 6 above and [ADR-0010](adr/0010-one-check-re-run-before-a-declined-ci-fix.md). A Check re-run starts no Repair, counts against no Repair or upstream-move budget, and never re-runs a check for being an Inherited failure.

### The Claim

The **Claim** is the mark that the factory has taken an issue, so the issue list shows what it is working on. When a Ticket run or a [Spec run](#spec-runs) starts on an issue, thirdshift labels the issue `in-progress`, in place of `ready-for-agent` if it has that. An issue with no `ready-for-agent` label still gets `in-progress`, so the label means the same thing however the Ticket run was started.

- It is made once every check of step 1 has passed and the branches are picked, and before the worktree is created. A Ticket run stopped by a check changes no label.
- It is one request, which adds `in-progress`, removes `ready-for-agent` and keeps the issue's other labels, so the swap can't stop halfway. stderr says `labelling #<n> in-progress, in place of ready-for-agent`, or `labelling #<n> in-progress`.
- thirdshift first creates the `in-progress` label if the repository has none.
- It is made however the Ticket run or Spec run was started: by you on an Issue URL, by an [Architect run](#architect-runs) for the plan it dispatches, or by a [Pickup run](#pickup-runs) for the Ready issue it took.
- A Ticket run in a Spec run makes none, since the Spec carries the Claim, and nor does a [Base fix](#base-fix): their issues' labels are left as they are.
- A [Continuation](#continuation) on an issue that is already `in-progress` changes nothing and makes no request. One on an issue that isn't Claimed yet Claims it.
- If the Claim can't be made, the Ticket run stops there, before any work, with exit `1` and the cause: `could not make the Claim on #<n>: <gh's error>`.

#### When the Claim ends

`in-progress` marks only a live Run ([ADR 0029](adr/0029-in-progress-marks-only-a-live-run.md)): it comes off when the Ticket run or the Spec run ends, and how it ended decides what, if anything, takes its place:

- **Released**, except for a failed Security fix, when it fails with nothing on `origin` to take over: no Issue branch for the issue there and no pull request from one, open, merged or closed, or for a Spec run, no Spec branch and no Spec PR. That is a session that fails before it changes anything, as on a usage limit or an expired login, a Ctrl-C before any work, or a worktree that can't be created, on an issue that was never started before. A retry that fails that way on an issue an earlier Ticket run left an Issue branch or a pull request for is labelled `agent-failed` instead, as below. The issue's labels go back as they were before the Claim: `in-progress` comes off, and `ready-for-agent` goes back if the issue had it, and only then. So an outage costs a retry and doesn't strand the issue. stderr says `releasing the Claim on #<n>: labelling it ready-for-agent, in place of in-progress`, or `releasing the Claim on #<n>: removing in-progress`. A Failed ticket run whose push failed is released too, since nothing of it reached `origin`: its work is only in the worktree it kept, which stops the next Ticket run on that machine at the pre-flight checks until you push or delete the local Issue branch.
- **Swapped for `agent-failed`** when a [Failed ticket run](#failed-ticket-runs) or Failed spec run pushed its Issue branch or left a pull request, and whenever a Security fix fails, even with nothing on `origin`. One request takes `in-progress` off and puts `agent-failed` on, keeping the issue's other labels, after `labelling #<n> agent-failed, in place of in-progress, so it waits for the Day shift` on stderr; an issue already labelled `agent-failed` only loses `in-progress`. The failure waits for you, and the [Failure limit](#the-failure-limit) counts it. A Run interrupted without a [Stop](#stopping-a-command) ends this way too. Making a Claim takes `agent-failed` off. It then posts its [Recovery comment](#the-recovery-comment) on the issue, except for a failed Security fix.
- **Handed back** when a [Spec run](#spec-runs), or a [Custom process](#custom-processes) whose `land-tickets` Step failed, ends only waiting, unless it is a Security fix, which is swapped for `agent-failed` as above, with no comment: no Ticket failed or was interrupted, and every Ticket not done waits on you or on other work. One request takes `in-progress` off and puts `ready-for-agent` back, with no `agent-failed`, after `labelling #<n> ready-for-agent, in place of in-progress: its Spec run is only waiting` on stderr, so a [Pickup run](#pickup-runs) continues the Spec once one of its Tickets can start. Before putting it back, thirdshift checks the Spec's title and body: if an account that is not a Trusted account edited either since the Spec's last `ready-for-agent` labelling by a Trusted account, the Spec is labelled `needs-triage` instead, and stderr names the edited part. A Spec that had no `ready-for-agent` when its Claim was made, as one you started by hand without labelling it, gets none: only `in-progress` comes off. Either way, it then posts a comment on the Spec, opening `This comment was generated by AI.`, with a line on each Ticket not done and what it waits on, such as `- #24 (labelled needs-triage)` or `- #22 (blocked by #21)`.
- **Removed**, with nothing put back, when the pull request is ready for review, or a policy, security or merge hold kept a Self-merge from merging and left its pull request ready: `in-progress` comes off, after `removing in-progress from issue #<n>` on stderr. The open pull request stands for the work, and the issue has no `ready-for-agent`, so no [Pickup run](#pickup-runs) takes it again. In a Ticket run that Self-merges, `in-progress` comes off once the Self-merge has left the issue closed, whether thirdshift closed it or GitHub did. An issue still open after its merge, because closing it failed, keeps `in-progress` until it is closed, so the finish it still owes stays visible.

A release undoes only what the Claim changed, in one request that keeps the issue's other labels, any added during the Ticket run included. An issue that was already `in-progress` when the Ticket run started stays `in-progress`, with `ready-for-agent` back if the Claim took it off (`releasing the Claim on #<n>: labelling it ready-for-agent again`), and one whose `in-progress` someone took off during the Ticket run is left as it is. A Claim that can't be released, removed or swapped for `agent-failed` doesn't change how the Ticket run ends: stderr gets a `warning:` line naming the command to run by hand, and each of these label edits is tried once more if it failed after Ctrl-C.

A process killed outright, with `kill -9` or by a power cut, releases nothing: the issue stays `in-progress` for you to relabel.

An issue closed some other way, as when you merge its pull request by hand, keeps `in-progress` until a [Pickup run](#pickup-runs) takes it off, in the [Sweep](#the-sweep).

### Status

The designed behaviour described in this manual is implemented. Known gaps and planned work are tracked in the [open issues](https://github.com/JacobStephens2/thirdshift/issues).

## Machine status

Every Console page's tab title names the serving host. The Inbox keeps its Needs you count beside the host, including through live updates.

### Other local accounts

By default, the Console and `thirdshift status` show only the serving OS account's Commands. Set `other_accounts = "readable"` under `[console]` in the User config to include other local accounts whose logs can be read, or use `other_accounts = ["conductor", "operator"]` to consider only named accounts. `"none"` is the default.

```sh
thirdshift console other-accounts readable
thirdshift console other-accounts conductor,operator
thirdshift console other-accounts --json # show the saved setting
thirdshift console other-accounts none
```

Setup also asks for this setting when configuring the Console. Discovery uses the passwd database's home directory and the account's readable User config `logs.dir` override, expanding `~` against that account's home. That directory is used only when its canonical path stays inside the account's home, and a file is read only when its canonical path stays under the directory. `show` and the Console print a Process's Steps from its Command log, and for an Other-account Command they read that log only when its canonical path stays under the directory. An Other-account Command's Session trace is read only when its log records and its spans are regular files whose canonical paths stay inside the directory that holds that Command record. The machine owner grants directory traversal and log read access using filesystem permissions or ACLs; thirdshift never grants access or asks for privilege. Grant access only to the logs you intend to expose, since they can contain sensitive work. Unreadable accounts are silently skipped in `readable` mode. For a named list, `status` reports each unavailable account once on stderr; the page stays quiet.

Other-account Commands carry their OS account name in every Inbox section (including Needs you), Lanes, Stages, History, Security, logs, Waterfall and Command details. JSON adds `account` only to other-account observations. Their Needs you rows count in the tab title. Stop, Requeue, Dismiss and Undo are unavailable for them, and the corresponding CLI requests refuse with the owning account's name. Reading never changes another account's logs, Activity log or repositories. The serving account's own Commands keep their existing controls.

### Inbox

`thirdshift status` names this host and shows the **Inbox** across every repository in the selected log sources and every live [Fleet](#fleet) entry. It counts active runs across those machines, such as `2 active runs`, with a per-machine breakdown. Each owning machine supplies its rows' groups; the caller does not regroup them. The count takes each Command with live work anywhere in it once, whatever its group: a Spec run with two parallel Tickets is one, and a Pass with the Spec run or Ticket run it dispatched, their Tickets and any Base fix, is one. A live child still counts when its outer record has ended or died; ended, died, ready and skipped work counts none. The Inbox groups come in this order:

- **Needs you:** live Silent Ticket runs, then Slow Ticket runs, then ended problems newest first: Died, Failed, Paused (a plan-limit stop), Triage (a Stop without requeue), or a Security finding waiting on a decision. An ended problem leaves when a later Command on the same issue starts on this machine, or when GitHub shows its issue closed or its pull request merged. A Triage row also leaves once its issue loses `needs-triage`; Resolved counts from the first read showing the label gone. Architect and Security runs use the issue and pull request of the Spec run or Ticket run they dispatched. A failed Ticket run whose pull request closed unmerged stays while its issue is open. Live Silent and Slow rows stay until their Commands end, whatever GitHub shows. A row GitHub can speak for no longer ages out; rows with no issue or pull request, no Command record, no read yet or nothing GitHub can find still age out after `inbox.days` (7 by default), straight to History. Reopening an issue brings back a row still in Done or Resolved. Dismissals hold across GitHub changes; Undo uses the latest kept facts. Failures with the same nonempty cause collapse into one item with a count; unknown causes stay separate.
- **Ready for review:** Commands that ended ready, with a pull request. One leaves when a later Command on the same issue starts on this machine, or when GitHub shows its pull request merged or closed; a pull request GitHub still shows as open keeps its row however old it is. A row GitHub can't speak for still leaves after `inbox.days`: one with no pull request, one with no Command record, one not read yet, or one whose pull request GitHub can't resolve. A merged pull request takes its row to Resolved for `inbox.days` from the merge time (a closed one from the close time); a pull request reopened while its row is in Done or Resolved brings the row back. From History on, a row keeps what GitHub last showed and its issue and pull request aren't read again. The Console reads ready rows' pull requests and Needs you rows' issues and pull requests in a batched query in the background once a minute, even with no pages open, and keeps the answer in one file on the machine. Changed answers wake open Inbox pages; unchanged reads leave pages idle. `status` uses the same answer while it is under 5 minutes old, and otherwise reads GitHub itself. Neither timing is a User config setting. The reads never write to GitHub. `status --json` gives each row what GitHub last showed and when, and how old the Inbox's answer is.
- **Landing:** live Ticket runs at CI watch or Self-merge. A Command already in Needs you has a reference here instead of a second row.
- **Working:** every other live Command.
- **Done:** Commands that ended in the last day with nothing waiting.
- **Resolved:** older completions with nothing waiting, back to `inbox.days` after they ended, after the later Command started for a row one took up, after GitHub shows its issue closed, its pull request merged (or closed for a ready row), or its triage label removed, or after the dismissal for a dismissed row. A row that ages out of Needs you goes straight to History. Any row in Needs you or Ready for review, live ones included, leaves on a [Dismissal](#dismissing-a-row).

When GitHub cannot answer, each row keeps the group its last facts give it; a row never read goes by age. Once the last good read is more than 5 minutes old, `status` and the Console warn with when GitHub last answered and why the latest read failed. Before the first good read, the warning says GitHub has not answered yet. A successful read clears the failure warning. `status --json` carries `github_last_answered_at` (an RFC 3339 time, or null before the first answer) and `github_failure` (the latest read failure, or null after success), alongside `github_answer_age_seconds`.

The Console's Ready for review subjects link to the recorded pull request and display its title, including Review runs without an issue. The existing batched GitHub refresh supplies titles for older records too, and title changes update open pages. Older caches or unavailable titles keep the PR link with **(title unavailable)**; failed reads retain the last title. Without a PR, rows use their issue subject and title, or the Command subject when neither exists. Activating the subject link opens GitHub directly without opening Command details.

Ready for review rows show the pull request's latest head CI as **CI green**, **CI red**, **CI pending**, **No CI checks** or **CI unknown**, with text as well as colour. The same batched GitHub read refreshes CI; an older Command's ready outcome does not imply its pull request is still green. `status` shows the same label, and `status --json` includes `github_ci` (`green`, `red`, `pending`, `no_checks` or `unknown`) when the pull request has been read. Older saved answers and unread pull requests show CI unknown. Failed reads retain the last CI answer with the Inbox's existing freshness warning.

A conflicting pull request also shows a separate **Merge conflict** pill beside CI, even when CI is green. It stays in Ready for review. The same GitHub read refreshes mergeability and wakes open pages when it changes; `status` prints **Merge conflict** too. `status --json` includes `github_mergeable` (`mergeable`, `conflicting` or `unknown`). Only `conflicting` shows the pill; unknown and older saved answers do not claim a conflict. Failed reads retain the last answer with the same freshness warning.

Ready for review rows with a pull request and either **CI red** or **Merge conflict** offer **Start Fix run** when the owning machine currently permits `run` and knows a Launch directory for that repository. Review the pull request, repository and owning machine, then confirm to start a [Fix run](#fix-runs) there. Cancel or Escape starts nothing. Omitted options use that machine's User config and CLI defaults; the earlier Command's options are not replayed. Other-account Commands stay read-only. The row and Command details (Peek) also retain `thirdshift fix <PR URL>` with **Copy fix command**; copy it and run it from a clone of that repository. A later Command on the same pull request URL takes up the earlier waiting row in Ready for review or Needs you, just as one on the same issue does, including when neither Command has a linked issue. The row says `taken up by a later Command started at <time>`, and retention counts from that later start.

Each row with a kept answer also carries `github`: `subjects` maps its own or dispatched issue and pull request URLs to their `facts` and RFC 3339 `answered_at`. An unresolved URL has null facts; an older cache without an observation time has null `answered_at`. Finding rows include `github.findings` with per-URL waiting flags, the first observed `triaged_at`, and `answered_at`, without private write-ups. History freezes these observation times with its facts. The existing `github_state` and `github_at` fields still describe the row's own pull request and its merge or close event.

The Inbox leaves the last of GitHub's quota to the factory. Both the Console and `status` skip their GitHub reads while the last observation showed fewer than 500 GraphQL points or 500 REST requests remaining, until that quota's reset time. The warning says which quota is low, how much remains and when it resets, even while the kept answer is fresh. Neither the reserve nor the 5-minute warning threshold is a User config setting.

A row a later Command took up says so wherever it goes: `status` prints `left needs you: taken up by a later Command started at <time>` (or `left ready for review: …`), `status --json` carries `left_from`, `left_reason` and `left_at`, and the Console shows the same line on the row. A row GitHub moved out of Ready for review says `left ready for review: pull request merged at <time>` (or `pull request closed at <time>`); a Needs you row says `left needs you: issue closed at <time>`, `pull request merged at <time>` or `needs-triage removed at <time>`. `status` batches these rows' issues and pull requests in the same read. A dismissed row says so the same way: `status` prints `dismissed by <who> from the CLI at <time>`, `status --json` carries `dismissal` with `who`, `dismissed_at`, `source`, `kind` and all covered `kinds`, and the Console shows the same line on the row. A Command that never waited still goes by when it ended.

`--all` adds **History** for everything older or without a known ending. Each row read from a Command record has a state word: its Needs you kind (`Silent`, `Slow`, `Died`, `Failed`, `Paused`, `Triage` or `Finding`), `Stopping` while a live Command given a Stop is still ending, `Ready` in Ready for review, `Landing` in Landing, and otherwise `live`, `ended` or `died`. The Console shows the same word. Rows read from Activity logs or Session traces show their start, end and outcome instead; only the Console gives them a word, such as `Ready`. After the word come its issue and title when present, Harness, Model, Effort, current stage and its age. Architect runs, Pickup runs and Security runs nest the Ticket runs or Spec runs they dispatch beneath themselves, each Spec's Tickets and their Ticket runs, and each Ticket run's Base fix. Every Ticket is listed: running, merged into the Spec branch, failed, waiting on named blockers, or not started. A Pass with no issue is named by its kind and Command log stamp, such as `architect-20261018T120000-0400` or `secure-20261018T120000-0400`. A Command or child Ticket run with no outcome whose process has gone shows as `died at <stage>`; its start time bounds how long it stays in Needs you when no ending is known. Linux process start identifiers distinguish a reused process id. Records remain beside their Command logs, as `*.command.json`, with child records named for their issue as `*.issue-<n>.child.json`. Each process writes only its own files, replacing them atomically. A record write failure warns once per recording process and does not change its outcome.

History uses each source only for Commands missing from the preceding sources: Command records, then Activity log start/end lines with their Command logs, then Session traces in the current `<logs.dir>/<owner>/<repo>/commands/<kind>/` layout. Activity entries have start and end times and outcomes, with no stages. Session entries group logs by issue and exact Command owner; they have no known end or outcome and appear only with `--all`. A Spec run or Pass's Sessions share that Command's stamp and owner token. Legacy tokenless logs retain their existing grouping. The flat layout from before [ADR 0011](adr/0011-thirdshift-keeps-a-per-repository-activity-log.md) is ignored.

For each repository and kind of Pass whose latest Activity log line is a skip, status also shows that Pass as idle with its reason, even when the skip is older than another kind's activity. A later start or end for that kind clears its idle entry. For example:

```text
Architect run idle on acme/widgets: Ready issue #7 "Make widgets" goes first: https://github.com/acme/widgets/issues/7
```

`status` and the Console Inbox also show `Pickup last fired <age> ago on <owner>/<repo>` (and the equivalent for Architect and Security), even when repeated Passes skip for the same reason. Every Pass saves its start once its repository is known, before launch checks and the Command limit, in `<logs.dir>/<owner>/<repo>/<pickup|architect|secure|review|fix|triage>.last-fired`. This replaces the previous time without adding Activity log lines. A repository with no saved start has no last-fired entry; older Activity log times are not used as evidence that the scheduler recently fired.

When no Commands are running, each bullet in the Inbox's **Last recorded skipped Passes** and **Last fired Passes** starts with its recorded date and time. A skipped reason uses its Activity log time, which repeated skips do not advance; a last-fired entry uses the saved Pass start and keeps its relative age. An unreadable skip time shows **Time unknown**.

`thirdshift cronjobs` and the Console's Cron jobs page group this account's thirdshift crontab entries alphabetically by full `owner/repo`, preserving crontab order and duplicate jobs within each group. A literal `cd <directory> && ... thirdshift ...` command is associated through that directory's GitHub `origin` remote on the owning machine, using the same quoted and home paths as Launch directory discovery. Unresolved entries stay visible in a trailing **Other** group. Cron command text is never executed. The page gives each group its own terminal-style block, with **Run Passes now** and **Last fired by repository** kept separately below.

`cronjobs --json` and `/api/v1/cronjobs` retain the object with a flat `jobs` array in group order (each entry's `schedule`, `command`, nullable `repository` and nullable `command_kind`) and independent `pass_starts`. Command kinds are recognized conservatively from literal CLI arguments; unknown or shell-dependent invocations remain visible. A selected Fleet machine supplies its own repository associations; older inventories without that metadata display under **Other**. The starts include manually launched Passes and other schedulers; they do not prove a particular cron entry fired. Both this inventory and `status --json` expose `pass_starts` entries with `repository`, `kind`, RFC 3339 `last_fired_at` and nonnegative `age_seconds`.

Choose **Fleet schedules** on Cron jobs (`/cronjobs?fleet=true`), or run `thirdshift cronjobs --fleet [--json]`, to inspect this account's configured schedules on every Fleet machine. The overview groups repositories alphabetically, then machines, with **Other** last; it keeps each machine's entry order and duplicate jobs. Each entry shows its machine, recognized Command kind (or **Unknown Command kind**), original schedule and command. Repository metadata comes from the owning machine; remote checkout paths are never resolved locally. Schedules retain their owning cron time zones without conversion.

The Fleet result's `repositories` contain `repository` and `machines` (each with `name` and `jobs`); its separate `machines` inventory lists `name`, Console `address`, `status` and nullable `error`. Successful empty inventories say so. Unavailable, refused, incompatible and link-only machines stay visible alongside healthy results. Link-only entries receive no requests. The overview inspects configured schedules only; use each machine's local view for separate **Run Passes now** controls and **Last fired** observations. Reads use the owning machine's effective `read` authorization and forward the signed-in person; CLI reads use the token holder. `/api/v1/cronjobs` stays local and refuses Fleet or remote-machine selection, so API callers cannot borrow saved Fleet credentials.

`thirdshift status --json` is the versioned API for agents. It runs outside a repository too. Version 2 adds each Command's `machine` (the owning machine's hostname) and `machine_name` (its Fleet entry name, or the local hostname), including nested and collapsed Commands, and a `machines` section. The Command's recorded `hostname` remains unchanged. The Console combines those same Fleet groups in its Inbox. Its `/api/v1/status` is the twin of `status --local --json`, which reads only this machine and never traverses its Fleet. Version 2 has this shape:

```json
{
  "version": 2,
  "hostname": "factory",
  "active_runs": 1,
  "machines": [{
    "name": "factory",
    "hostname": "factory",
    "fetched_at": "2026-10-18T12:00:53-04:00",
    "reachability": "ok",
    "active_runs": 1,
    "error": null
  }],
  "commands": [{
    "machine": "factory",
    "machine_name": "factory",
    "version": 2,
    "kind": "Run",
    "repository": "acme/widgets",
    "name": "acme/widgets#7",
    "issue": {"number": 7, "url": "https://github.com/acme/widgets/issues/7", "title": "Make widgets"},
    "hostname": "factory",
    "process_id": 1234,
    "process_start": "<OS process start identifier>",
    "harness": "claude",
    "model": "opus",
    "effort": "high",
    "started_at": "2026-10-18T12:00:00-04:00",
    "ended_at": null,
    "stages": [{"name": "implement", "began_at": "2026-10-18T12:00:01-04:00", "session_log": "/logs/acme/widgets/commands/issue/7-20261018T120000-0400~ownerA-implement.logs.jsonl"}],
    "session_log": "/logs/acme/widgets/commands/issue/7-20261018T120000-0400~ownerA-implement.logs.jsonl",
    "issue_branch": "issue-7",
    "pull_request": null,
    "outcome": null,
    "cause": null,
    "source": "command_record",
    "command_log": "/logs/acme/widgets/commands/issue/7-20261018T120000-0400~ownerA.log",
    "dispatched": [],
    "state": "live",
    "group": "working",
    "needs_you_kind": null,
    "landing": false,
    "stopping": false,
    "count": 1,
    "stage": {"name": "implement", "began_at": "2026-10-18T12:00:01-04:00", "age_seconds": 52},
    "parent_record": null,
    "parent_dispatch": null,
    "tickets": [],
    "children": []
  }],
  "pass_starts": [{
    "repository": "acme/widgets",
    "kind": "Pickup run",
    "last_fired_at": "2026-10-18T12:00:00-04:00",
    "age_seconds": 52
  }],
  "idle_passes": [{
    "repository": "acme/widgets",
    "kind": "Pickup run",
    "reason": "no Ready issue on acme/widgets",
    "recorded_at": "2026-10-18T12:00:00"
  }]
}
```

`idle_passes.recorded_at` is the Activity log's machine-local date and time, without an offset, or null when it cannot be parsed. Unlike the instants below, that older format does not retain a time zone.

Times are RFC 3339; ages are nonnegative seconds. `model` and `effort` are null when left to the Harness. `issue` is null for a Pass with no issue; `session_log`, `issue_branch`, `pull_request`, `outcome`, `cause`, `ended_at`, `parent_record` and `parent_dispatch` are nullable. Command kinds are `Run`, `Spec run`, `Architect run`, `Pickup run`, `Security run`, `Triage run` and `Base fix`. Text output and the Console display the stored `Run` kind as **Ticket run**; Command records, the Activity log and JSON retain `Run`, including when reading older records ([ADR 0022](adr/0022-ticket-runs-and-plain-schedules.md)). `name` identifies an issue or a Pass's kind and stamp. `dispatched` is an array of the Ticket runs or Spec runs a Pass dispatched, with the same fields as its parent (and an empty `dispatched` array); it shares the Pass's process identity and Command log. It retains its own outcome, end time, cause, Issue branch and pull request. The retained Command record has the same fields, including dispatched work, without the computed `state`, `stage`, `source`, `command_log` and `children` or empty leaf `dispatched` arrays. Older records without an end time use their last modification time. `active_runs` is the count above, computed from the same observations as `commands`, whatever `--all` asks; the Console shows the same total. `idle_passes` contains one entry per repository and kind whose latest Activity log line is a skip; it is independent of `commands`, and never creates a Command record or log for a skipped Pass.

Each top-level `commands` entry adds the computed `group` (`needs you`, `ready for review`, `landing`, `working`, `done`, `resolved` or `history`), nullable `needs_you_kind` (`silent`, `slow`, `died`, `failed`, `paused`, `triage`, `finding`), `landing` (also true for a Needs you item referenced from Landing), `stopping` (true while a live Command given a [Stop](#stopping-a-command) is still ending), and `count`. A row a later Command took up also carries `left_from` (the waiting group it left), `left_reason` (`taken up by a later Command`) and `left_at` (that Command's start); rows still waiting, that never waited, or that aged out omit all three. With `group` and `needs_you_kind`, `stopping` gives the row's state word shown in text output and the Console; `state` stays the Command's own. A dismissed row also carries `dismissal` with `who`, `dismissed_at`, `source` (`CLI` or `Console`), the current covered `kind`, and all covered `kinds` in dismissal order. While a live row has no problem, `kind` is the last kind dismissed. Rows waiting on an uncovered kind, and rows never dismissed, omit `dismissal`. A collapsed failure has a `collapsed` array containing the other Commands, each with its own group and kind. These fields are observations, absent from durable records and `show`; child Ticket runs remain within their Command. The durable `security_findings_waiting` flag defaults to false for older records.

`state` is `live`, `died`, `ended`, or `unknown` when historical evidence has no ending. `stage` is null before the first known stage. Readers skip unknown stage names. Known stages are `implement`, `Resume`, `Security review`, `pull request`, `CI watch`, `Repair`, `Self-merge`, `cleanup`, `Tickets`, `Spec review`, `Architecture review`, `Triage`, `Security audit`, `Security reproduction`, `Security fix publishing`, `Security close check`, `dispatched Run` and `dispatched Spec run`. A Pass retains its own stages while its dispatched work records its stages separately. A Pickup run or Security run enters `dispatched Run` or `dispatched Spec run` when it dispatches, so its row reads, for example, `dispatched Spec run · 19 hr 46 min`, timed from the dispatch, and `died at dispatched Spec run` if its process goes. A Pickup run's `issue.title` is the one its Ready issue was listed with; older records have null.

`children` recursively contains the immediate child Ticket runs in separate processes, with the same fields as their parent. A Pickup's `dispatched` contains its Ticket run or Spec run. A Spec's `tickets` is its complete roster in issue-number order; each entry has `issue` (`number`, `url`, nullable `title`), `state` (`running`, `merged`, `failed`, `waiting`, or `not started`) and `blockers` (the named open blocking issues, with the same issue fields). Match a Ticket's `issue.url` to the Ticket run in that Spec's `children` for its stage, age, liveness and Base fix descendants. Tickets without a Ticket run remain in the roster. Completed child Ticket runs stay in the tree while its Command is listed. A killed child's `state: "died"` remains independent of the Spec's Ticket accounting. `parent_record` links each child to its parent's exact file; `parent_dispatch`, when present, names the dispatched issue's URL within that file. A top-level Command has null for both. Records from before these fields existed read as having no children or Tickets.

An Experiment or Scoring run stopped at a plan-limit warning or rejection has
outcome `paused`, shown as Paused in Needs you. Its `resume_command` continues
the same work without repeating finished Trials or Scores. Its `limit` object
contains `harness`, `window`, fractional `utilization`, and `resets_at` in RFC
3339; each unknown fact is null. When a reset is reported, the cause, Inbox row
and Command details name the window, utilization and local reset time, and the
Console offers the resume command to copy. Without a reset the cause keeps its
earlier wording. A later Command starting the same Experiment or Scoring work
takes the paused row out of Needs you; Dismissal also works. Pauses count as
neither successes nor failures and send no failure email. Resuming automatically
is separate. Older `failed` records keep their recorded outcome. See the
[checked result contract](experiment-results.md#paused-command-records).

For example, this tree excerpt omits the common Ticket run fields shown above:

```json
{
  "kind": "Pickup run",
  "dispatched": [{
    "kind": "Spec run",
    "stage": {"name": "Tickets", "began_at": "2026-10-18T12:00:01-04:00", "age_seconds": 52},
    "tickets": [
      {"issue": {"number": 21, "url": "https://github.com/acme/widgets/issues/21", "title": null}, "state": "running", "blockers": []},
      {"issue": {"number": 22, "url": "https://github.com/acme/widgets/issues/22", "title": null}, "state": "waiting", "blockers": [{"number": 21, "url": "https://github.com/acme/widgets/issues/21", "title": null}]},
      {"issue": {"number": 23, "url": "https://github.com/acme/widgets/issues/23", "title": null}, "state": "merged", "blockers": []},
      {"issue": {"number": 24, "url": "https://github.com/acme/widgets/issues/24", "title": null}, "state": "not started", "blockers": []}
    ],
    "children": [{
      "kind": "Run",
      "issue": {"number": 21, "url": "https://github.com/acme/widgets/issues/21", "title": "Make widgets"},
      "state": "live",
      "stage": {"name": "implement", "began_at": "2026-10-18T12:00:01-04:00", "age_seconds": 52},
      "children": []
    }]
  }]
}
```
Every entry has `source`: `command_record`, `activity_log` or `session_log`. The latter two carry `repository`, `kind`, nullable `issue` (number, URL, nullable title), `harness`, `model`, `effort`, `started_at`, nullable `ended_at` and `outcome`, nullable `command_log`, `session_logs` (paths), `state`, `stages: []` and `stage: null`. They omit record-only fields such as process identity and branch information. Activity times use the UTC offset in the Command log's stamp; their outcome is the Activity log's full ending text. A Session entry has null Harness, Model, Effort, end time and outcome, and lists its grouped Session traces. Both flags can be combined as `status --all --json`.

## Show and read one Command

Name a Command by `widgets#7`, `acme/widgets#7`, or its full Issue URL. The owner is needed only when repositories on this machine share the name; an ambiguous short name is refused with the matching repositories. When several Commands worked on the issue, the live one wins, otherwise the latest start wins. A Ticket's issue names its Ticket run within the Spec run. A Pass with no issue is named by kind and stamp, such as `architect-20261018T120000-0400`, as listed by `status`.

```sh
thirdshift show 'widgets#7'
thirdshift show https://github.com/acme/widgets/issues/7 --json
thirdshift logs 'widgets#7'
thirdshift logs 'widgets#7' --session implement
thirdshift logs 'widgets#7' --session repair --follow
```

`show` includes the Ticket runs, stage history with start times and Usual ranges, outcomes, and paths to Command logs and Session traces. Each live Ticket run also gets its latest event, such as `Bash: cargo test`, from the last 64 KiB of its current Session trace. It uses the Harness's stream interpretation, including Claude and Codex, and ignores malformed or unknown lines. Missing or unreadable Session traces leave the event unavailable.

`status` and `show` describe live work as **Silent** when neither its Session trace nor its Command log has grown for `inbox.silent_minutes` (10 by default). Silence starts no earlier than the current stage. A dispatch stage is never Silent or Slow and has no Usual range: the dispatched Ticket run or Spec run carries its own. At three times the threshold, the words escalate: `silent 45 min · past 30`. A fresh line in either log keeps the Ticket run from being Silent. Missing logs use the stage's start time.

A stage's **Usual range** is its 25th–75th percentile time over the repository's last 30 Command records on this machine. Completed stages supply times, with the next stage's start or the Command's end marking completion; an unfinished stage supplies none. The range appears once there are at least three stage times. Quartiles interpolate between sorted times. A live Ticket run past the top of the range is **Slow**: `slower than usual (12–17 min), still working`. At twice the top it also shows the multiple, such as `2× usual` or `3× usual`. Silent takes precedence over Slow.

Both JSON views add `health` to recorded Commands: `{"state":"ok"}`, `{"state":"slow","step":1,"usual_range":{"lower_seconds":720.0,"upper_seconds":1020.0},"multiple":1}`, or `{"state":"silent","step":2,"seconds":2700,"threshold_seconds":600}`. Step 1 is the first threshold; step 2 is the escalation. Ended or dead Commands have null health. The `usual_ranges` map gives each stage's current range by name, for example `{"implement":{"lower_seconds":720.0,"upper_seconds":1020.0}}`; a stage is omitted until enough times exist. Health and this map are reader observations.

At completion, each Ticket run, Base fix and Spec run writes `run_metrics` into its own Command record (version 2). Ticket runs retain their own metrics. The field holds `outcome`, `repairs` (the number of Repair stages), `ci_rounds` (CI watch stages), `total_minutes` from launch to completion, and a `stages` array with each stage's `name`, `seconds`, `minutes`, `usual_range` and `position`. Position is `below`, `within`, `above` or `too_few_runs`; the last has a null range. The saved ranges use the same repository history as health, excluding the record being finished. They remain fixed as later Ticket runs finish. `show --json` and Console details include these retained metrics, reconstruct available metrics for past completed Ticket runs, and join confirmed Bug origins at read time, just as `metrics` does. Old records are never rewritten; signals they never recorded remain missing.

`unaddressed_findings` holds separate `standards`, `spec` and `security` counts from the PR body's Unaddressed findings section after Delivery's last Repair. Each list entry under an axis counts once; nested evidence does not. The Security review's deterministic outcome is included without counting its detailed entries twice, even if publishing its summary fails. A body without the section records three zeros; no PR or an older record without this signal shows `null`. If the body cannot be read, a known Security review count is retained with null Standards and Spec counts; with neither source available, the whole signal is null. These counts stay fixed when the Day shift later edits the PR.

### Run metrics and weekly trends

`thirdshift metrics <command> [--json]` reads one Ticket run's metrics, or a Spec run together with its Ticket runs and Base fixes. It accepts the same Command names as `show`. Saved completion metrics stay fixed. For older Command records, metrics are computed when read, without writing back: outcome, Repairs, CI rounds and the stage times the record holds, plus signals from converted Session traces. This also fills Session-trace signals in saved metrics that predate them. Missing completion times, review counts and saved Usual ranges remain missing. Live Ticket runs have no completion metrics yet.

`thirdshift metrics [--json]` reads this machine's Command records across repositories, including child Ticket runs exactly once. It groups Ticket runs by their start week (Monday in UTC), repository, Harness, requested Model and Effort, and kind of Ticket run. Session-stage rows add the kind of session and Harness version from the Session trace's resource, and use that session's own retained Harness, requested Model and Effort when available, so a Security review can differ from its Command. Without retained session setup, ordinary sessions inherit the Command's choices; a Security review's setup remains missing because it may have used another Harness. Ticket run totals have null `session_kind` and `harness_version`, so totals are never repeated for every session or version. Records without completion metrics contribute missing values. It neither reads another machine nor contacts GitHub.

When metrics are read, `confirmed_bug_origins` counts the confirmed Bug origins against the Ticket run whose pull request introduced each bug. The reader uses the Scoring data under `~/.thirdshift/evals/scoring/`, which covers both hosts, and matches only this machine's Ticket runs. A retained local identity selects that exact record path and Command name under the matching pull request; an unavailable or mismatched identity counts for nothing, with no fallback to another Continuation. Absent local attribution and cross-host attribution select the latest local Command, using the same matching and chronological ordering as Scoring (described below). A Continuation sharing the pull request never multiplies the count. A confirmation made after the Ticket run ended still counts in that Ticket run's start week. The latest Scoring window's decision for each bug wins: rejected and unsettled origins count for nothing, and a correction counts against the settled pull request. Counts are computed without contacting GitHub or rewriting Command records; weekly Ticket run totals summarize them separately from other signals.

At completion a Ticket run sums its Session-trace signals by session kind in `session_signals`, with observed and missing session counts. Each originating Session stage also retains its signals and Harness version; later stages referencing that same Session do not count it again. Tokens stay split by observed Model as input (including cache), output, cache read and cache write; an unreported Model is null, never inferred from the requested Model. Cost is in USD only when reported by the Harness, without a price table. Tool errors, permission denials, killed work and repeated tool calls remain separate counters. A repeated call uses the same tool and JSON input as an earlier call in that same session; object key order does not matter. Late permission metadata amends the original call. Missing measurements are null, including cost that a Harness does not report. A missing trace contributes a missing session rather than zero counters. Weekly Session rows summarize each signal independently, with tokens kept by observed Model.

Token counts and cost use the same [Session usage rules as Experiments](#experiments).
Partial authoritative totals refine only reported fields, retaining known input,
cache counts and cost when omitted. Saved completion metrics remain unchanged;
these rules also apply when reconstructing historical Session signals.

Each session's shell commands are also checked against one code-owned pattern list: force pushes, explicit shared-branch history rewrites, and recursive deletes outside the Worktree. Matches appear as `destructive_commands` entries with `pattern` and the original `command` in the Session stage's signals and the Ticket run's per-kind summary. They are advisory and never block or fail a Ticket run. Weekly Session rows summarize the number of flags. Older saved signals without this field show missing evidence. A historical trace without a recorded Worktree directory also shows missing evidence when no matches can be established; known matches are retained. The check matches literal commands; it does not execute shell expansions or resolve filesystem symlinks.

```sh
thirdshift metrics 'widgets#7' --json
thirdshift metrics --from 2026-10-05 --through 2026-10-19 --repo acme/widgets --json
```

`--from` and `--through` select inclusive Monday week-start dates (`YYYY-MM-DD`); omit either for an open end. Repeat `--repo owner/repository` to select several repositories. These filters apply only to trends. Without filters, all recorded weeks and repositories are included.

The version 1 JSON has `version`, `hostname` and either `command` or `weeks`. A Command has its identity, `metrics` and `children`. Each weekly row identifies its group and includes `runs`, separate numeric signal summaries (`observed`, `missing`, `sum`, `mean`), outcome counts, Unaddressed findings by Standards, Spec and Security, and stage summaries. A summary with no observations has null `sum` and `mean`; zero is reserved for an observed zero. Stage summaries keep times, Usual-range bounds, position counts and Standards and Spec review counts separate. Text shows the same signals, spelling null as `missing`. No view combines signals into a score.

`show --json` is a versioned API, usable outside a repository.

When a local GitHub answer exists, the Command also includes the kept `github_state`, `github_ci`, `github_mergeable` and `github_at` fields for its pull request, and `github` with cached issue/pull request facts and their `answered_at` observation times. Fields without an answer are omitted. History uses its frozen observation. `show` reads this cache even when stale and makes no GitHub request.

Version 1 wraps the selected Command in this shape:

```json
{
  "version": 1,
  "hostname": "factory",
  "command": {
    "version": 2,
    "kind": "Run",
    "repository": "acme/widgets",
    "name": "acme/widgets#7",
    "state": "live",
    "latest_event": "Bash: cargo test",
    "stages": [{"name": "implement", "began_at": "2026-10-18T12:00:01-04:00", "session_log": "/logs/acme/widgets/commands/issue/7-20261018T120000-0400~ownerA-implement.logs.jsonl"}],
    "command_log": "/logs/acme/widgets/commands/issue/7-20261018T120000-0400~ownerA.log",
    "session_log": "/logs/acme/widgets/commands/issue/7-20261018T120000-0400~ownerA-implement.logs.jsonl",
    "session_logs": ["/logs/acme/widgets/commands/issue/7-20261018T120000-0400~ownerA-implement.logs.jsonl"],
    "children": [],
    "dispatched": []
  }
}
```

The Command excerpt omits the common fields documented for `status --json`; all those fields are retained, including process identity, issue, Harness, Model, Effort and nullable outcome. `children` and `dispatched` retain the same recursive shape. `session_logs` lists the selected Ticket run's Session trace paths, including original sessions and Resumes that share a stage. `latest_event` is optional, present only when a live Ticket run has a readable event, including in child Ticket runs. History without a Command record uses the same Activity-log or Session-trace shape as `status --all --json`, with Session traces discovered by issue/kind and exact Command owner, without invented stages or liveness.

`logs` writes the Command log verbatim. `--session <kind>` writes that kind's latest Session trace as raw JSON lines; `implement` and `spec-review` include a later Resume, and `repair` selects the latest numbered Repair. A missing log or session kind gives an error. `--follow` first prints the selected log, then flushes appended bytes until the captured outer Command process exits, including output written after its outcome was recorded. A Ticket shares its Command's Command log but selects its own Session traces. The selected Command and Session trace stay fixed while following. Exact-file following (`logs --file <id> --follow`) and the Console also drain through writer exit; an exact Session trace becomes complete when its owning record names a later Session. Retained files without a captured writer are finite. Each exact-file or Console read first checks that the selected file is still in the log inventory: removing it, or replacing its owner, repository or kind folder or the file itself with a symlink, ends the read with an error. Following by Command is unaffected. The CLI emits raw bytes; the Console holds an unfinished live line until its newline arrives or the selected file is complete.

## Install

```sh
curl -LsSf https://github.com/JacobStephens2/thirdshift/releases/latest/download/thirdshift-installer.sh | sh
```

The shorter `curl -fsSL https://thirdshift.app/install.sh | sh`, shown on [thirdshift.app](https://thirdshift.app), redirects to the same installer. The shell installer and the binary both come from this repository's [GitHub Releases](https://github.com/JacobStephens2/thirdshift/releases). It puts `thirdshift` in `~/.local/bin`, where Claude Code's installer puts `claude`, and needs no Rust toolchain.

thirdshift is a statically linked Rust binary with the Factory skills compiled in. Unlike an interpreted script, it needs neither a language runtime nor a checkout of thirdshift on the target machine ([ADR-0001](adr/0001-rust-binary-with-embedded-skills.md), [ADR-0003](adr/0003-static-binaries-through-github-releases.md)).

Rust's data-carrying `enum`s represent the unattended Ticket run, Claim and CI states. Exhaustive `match` means adding a state fails compilation until every match handles it. Pickup's reservation protocol across competing hosts is model-checked with `stateright` inside `cargo test` ([ADR-0017](adr/0017-pickup-reserves-issues-on-origin.md)). These checks matter when nobody is watching the control flow.

The installer ends by pointing you to Setup. Run `thirdshift setup` to choose your defaults, or just start a Ticket run and thirdshift will offer it (see [User config](#user-config)).

If you use Rust, you can install it from crates.io instead:

```sh
cargo install thirdshift
```

### Console installation

To open this machine's Inbox locally, run:

```sh
thirdshift console --no-sign-in
```

Open the localhost address it prints. The Console shows the same Inbox as `thirdshift status`, with live stages, logs and Session traces. It opens on Overview, showing Needs you, Ready for review, Landing and Working together under labeled headings with counts. The folders beside the one-line rows filter to an individual section; `/?section=done` opens Done and `/?section=overview` returns to Overview. Hidden sections stay hidden in Overview, and these views work without JavaScript. A clicked row's Command details open alongside on a wide screen. Ended rows show their relative age, with the recorded finish in this machine's time zone on hover, or in full without JavaScript, for example **Ended 2026-10-23 19:03 EDT · 52 min ago**. Every date and time the Console shows reads this way, to the minute. This is time since finish, not run duration. Nested Ticket runs and History use each Command's own finish time; missing or invalid finish times say **End time unknown**. The finish information also works without JavaScript. With `run`, use **Start work** on Inbox or **Run now** on Cron jobs to request a Command with confirmation. The Console starts work only when asked; the CLI and operating system's scheduler remain available too.

Click the serving machine's name in the Console header to return to Overview (`/?section=overview`) from another page or section, clearing any machine filter.

Live Fix runs and Review runs show a clickable **PR #number** beside their repository and run type in compact Working rows, including Overview, on desktop and phone. Explicit targets and Pass-selected targets use the same presentation for local and Fleet Commands. A Fix Pass repairing Base branch CI shows the exact selected **Base branch** before a PR exists, and keeps that branch visible alongside the PR link once published. Older records without a recorded target keep their repository and Command label.

Specs with recorded Tickets show a count such as **2 / 5 Tickets complete** on their Inbox row, including on phones and when a Pass dispatched the Spec. It counts merged Tickets, including those closed before the run, from the owning machine's last recorded accounting. Record updates refresh the count, and ended runs retain it. Missing or empty accounting shows no counter. All Tickets complete can still leave Spec review or Delivery running; the row keeps its state, stage and health information.

Every Inbox group starts open. Click its heading, or focus it and press Enter or Space, to fold its rows while keeping its heading and count visible. Each browser remembers its group choices through live updates, folder changes and reloads when storage is available. Folding still works through live updates without storage, and native disclosures work without JavaScript. Counts and active-run totals include folded rows; keyboard row navigation skips them. This works in every Theme and on phones.

Command details shows the last five lines of recent Command output above **Full Command log**, updating as output arrives. It reads at most 4 KiB, so a long log stays a small preview. This helps assess a Slow run without leaving its details. Empty or unavailable logs say so; the full-log link stays available.

#### Fleet

The Fleet lists the other machines known to this Console. To pair one, create
a token on that machine, then supply it to the watching machine through standard
input. Choose only the scopes that machine needs:

```sh
# On the machine to pair (prints the token once):
thirdshift console token create watcher --scopes read,act
# On the watching machine (paste the token at the hidden prompt):
thirdshift console fleet add server https://console.example.com
thirdshift console fleet list
thirdshift console fleet list --json
thirdshift console fleet remove server
```

The token is never an argument. Piped standard input works too. Pairing checks
`/api/v1/whoami`, then saves the hostname, thirdshift version, scopes and last
contact. An unreachable machine, a refused token or an older Console without
that endpoint leaves the saved Fleet and Credentials unchanged. Pairing requires
HTTPS, with an exception for `http://127.0.0.1` for local use. Redirects are refused.

Tokens are stored under `[fleet]`, keyed by entry name, in the owner-only
`~/.thirdshift/credentials.toml`. The User config holds no token. Removing an
entry deletes its saved token too; revoke the token on its issuer separately
when its access is no longer wanted. Adding an existing name pairs it again.

`thirdshift status` fetches each live entry's own `/api/v1/status` Inbox with
a three-second timeout per machine. Its rows join the local Inbox groups,
tagged with their Fleet entry name. Other-account Commands retain their account
tag too. The total active runs includes reachable machines, with each machine's
count shown separately. Link-only entries are not fetched.

Use `thirdshift status --machine server` to show only that paired machine;
`--json` and `--all` can be combined with it. Giving this machine's own hostname
behaves like plain `status`, including its Fleet. Unknown and link-only names
are rejected. Human-readable rows carry machine tags once a live Fleet exists.

**Start work** lists known Launch directories across the Fleet, labelled by
machine. Select the repository and machine, review the request, then confirm.
**Cron jobs**, **User config** and **Update** offer machine links; their
`?machine=<name>` selection remains in forms and confirmation dialogs. A control
appears only when that machine's live `whoami` includes `run` or `admin` for
the signed-in person. The owning machine checks the token and that person's
own scopes again on submission, so a forced request still receives its 403.
Only the owner starts work or changes settings. Its Activity log names
`by <person> from the Console on <token holder>`; name the pairing token for the
calling Console. Its Command appears in the merged Inbox when the token also
has `read`. The sign-in list and address scopes remain shell-only.

The CLI uses the saved token holder's identity, without naming a signed-in
person. `start` runs detached in a known Launch directory on the selected
machine and returns JSON. It accepts the shared Ticket options:

```sh
thirdshift start acme/widgets 7 no-merge no-email --machine server
thirdshift start --options --json --machine server
thirdshift config spec.parallel --json --machine server
thirdshift config spec.parallel 5 --machine server
thirdshift update --check --json --machine server
thirdshift update --machine server
```

Remote `config` and `update` return the owner's JSON. Unknown and link-only
machines are refused. Omitting `--machine` selects local work. A configured
Fleet name always selects its owner, even when the name matches the local
hostname; local choices then say `(local)`. An unpaired local hostname also
selects local work. `/api/v1/start-options` requires `run` and returns known
repositories and startable Passes; `whoami` accepts any authenticated scope so
`run`-only and `admin`-only tokens can pair without general read access.

Open a remote row to see its Command details in the same Console, including
child Ticket runs and stages. Waterfall, Full Command log and Session trace
links keep the owning machine selected. Details are fetched live from its
`/api/v1` and kept only for that request: remote logs and traces are never
written under the caller's home. Log readers show a snapshot; reload for newer
output. Every remote row and details view also links to the owning Console.
Security run details and findings need `security` on the owning machine's
token, and on the signed-in person's account there. A refusal says
"needs the `security` scope on `<machine>`".

The details commands accept the same machine selection and return the owning
machine's JSON:

```sh
thirdshift show widgets#7 --machine server --json
thirdshift show widgets#7 --spans --machine server --json
thirdshift show widgets#7 --span <span-id> --machine server --json
thirdshift logs widgets#7 --machine server --json
thirdshift logs widgets#7 --tail --machine server --json
thirdshift logs widgets#7 --session implement --machine server --json
```

Remote reads do not follow redirects or cache details between requests. A
local hostname selects the ordinary local command. Remote log following and
Trace export remain on the owning machine. The details API reads its own
machine; the Console page and CLI call that owning API directly, rather than
relaying an API caller through another Console's Fleet credentials.

`logs <command> --tail [--json]` reads only the last 4 KiB, on either machine.
It cannot be combined with `--follow`. Command details use this bounded tail
through the existing `/api/v1/log?tail=true` endpoint for their recent output.

`thirdshift status --local` reads only this machine. It can be combined with
`--all` and `--json`, but not `--machine`. This is the Console API's owning-machine
read, so Consoles paired in both directions never recursively fetch one another.

`status --json` version 2 includes a `machines` array with `name`, `hostname`,
RFC 3339 `fetched_at`, `active_runs`, `reachability` and nullable `error`.
Reachability is `ok`, `unreachable` (including a timeout), `refused` (including
a revoked token) or `needs update` (a missing or incompatible API). A failed
machine contributes no rows or active runs to that read; it never fails the
rest of `status`. Reads do not follow other machines' Fleets or change the
saved pairing's last-contact time.

`fleet list` reports saved metadata without contacting the machines. **Live**
means Credentials hold a token for the entry's name; it does not promise the
machine is reachable or the token still valid. **Last contact** is the last
successful pairing, not a background health check. Entries without a token are
**link-only**. Both kinds appear as named links in the Console header. These
commands are CLI-only and have no API endpoints.

Under `[console]`, a link-only entry can be written directly:

```toml
fleet = [{ name = "server", address = "https://console.example.com" }]
```

Existing `other_consoles` addresses are read as link-only Fleet entries named
after each address's host. Names that collide receive `-2`, `-3`, and so on.
Setup and Console settings writes replace `other_consoles` with `fleet`, keeping
the links and other settings.

Act on a paired machine from the shell:

```sh
thirdshift stop widgets#7 --machine server
thirdshift stop widgets#7 --machine server --requeue --json
thirdshift dismiss widgets#7 --machine server
thirdshift dismiss widgets#7 --machine server --undo --json
```

The Console's remote rows offer Stop with confirmation, Dismiss and Undo when
the owning machine's live `whoami` answer allows `act`. It intersects the saved
token's scopes with the signed-in person's scopes on that machine. The person
must also be on that machine's sign-in list. A read-only token or person sees
no action controls; the owning machine also refuses a forced request with 403.
Other-account Commands stay read-only on every machine. Stale or refused
answers offer no controls until access is checked again.

The caller sends the action to the owning machine's `/api/v1`, naming the
signed-in person in `X-Thirdshift-Person`, and shows that machine's answer,
including refusals. Dismiss takes the remote row out of Needs you or Ready for
review; Undo brings it back when it still needs attention. The next Fleet
refresh reflects the change. The owning machine signals its own processes,
keeps its Dismissals beside its Command records, and writes its own Activity log:
`by <person> from the Console on <holder>`. No Command logs or Activity log
entries are written on the caller. CLI requests name no person and are
attributed to the token's holder on the owning machine.

#### Console API

The Console serves read views as JSON under `/api/v1`, using a bearer token or
the same sign-in session as the page. `console --no-sign-in` also enables the API on localhost.
An unauthenticated API request receives a 401 JSON error instead of the sign-in
page. Reads use GET; these endpoints start no work and change no Commands.

Issue a token on the serving machine, from its owner's shell:

```sh
thirdshift console token create laptop
thirdshift console token create automation --scopes read,security,act,run,admin --expires 2027-01-01
thirdshift console token list
thirdshift console token list --json
thirdshift console token revoke laptop
```

Create prints the `ts_` token once; copy it into the client's Credentials.
Holders are unique on this machine. The default scope is `read`. The five
accepted scopes are `read` (views), `security` (Security run details and findings),
`act` (actions), `run` (starting Commands) and `admin` (administration).
A token without `security` still receives the other fields of a read route, but
not Security finding records: `security_findings`, `security_fix_findings`, and
a true `security_findings_waiting` flag are omitted or cleared. It also cannot
read a Security session trace (`security-review`, `security-audit`,
`security-reproduction-<n>`, `security-fix-publishing`, `security-close-check`,
and their resumes); those log reads return 403 naming `security`. Span and
waterfall responses keep the Command's other stages and omit those sessions,
including their prompts and tool output. A token that
has `security` receives the finding records and those traces. The `act` endpoints
and their auditing are described below. `run` starts Ticket and Spec runs;
`admin` reads and changes User config, updates thirdshift, imports Themes and
manages Eval data. A missing route scope returns 403 JSON naming that
scope. An expired or revoked token returns 401.

The machine stores only SHA-256 hashes in the owner-only
`~/.thirdshift/console-tokens.json`, beside the Credentials. List shows holder,
scopes, issue date, optional expiry and last use, never the token or its hash.
Expiry accepts a UTC date (`YYYY-MM-DD`, expiring at its start) or an RFC 3339
timestamp. Revocation deletes the record and takes effect on the next request.
Last use updates on successful authentication. Token management is CLI-only;
there is no API endpoint to create, list or revoke tokens.

Each address in `console.allowed_emails` has all five scopes unless narrowed in
`console.address_scopes`. Set and show an address's scopes from the machine's shell:

```sh
thirdshift console scopes --email reader@example.com --scopes read
thirdshift console scopes --email reader@example.com --json
```

With exactly one allowed address, `--email` can be omitted. `--scopes ''` grants
no scopes; omitting `--scopes` only shows the current scopes. Setup writes
`address_scopes = {}` with its default stated and preserves existing entries.
For example, under `[console]`:

```toml
allowed_emails = ["owner@example.com", "reader@example.com"]
address_scopes = { "reader@example.com" = ["read"] }
```

A sign-in session uses its address's current scopes on every request. The page
hides controls it cannot use, and a refused API call returns 403 naming the
missing scope. The sign-in list and address scopes are CLI-only settings: no
page or API endpoint can write them, even with `admin`.
Signing out of your own browser remains available even with no scopes.

A bearer request can name a person with `X-Thirdshift-Person: reader@example.com`.
The owning machine requires that exact address on its own `allowed_emails` list,
or returns 403. Its effective scopes are the intersection of the token's scopes
and the address's scopes; neither can grant what the other lacks. For example:

```sh
curl -H "Authorization: Bearer $THIRDSHIFT_TOKEN" \
  -H "X-Thirdshift-Person: reader@example.com" \
  https://console.example.com/api/v1/whoami
```

The header applies only to bearer authentication. A session always acts as the
address that signed in. A token without the header acts as its holder.

Send the token as `Authorization: Bearer <token>`. Tokens require HTTPS to the
installed Caddy or Apache proxy, which sets `X-Forwarded-Proto: https`.
The exception is a direct connection to `127.0.0.1` with no proxy headers.
Other transports are refused before checking the token, with the same 401
whether it was valid or not.

Failed bearer tokens and password sign-ins share an in-memory limit per client
IP address, across token holders and account names. From the third failure,
responses slow down; the eighth failure starts a 60-second cool-down. Requests
from that address then receive 429 with `Retry-After` in seconds; API errors
also include `retry_after` in their JSON. A success does not clear the count.
Idle failure counts expire after 60 seconds, and restarting the Console clears
the limiter. Other client addresses can still authenticate. The existing
account password slowdown and five-tries-per-code limit remain in place.

Only a proxy connecting from `127.0.0.1` may supply `X-Forwarded-For`: the Console
uses the last address of the first header, the one the proxy appended or
replaced. A later duplicate header is ignored. Other peers' headers are ignored
and their connection's IP address is used. A missing or invalid forwarded
address also falls back to the peer. Set this header in a custom proxy as in
the nginx example below.

`GET /api/v1/whoami` returns `hostname`, `thirdshift_version`, `api_version`,
`identity` (token holder, session address or local caller), and effective
`scopes`. Its CLI twin is `thirdshift console whoami [--json]`, reporting the
local caller with all scopes. In `--no-sign-in` mode its JSON matches the HTTP
response. For example, with a token in the client's `THIRDSHIFT_TOKEN` variable:

```sh
curl -H "Authorization: Bearer $THIRDSHIFT_TOKEN" https://console.example.com/api/v1/whoami
```

Each response equals its CLI twin's `--json` output. A caller with `read` sees
Security run rows and stages, with finding records withheld. Security run
details, the Security page and Security Session traces need `security`.
For example, `GET /api/v1/status` equals
`thirdshift status --local --json`, and `GET /api/v1/peek?command=widgets%237` equals
`thirdshift show widgets#7 --json`, subject to those scope checks.
Query arguments use the CLI flag names without `--`; positional Command
selectors use `command`, and Scores selectors use `pull_request`.

`GET /api/v1/openapi.json` returns the OpenAPI description of the endpoints
this Console serves. Its CLI twin, `thirdshift console openapi`, prints the same
JSON without a running Console. Both generate it from the shared route table:
each operation lists its declared scope, CLI twins, arguments and response
schema. The description contains no credentials or local records. Routes added
by later Console API tickets appear when they are served.

| Read | API path | CLI twin (add `--json`) |
| --- | --- | --- |
| Machine and caller | `/api/v1/whoami` | `console whoami` |
| Inbox | `/api/v1/status` (`?all=true` includes History) | `status` (`--all`) |
| History, Security, Lanes, Stages | `/api/v1/history`, `/api/v1/security`, `/api/v1/lanes`, `/api/v1/stages` | `status --all` |
| Command details, child Ticket runs and stages | `/api/v1/peek?command=<selector>` | `show <selector>` |
| Waterfall | `/api/v1/waterfall?command=<selector>`, `/api/v1/spans?command=<selector>&span=<id>` | `show <selector> --spans` or `--span <id>` |
| Command log or Session trace | `/api/v1/log?command=<selector>&session=<kind>` (omit `session` for the Command log) | `logs <selector> [--session <kind>]` |
| Log inventory and exact file | `/api/v1/logs`, `/api/v1/logs/command/<id>`, `/api/v1/logs/<id>` | `logs`, `logs --command <id>`, `logs --file <id>` |
| Run metrics | `/api/v1/metrics` (`command`, `from`, `through`, repeated `repo`) | `metrics` |
| Scores, Bug origins | `/api/v1/scores?pull_request=<selector>`, `/api/v1/bug-origins` | `scores [<selector>]`, `bug-origins` |
| Experiments, Trial Session evidence and blind pairs | `/api/v1/experiments`, `/api/v1/experiments/<id>`, `/api/v1/experiments/<id>/sessions/<session>`, `/api/v1/experiments/<id>/pairs/<pair>` | `experiments [<id>] [--session <session> \| --pair <pair>]` |
| Cron jobs, Resources, Console log, Theme export | `/api/v1/cronjobs`, `/api/v1/resources`, `/api/v1/console-log`, `/api/v1/themes/<name>` | `cronjobs`, `resources`, `console log`, `console theme export <name>` (already JSON) |
| Known Launch directories | `/api/v1/launch-directories` | `launch-directories` |
| Selected Theme and hidden sections | `/api/v1/look` | `console sections` |
| Available Themes | `/api/v1/themes` | `console theme list` |

Finite log reads support `--json`, returning `{"version":1,"contents":"..."}`;
`--follow` stays a separate streaming option. Other-account Commands retain
their account tags and remain read-only: Stop and Dismissal refuse them and
name the owning account. CLI refusals return 422 JSON with an `error` message.
An unrestricted signed-in session and `console --no-sign-in` hold every scope,
so their JSON still matches the CLI. A restricted session's JSON follows its
address's scopes, including the Security finding limits above.

| Scope | Calls |
| --- | --- |
| `read` | The read calls above, including Security run rows and stages |
| `security` | `/api/v1/security`, Security run details and Waterfall, and Security Session traces |
| `act` | Stop, Dismissal, judgments, selecting a Theme and hidden sections |
| `run` | `POST /api/v1/runs` starts Ticket, Spec, Architect, Pickup, Security, Review, Custom process, skill, Scoring, Triage and Experiment work; Process checks |
| `admin` | User config writes, Update, Theme and Eval data imports, Other-account settings, test email, Experiment names and Difficulty recording |

The actions in the following table take `application/x-www-form-urlencoded`
bodies using the listed fields; Theme import takes `application/json` instead.
Starting work and the additional CLI twins below also take JSON where listed.
Bearer requests need no CSRF token; sign-in sessions and
`--no-sign-in` requests must send the page's CSRF token in `X-CSRF-Token`.
The response is the CLI twin's JSON. Stop waits for cleanup to finish.

| POST path under `/api/v1` | Fields | CLI twin (add `--json`) |
| --- | --- | --- |
| `/stop` | `command`, optional `requeue=true` | `stop <command> [--requeue]` |
| `/dismiss`, `/dismiss/undo` | `command` | `dismiss <command> [--undo]` |
| `/scores/mine` | `pull_request`, each of `Correct`, `Scoped`, `Tested`, `Honest`, `Standards` as `pass` or `fail`, and each corresponding `<criterion>_reason` | `scores <pull_request> --mine` |
| `/bug-origins/settle` | `issue`, `action=confirm\|correct\|reject`, `pull_request` for a correction | `bug-origins <issue> --confirm\|--correct <pr>\|--none` |
| `/experiments/proposals/<suite>/<task>/approve` | none | `evals approve <suite> <task>` |
| `/theme` | `theme` | `console theme <name>` |
| `/sections` | comma-separated `hide`, `show` | `console sections --hide <section> --show <section>` |
| `/themes` | JSON Theme document | `console theme import <file>` (already JSON) |
| `/update` | none | `update` |
| `/evals/import-replays` | none | `evals import-replays` (already JSON) |
| `/evals/propose-process` | `repository` (known owner/repo), optional `limit` (1–100) | `evals propose-process <repository>`; requires `admin` |

Additional CLI twins use these scopes and bodies. All paths are under `/api/v1`;
JSON bodies use `Content-Type: application/json`. GET calls take no body.

| Method and path | Scope | Body | CLI twin |
| --- | --- | --- | --- |
| GET `/help`, `/version` | `read` | none | `--help`, `--version` |
| GET `/processes`, `/processes/<name>` | `read` | none | `process list`, `process show <name>` |
| POST `/processes/check` | `run` | JSON `repository`, `name`, optional Process run options | `process check <name>` |
| GET `/evals` | `read` | none | `evals list` |
| POST `/evals/touched` | `read` | JSON `paths` array of changed path names | `evals touched <paths>...` |
| POST `/evals/verify` | `read` | JSON `repository` (a known Launch directory's owner/name), `base` commit | `evals verify <repository> <base>` |
| GET `/other-accounts` | `read` | none | `console other-accounts --json` |
| POST `/other-accounts` | `admin` | JSON `value` (`none`, `readable`, or account list) | `console other-accounts <value>` |
| POST `/email-test` | `admin` | JSON with optional `address` | `email-test [<address>]` |
| POST `/experiments/<id>/name` | `admin` | JSON `name` | `experiments <id> --name <name> --json` |
| POST `/experiments/<id>/difficulty` | `admin` | none | `experiments <id> --record-difficulty --json` |
| GET `/experiments/<id>/rechecks` | `read` | none | `recheck <id> --pending --json` |
| POST `/experiments/<id>/pairs/<pair>/merge` | `act` | form `a` and `b`, each `ready` or `not-ready` | `experiments <id> --pair <pair> --merge <a> <b> --json` |
| POST `/experiments/<id>/pairs/<pair>/preference` | `act` | form `preference` (`a`, `b`, `tie` or `both-bad`), optional `rubric_<criterion>` | `experiments <id> --pair <pair> --prefer <preference> [--rubric <criterion>=<value>]... --json` |
| POST `/experiments/<id>/rechecks` | `act` | JSON `trial` or `fingerprint`, `decision` (`pass` or `fail`), `reason`, optional `wrong_finding` | `recheck <id> <trial> <decision> --reason <reason> --json`, or `--batch <fingerprint>` |

See OpenAPI for each CLI twin's response and full argument schema. The route
inventory and its explicit CLI-only exclusions are checked against the CLI.

#### Updating and administering a machine

With `admin`, open **Update thirdshift** in the Console navigation. It shows the
current and latest stable versions. Choose **Update thirdshift** to install the
release, then reload after the Console restarts. The install receipt must belong
to the running copy, just as for `thirdshift update`; source builds need a shell
reinstall. If checking the latest release fails, the page says so and offers Reload.

`GET /api/v1/update` returns `{"current":"…","latest":"…"}`, the same as
`thirdshift update --check --json`. POST runs the same updater as the CLI and
returns its result as a JSON string (`thirdshift update --json`). It answers once
the installer has placed the binary, before the Console re-executes itself:

```sh
curl -H "Authorization: Bearer $THIRDSHIFT_TOKEN" https://console.example.com/api/v1/update
curl -X POST -H "Authorization: Bearer $THIRDSHIFT_TOKEN" https://console.example.com/api/v1/update
```

Theme import requires `admin` and takes the Theme document itself as JSON;
a file path or a `path` field is refused. Selecting an existing Theme still
requires `act`. POST `/api/v1/evals/import-replays` imports the machine's private
replay manifests and grading index from their standard locations, like the CLI.
It accepts no paths. Eval task approval remains an `act` judgment. Eval verification
uses a known Launch directory through POST `/api/v1/evals/verify` with `read`.
Eval preparation and Arm preparation write caller-selected local paths, so remain
CLI-only. Updates, imports and judgments name their requester
in the Console log.

Every attempted API change records its holder or session address, endpoint and
HTTP outcome in the Console log; reads add no events. Activity log lines for
token Stops and Dismissals say `by token <holder>`, alongside the CLI and
Console callers already recorded there. A token naming a person records
`by <person> from the Console on <holder>`, naming both. Token secrets and action bodies are
never written to that audit record.

#### Starting Commands through the API

<a id="starting-ticket-and-spec-runs-through-the-api" name="starting-ticket-and-spec-runs-through-the-api"></a>

`GET /api/v1/launch-directories` and `thirdshift launch-directories --json`
return the same `{"directories":[{"repository":"acme/widgets","path":"/srv/widgets"}]}`
inventory. Known Launch directories come from this account's thirdshift cron
jobs with literal `cd <directory> && ... thirdshift ...` commands, including
`env NAME=value thirdshift` wrappers, plus the
top-level `launch_directories` list in User config. Paths may be absolute or
start with `~/`; aliases of the same directory are listed once. Each directory
is resolved through its GitHub `origin` remote. Stale cron directories are
omitted; an invalid configured directory is an error. Cron shell text is never
evaluated. For complex shell scripts or wrappers, list their directory explicitly.
An account without `crontab` can use the config list alone.

A client with `run` starts work with structured JSON:

On the Console's Inbox, a signed-in person with `run` can open **Start work**,
choose a repository from the known Launch directories and enter an issue number
or URL. **Shared options** offers merge, email, Harness, Model, Effort, parallel
Tickets, Base fix, Security review, Security fix and closing Security findings.
**Review start** shows the request and its Harness; only **Start now** submits
it. Cancel or Escape starts nothing. The result names the new Command, which
appears in the Inbox, or explains a refused start. Check Inbox and logs before
retrying after a lost response.

On **Cron jobs**, **Run now** offers the same confirmation for each recognizable
Pass, preserving its CLI arguments. Literal `cd` directories and Pass arguments
are supported; shell expressions and per-invocation environment wrappers remain
display-only. The result names a Command
or gives the Pass's skip reason, with a link to Inbox for started work.
Both controls require JavaScript and are hidden without `run`. Each confirmed
start uses the same scoped, CSRF-protected API as a client.

```sh
curl -H "Authorization: Bearer $THIRDSHIFT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"repository":"acme/widgets","issue":7,"merge":false,"email":{"mode":"never"},"harness":"codex","model":"gpt-6.1-sol","effort":"high","base_fix":false,"security_review":true,"security_fix":false}' \
  https://console.example.com/api/v1/runs
```

`issue` accepts a positive number, its decimal string or a full Issue URL in
the named repository. `merge`, `base_fix`, `security_review` and `security_fix`
are optional booleans; `harness`, `model` and `effort` are optional strings.
`email` has `mode` `always`, `unless_merged` or `never`, with an optional
`address` for the first two. Omitted options use the CLI's User config defaults.
Unknown fields and invalid arguments are refused. A repository without a known
Launch directory is refused before anything starts. If several directories
name it, the first path in the inventory is used.

The optional `command` selects the CLI twin; leaving it out means `ticket`,
which also starts a Spec run when the issue has Tickets. Every request names
`repository`. These commands are startable on the same `POST /api/v1/runs` path:

| `command` | Target and command-specific options |
| --- | --- |
| `ticket` | Required `issue`; shared run options above, plus positive `parallel` and boolean `security_close` |
| `architect` | Optional `base`, `focus`, `plan_only`; shared run options, `parallel`, `security_close` |
| `pickup` | Optional `base`, `order` (`lowest-first` or `highest-first`); shared run options, `parallel`, `security_close` |
| `secure` | Optional `base`; shared run options, `parallel`, `security_close` |
| `review` | Required `pull_request` URL or `author` login; optional `recommend_only`, `email`, `harness`, `model`, `effort`, `security_review` |
| `fix` | Optional `pull_request` URL for a targeted Fix run, or `base` and `author` for a Fix Pass; optional `merge`, `base_fix`, `email`, `harness`, `model`, `effort` |
| `process` | Required `name`; optional `issue` or `pull_request` URL, `plan_only`, `merge`, `email`, `harness`, `model`, `effort`, `security_review`, `security_fix`, `security_close` |
| `skill` | Required `name`; optional `issue` |
| `score` | No options; uses the CLI's machine-wide Scoring lock and fixed Scoring repository |
| `triage` | Required `report` text; optional `read_machine`, `recommend_only`, `allow_ready_for_agent`, `email`, `harness`, `model`, `effort` |
| `experiment` | Structured `experiment` options: `candidate`, `baseline`, per-arm Harness/Model/Effort, `suite` array, sampling and timeout settings, optional `release` and `yes` |

Booleans use `true` or `false`. All options and combinations are checked by
the CLI argument parser; for example, Architect `plan_only` refuses options
for a dispatched run. Issue and pull request URLs must belong to the named
repository. Triage receives the Report verbatim through standard input;
`file`, `path` and arbitrary CLI arguments are refused. `read_machine` has
the same meaning as the CLI's `--read-machine`, including User config defaults.

For example, start a Pickup run on `main`, taking the highest issue first:

```json
{"repository":"acme/widgets","command":"pickup","base":"main","order":"highest-first"}
```

Or compare two commits in an Experiment using the machine's Eval suites:

```json
{"repository":"acme/widgets","command":"experiment","experiment":{"candidate":"HEAD","baseline":"HEAD~1","baseline_harness":"claude","candidate_harness":"codex","suite":["code-review"]}}
```

Experiment option names match the CLI's long flags with underscores in place
of hyphens. `suite` is an array of suite names, and `candidate` is a Git reference.
The same CLI parser validates the combination; OpenAPI lists the option types.

The Console starts the same binary in that directory, in its own OS session
with the account's login shell environment. Standard output and errors append
to the cron command's literal `>>` or `>` output path when present, otherwise
to `<logs.dir>/cron.log`, the shared cron log used in the scheduling examples.
It waits at most 30 seconds for the Command record and returns
`{"version":1,"name":"acme/widgets#7"}`. Passes use the same gates as cron,
including the Command limit. A skip before a Command record exists returns
`{"version":1,"outcome":"skipped","reason":"..."}`, even with quiet skips
or a repeated skip reason. A Custom process's skip retains its Command record
as in the CLI, so returns its name. Skill runs keep no Command record in the
CLI; after preflight they return
`{"version":1,"outcome":"started","process_id":1234}` instead. Their API start
names the requester in the repository's Activity log. An early failure returns an error naming
the exit status and log; a timeout names the process and warns that it may still
start, so check `status` before retrying. Follow the Command with the usual
`show`, `status` and log views. It keeps running through a Console restart.
The generated systemd service uses `KillMode=process` to preserve these
Commands during a service restart; regenerate an older installed service to
apply that setting.

An issue with sub-issues starts a Spec run. As with a typed Issue URL, the
Command limit never skips this work. The Command record and Activity log keep
the token holder or the named person and calling machine. Every start attempt
goes in the Console log. Cron and terminal starts keep their usual wording.

#### Console on a server

Set the machine's address, fixed localhost port and sign-in allowlist in `~/.thirdshift/config.toml`:

```toml
[console]
address = "https://console.example.com" # a DNS name, with or without https://; no port or path
port = 8711
allowed_emails = ["you@example.com"]
```

Point that DNS name at the machine, then run these commands as the owner:

```sh
thirdshift console password --email you@example.com
thirdshift console install --output install-console.sh
# Read the script, then install it:
sudo sh install-console.sh
```

`console install` only prints a script; `--output <file>` saves it to that file instead, replacing any earlier copy, and writes nothing if the settings can't make a script. On Linux it prefers a running Caddy or Apache service; otherwise it checks for `caddy`, `apache2ctl` or `httpd` on PATH. For either proxy, the script first checks the Console's address with the system resolver (`getent hosts`). If it doesn't resolve, it stops before writing files or changing services and asks you to add an A or AAAA record pointing at this server, then run the script again. It checks resolution only, not whether the address points at this machine. The script writes `thirdshift-console.service`, running the installed binary as you with your HOME and automatic restarts. Only the script needs root.

Install `curl` before running the script. After enabling and restarting the Console, it waits for the service to be active and answer at `127.0.0.1:<console.port>` before configuring or restarting the proxy. It tries up to 15 times, with one-second request timeouts and one-second pauses (about 30 seconds). A sign-in response counts as answering. If startup fails or the checks run out, the script exits nonzero and prints the unit's last 50 journal lines. If `getenforce` reports `Enforcing`, it also warns that SELinux can block the Console and links to [#1078](https://github.com/JacobStephens2/thirdshift/issues/1078); it does not change SELinux labels or policy.

For Caddy it writes `/etc/caddy/sites/thirdshift-console.caddy`, imports the sites folder from `/etc/caddy/Caddyfile` if needed, and disables proxy buffering with `flush_interval -1`. Caddy handles HTTPS. It **restarts**, rather than reloads, Caddy to preserve HTTP/3 on Android. For Apache it writes the port-80 site under `/etc/apache2/sites-available` or `/etc/httpd/conf.d`, preserves Host, forwards the request protocol and disables gzip on the Console's event streams. Install certbot with its Apache plugin first; the script runs `certbot --apache -d <name>`. Debian's module/site helpers are included. On an `httpd` machine, enable `proxy`, `proxy_http`, `headers`, `ssl` and `setenvif` and permit proxy connections in the host's SELinux policy first.

With neither proxy, the script installs a localhost-only service with `--no-sign-in` and prints an SSH tunnel command. No address or accounts are needed for that mode. Run the tunnel on your computer and open the printed `http://localhost:<port>` address. When using a Linux VM on Apple Silicon macOS or WSL2 on Windows, keep the Console inside Linux and open the tunnel from the host.

#### nginx

For nginx, use the generated service but remove `--no-sign-in` from its `ExecStart` before installing it. Configure the allowlist and password above. Obtain an HTTPS certificate for your DNS name, then add a site like this, adjusting the name, certificate paths and port:

```nginx
server {
    listen 443 ssl;
    server_name console.example.com;
    ssl_certificate /etc/letsencrypt/live/console.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/console.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8711;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        gzip off;
        proxy_read_timeout 1h;
    }
}
```

Run `sudo nginx -t`, then `sudo systemctl restart nginx` on a systemd host. The Console still binds only to 127.0.0.1; nginx terminates HTTPS and passes live updates without buffering.

### Updating

```sh
thirdshift update
```

It replaces the installed binary with the latest stable GitHub Release, or says it is already on it. Messages go to stderr and stdout stays empty. It exits `0` when it updated or was already up to date, and `1` on any failure, such as no network. Updating is safe while a Ticket run, Spec run or Experiment is using the old binary: it keeps running it. So do the child Ticket runs it starts afterwards, a Ticket run or a Base fix, which it starts through `/proc/self/exe` from the binary it is running rather than from the install path, so they run its version even once that path holds the new one or nothing at all. An Experiment's later Trials and Graders keep its original OOM wrapper through the owning process's `/proc/<pid>/exe` link, including scopes prepared before the update. The requested Arm programs, arguments, environment and memory caps stay the same. A Ticket run never checks for updates or updates itself.

`thirdshift update` only replaces a copy put in place by the shell installer (the `curl` command above), which leaves an install receipt in `~/.config/thirdshift/`. It refuses to touch any other copy and lists the command that updates each other kind of install: `cargo install thirdshift` for a crates.io install, pulling and reinstalling for a build from source (see [Building from source](#building-from-source)), and the `curl` command for a copy placed by hand.

Keep a single copy: with copies in more than one directory on your `PATH` (say `~/.local/bin` and `~/.cargo/bin`), you can end up running a stale one without noticing. `type -a thirdshift` lists every copy on your `PATH`.

## Supported platforms

thirdshift supports Linux only. Each architecture gets a statically linked musl binary, so it doesn't depend on the host's glibc: `x86_64-unknown-linux-musl` or `aarch64-unknown-linux-musl`.

**Test suite in CI:**

- **Ubuntu** 24.04.3 and later, `x86_64`.
- **Ubuntu** 24.04.3 and later, `aarch64` (ARM Linux), with the full CI test suite on `main` and nightly. On Apple Silicon macOS, run Ubuntu 24.04 `aarch64` in a Linux VM such as Lima, using `vz` and `--mount-none`. Keep repositories on the VM's Linux filesystem (e.g. `~/repos`), not under `/Users`, just as WSL2 repositories stay off `/mnt/c`. Install and authenticate `gh` and the Harness inside the VM, and run thirdshift there.

**Release smoke check only:**

- **Rocky Linux** 9.8 and later, `x86_64`.
- **WSL2**, latest release, with Ubuntu 24.04 or later, `x86_64`. Keep your repositories on the Linux filesystem (e.g. `~/repos`), not under `/mnt/c`, where git is slow and file permissions misbehave. WSL1 is not supported.

Native macOS (including Intel macOS) and native Windows have no binary. Apple Silicon macOS uses the `aarch64` Linux binary in its VM; Windows uses the `x86_64` Linux binary in WSL2. Rocky Linux and WSL2 support is `x86_64` only.

## Prerequisites

The user account that runs thirdshift needs:

- The selected **Harness** installed and authenticated: **`claude`** (Claude Code, the default), **`codex`** (Codex CLI), **`agy`** (Google Antigravity CLI), **`grok`** (Grok Build), **`muse`** (Muse Code), **`opencode`** (OpenCode, with a configured Model provider), or **`kimi`** (Kimi Code CLI, signed in or with a configured provider). See [Harness, Model and Effort](#harness-model-and-effort) for each CLI's flags and quirks.
- **`gh`** (GitHub CLI), logged in. For a fine-grained personal access token, grant repository permissions **Contents**, **Issues** and **Pull requests** read and write, plus **Actions** and **Commit statuses** read. If `check-runs` returns HTTP 403, CI watch, CI-fix Repairs and Score packets read the latest GitHub Actions workflow jobs instead, alongside commit statuses. Checks from non-Actions apps are unavailable through this fallback.
- **`git`** with a global `user.name` and `user.email`, and credentials that can push to the repository (`gh auth setup-git` makes git use `gh`'s login). The agents commit as this identity; without it, an agent may borrow the author of the last commit.
- **`node`** (Node.js) on `PATH`, for a [Security run](#security-runs) only: the Security audit's report validators run on it.

### Unattended sessions

Sessions run headless with the full permissions of that user account, including `sudo` if the user has it, and nobody is there to approve anything. On Claude Code they run in auto mode (`claude -p --permission-mode auto`): its classifier checks each action and may block ones it judges risky, such as destructive commands or actions outside the task. A blocked action the agent can't work around can end the Ticket run as a Failed ticket run. The other Harnesses run with approvals and their sandbox turned off ([ADR-0013](adr/0013-every-harness-runs-unattended-and-fully-trusted.md)), so no approval step or sandbox stands between an action and the account.

Every factory session on Claude Code, Repairs, reviews and Resumes included, also passes `--settings '{"attribution":{"commit":"","pr":""}}'`. These per-session settings override the user's and repository's attribution settings, hiding Claude Code's commit trailer and pull request attribution. The pull request keeps thirdshift's `Built with` line as its only attribution; nothing replaces the commit trailer. Claude Code run by hand keeps its own settings. The release-summary invocation, which runs with tools disabled, keeps its existing arguments.

`claude -p` exits as soon as the agent ends its turn, killing any background task it started. So every prompt tells the agent to run long commands, such as tests, in the foreground, and to stop any background task it no longer needs, with the `TaskStop` tool, before it ends its turn. If a session still ends with background work running, thirdshift takes it as work the session was waiting on and gives it a **Resume**: it continues that same session once (`claude -p --resume`), asking the agent to re-run the work in the foreground and finish. If the Resume ends the same way, the work may have been abandoned, such as a hung test run the agent could not stop: thirdshift says which task was killed and carries on, so the pull request check, CI and the rest decide how the Ticket run ends. If the Ticket run then fails, its cause names the killed task ahead of what failed.

### What sessions leave behind

When a Harness session ends normally, fails or is stopped, thirdshift stops its process tree, then sweeps for surviving processes. On Linux with a reachable systemd user manager, ordinary sessions have their own scopes: cleanup kills everything left in that cgroup, even work detached by `setsid`, a double fork or reparenting. Ordinary sessions get no new resource limits. Trials and Graders keep their existing memory caps. A Trial's sequential sessions reuse its dedicated capped scope, sweeping processes added by each session while preserving the supervisor; parallel Trials have separate scopes. An uncapped standalone `--trial` creates its own session scope. When an external caller caps a standalone Trial without declaring a verified dedicated Trial scope, it stays in the caller's cgroup and uses the marker fallback, preserving that caller's limits.

On Linux without a user manager, cleanup is best effort: each session carries a unique `THIRDSHIFT_SESSION` environment marker, and thirdshift finds processes belonging to the same OS user with that exact marker. It sends SIGTERM, waits the existing ten-second grace period, then sends SIGKILL to survivors. A process that clears its environment can escape this fallback. Parallel sessions have different markers and scopes. Cleanup logs a count when it kills survivors; a sweep failure logs a warning and leaves the Command's outcome unchanged. This cleans up work from the current session, not processes older versions already leaked.

File cleanup removes thirdshift's own worktree, local Issue branch and the temporary directory it wrote the Factory skills out to. The `.git/info/exclude` entry that keeps the linked skills out of git, `/.claude/skills/thirdshift-*`, or `/.agents/skills/thirdshift-*` on the other Harnesses, is added once and left in place, as every worktree of the repository shares the file. Each home skill linked from `~/.thirdshift/skills` adds its own entry for that name, and that entry is left in place too. Other files an agent creates as your user stay. For example, one Ticket run downloaded a JDK to `~/.local/jdk/` because the server had no Java, installed Playwright in `/tmp/pw`, and left a pull request body draft in `/tmp/`. This is by design, but worth knowing:

- **Install the target repository's toolchains up front** (language runtimes, package managers, test tools), so the agents don't download their own on every Ticket run.
- **For UI work, install the headless browser dependencies**, e.g. `libgbm1` on Ubuntu server, which headless Chromium needs. Without it, agents can't take screenshots to check a UI change and fall back to reading the code.

### Usage and cost

When `claude` is logged in with a claude.ai subscription, Ticket runs use the plan's usage allowance, not API billing. The `total_cost_usd` in the session traces is the API-price equivalent, not a charge. An unattended Ticket run that hits the plan's usage limit stalls or fails partway through.

## Usage

```sh
cd ~/repos/widgets          # a clone of the issue's repository, on the Base branch
thirdshift https://github.com/acme/widgets/issues/7
```

You can use a positive decimal issue number anywhere a Ticket run takes an Issue URL:

```sh
thirdshift 7
thirdshift merge 7
thirdshift --no-merge 7 harness codex
```

The number resolves against the Launch directory's `origin`, including from nested
directories in the clone. Supported origins are `https://github.com/owner/repo`,
`git@github.com:owner/repo` and `ssh://git@github.com/owner/repo`, with or without
`.git`. The Ticket run uses the same Issue URL and Origin match as the full-URL form.
Zero, overflow and malformed numbers are rejected. A missing or non-GitHub
`origin`, or starting outside a clone, stops shorthand resolution before any
session or tracker change. All Ticket run options work with either form.

A Ticket run takes minutes to tens of minutes.

To have the Ticket run merge its pull request instead of leaving it for your review, ask the Ticket run to **Self-merge**:

```sh
thirdshift merge https://github.com/acme/widgets/issues/7
```

`thirdshift --merge <Issue URL>` does the same, and either goes before or after the URL. The agent gets the same implement prompt either way; the differences are the Self-merge at the end and the review of [Foreign commits](#foreign-commits-in-a-ticket-run-that-self-merges). To have every Ticket run on a machine Self-merge, set `merge.always` in the [User config](#user-config); `no-merge` (or `--no-merge`), before or after the URL, then makes one Ticket run end ready for review instead. Giving a flag twice, or `merge` together with `no-merge`, is an argument error.

A Ticket run that Self-merges ends in one of four ways:

- **Merged**: exit `0`, the pull request's URL on stdout, and `PR <url> is merged` as stderr's last line.
- **Review required**: the PR's `reviewDecision` is `REVIEW_REQUIRED` or `CHANGES_REQUESTED` just before a Self-merge attempt. Exit `1`, the PR URL on stdout, and `PR <url> needs an approving review before it can merge; it is ready for review` on stderr and in the Run notification. The Run notification and Activity log summary name `review required`. The PR stays ready, the Claim is kept, and no merge attempt or further Repair round runs. An empty or `APPROVED` decision, or a failed read, leaves the existing merge behavior in place.
- **Policy refusal**: GitHub refused the merge and a round of merging the Base branch and watching CI found nothing left to fix. Exit `1`, the pull request's URL on stdout, and GitHub's error on stderr. The pull request stays open and ready for review, not a draft, for you to merge by hand or to change the repository's settings. thirdshift never reads GitHub's error text to decide this.
- **Any other failure**: a [Failed ticket run](#failed-ticket-runs), as for a Ticket run without `merge`.

To be emailed when the Ticket run ends, add `--email` (or `email`), optionally followed by the address, before or after the URL and alongside `merge`:

```sh
thirdshift --email you@example.com https://github.com/acme/widgets/issues/7
```

It sends one [Run notification](#run-notifications), whatever the outcome. To have every Ticket run on a machine send one, set `email.always` in the [User config](#user-config); `no-email` (or `--no-email`) then skips it for one Ticket run.

- **stdout** carries only the pull request's URL: on success, and on a Failed ticket run that leaves an open pull request, a draft or, after a policy refusal, one ready for review. The exit code tells the two apart, so script it as `url=$(thirdshift "$issue") && echo "ready: $url"`.
- **stderr** carries everything else: errors, cleanup problems, and progress lines while sessions run. Each line starts with the local time it was printed, as in `thirdshift: 12:14:49 pushing issue-7`, so a quiet terminal shows how long the Ticket run has been on its last step. The first line of a Ticket run, a Spec run or a Pass also names the date and the UTC offset, as in `thirdshift: 12:00:01 starting on https://github.com/acme/widgets/issues/7, 2026-10-03 -0400`, so a log that collects many commands, such as a crontab line's, reads as a dated list. Everything on stderr and stdout is kept in the command's [Command log](#logs) too. A top-level Ticket run or Spec run prints its elapsed wall time near the end, as `Took: 1h 2m 3s`, before its final outcome or failure cause. This also covers graceful interruption, works without email, and adds no summary for child Ticket runs or skipped Passes. A successful Ticket run's last line names the pull request too: `PR <url> is ready for review`, or `PR <url> is merged` after a Ticket run that Self-merges, followed only by a `warning:` line if a [Run notification](#run-notifications) can't be sent.
- **Exit code** `0` means the Ticket run ended with a pull request the factory stands behind, merged in a Ticket run that Self-merges. Once the Self-merge has merged, the Ticket run succeeds even if deleting the Issue branch on `origin`, closing the issue or removing `in-progress` from it then fails: the merge can't be undone, so each failed step is a `warning:` line on stderr naming the command to run by hand, and the Ticket run still exits `0` with the URL on stdout. Ctrl-C likewise: before the merge it makes a Failed ticket run, after it thirdshift finishes these steps and exits as merged. `2` means the command is one thirdshift can't use: the issue argument is missing or isn't a GitHub Issue URL or positive decimal number, there is an argument other than the issue and the Ticket run flags, a Ticket run flag is repeated or contradicts another, or `parallel` isn't followed by a whole number from 1 up; the error and the help text go to stderr, before any work. Failure to resolve a number against the clone's origin exits `1`. A [User config](#user-config) thirdshift can't use exits `1`, also before any work. Any other failure exits `1`.

During a CI wait, `CI on <short sha>: 3 still running out of 4 checks listed so far` counts the checks GitHub currently lists, including commit statuses. Dependent jobs and matrix jobs may become visible later, so both the pending count and the listed total can rise as CI progresses. A change to either count prints a new progress line; identical repeated counts stay quiet. The listed total is not a prediction of the final workflow total. This reporting does not change which checks count as passing or when Delivery may merge.

CI check observations get at most three total attempts: the original read and two retries, with interruptible delays of one second then two seconds. Transport failures, HTTP 429 or 5xx responses, and truncated JSON can recover this way; known permanent errors and unclassified failures stop immediately with their diagnostics. This applies to the initial watch, pending-check polling, Base comparison and Check re-run reconciliation. Each retry reads the same repository and full commit again. Failed reads never count as passing or absent CI, never start a Repair, and never repeat a workflow re-run request. Progress lines retain each failure and delay; exhaustion reports all three attempts and their causes. Cancellation stops active reads and backoff without another request.

Reads of `origin` by git, `git ls-remote` and `git fetch`, get the same three attempts with the same interruptible delays when git's error says the connection failed in transport: a dropped HTTP/2 stream or connection (`RPC failed; curl <n>`, `early EOF`, `the remote end hung up unexpectedly`, `Connection reset`), a timeout, a name lookup, a TLS read, or HTTP 429 or 5xx. Each retry prints a progress line with the command, its git error and the attempt, as in `git ls-remote --heads origin refs/heads/issue-7 refs/heads/issue-7-branch-* failed: error: RPC failed; curl 16 Error in the HTTP2 framing layer (attempt 1/3); retrying in 1s`. Authentication failures, a repository not found, a missing ref and any error not recognised fail at once, and a read that fails all three times fails with its last error. `git push` is never retried this way.

The other commands:

```sh
thirdshift architect [<focus>]      # review the Base branch's architecture, publish a plan and run it (see Architect runs)
thirdshift architect [<focus>] --plan-only   # publish the plan, mark it ready and stop there
thirdshift architect base <branch> [<focus>]   # do either with <branch> as the Base branch, from a clone on any branch
thirdshift pickup                   # take the lowest-numbered Ready issue in the repository and run it (see Pickup runs)
thirdshift pickup highest-first   # take the highest-numbered Ready issue instead, for that one pass
thirdshift pickup base <branch>     # do that with <branch> as the Base branch, from a clone on any branch
thirdshift secure                   # audit the Base branch and record findings privately (see Security runs)
thirdshift secure base <branch>     # do that with <branch> as the Base branch, from a clone on any branch
thirdshift skill <skill> [issue <issue>]   # run one skill headlessly and print its final message
thirdshift process list                 # list Processes, marking Built-in processes (experimental)
thirdshift process show <name>           # print a Process file exactly (experimental)
thirdshift process <name> [issue <issue>]   # run a Custom process, optionally on an issue; email, merge and no-merge match a Ticket run (experimental)
thirdshift process check <name> [issue <issue>]   # validate one and print its plan (experimental)
thirdshift score                    # sample merged factory pull requests (see Scoring runs)
thirdshift scores [<pull request>] [--json] # show Scores and calibration
thirdshift scores <pull request> --mine [--json] # enter your five Scores
thirdshift bug-origins [<issue>] [--json]  # list Bug origins or show one
thirdshift bug-origins <issue> --confirm   # confirm the proposed pull request
thirdshift bug-origins <issue> --correct <pull request> # confirm a different pull request
thirdshift bug-origins <issue> --none      # reject the origin
thirdshift email-test [<address>]   # send a test email through Resend (see Email)
thirdshift setup                    # choose your defaults and write the User config with every setting (see User config)
thirdshift evals list               # list private Eval suites and approved/proposed Eval tasks
thirdshift evals approve <suite> <task> [--json]  # approve a proposed Eval task in its suite
thirdshift evals import-replays     # import #429's private manifests and grading files once
thirdshift evals propose-process <repository> [--limit <1..100>]  # draft process Eval tasks from merged Tickets
thirdshift evals touched <path>...  # select suites from their declared source dependencies
thirdshift evals prepare <suite> <task> <destination>  # prepare a throwaway repository at its base
thirdshift evals verify <repository> <base>  # refuse history beyond the base commit
thirdshift evals prepare-arms <repository> <baseline-commit> <baseline-harness> <candidate-commit> <candidate-harness> <record.json>  # cache builds and record fixed Harness paths
thirdshift experiment <candidate> [--baseline <ref>] [--suite <name>] [--name <text>] [--json] [--yes]  # run or resume an Experiment
thirdshift experiment --release <commit> [--baseline <ref>] [--json] [--yes]  # use the last release tag by default and touched suites
thirdshift experiments [<id>] [--json]  # list Experiments or show one
thirdshift experiments <id> --name <text> [--json]  # rename an Experiment; --name '' brings back its default name
thirdshift experiments <id> --session <session-id> [--json]  # read a Trial's retained session from its inventory
thirdshift experiments <id> --record-difficulty [--json]  # replace each Eval task's Difficulty from a completed A/A
thirdshift recheck <id> <trial> <pass|fail> --reason <text> [--wrong-finding <true|false>] [--json]
thirdshift recheck <id> --pending [--json]  # review pending Scores and their fingerprint
thirdshift recheck <id> --batch <fingerprint> <pass|fail> --reason <text> [--wrong-finding <true|false>] [--json]
thirdshift update                   # update to the latest release (see Updating)
thirdshift version                  # print thirdshift <version>
thirdshift help                     # print a compact command and option reference
```

`help` lists commands and shared options, with a link to this manual for workflow details, settings, Harness setup, email, logs and scheduling.

### Eval tasks

Eval suites live privately under `~/.thirdshift/evals/suites/<suite>/`. Their
manifests declare Factory skill, Session prompt and Harness, Model and Effort
default dependencies, plus Trials per Arm. `evals touched` selects suites from
those declarations. `evals list` includes proposed Eval tasks, while `evals
prepare` refuses them until approved. `evals approve <suite> <task> [--json]`
approves one in its suite without changing its inputs or starting work. The
Console offers the same action under Proposed Eval tasks on the Experiments
list and, for its suites, on an Experiment page. Approval affects future
Experiments; existing Experiments keep their fixed Eval tasks when resumed.
`evals propose-process <repository>` drafts proposed process Eval tasks from
recent merged pull requests closing Tickets, listing their bug or feature kind,
source line count and separate test layout. Review each draft's selectors before
approving it. `evals prepare` screens process tasks on the host with network
access: each fail-to-pass selector must fail at the base and pass at the merge
with the reference tests and shared fakes overlaid. It refuses changed inline
Rust tests and names the file. The prepared process repository keeps the fix
and test overlay private. See the [task format](https://github.com/JacobStephens2/thirdshift/blob/main/docs/eval-tasks.md#process-task-preparation-and-proposals).
Preparation keeps only base history, applies
the change under review without its commit objects, and gives Spec-review Eval
tasks a local bare origin. These commands write JSON and start no agent sessions.
`evals prepare-arms` prepares both Arms before Trials: it caches release builds
by commit under `~/.thirdshift/evals/builds/` and records their commits, binaries,
and each Harness's real path and version in a new JSON file. A failed build or
version lookup stops preparation. Trials use the recorded Harness path so an
installation's symlink update cannot change the Harness between Arms.
For process Arms, add `--baseline-process <name-or-file.toml>` and
`--candidate-process <name-or-file.toml>`; the other Arm defaults to `ticket-run`.
Names select Built-in processes or files under `~/.thirdshift/processes/`.
The Process file and its referenced home skills, including supporting files,
are copied into private Arm folders beside the record. The record lists each
file's SHA-256 and the resolved Harness, Model and Effort per Step. Optional
`--baseline-model`, `--baseline-effort`, `--candidate-model` and
`--candidate-effort` set the inherited choices.
The [Eval task format](https://github.com/JacobStephens2/thirdshift/blob/main/docs/eval-tasks.md)
documents the manifests with made-up data and the Arm record.

On the host holding #429's material, `thirdshift evals import-replays` reads
the private replay manifests, cached original issue bodies and grading index
under `~/.thirdshift/replays/` into the code-review and Spec-review suites.
Rerunning adds missing Eval tasks and completes missing Trial inputs in both suites,
preserving local edits. The format document also describes the
grading index to prepare on that host; private material stays outside the repository.

### Experiments

From a local thirdshift clone, `thirdshift experiment <candidate>` compares a
branch or commit with its merge-base with `main`. Use `--baseline <ref>` to name
another Baseline. Suites default to those touched by the change, using their
declarations; repeat `--suite <name>` to select them explicitly, including for a
Harness, Model or Effort comparison with the same build in both Arms.
Before building either Arm, an Experiment names every selected approved Eval
task missing a `[trial]` table. This check also precedes the release Baseline probe.

For an **A/A Experiment**, use one commit and the same flags in both Arms.
This measures how often the Arms disagree when nothing differs, so you can
assess ordinary Trial variation before weighing a change. For example:

```sh
thirdshift experiment HEAD --baseline HEAD \
  --suite code-review --suite spec-review \
  --baseline-harness claude --candidate-harness claude \
  --baseline-model opus --candidate-model opus \
  --baseline-effort high --candidate-effort high
```

Choose matching Harness, Model and Effort values available on your machine.
Select the suites explicitly with `--suite`: identical commits touch no paths
from which to select them automatically. Both Arms follow the ordinary build
and Trial path (the commit's cached build may be reused), with separate Trials,
Graders and a Verdict under the fixed Bar. Identical Arms do not guarantee
identical Scores or a pass; the Verdict may be pass, fail or inconclusive.
The ordinary resume rules below still apply.

After it completes, `thirdshift experiments <id> --record-difficulty` pools
both Arms' retained, non-void Trials for each Eval task and replaces its
optional `[difficulty]` table. It records passes, Trials, the Experiment ID,
commit, Harness, Model and Effort, using the latest rechecked Scores. An
unfinished Experiment, or Arms differing in any of those setup choices, is
refused before writing. Each manifest is written atomically under the suite
lock shared with approval; comments and Trial inputs are preserved. The saved
Experiment and its Verdict stay unchanged.

The command prints each Eval task's Difficulty as passes / Trials and whether
it is **discriminating**: at least 6 Trials, with Difficulty between 0.15 and
0.95 inclusive. Fewer than 6 Trials counts as **unmeasured**, as does a missing
table. The band is fixed by the method, not a Bar flag. Add `--json` for the
readings and their `measured` and `discriminating` flags. `thirdshift evals`
(or `evals list`, optionally `--json`) lists every Eval task's table or `null`,
with the same flags. See [the manifest format](eval-tasks.md).

Before the first Trial, the Bar saves each selected suite's list of
discriminating Eval tasks from recorded Difficulty. Only that list is judged.
Other approved Eval tasks still run and are graded; each suite reports their
Trials per Eval task under `measurement`. These Trials change no interval,
required recheck or prediction of how many more Eval tasks are needed.
`experiments <id>` and `--json` show each suite's counts: judged,
measurement-only, void-dropped and judged tasks measured on another setup
(commit, Harness, Model or Effort) than the Baseline's. The first three counts
partition the suite: a task with an exhausted Void Trial counts as void-dropped,
including when it was only measurement. Difficulty from another setup still
qualifies. A suite with no discriminating Eval tasks is inconclusive.

The Bar also fixes `min_discriminating_tasks`, defaulting to 20. Set it for one
Experiment with `--min-discriminating-tasks <count>`; changing it after the first
Trial refuses resume. A suite whose saved discriminating list is shorter is an
**Advisory suite**. Its Verdict and intervals are still shown, with `advisory: true`
in JSON and an Advisory mark in the text view and Console. The Console also shows
the judged and measurement counts. Advisory suites cannot pass or block a release:
only the other suites decide the overall Verdict. When every suite is advisory,
the overall Verdict is inconclusive. The minimum uses the fixed list's size,
before Void dropouts, rather than the retained judged count.

Before building either Arm, an Experiment prints what its Trials will cost: how
many it will run, per suite and Arm; the worst case, those Trials times the
Bar's timeout, in session-minutes; and, for each suite and exact Arm setup that has
history, an estimate from completed, non-Void Trials in this machine's earlier
Experiments. The setup includes the build, Harness, Model, Effort and Process.
Estimates count every attempt's minutes and show priced dollars when all of
that history has complete accounting. The total time estimate appears only when every suite
and Arm has one. A resumed Experiment counts only its remaining Trials. When
stdin is a terminal it then asks `Run these Trials? [y/N]`; any answer but `y` or `yes`
exits without building an Arm or starting a Trial, and a new Experiment
leaves no record. In release mode the Baseline probe comes first and may build
the last release's Arm. `--yes` skips the question,
and so does a stdin that is not a terminal. `scripts/release.sh
--with-experiment` passes `--yes`, so a release asks only its own question.
There is no cost ceiling in the Bar: the cost is already bounded by Trials
times the timeout.

Each new Experiment freezes a dated token price table. `--prices <file.json>`
supplies another table with exact observed Model names and USD rates per million
input, output, cache-read and cache-write tokens; otherwise it uses the bundled
standard-rate snapshot. The table cannot change once a Trial starts. Every
session, including a Resume or fallback, is priced and attributed to its starting
Step. Missing usage or a missing Model price makes the Trial Void with an
accounting-gap cause. Arm totals include all attempts; paired median
Candidate-to-Baseline cost and time ratios use matching complete, non-Void Trials.
Time spent paused at a usage limit between invocations is excluded. Harness-reported
costs remain separate from these frozen comparison prices. See the
[Experiment accounting format](experiment-results.md) for the table and result fields.

`--name <text>` saves a name with the Experiment: one line of at most 100
characters, trimmed. An empty or over-long name is refused before any build.
`thirdshift experiments <id> --name <text>` renames a saved Experiment in any
state, even while it runs; `--name ''` clears the name. The name is not part of
the Bar, so it never changes Trials, Scores or the Verdict and never stops a
resume. The resume command an Experiment shows leaves `--name` out, so
following it keeps a later rename. Without a name, an Experiment is called `A/A at <ref>` when both Arms
share their build, Harness, Model and Effort, `Release <ref>` after `--release`,
and otherwise by what differs between its Arms. The CLI list, `experiments
<id>` and the Console's Experiment pages and tab title show the name;
`--json` gives it as `name`, with `name_set` saying whether you gave it.

`thirdshift experiment --release <commit>` uses the last reachable `v<version>`
tag as its Baseline and selects suites touched since that tag. `--baseline`
and `--suite` do not apply in this mode. When no suite is touched, or the last
release's build has no Trial flag, it prints a note and succeeds without an
Experiment. With `--json`, these cases return `release_skip` (`no_suites` or
`baseline_without_trial`) and `reason`; otherwise the ordinary Experiment
result and resume rules apply.

Each Arm accepts `--baseline-harness`, `--baseline-model`, `--baseline-effort`
or the corresponding `--candidate-*` flag, followed by a value. Unspecified
choices follow the User config, then the Harness defaults. Both builds must
support the [versioned Trial protocol](https://github.com/JacobStephens2/thirdshift/blob/main/docs/trial.md).
Both Code review and Spec review Eval tasks run. Code review Trials use the
production code-review Factory skill on the historical diff and retain both
axis reports without fixing or publishing anything. Spec review Trials keep
the production Spec review prompt. They have no PR service: `gh` calls fail
inside the sandbox and only their reports are graded.

Process Eval tasks run each Arm's Process at the task's base commit, stopping
before its first publishing Step. `--baseline-process <name-or-file.toml>` and
`--candidate-process <name-or-file.toml>` select a Built-in or Custom process;
both default to the Built-in `ticket-run` with `implement` and `security-review`.
Preparation freezes the Process file and referenced home skills by SHA-256,
recording each Step's Harness, Model and Effort in the Experiment's description.
Custom process and home-skill content also identifies the Arm: editing either
starts a new Experiment and uses separate cost-estimate history. Repeating the
command with unchanged inputs resumes its frozen Experiment.
Each Trial gets its own copies in its fresh home. Both Arms' frozen files are
checked before every Trial; a mismatch pauses the Experiment with the filename.
A Process needing GitHub before publication is refused at start. The Trial
publishes nothing and creates no factory run of its own. Its Steps and all
sessions appear in the Experiment's Trial Peek and Trace. Process outcomes are
delivered, stopped-to-ask or failed, with the existing Void causes.
Stopped-to-ask counts as failed; each Arm's outcome counts appear beside the
Verdict. A delivered Trial passes only when its code Grader passes both the
fail-to-pass and pass-to-pass selectors. The Grader exports the Trial's final
commit and overlays the reference fix's test files and changed shared test
fakes, replacing any Trial edits to those files. Python selectors search
the repository after the standard library, so a committed module cannot
replace one. Selectors run offline in bwrap, sharing the Bar's timeout with
preparation of the final-commit snapshot,
and their failures name the selector in
the Score's reason. The task's required `process_grading` table declares the
files and selectors; see [Eval task manifests](https://github.com/JacobStephens2/thirdshift/blob/main/docs/eval-tasks.md).

When the task's `process_grading.new_tests` table says how to find and run an
Arm's own new tests, each pair of Trials (Baseline Trial *k* with Candidate
Trial *k*) also gets base-tests and cross-tests once both Trials finish. Each
Arm's new test files, those its final commit adds or changes that match the
table's paths, run on the unchanged base and against the other Arm's final
commit, offline in the code Grader's sandbox, each run within the Bar's
timeout. New tests that pass on the base may not check the change. A
cross-test failure is a disagreement to look into, not a defect: this evidence
changes no Score and no Verdict. A run cut short by the timeout, or whose
snapshot could not be prepared, decides nothing either way. The Console's
Experiment page lists it under Pair evidence. The text view adds a line for
each disagreement, new test that passes on the base, run that did not finish
and evidence that could not run. `thirdshift experiments <id> --json` keeps it
under `pairs`, with each Arm's whole change since the base.

Each pair with evidence can also be read blind, one person at a time. The
Experiment page's **People's calls** section links each pair's page, which shows
the Ticket, its acceptance checklist numbered from 1, the two changes side by
side with code before tests, and each change's evidence. The sides, A and B, are
drawn for each pair from the Bar's seed, and the page names no Arm, build,
Harness or Model and shows no model call. First make a sealed merge call for
each side, ready or not ready; then give a preference (A, B, tie or both bad)
and, optionally, the rubric: which change better does what the Ticket asks
(`correctness`), has proportionate tests that check the change (`tests`) and
keeps to what was asked (`scope`). The preference and rubric are refused until
both merge calls are sealed, and sealed calls can't be made again until you
have given that preference. Every call is a new record, attributed to you and
never changed, so reading a pair again adds a second review; one begun after
your reveal is marked as not blind and left out of people–panel agreement.
Once you have given
a preference, the page shows which Arm made each side, the Grader panel's calls
when it has read the pair, and every reader's calls. In the shell:

```sh
thirdshift experiments <id> --pair <pair-id>
thirdshift experiments <id> --pair <pair-id> --merge ready not-ready
thirdshift experiments <id> --pair <pair-id> --prefer a --rubric scope=tie
```

People's calls, in Arm terms, and their agreement with the panel's merge calls
and with each other show beside the Verdict on the Experiment page, in the text
view, and under `people` in `--json`. They change no Score, and change the
Verdict only when the Bar counts them.

A Grader panel can also grade each pair of process Trials. Name its seats in
the Bar, one `--panel-seat` per Harness and Model, several per family allowed:

```sh
thirdshift experiment <candidate> \
  --panel-seat harness=codex,model=gpt-5.5,effort=high \
  --panel-seat harness=kimi,model=kimi-k3.1-pro \
  --panel-seat harness=claude,model=claude-opus-5-5
```

Each seat reads every pair in a blind packet twice, once in each presentation
order, in fresh sandboxed sessions. The packet holds the Ticket, the success
criteria, a rubric, and for each side its outcome, its diff against the base and
its Pair evidence, with the sides labelled A and B at random and swapped for
the second order. For each side the Grader rates each rubric criterion with
evidence and makes a merge call, then gives its reason and a preference: A, B,
tie or both bad. A call that flips with the order is a tie. A seat's family is
its provider: the Harness's own, or the provider an OpenCode Model names.
The panel votes one vote per family by default, each family taking its own
majority first; `--panel-vote model` gives each Model a vote, with seats
naming the same Model taking their own majority first. A seat from
either Arm's family is reported but doesn't vote while a seat from another
family sits on the panel; `--panel-arm-family-rule off` lets it vote. A call
needs more than half the votes, otherwise it is a tie, and a tied merge call is
not ready. Every seat's calls and the panel's result are reported beside the
Verdict, in the text view and under `panel` in
`thirdshift experiments <id> --json`; they change no Score and no Verdict
unless the Bar counts them.

The Bar fixes who decides the Verdict before the first Trial. The panel and
the people are each off, beside the Verdict or counted in it: `--panel off`,
`beside` (the default with seats) or `counted`, and `--people off`, `beside`
(the default) or `counted`. Name each reader with `--people-reader`, as the
Console or the CLI names them (a Console address, a token's person, or a Unix
user). `--people-sample <n>` gives each reader `n` pairs drawn from the Bar's
seed, and `--people-overlap <n>` how many of those every reader shares; with
no sample, every reader reads every pair. Each reader's queue lists their pairs
on the Experiment page, in the text view and under `people.queues` in
`--json`, and the Experiment refuses a sample larger than it has pairs, or
readers when a process Eval task has no pair evidence to read:

```sh
thirdshift experiment <candidate> \
  --panel-seat harness=codex,model=gpt-5.5 \
  --panel-seat harness=kimi,model=kimi-k3.1-pro \
  --panel counted --people counted \
  --people-reader ann@example.com --people-reader bo@example.com \
  --people-sample 7 --people-overlap 4
```

When the panel or the people are counted, a process Trial passes only if its
Score passes and whoever decides its pair calls it ready to merge. People's
call is each reader's latest blind merge call; on a pair two readers share, it
is ready only if both say so. With only the panel counted, its calls decide
every pair and people's calls calibrate it. With only the people counted on a
sample, the Verdict rests on the sampled pairs alone, each pair a unit, and a
small sample usually comes out inconclusive rather than wrong. With people
counted on every pair, their calls decide every pair. With both counted, the
panel stands in on the pairs people didn't read. That needs a voting panel
spanning `--panel-families` families (two by default), or the Experiment
refuses to start, and people–panel agreement on the sample of at least
`--panel-agreement` (0.8 by default) of the merge calls compared, or the
Verdict is inconclusive and says why. While a reader has a pair still to call,
the Verdict is `waiting_on_people`; each call recalculates it once the
Experiment has completed. The Verdict says who decided it and on how many
pairs. People–people agreement on shared pairs and people–panel agreement are
reported in every mode.

The estimate shown before the Trials includes the panel: for each seat, its
remaining sessions (pairs × 2 orders) and their expected cost, priced from the
Experiment's frozen price table. A seat is priced at the mean of its sessions
measured in this Experiment once there are some, and otherwise at an assumed
session of 400k input tokens (80% of them cache reads) and 15k output tokens.
A seat whose Model has no frozen price is listed without one. Panel spend is
reported apart from the Arms' cost, in the text view and under `panel_spend`
in `--json`, and never counts toward an Arm's cost or the Bar's
`--cost-ceiling`. `--panel-spending-limit 25` caps what each run of the
Experiment spends on panel sessions, in USD: once this run's priced panel
sessions reach it, grading pauses before the next session, as it does when a
Grader is unavailable. A panel session that can't be priced, because its
Model has no frozen price or it reported no usage, also pauses grading while a
limit is set, since the limit can't count it; its call is kept. Resuming gets
the limit afresh and continues from the calls already made; none is graded
again. When every Trial has run and only panel calls remain, the estimate lists
just the panel and a terminal asks `Run the remaining Grader panel sessions?`.

Before that estimate or any new paid work, resume reads every expected saved
panel call, including later seats and orders behind a missing call. An unreadable
or malformed call stops the command with its pair, seat and order, even with
`--yes`; only a missing file is pending work. Correct the retained-call problem
before resuming. Reports use the same completion facts and show a pair only
once every seat has both saved orders.

After each process Trial, thirdshift searches its Session traces for the
real fix's merge commit (including abbreviations of at least seven characters),
pull-request and issue references, branch and title. Matches appear as leak hits
on the Console's Experiment page and in `thirdshift experiments <id> --json`.
The Verdict waits on these hits, including hits from measurement-only tasks.
Review the linked Session evidence, then dismiss a false positive or confirm a
leak in the Console, or use:

```sh
thirdshift experiments <id> --leak <hit-id> dismiss --reason 'False positive'
thirdshift experiments <id> --leak <hit-id> confirm --reason 'Saw the real fix'
```

Each decision retains the reviewer, time and reason. Dismissals keep the Trial
and remain on the auditable list; confirmation makes the Trial Void and drops
its paired Eval task from the Verdict. Original results and Session traces remain
unchanged. Decisions require the Experiment to have stopped and cannot be
overwritten. A confirmed leak is excluded when the Experiment resumes.

The Bar is saved before the first Trial: margin `-0.10`, pass level `0.70`, fail level `0.95`,
prior `1`, seed `0`, `20000` draws, each suite's Trials per Eval task, an
Advisory minimum of `20` discriminating Eval tasks, an `1800`-second per-Trial
timeout, and up to two fresh retries for Void Trials.
Override these with `--margin`, `--pass-level`, `--fail-level`, `--prior`, `--seed`,
`--draws`, `--trials-per-task`, `--min-discriminating-tasks`, `--timeout` (seconds), or `--void-retries`.
The Grader panel's `--panel-seat`, `--panel-vote`, `--panel-arm-family-rule`,
`--panel-spending-limit`, `--panel`, `--panel-families` and `--panel-agreement`,
and the people's `--people`, `--people-reader`, `--people-sample` and
`--people-overlap`, are part of the Bar too; it has no panel by default, and
anyone may read any pair beside the Verdict.
Both levels are credible levels strictly between zero and one. Changing
either level after the first Trial is refused, as with the rest of the Bar.

Optional `--cost-ceiling 2` and `--time-ceiling 2` cap the paired median
Candidate/Baseline ratios at 2×. Both are off by default and fixed with the Bar;
a ratio above either set ceiling fails the Experiment. Unmeasured ceilings
cannot pass. Quality statistics still follow ADR-0025. When quality passes,
the Verdict adds "cheaper" or "faster" when the paired ratio's pass-level
Bayesian bootstrap interval lies below 1 (at least two paired tasks), or says
"costs more" or "takes longer" when its median exceeds 1. JSON `verdict.line`,
the text view and the Console show the same line. See the
[resource comparison rules](experiment-results.md#verdict-and-bar).

The default pass level is the highest at which an A/A Experiment at the
measured disagreement rate passes at least 80% of the time on each suite at
its size, but never below 70% (#1268). #1370's A/A Experiment measured these
rates, as paired task differences:

| Suite | Size | Accuracy disagreements | Wrong-finding disagreements |
| --- | --- | --- | --- |
| `code-review` | 10 tasks × 3 Trials | 2 of 10 tasks (one by two Trials, one by one) | none |
| `spec-review` | 30 tasks × 1 Trial | 5 of 30 tasks | 2 of 30 tasks |

No pass level from 70% to 95% reaches 80% on either suite at today's size, so
the default is the 70% floor; without ADR-0024's upper-bound clause a higher
pass level only lowers the pass rate. Simulated A/A Experiments at those rates,
each judged by the Verdict at a 70% pass level, pass this often under the
current rule ([ADR-0025](adr/0025-a-pass-needs-only-the-margin.md)) and
ADR-0024's rule, whose pass also needed the pass-level upper bound to reach zero:

| Suite size | `code-review`, ADR-0025 | `code-review`, ADR-0024 | `spec-review`, ADR-0025 | `spec-review`, ADR-0024 |
| --- | --- | --- | --- | --- |
| Today (10 / 30) | 67% | 67% | 56% | 46% |
| 40 | 94% | 86% | 67% | 53% |
| 60 | 97% | 85% | 76% | 61% |
| 80 | 98% | 86% | 84% | 68% |
| 100 | 98% | 86% | 89% | 71% |

#1370's own counts give these 70% intervals: `code-review` accuracy
[−0.171, −0.018] and wrong findings [−0.039, +0.039]; `spec-review` accuracy
[−0.042, +0.108] and wrong findings [−0.047, +0.048]. At 95% (before #1268),
the A/A pass rates were 0% and 13%.

Both suites fall short at today's size. `code-review` needs about 20 Eval tasks
(between today's 10 and the table's 40) to reach 80% at 70%, and #1434 grows
it. `spec-review` needs about 80. Under
ADR-0024's rule `spec-review` could not reach 80% at 70% at any size: for
identical Arms a 70% interval's upper bound falls below zero about 15% of the
time per noisy metric, capping the pass rate near 72%.

`--void-retries` accepts zero, one or two. A sandbox that cannot start, a
provider connection or login failure, a provider server error before work,
provider capacity or overload errors, a plan-limit stop, or a host kill or
Trial-only memory cap makes a Trial void.
Timeouts, context-window overflow, refusals and agent failures count as failed
Trials. Void Trials retry fresh up to the Bar's limit and remain void if
exhausted. A task still void in either Arm drops out of both Arms.

Usage/rate limits, including provider capacity and overload errors, pause
scheduling until the same Experiment is started again.
Claude or Codex quota windows at 85%, or a Claude rejection, also pause it
immediately. Claude warnings continue when all readable windows are below 85%;
a warning with no readable utilization still pauses the Experiment. A Trial cut
short by a quota stop is void; a Trial already running on the other worker may
finish, but neither worker starts another Trial or retry. Ordinary Runs do not
stop at these warnings.
The Experiment watches each Trial with the current detectors, including when
an Arm's build predates warning detection.

Two workers take alternating Baseline and Candidate Trials, each in a fresh
prepared repository. Before the session, the host installs that repository's
pinned Rust toolchain from `rust-toolchain.toml` or `rust-toolchain`, including
its listed components. Trials with the same pin share one preparation across
both workers. An installation failure makes the Trial void with
`session_unavailable`; it does not count as failed. The sandbox's network
allowlist stays unchanged. Trial artifacts and one result per finished Trial live
privately in `~/.thirdshift/evals/experiments/<id>/`. Trials run in a bwrap
sandbox with a fresh home and provider-only network. Code Graders then score each Trial:
for review Trials, editing or deleting `.thirdshift-issue.md` or a declared input, moving the Base
branch, or altering or removing the base or prepared change commit makes an
otherwise successful Trial void with `repository_changed`. Issue branch commits,
pushes to the local origin, reports and other working-tree files are allowed.
A review with no reports fails, and the Eval task's mechanical checks must pass.
Those checks run on a private copy of the prepared repository captured before
the session, so the session cannot change the code they grade. Checks share
their own build artifacts. Scores retain each check and its reason.
For review Trials, a fresh model Grader then scores one blind packet per Eval task against its
written success criteria. Each packet holds every Trial's review reports with
shuffled neutral labels and identifying Harness, Model, Effort and Arm lines
removed. Graders see report text, never Trial paths or raw session streams.
When an installed Harness has a configured Model from a family neither Arm
runs on, as the Grader panel's family rule reads it, that Model grades;
otherwise the User config's default choice grades. The
Grader choice and executable are fixed before Trials start. Model Graders run
in the same sandbox, seeing only their packet workspace. Code Graders run
offline with their report packet and prepared repository. Neither can read
Trial logs, Arm mappings or the Experiment's other files. An unavailable
model Grader pauses grading without publishing Scores; resume reuses Trials.
`THIRDSHIFT_TRIAL_NO_SANDBOX=1` selects the pass-through launcher for tests
and emergency use, for both Trials and Graders.

Each Trial and each Grader runs in a scope of its own, with the `[trial]` caps, and raises its own `oom_score_adj` to the maximum, so it gives way before the factory under system-wide memory pressure. A Trial its cap kills dies alone and is void with `memory_cap`, from the scope's `memory.events` or journal evidence. An agent's own out-of-memory error stays failed. Each code check has its own Grader scope and the Trial timeout. A Grader killed by its cap stops the Experiment with a diagnostic so you can raise the cap and retry.

Each Trial retains the model's pass/fail, reason, wrong-finding flag and
borderline mark beside its mechanical checks. A mechanical failure still fails
the Trial. Wrong-finding flags enter the paired Verdict; the Verdict also shows
the number of borderline Trials for rechecking, without changing the Bar.
Packets, Grader session output and validated Scores stay in the private
Experiment directory. Grader sessions retain OTLP log records and spans, model
evidence and stderr there, including after interruption or timeout. A failed,
incomplete or malformed Grader response pauses the Experiment; resuming retries
grading without rerunning finished Trials,
and reuses already validated Scores.

The Verdict stays `waiting_on_rechecks` until you have rechecked every borderline
Score and every decisive Score on the Bar's judged list in suites that are not
advisory. A Score is decisive when flipping its pass/fail
or wrong-finding flag changes the Experiment's pass/fail/inconclusive decision
under the fixed Bar. Scores from a task dropped as void are excluded.
`thirdshift experiments <id> --json` lists these under `pending_rechecks`, with
each Trial's `id`, suite, task, Arm, Trial number and borderline/decisive flags.
`decisive_flips` names `passed`, `wrong_finding`, or both;
`decisive_verdicts` maps each named flip to the provisional Verdict it would
give (`pass`, `fail` or `inconclusive`). These are separate one-flag flips,
not both flags flipped together. A Score pending only because it is borderline
has an empty list and map.
The text view lists the same IDs. `verdict.provisional_verdict` and suite
intervals show the calculation while `verdict.verdict` waits.

Read the Trial's reports and record your decision:

```sh
thirdshift recheck <experiment-id> <trial-id> pass --reason 'The report meets the written criteria.'
thirdshift recheck <experiment-id> <trial-id> fail --reason 'This finding is wrong.' --wrong-finding true
```

Your latest recheck supplies the pass/fail used in the Verdict; the optional
`--wrong-finding true|false` corrects that flag too. Omission retains its last
value. Each Trial's `score` keeps the original Grader's decision, checks and
model evidence, with your timestamped decisions and reasons in `score.rechecks`.
Rechecking again appends to that history. The command atomically saves the
history and recalculated Verdict, then prints the updated Experiment, with
`--json` available. A changed Score can make another Score decisive, so consult
the updated pending list. Trials and Graders never rerun for a recheck, and the
Bar stays fixed. An Experiment being run or rechecked refuses concurrent writes.

To record the same decision and reason for every Score on a reviewed list:

```sh
thirdshift recheck <experiment-id> --pending --json
thirdshift recheck <experiment-id> --batch <fingerprint> pass --reason 'I checked every listed Trial against the written criteria.'
```

The first command lists every pending Score with its suite, Eval task, Arm,
Trial number, ID and borderline/decisive reason, plus a `fingerprint` of that
Experiment's list. Omit `--json` for text. The second command takes that
fingerprint and appends one timestamped recheck to each listed Score's history,
using one exclusive lock and one atomic save. It accepts `--wrong-finding` and
`--json` just like a single recheck. A stale fingerprint refuses the entire
batch without changing anything; list the pending Scores again and review
them before retrying. An empty pending list refuses a batch too. The batch
only covers the reviewed list: its decisions may make other Scores decisive,
so check the updated pending list afterwards. Rechecks stay in the CLI.

Each suite gets a paired Verdict using its recorded Trials per Eval task (one
or three). For each metric, fail when the upper bound at the fail level is below
zero. Otherwise pass when the lower bound at the pass level is above the margin;
otherwise the metric is inconclusive. A pass whose whole pass-level interval is
below zero is reported as worse, within the margin: in JSON as
`worse_within_margin: true` on that metric, in the text view after the Verdict
and in the Console. It doesn't change the decision.
One set of draws supplies both intervals. Both accuracy and wrong findings must
pass; either can fail the suite. The prediction of how many more Eval tasks
would settle an inconclusive metric uses the same two-level decision.
Among suites that are not advisory, any failed suite fails the Experiment;
otherwise any inconclusive suite makes it inconclusive. More than a tenth of their
judged Eval tasks dropped as void also makes it inconclusive. When every suite is
advisory, the Experiment is inconclusive. Results include the suite intervals, the Bar and
each Arm's minutes across all attempts, including Void Trials and timeouts.
The code-review suite runs three Trials per Arm per Eval task by default; the
Spec-review suite runs one. For three-Trial suites, `experiments --json` reports
`pass_cubed`: the share of retained Eval tasks where all three Trials passed,
separately for each Arm.
The Bar's JSON carries `pass_level` and `fail_level`; each metric carries
`pass_interval` and `fail_interval`. New Verdicts use `paired-dirichlet-v4`, and
their Bar records `"pass_rule": "margin"` and `discriminating_tasks` per suite.
Saved Experiments without `min_discriminating_tasks`, including earlier v4
Experiments, keep their original Bar, Verdict and aggregation policy when read
or resumed; their suites omit `advisory`.
Saved Experiments under `paired-dirichlet-v3` keep judging all their retained
Eval tasks, with their stored Bar and Verdict. Saved Experiments under
`paired-dirichlet-v2`, whose pass also needed the pass-level upper bound to
reach zero, keep that rule and their stored Bar and Verdict when read, and
when resumed with the same levels. Saved Experiments under `paired-dirichlet-v1`
remain readable with their stored single-level Bar and Verdict unchanged. See
[ADR-0024](adr/0024-pass-and-fail-use-separate-levels.md) and
[ADR-0025](adr/0025-a-pass-needs-only-the-margin.md).
The judged-list decision is recorded in
[ADR-0026](adr/0026-judge-the-recorded-discriminating-tasks.md).
For a paused single-level Experiment, its saved view and Console show a resume
command using both recorded levels in place of the removed `--credible-level`
flag. Reading that command does not rewrite its stored Bar or Verdict.
Provider usage/rate limits pause scheduling until the same Experiment is
started again, consuming the same fresh-retry budget across resumes. Completed
attempts count toward minutes and per-Arm Void totals even while paused or
after resume. Stop preserves completed attempts and the remaining budget.
Recovery applies the saved Bar's Void cause list as well as its retry count,
including older saved lists. Pending history that is already terminal publishes
without another attempt after a publication failure. A newly completed limit
or interrupted Void checkpoints before pausing, even on the last attempt;
resuming exhausted history finishes without replaying its old pause.

The same Arms and suite names identify the same Experiment. Running it again
skips finished Trials and re-runs interrupted ones; a completed Experiment only
reports its saved results. A changed Bar is refused after the first Trial.
That includes a changed discriminating list or any changed Difficulty reading
for its retained Eval tasks, even when the new reading stays inside the band.
`thirdshift experiments --json` lists them and `thirdshift experiments <id>
--json` shows one. Both use the versioned
[Experiment results format](experiment-results.md), identified by `format: 10`.
The starting command's `--json` ends with one JSON line
containing the Verdict and suite intervals alongside the Trial results and Arm
minutes. Both views also show each Arm's tokens by observed Model and its cost
in USD where the Harness reports one. JSON keeps these under `usage.baseline`
and `usage.candidate`, with `models` and `cost_usd`; missing measurements are
`null`, and tokens without a reported Model are grouped under `unknown`.
Input tokens include cache reads and writes, which are also shown separately.
Experiments and Run metrics share Session usage accounting. Partial Model totals
replace only reported fields: a call with 11 input tokens and 5 cache reads,
followed by a total reporting only 3 output tokens, keeps 16 inclusive input
tokens and 5 cache reads. A raw input total of 20 instead yields 25 inclusive
input tokens. A single matching Model can also be refined by Session totals;
whole-Session tokens spanning several Models are not distributed or added again.
Turn totals supply unknown-Model tokens only when call, Model and Session token
evidence is absent. Reported Session cost wins, including zero; otherwise each
Model's reported cost replaces its call-cost sum, retaining costs the total omits.
Totals include all attempts and Resume sessions; Grader usage is not charged
to either Arm. The text view shows usage beside each Arm's minutes.
Both views show Void counts and causes per Arm, and report repeated
Trial-only memory-cap stops as a finding against that Arm.

Each attempt keeps its request, result, start record, stdout, stderr, scope,
traces, Session reports and summaries, model evidence and native transcripts.
Harness caches in the Session home's `.codex/cache/`, `.cache/` and
`.local/share/muse/model-catalog/` are removed when the Trial session ends,
whatever its outcome. After grading finishes and
the Verdict has no pending rechecks, every attempt's `repository/` copy is
removed. Paused or interrupted Experiments keep their repositories for resume;
waiting rechecks keep them until the last recheck is recorded. Grader output,
packets and Scores stay in place, and `experiments <id>` and `--session` still
read the retained evidence. Pruning failures print a `warning:` without changing
the Verdict or exit status.

The Console's **Experiments** link opens `/experiments`, grouped into Running,
Needs you and Done, newest first within each, one line apiece with its accuracy.
Open an Experiment for what it tests, then its live Trial grid, per-suite
Verdict intervals, Arm comparison and Bar, each folded to a one-line gist. Select
a Trial or Eval task to open its Peek, including Grader reasons, rechecks,
Void causes and links to retained Session logs or Session traces. Both pages
pair with `experiments --json`; its view includes task names, active Trial start
times and the `sessions` inventory. Read one with
`thirdshift experiments <id> --session <session-id>` (add `--json` for exactly
`id`, `trace` and UTF-8 `contents`). The CLI and Console share the Experiment's
confined Session evidence reader. Reading one Session validates the saved
Experiment and selects its evidence without calculating accounting, reading
Trial metadata or upgrading a legacy Verdict. Healthy evidence remains readable
when unrelated Trial metadata or usage spans are corrupt. Session IDs stay the
same when raw logs become Session traces; converted log records take precedence.
Pending rechecks offer a
copyable CLI command and a filter for their Eval tasks; the Console records no
recheck itself. The page polls every two seconds, including after completion
so rechecks recorded in the CLI appear. Older records show unknown refs,
versions or end times where those facts were not retained.

Each invocation that does work keeps a Command record, Command log and Activity
log lines under `<logs.dir>/JacobStephens2/thirdshift/commands/experiment/`
(the Activity log is at the repository level). The record names both Arms and
the Bar and moves through Arm builds, Eval tasks and Trials. It appears in the
Inbox: a pass goes in Done, and a fail, inconclusive Verdict or waiting rechecks
go in Needs you. Rechecking a Score updates the latest invocation's Command
outcome and Inbox group alongside the saved Verdict, keeping its completion time.
Use the name from `status` with `thirdshift stop <command>` to Stop it.
The individual Trials keep no factory Command records.
Trial and model Grader Session traces and code Grader spans join the invocation's
Command Trace. Export it with `thirdshift logs <command> --export <dir>`; the
private Trial and Grader artifacts stay under the Experiment's Eval folder.
On resume, each invocation's Trace keeps the Trial attempts and Grader sessions
it started, while Arm totals cover the whole Experiment.
Older Arms with Session traces are joined after completion; Arms predating
Session traces contribute minutes only.

`version` and `help` print to stdout and exit `0`. `update`, `setup` and `email-test` follow the Ticket run's rule: stdout stays empty, messages go to stderr. `architect` follows it too: stdout carries the pull request's URL of the run it dispatches, or, in its place, the URL of the issue it ended on: its plan with `--plan-only`, or its idea when the review published no plan. A skipped Architect run prints nothing there when [another Command is still running](#the-command-limit), the URL of each Architect plan that is [still open](#one-architect-plan-at-a-time), the URL of each [Architect idea waiting for triage](#an-architect-idea-waits-for-triage), and the URL of the [Ready issue, or issue still settling, that goes first](#a-ready-issue-goes-first). `pickup` follows it as well: stdout carries the pull request's URL of the run it dispatches, and nothing when the [Pickup run](#pickup-runs) is skipped. So does `secure`: stdout carries the pull request's URL of a fix it dispatches, and nothing otherwise.

Uncommitted changes in your clone are fine: the Ticket run works in its own worktree from `origin`, so they are simply left out. Unpushed commits on the Base branch are not: push them first, or the Ticket run stops.

### Host resources

`thirdshift resources` (or `thirdshift resources --json`) reports this host's available and total RAM in MB (1,000,000 bytes), logical CPU count, one-minute load average, configured limits and whether another session may start. The Console's **Resources** page shows the same snapshot; reload to update it.

Every Console reader page also shows the host's session admission status below
the notification control in the top right. It links to Resources and refreshes
every ten seconds while the page is visible. **Host ready for another session**
means the configured limits currently pass; **Host busy · new sessions wait**
means a limit blocks new sessions. **Host limits off** means neither limit is
configured, and **Host resources unavailable** means the status could not be
read. Without JavaScript, reload to refresh it. This indicator checks host
resources only; it does not reserve capacity or check repository Pass gates.

Set `[resources]` in `~/.thirdshift/config.toml` to delay new sessions when this machine is busy:

```toml
[resources]
min_available_memory_mb = 2048
max_load_per_cpu_percent = 100
```

Both settings default to `0`, disabling that limit. Values are nonnegative whole numbers; `max_load_per_cpu_percent` is at most 4,294,967,295. A load limit of 100 permits a one-minute load of 8 on eight logical CPUs. Load includes runnable work and, on Linux, tasks waiting for IO; it is not instantaneous CPU usage.

Before every session, including a Resume, Repair, Security review or a preflight Model test call, thirdshift checks the host. If available RAM is below the minimum or load per CPU exceeds the maximum, it reports why and waits, rechecking every ten seconds. Running sessions continue. Limits are read again on every check, so editing the config can release a waiting Command. Stop or Ctrl-C interrupts the wait through normal cleanup. A failed resource read with limits enabled fails the Command rather than starting a session without a measurement.

These are host snapshots, not resource reservations or per-session budgets: simultaneous Commands may both pass a check, and container quotas are not measured. `spec.parallel` still sets the upper bound on parallel Ticket runs. Limits apply to sessions; they do not prevent worktree preparation or Claims.

### Standalone skills

Run one skill without starting a Run:

```sh
thirdshift skill to-spec issue 42
thirdshift skill thirdshift-code-review
thirdshift skill my-repository-skill
```

The command uses the User config's default Harness, Model and Effort. It looks
up `<name>` in order. First a Factory skill whose directory is exactly
`<name>`. Then the repository's committed `.agents/skills/<name>/SKILL.md`, or
`.claude/skills/<name>/SKILL.md` when only that copy exists; `.agents/skills`
wins when both exist. Then `~/.thirdshift/skills/<name>/SKILL.md`. Then the
Factory skill `thirdshift-<name>`. A skill file that resolves outside the
directory being searched is not a match, so a symlink cannot select
instructions from somewhere else. A repository skill wins over the home skill
of the same name. An unknown name lists the available skills and starts no
session. The optional issue is an Issue URL or a positive number resolved from
`origin`. An Issue URL from another repository is an origin mismatch and stops
the command before any work.

The session runs in a temporary worktree at the head of the checked-out branch,
with the Factory skills available, and with each home skill linked under its
own name in that same project skills directory. The link points at a copy
written out beside the Factory skills. A Trial binds that folder and not
`~/.thirdshift/skills`, so the session reads the copy; the prompt still names
the home file, which is where the skill was found. A repository skill of the
same name is left in place. Each linked home skill is kept out of git by its own
`.git/info/exclude` entry, added once and left there, as the Factory
`thirdshift-*` pattern is ([ADR-0012](adr/0012-factory-skills-linked-into-the-worktree-codex-unsandboxed.md)).
Uncommitted changes in your checkout stay out of it. Your checkout stays
untouched. The final message goes to stdout; progress,
failure causes and the path of any retained worktree go to stderr. A completed
session exits `0`; a failed or incomplete session exits non-zero.

The worktree is kept when it has uncommitted changes, commits absent from all
remote-tracking branches, or uncertain ownership. Otherwise it is removed. No
Command record, Console entry or Session log is created for a standalone skill.

### Custom processes

A Custom process runs Steps in order, and can run consecutive Steps together.
A Step is a skill session, a command, or a catalogue Step. It is
experimental. Write `~/.thirdshift/processes/<name>.toml`. The name is the
file's stem.

`thirdshift process list` (or just `thirdshift process`) lists Processes with
their descriptions, marking compiled-in Built-in processes as `(built-in)`.
`thirdshift process show <name>` prints the file exactly, so it can be saved
under a new name in `~/.thirdshift/processes/` as a starting point.
Built-in process files live in the repository's [`processes/`](../processes/)
folder and are compiled into the binary, like Factory skills (ADR-0001).
They use the same format and validation as Custom processes. The built-in
`ticket-run` runs `implement` → `security-review` → `delivery` → `self-merge`,
inheriting the Command's Harness, Model and Effort, Child asks and Limits.
Ticket runs execute it by default, including those started by Spec, Architect
and Security runs. The command and User
config still decide whether the Security review and Self-merge run. The
Command keeps its Ticket run identity, sessions and progress lines.
Inspect it with `thirdshift process show ticket-run`, or validate it with
`thirdshift process check ticket-run issue <issue>`. Save the printed file
under a new name to run it as a Custom process.
A Custom process cannot take a reserved Built-in process name.

The Built-in `spec-run` owns `land-tickets` → `spec-review` → `security-review`
→ `delivery` → `self-merge` on a `spec-branch` worktree, inheriting the Command's
Harness, Model and Effort, Child asks and Limits. Every starter of a Spec run
uses it: an Issue URL, Pickup, Architect and Security runs, and
`run-published-issue`. Spec-or-Ticket dispatch and the Claim stay before the
file; the Command keeps its Spec run name, sessions and progress lines.
Inspect it with `thirdshift process show spec-run`, or validate it with
`thirdshift process check spec-run issue <spec>`. Save the printed file under
a new name to run a Custom process on a Spec.

The built-in `architect-run` runs `architecture-review` → `run-published-issue`.
Architect runs execute it after their Command limit, the lock of their kind
and skip gates. The first Step owns the review session and the plan-or-idea
conclusion and labels; it ends
successfully on an idea in the repository at origin, or with `--plan-only`.
An idea outside that repository is refused before it is viewed or labelled.
Otherwise the second Step runs
the published plan. Inspect it with `thirdshift process show architect-run`
and validate it with `thirdshift process check architect-run`. A copy saved
under a new name runs as a Custom process, following the Command limit without
a lock of a kind or the Architect run's open-plan, waiting-idea or Ready-issue gates.

The Built-in `security-run` owns `security-audit` → `reproduce-findings` →
`fix-findings` → `close-findings`, inheriting the Command's Harness, Model and
Effort and limits. Its Command limit, the lock of its kind and Ready-issue,
failed-fix and unchanged-Base skip gates stay before the file. The first two
Steps skip when an earlier
reproduced finding awaits an allowed fix; fixing and closing retain their
permission gates. The Security run fixes at most one finding per invocation,
and closes only that finding after its fix merges and its proof passes.
Inspect it with `thirdshift process show security-run` or validate it with
`thirdshift process check security-run`. A copy under a new Custom process
name follows the Command limit without a lock of a kind and can fix several findings.

Pickup has no Process file: it selects and reserves a Ready issue, then
dispatches `ticket-run` or `spec-run`.

Every skill Step gets one Resume if its session ends with background work
still running that was killed with it, using the same Session prompt and
rules as a Ticket run. If the Resume ends the same way, a progress line
names the killed work and the Process carries on. Following Steps decide
the outcome; if the Process then fails, its cause names that work ahead of
the failing Step. A Resume does not count against the Process's Repair cap.

```toml
version = 1
description = "Gather notes, then review them"

[[steps]]
name = "gather"
command = "printf 'notes for review\n'"

[[steps]]
name = "review"
skill = "thirdshift-code-review"
harness = "codex"
model = "gpt-6.1-sol"
effort = "high"

[[steps]]
name = "extra"
command = "false"
optional = true
```

With no `[worktrees]` table, every Step shares one throwaway worktree. To run
Steps at the same time, declare a throwaway worktree for each and give
consecutive Steps the same `parallel` group:

```toml
version = 1
description = "Three families, then a judge"

[worktrees.claude]
kind = "throwaway"

[worktrees.codex]
kind = "throwaway"

[worktrees.grok]
kind = "throwaway"

[worktrees.judge]
kind = "throwaway"

[[steps]]
name = "claude"
skill = "thirdshift-code-review"
worktree = "claude"
parallel = "families"

[[steps]]
name = "codex"
skill = "thirdshift-code-review"
worktree = "codex"
parallel = "families"

[[steps]]
name = "grok"
skill = "thirdshift-code-review"
worktree = "grok"
parallel = "families"
optional = true

[[steps]]
name = "judge"
skill = "thirdshift-to-spec"
worktree = "judge"
```

One worktree may instead be an Issue branch, and one Step may publish it:

```toml
version = 1
description = "Ship a fix"

[worktrees.fix]
kind = "issue-branch"

[[steps]]
name = "implement"
catalogue = "implement"
worktree = "fix"

[[steps]]
name = "ship"
catalogue = "delivery"
worktree = "fix"

[[steps]]
name = "land"
catalogue = "self-merge"
worktree = "fix"
```

```sh
thirdshift process check ship issue 7
thirdshift process ship issue 7
thirdshift process ship issue 7 merge
```

A declared worktree's `kind` is `throwaway`, `issue-branch` or `spec-branch`. A throwaway
worktree is detached at the Base branch. An Issue-branch worktree is the
Issue branch a Ticket run would use for the issue the command names:
`issue-<n>`, then `issue-<n>-branch-<k>` for k ≥ 2. A Continuation reuses
the existing branch, and an open pull request's base is the Base branch.
Session Steps in that checkout are told to build on its commits. A
Process has at most one Issue-branch worktree. The Steps that name it run in
that checkout. Any other declared worktree stays throwaway.

A Spec-branch worktree uses the Spec's Issue branch and the same Continuation
rules. A file can declare one Issue-branch or one Spec-branch worktree, never
both. Both need an issue: a Spec-branch file requires sub-issues, and an
Issue-branch file refuses an issue that has sub-issues, before any session.
The Claim is made before acquiring either branch worktree.

`catalogue = "land-tickets"` runs the Spec run's whole Ticket loop on a
Spec-branch worktree: push the Spec branch, start Tickets in dependency order,
re-read the graph after each ending, and open a draft Spec PR on the first
landing, updating its Tickets checklist. `spec.parallel` in the User config
sets how many Tickets can run at once. Closed Tickets, Tickets in another
repository, Unready Tickets, Specs, blocked Tickets and Tickets that fail the
Trusted-account checks cannot start. A failed Ticket stops only its dependents;
any Ticket not done fails the Step. When the Spec is only waiting, as a
[Spec run](#spec-runs) can be, the Process's Claim is handed back as a Spec
run's is, with no `agent-failed`. The optional `process = "<name>"` setting
selects every child Ticket's Process, defaulting to `ticket-run`; the named
Process must exist and declare an Issue-branch worktree. Child Tickets inherit
the Step's Harness, Model and Effort and the Process's Repair cap and protected
paths. The Step is required, outside a parallel group, and returns the draft
Spec PR URL after updating the local worktree from the landed Spec branch.
It leaves the Claim while the Spec waits for completion.
Spec-branch cleanup keeps uncommitted work and commits absent
from the remote-tracking branches in the local worktree and branch, and names
the retained path. Inspect and publish that work before retrying.

```toml
version = 1
description = "Gather a Spec's Tickets"

[worktrees.spec]
kind = "spec-branch"

[[steps]]
name = "land"
catalogue = "land-tickets"
worktree = "spec"
process = "ticket-run"
```

Run it with `thirdshift process <name> issue <spec>`. This Step gathers the
Tickets; it leaves the Spec PR draft for subsequent review and Delivery.

Follow `land-tickets` with `catalogue = "spec-review"` on the same Spec-branch
worktree to run the Spec review over the whole Spec against the Base branch.
It uses the Spec run's prompt and report contract, and takes its own Harness,
Model and Effort. The Step must be required, outside parallel groups, and
after `land-tickets`. Then `security-review` → `delivery` → `self-merge` on
that worktree deliver the Spec PR with the same flag and User config gates
as a Spec run. Delivery restores the Tickets checklist after the review
rewrites the PR body, runs the Repair loop and marks the PR ready. A failure
preserves the work and leaves an open PR draft; a Security hold leaves it
ready for review. A delivered Spec PR removes the Claim. The Built-in Spec
run reads this sequence from `spec-run.toml`.

`catalogue = "implement"` runs the same implementation session as a Ticket
run, using its fresh or Continuation prompt. It must name the Issue-branch
worktree, and takes its own Harness, Model and Effort like other Steps.
On a `bug` issue it diagnoses before fixing, reproducing at the merge base
when the Issue branch is ahead of the Base branch. A reproduced bug goes on
to the later Steps. An unreproduced bug ends the Process successfully with
triage notes and `needs-info`, skips all later Steps, ends the Claim and
cleans up the Issue-branch worktree. Its result is the triage comment URL;
the progress line and Ending say the bug was not reproduced. Only
`implement` can end a Process early; there is no file setting for this.

`catalogue = "security-review"` runs the same Security review as a Ticket run.
Place it on the Issue-branch or Spec-branch worktree after its editing Steps and before
`delivery`, outside any parallel group. The Step runs when `security-review`
(or `--security-review`) on the command or `[security] review = true` asks;
`no-security-review` overrides the config. Otherwise it prints that the review
was skipped. Before the Process name, spell these flags with `--`; the bare
words remain valid Custom process names. It uses `security.harness` when configured, including that
Harness's Model and Effort, and keeps the Ticket run's default-Harness fallback.
A Harness explicitly named by the Step must start at preflight, with no
fallback. A refused or incomplete review, or unaddressed introduced findings,
holds a following Self-merge while Delivery still leaves the PR ready and
repairs conflicts and CI. The public review outcome is written to the PR;
pre-existing findings stay private as in a Ticket run.

`catalogue = "delivery"` publishes that Issue branch or Spec branch after the earlier Steps'
editing sessions and any Security review. It pushes, opens a draft pull request
when the branch has none, writes the Built-with line, marks the pull request ready
for review, and keeps it mergeable with green or absent CI through the Repair
loop. When thirdshift opens the pull request, its title is the issue's and its body
starts `Closes #<n>`. Repairs run on the Delivery Step's Harness, Model and Effort.
A Process has at most one delivery Step. It names the Issue-branch or Spec-branch worktree,
it is not optional, and it is not in a parallel group. It comes after the
last Step that uses that worktree. A `self-merge` Step is not one of those
editing Steps.

`catalogue = "self-merge"` is the Self-merge, and it has to be the Step
directly after `delivery`. With `merge` (or `--merge`) on the command, or
with `merge.always` in the User config, it merges as a Ticket run asked to
merge does: `gh pr merge --merge --match-head-commit` on the head whose CI
was watched, then the same close comment, and the Issue branch deleted. The
pull request URL is the Step's result. Without that ask, and with `no-merge`
even when `merge.always` is set, the pull request stays ready for review and
the Process succeeds. `merge` on a Process with no `self-merge` Step does not
merge. The Step names the Issue-branch or Spec-branch worktree, it is not optional, it is
not in a parallel group, and a Process has at most one. One anywhere else is
refused. `merge` and `no-merge` are not accepted by `check`.

A file can only tighten limits, never loosen them. `[limits]` may set:

- `repair_cap`, a whole number from 0 to 5. 5 is the effective cap. A lower
  one stops the Repair loop there, including when the Process is not merging.
  A higher one is refused as a loosening limit, before any session.
- `self_merge = false`, which holds the Self-merge even when the command or
  the User config asked for one. The Process fails, the outcome says
  `self_merge = false holds the Self-merge`, and the pull request stays ready
  for review. `self_merge = true` is refused as a loosening limit.
- `protected_paths`, an array of globs. A change that touches one holds the
  Self-merge the way an unaddressed Security finding does: the pull request
  stays ready for review, the Process fails, and the outcome names the path.
  `*` stays inside one path segment, `**` crosses segments, and `?` is one
  character other than `/`.

```toml
[limits]
repair_cap = 2
self_merge = false
protected_paths = ["secrets/**", "**/*.pem"]
```

An Issue-branch or Spec-branch worktree needs an issue. `thirdshift process <name>` and
`thirdshift process check <name>` refuse the file before any session, any
Claim and any branch, naming the `issue` rule and the file line. With an
issue, the run makes the Claim when it starts, labelling the issue
`in-progress` in place of `ready-for-agent`, and holds it until the end. On an
Issue-branch worktree, a pull request left ready for review removes the Claim and does not put
`ready-for-agent` back, so Pickup does not take an issue that already has an
open pull request. A Self-merge that merged takes the Claim off once the
issue is closed, as a Ticket run's does, so an issue whose closing failed keeps
`in-progress` until it is closed. A Step that fails before Delivery keeps the
Issue-branch work as a Failed ticket run does, and the failure says where it stopped, what
was preserved and the command `thirdshift process <name> issue <url>`. When
that work reached origin, `agent-failed` takes the place of `in-progress` and the
[Failure limit](#the-failure-limit) counts it; when it did not, the Claim is
released.

`version` must be `1`. Each Step has a `name` and exactly one kind. `skill` is
looked up the same way as `thirdshift skill`. First a Factory skill whose
directory is exactly that name. Then the repository's committed
`.agents/skills/<name>/SKILL.md`, or `.claude/skills/<name>/SKILL.md` when
only that copy exists; `.agents/skills` wins when both exist. Then
`~/.thirdshift/skills/<name>/SKILL.md`. Then the Factory skill
`thirdshift-<name>`. A repository skill wins over the home skill of the same
name. A skill file that resolves outside the directory being searched is not
a match. The home skill is linked into the Step's worktree the way the Factory
skills are
([ADR-0012](adr/0012-factory-skills-linked-into-the-worktree-codex-unsandboxed.md)),
under its own name, as a copy written out beside those skills, and kept out
of git. A repository skill of the same name is not replaced. `command` is a command or script,
run with `sh -c` in the Step's worktree. It starts no session. A command may
contain newlines and tabs. Any other control character in the command, the
description, a step or worktree name, a skill, a model, an effort, a parallel
group or a protected-path glob is refused before a step runs, so the plan
`check` prints cannot hide the command. `catalogue` names a
built-in Step: `implement`, `spec-review`, `security-review`, `delivery`, `self-merge` or
`land-tickets`, described above, or `architecture-review`, `run-published-issue`,
`security-audit`, `reproduce-findings`, `fix-findings` or `close-findings`.

`security-audit` audits origin's Base branch in its own throwaway worktree,
validates the report and creates or reuses each finding's private record.
Follow it with `reproduce-findings` to run one reproduction session per pending
finding at its audited commit, score the reproduced findings and keep their tests
in those private records. Completed reproductions and the Day shift's grades are
kept when an audit finds the same finding again. Both Steps must be required,
outside parallel groups, and cannot use an Issue-branch or Spec-branch worktree.
Each takes its own Harness, Model and Effort. Their session traces stay local,
including when OTLP export is configured.

With `security-fix` (or `--security-fix`) on the command, or `[security] fix = true`,
each Step skips itself when a recorded finding awaits an allowed fix;
`no-security-fix` overrides the config. Before the Process name use the dashed
flags. These Steps publish no fix or finding, and a file cannot loosen their
privacy rules. Security runs execute the Built-in `security-run` sequence
after their existing skip gates.

```toml
version = 1
description = "Audit and reproduce findings privately"
[[steps]]
name = "audit"
catalogue = "security-audit"
[[steps]]
name = "reproduce"
catalogue = "reproduce-findings"
```

`architecture-review` runs the Architecture review in its own throwaway worktree
at the Base branch on origin, checks the final line and any plan, and applies
`architect-plan` or `architect-idea` labels using the Architect run's rules.
It takes its own Harness, Model and Effort like any Step, and runs outside
parallel groups. It cannot use an Issue-branch worktree. Follow it with
`run-published-issue` to start a Ticket run or Spec run on a Strong plan.
It must precede Issue-branch editing Steps or follow their Delivery, so an
early end cannot discard unpublished work.
An idea, including an open issue that already covers the recommendation, ends
the Process successfully with that issue's URL and no child run. So does a plan
when the command asks for `thirdshift process <name> --plan-only`. Later Steps
are skipped, and the progress lines and Ending say why. This early end belongs
to the Step; there is no file setting for it. Issue-less Custom processes follow
the Command limit without a lock of a kind or the Architect run's skip gates.

`run-published-issue` starts a Ticket run, or a Spec run when the issue has
Tickets, on the issue the session Step before it published. Its optional
`process = "<name>"` setting selects the Process for a child Ticket run,
defaulting to `ticket-run`. The named Process must exist and declare an
Issue-branch worktree; `process check` refuses either problem before any
session. An issue with Tickets still starts a Spec run through normal dispatch,
regardless of this setting. For example, to use a Custom process named
`contractor-ticket` after a publishing session:

```toml
[[steps]]
name = "run"
catalogue = "run-published-issue"
process = "contractor-ticket"
```

The publishing session's final
message ends with the issue's URL on its last non-blank line; an
`architecture-review` Step supplies its checked plan instead. Before it starts a
run, thirdshift checks that the issue is in this repository, which it checks
before viewing the issue, that the issue is open, that a Trusted account
published it, and that it was created since that session Step began. A final
message without that URL, or an issue that fails a check, fails the Step, names
the reason, and starts no run. The child run is part of this Command. Its
Tickets, when the issue is a Spec, run at once up to `spec.parallel` in the User
config. The child run's outcome is the Step's outcome, and the Step's result is
the pull request's URL. The run uses the Process's Base branch and the
Step's Harness, Model and Effort, defaulting to the Command's.
It inherits the Command's merge choice and the Process file's restrictions.
Protected paths and the Repair cap also apply to a Spec's child Tickets.
`run-published-issue` is the Step immediately after a session
Step, and it does not share that Step's `parallel` group. When the Process
declares worktrees, every Step names one with `worktree`.
Consecutive Steps with the same `parallel` name run at the same time. Every
session or command Step edits the worktree it runs in, so Steps in one group
cannot share a worktree. The same group name after a Step that is not in the
group starts a new group. `optional = true` records that Step's failure and
the Process carries on. Without `optional`, or with `optional = false`, a
failure stops the Process once the other Steps in its group have finished.

```sh
thirdshift process list
thirdshift process show gather-review
thirdshift process check gather-review
thirdshift process check ship issue 7
thirdshift process gather-review
thirdshift process gather-review --harness claude --model opus --effort high
thirdshift process ship issue 7
```

`thirdshift process list` lists each Process and its description. `check`
validates the file and prints the plan: the description, the Command's Harness,
Model and Effort, and each Step's choices, where each came from (`Step`,
`command`, `User config` or `default`), and whether its Harness starts.
A Process with no named worktrees prints one
throwaway worktree at the Base branch. A Process that declares worktrees prints
each one, the worktree each Step uses, and a `together:` line for each group
of Steps that run at the same time. A throwaway worktree is described as
throwaway at the Base branch. A branch worktree is described as an
Issue branch or Spec branch. When a limit tightens a built-in rule, `check` prints it: the
repair cap out of 5, that self-merge is held, and the protected paths. A skill
Step shows the skill and where it was found. A command
Step shows its command, and `check` does not run it. A delivery Step shows
`delivery`. A Security review Step shows `security-review`. A self-merge Step shows `self-merge`. A `run-published-issue` Step shows `run-published-issue`. An
optional Step is marked `(optional)`. `check` performs the same Harness
preflight as running, including a minimal Model test when the Harness needs
one, and runs no Step. `check <name> issue <issue>` resolves the issue and
still creates no Issue branch and makes
no Claim. Without an issue, either branch worktree is the refusal above, not
a plan.

Running the Process starts the Steps in its throwaway worktrees, detached at
the Base branch and cleaned up as a standalone skill's worktree is. Every
throwaway worktree is removed at the end, including after a failure, unless
uncommitted changes, commits absent from every remote-tracking branch, or
uncertain ownership keep it. The Issue-branch worktree is a real checkout of
the Issue branch, beside the launch repository, and is removed at the end
when its work is on origin, as a Ticket run's is. The Base branch is the
branch checked out in the launch directory, at its commit on origin, or the
open pull request's base in a Continuation. The launch checkout stays
untouched.

`harness`, `model` and `effort` are optional on each Step. A Step that names
nothing uses the Command's Harness, Model and Effort. Each omitted field
inherits the Command's resolved value and where it came from, even when the
Step names another Harness. The Command's choice comes from its command word,
with or without `--`, then the User config for the Command's Harness, then
the Harness's default. To use another Harness's configured Model or Effort,
name those values on the Step. Every selected Harness is checked before the
first session. One that can't start fails the Command, naming the Step and
Harness, with no fallback and no session run. A command Step starts no session.
Each finished Step's result is stored beside the Command log, one file
per Step. A session's result is its final message. A command's result is its
stdout followed by its stderr. A `run-published-issue` Step's result is the pull
request URL of the run it started. The next session Step's prompt names the paths
of those finished results. Members of a parallel group do not see one
another's results; each member's result is passed on to the Steps after the
group. A failed command's stdout and stderr are retained too; an optional
failed command passes that result on to later Steps. The last finished Step's
result goes to stdout. Progress and failure causes go to stderr. When one
Step in a group fails, the others finish and record their results first. The
group then fails unless every failed Step is optional, and later Steps do not
run. A failed Step outside a group stops the Process immediately, unless that
Step is optional. Exit codes match `thirdshift skill`: `0` when the Process
finishes, including when the only failures were optional Steps, `1` when a
required Step or a check fails, `2` when the arguments are wrong.

A command Step's environment sets `THIRDSHIFT_RESULTS_DIR` to the folder of
Step result files and `THIRDSHIFT_STEP_RESULT` to the path of that Step's own
result file. thirdshift writes the combined output to that path when the Step
finishes. `THIRDSHIFT_ISSUE_URL` is set to the issue's URL when the Process
has an issue, and is unset when it does not.

`thirdshift process <name> issue <issue>` gives the Process an issue.
`<issue>` is an issue number or an Issue URL, resolved as `thirdshift skill`
resolves it. An Issue URL from another repository is an origin mismatch and
stops before any work. Every session Step's worktree gets `.thirdshift-issue.md`
before the session starts, and again before a Resume: the issue's title, body
and only the comments of Trusted accounts. The Session prompt names the issue.
Before each of those sessions, a Resume included, the issue is checked again,
as in a Ticket run. An edit to the title or body by an account that is not a
Trusted account, made since a few minutes before the Process started, fails
that Step instead of starting the session. The Command log names the cause.

`check` and running refuse a missing file, a file that is not valid TOML, a
missing or wrong `version`, an unknown key, an unknown Harness, a Step without exactly one of
`skill`, `command` and `catalogue`, a command that is not a string or is empty,
a catalogue value outside the documented Step catalogue, an
`implement` Step outside an Issue-branch worktree, a
`self-merge` Step that is not directly after `delivery`, a second self-merge
Step, an optional self-merge Step, a self-merge Step in a parallel group, a
self-merge Step on a worktree other than the Issue branch, a
`run-published-issue` Step that does not directly follow a session Step, an
`optional` value that is not a boolean, a skill that cannot be found, an
unknown worktree, a Step that does not name a worktree when the Process
declares them, parallel Steps that share a worktree, a worktree kind other
than `throwaway` or `issue-branch`, a second Issue-branch worktree, a delivery
Step with no Issue-branch worktree or on a different worktree, a second
delivery Step, an optional delivery Step, a delivery Step in a parallel group,
an Issue-branch worktree with no delivery Step after the last Step that uses
it, a limit above the built-in rule (`repair_cap` above 5, or `self_merge = true`),
a `repair_cap` that is not a whole number from 0 to 5, a `self_merge` value other
than false, a `protected_paths` value that is not an array of globs, an empty
protected-path glob, an Issue-branch worktree with no issue, and a reserved name (`check`,
`list`, `ticket-run`, `spec-run`, `architect-run`, `pickup-run`,
`security-run`). The refusal names the rule and the file line, and starts no
session.

The Command is recorded as kind `Process`, with the process name. Its Command
log has one line per Step: its name, kind, worktree, Harness, Model, Effort,
duration, outcome and cause. Steps that cannot start after a required failure
are recorded as skipped, naming the failed Step. A
command that exits non-zero is failed, and the line names its exit status.
Stop and Ctrl-C interrupt a command Step the way they interrupt a session,
and `[resources]` is checked before each Step and each session's Resume.
Every skill Step keeps a Session trace and Model evidence. Its prompt names
the worktree kind, and it gets the usual one Resume with or without an issue.

### Fixing and closing Security findings

`fix-findings` reads the repository's private finding records and, when
`security-fix` or `fix = true` under `[security]` allows it, fixes each
reproduced finding still awaiting a fix, in severity order. `no-security-fix`
overrides the setting. Unreproduced findings and findings with an existing
fix are skipped. The Step uses the Security run's private publication checks:
a public fix issue contains only the proposed change and a private-record
link. It links the fix, starts a Ticket run or Spec run, and records its
ending privately. A failed fix stops the Step and stays with the Day shift.
If a merged fix auto-closes a private finding issue, the Step reopens it until
`close-findings` verifies the proof, even when closing is disabled or omitted.
The optional `process = "<name>"` setting selects a child Ticket Process,
defaulting to `ticket-run`, with the same validation and Spec dispatch as
`run-published-issue`. Children inherit the Step's Harness, Model and Effort,
the Command's merge choice and the file's tighter limits.

`close-findings` reads successful fixes from the private records and checks
which merged into this Base branch, including fixes from an earlier Process
that failed or stopped before closing. Each proof-of-concept test runs against
the current merged Base branch on origin. Only a passing check closes the
private record; a failing check or error leaves a private note for the Day
shift and reopens a private finding issue that its fix PR closed.
Unmerged fixes are left open. Closing defaults to allowed when fixing
is allowed; `no-security-close` or `close = false` under `[security]`
disables it, and `security-close` overrides that setting. Both Steps run
outside parallel groups and use throwaway worktrees; their sessions acquire
fresh worktrees for publication and merged-Base checks. Their sessions and the
Ticket runs they start stay off any configured OTLP endpoint, as a Security
run's do. The existing Security run still fixes at most one finding per
invocation.

```toml
version = 1
description = "Fix reproduced findings"
[[steps]]
name = "fix"
catalogue = "fix-findings"
# process = "contractor-ticket"
[[steps]]
name = "close"
catalogue = "close-findings"
```

```sh
thirdshift process fix-records security-fix merge
thirdshift process fix-records no-security-fix
```

`thirdshift status` and `status --json` list a running or finished Process as
Process `<name>`, with the ending succeeded, failed, skipped or interrupted.
The stored kind stays `Process`, and the selector used by `show` and `stop`
stays `process-<name>-<stamp>`. `thirdshift show` prints each Step's Command
log line and, when that Step wrote a result, the path of the result file. The
Console lists the Process, and a failed one is in Needs you. The Activity log
says Process `<name>`. A succeeded, failed or interrupted Process sends a Run
notification under the same `email`, `email-unless-merged` and `no-email`
flags and the same User config rules as a Ticket run. A missing address or
Resend key stops the Process before any Step. A skipped Process sends none.
`email-unless-merged` saves the notification without emailing it when all
published pull requests merged and no dispatched run failed.

A Custom process started with no issue is a [Pass](#the-command-limit), except one
that declares an Issue-branch worktree: that is refused, as above, rather than
skipped. While the repository is at its [Command limit](#the-command-limit), a Pass's Spec run or Ticket run counted, `thirdshift process <name>` is skipped: it prints how many Commands are running and the limit, such as `at the Command limit on <owner>/<repo>: 1 Command is running, pass.command_limit is 1` at the default Command limit of 1, prints nothing on stdout, exits `0` and sends no Run notification. It creates no worktree and starts no Step. Above a limit of 1 it runs beside any other Command, and takes a slot as a Pickup run does, never a lock of a kind, so it holds no Architect run or Security run off. It does not take an Architect run's Ready-issue or Architect-idea gates, so a Ready issue or an Architect idea waiting for triage does not skip it. The Command record's outcome is `skipped`, and its cause is that reason. The Activity log records `Process <name> skipped: <reason>` when that is not already the last Process line. With `activity.quiet_skips` set, a skipped Process prints nothing. `thirdshift process <name> issue <issue>` is not a Pass: this rule does not skip it, but it holds a slot, so it counts toward the Command limit.

### User config

A **User config** at `~/.thirdshift/config.toml` sets this machine's defaults for every Ticket run. It is optional: with no file, or one that says nothing about a setting, a Ticket run does only what its command asks for.

Read every setting with its value and default, read one, or set one:

```sh
thirdshift config
thirdshift config spec.parallel
thirdshift config spec.parallel 6
thirdshift config harness.codex.model gpt-6.1-sol --json
thirdshift config console.hidden_sections '["done", "resolved"]'
thirdshift config email.to_by_repo '{ "acme/widgets" = "team@example.com" }'
```

All three forms accept `--json`, before or after their arguments. The whole
config returns `{"version":1,"settings":[...]}`; a read or write of one key
returns its `key`, `value`, `default`, `editable` and `reason`. Strings accept
bare text or TOML quotes; arrays and maps use TOML. `null` means no default
for `email.to`. A write validates exactly as `setup` does and preserves the
other settings, comments and layout. An invalid value leaves the file intact.

Open **User config** in the Console navigation (`/config`) to see the same
inventory. A session with `admin` can save one setting at a time; a `read`
session sees values and defaults without edit controls. Saving returns to that
setting and confirms its key, saved value and machine, for example
`Saved spec.parallel = 10 on orchestrate`. This works with or without JavaScript,
including Fleet pages at `/config?machine=<name>`; export endpoints stay redacted
in the confirmation. Invalid values and remote refusals show an error instead.
The API requires
`admin` for both GET `/api/v1/config` and GET `/api/v1/config/<key>`, and for
POST `/api/v1/config/<key>` with an `application/x-www-form-urlencoded`
`value` field. Its response equals the CLI's JSON. Session writes need CSRF
as other Console actions do; bearer writes do not.

The sign-in list (`console.allowed_emails`), address scopes
(`console.address_scopes`) and Fleet destinations (`console.fleet`)
cannot be read or written with `config` or its API
twins. The inventory names them with `null` values and explains the refusal:
edit the sign-in list on the machine or use `setup`, and use `console scopes`
for address scopes and `console fleet` for Fleet pairing. They control who
can get access and which destinations receive Fleet tokens. Credentials are never
read by this command; nonempty `otlp.endpoint` values are redacted because
export URLs can contain credentials. Enter a replacement URL to change one,
or blank to disable export. Every actual config change through these three
ways in records the caller, key, old value and new value in the Console log,
with sensitive values redacted. Reads and unchanged saves record no config
change. New values apply on subsequent config reads; restart the Console
after changing its listening port.

```toml
launch_directories = ["~/repos/widgets"]  # additional known Launch directories for API starts

[merge]
always = true   # every Ticket run Self-merges, without the merge word

[base]
fix = true      # every Ticket run may start a Base fix, without the base-fix word

[launch]
pull = true     # every Ticket run first fast-forwards your checkout of the Base branch

[email]
always = true                                 # every Ticket run sends a Run notification, without the email word
to = "you@example.com"                        # where email goes when the command names no address
from = "thirdshift@your-verified-domain.com"  # the sender; onboarding@resend.dev if unset

[logs]
dir = "~/elsewhere/logs"   # the root of the logs, instead of ~/.thirdshift/logs
waiting_line_minutes = 5  # repeat unchanged CI watch, Self-merge and Trial waiting lines

[otlp]
endpoint = "http://localhost:4318/v1/traces"   # also send ended spans to a local viewer

[activity]
quiet_skips = true   # a skipped Pass prints nothing

[spec]
parallel = 2   # how many Tickets a Spec run runs at once, instead of 3

[pass]
command_limit = 2   # let two Commands run on one repository on this machine at once, instead of 1

[pickup]
failure_limit = 5   # how many open issues the factory failed on stop a Pickup run taking another, instead of 3
wait_minutes = 60   # minutes since the latest shaping event before an issue is Ready, instead of 5; 0 disables waiting
order = "highest-first"   # take the highest-numbered Ready issue, instead of the lowest-numbered

[security]
review = true   # review each Ticket run's change for Security findings
harness = "claude"   # the Harness for Security runs and Security reviews; blank or missing follows the Command's

[harness]
default = "claude"   # the Harness every session runs on; claude unless set

[harness.claude]
model = "opus"   # the Model Claude Code's sessions run on; blank for its own default
effort = "high"  # how hard that Model reasons; blank for Claude Code's own default

[harness.codex]
model = ""
effort = ""

[harness.agy]
model = "gemini-3.8-flash"
effort = "medium"
```

`otlp.endpoint` is optional and blank by default. Set the full OTLP/HTTP traces URL (usually ending in `/v1/traces`) to receive each Session's ended spans live as OTLP JSON. Delivery is best effort: sends run off the Session's stream reader, each request times out after 150 ms, and a Session waits at most 200 ms for pending sends on exit. A full queue drops spans; local Session traces are still kept. Security and Scoring runs export none of their sessions, including child Ticket runs. `fix-findings` and `close-findings` likewise export none of their sessions or the Ticket runs they start. Sandbox launcher environment values are redacted from retained Session arguments.

`thirdshift setup` writes this file for you, listing every setting at its default so the file itself shows what can be changed:

```toml
launch_directories = []  # additional known Launch directories for API starts; cron directories are included automatically; default []

[merge]
always = false   # every Ticket run Self-merges, without the merge word; default false

[base]
fix = false      # every Ticket run may start a Base fix, without the base-fix word; default false

[launch]
pull = false     # every Ticket run first fast-forwards your checkout of the Base branch; default false

[email]
always = false                  # every Ticket run sends a Run notification, without the email word; default false
unless_merged = false           # every Ticket run sends a Run notification unless it merged, without the email-unless-merged word; default false
# to = "you@example.com"        # where email goes when the command names no address; no default
from = "onboarding@resend.dev"  # the sender; default onboarding@resend.dev, which only delivers to your Resend account's address
to_by_repo = {}                 # Run notification recipients keyed by "owner/repo"; default empty, falling back to email.to

[review]
commands_by_repo = {}   # extra validation commands for each "owner/repo" in every Review run; default empty

[logs]
dir = "~/.thirdshift/logs"   # the root of the logs, each repository's in <owner>/<repo>/; default ~/.thirdshift/logs
waiting_line_minutes = 5   # repeat unchanged CI watch, Self-merge and Trial waiting lines; default 5 minutes

[otlp]
endpoint = ""   # optional OTLP/HTTP traces URL, including /v1/traces; default blank (off); Security and Scoring runs never export

[inbox]
days = 7             # days to keep Resolved and rows GitHub cannot speak for; default 7
silent_minutes = 10   # minutes without growth in either log before a Ticket run is Silent; default 10

[activity]
quiet_skips = false   # a skipped Pass prints nothing, leaving only its Activity log line; default false

[spec]
parallel = 3   # how many Tickets a Spec run runs at once; default 3

[pass]
command_limit = 1   # how many Commands running on one repository on this machine stop a Pass starting another; default 1

[pickup]
failure_limit = 3   # how many open issues the factory failed on stop a Pickup run taking another; default 3
wait_minutes = 5   # minutes since the latest shaping event before an issue is Ready; 0 disables waiting; default 5
order = "lowest-first"   # which Ready issue a Pickup run takes, lowest-first or highest-first; default lowest-first

[harness]
default = "claude"   # the Harness every Ticket run's sessions run on, claude, codex, agy, grok, muse, opencode or kimi; default claude

[harness.claude]
model = ""    # the Model Claude Code's sessions run on; default blank, for Claude Code's own
effort = ""   # how hard that Model reasons; default blank, for Claude Code's own

[harness.codex]
model = ""    # the Model Codex's sessions run on; default blank, for Codex's own
effort = ""   # how hard that Model reasons; default blank, for Codex's own

[harness.agy]
model = ""    # the Model Antigravity CLI's sessions run on; default blank, for agy's own
effort = ""   # how hard that Model reasons; default blank, for agy's own

[harness.grok]
model = ""    # the Model Grok Build's sessions run on; default blank, for Grok Build's own
effort = ""   # how hard that Model reasons; default blank, for Grok Build's own

[harness.muse]
model = ""    # the Model Muse Code's sessions run on; default blank, for Muse Code's own
effort = ""   # how hard that Model reasons; default blank, for Muse Code's own

[harness.opencode]
model = ""    # the Model OpenCode's sessions run on, provider/model; default blank, for OpenCode's own
effort = ""   # the Model's variant, passed as #effort; default blank, for OpenCode's own

[harness.kimi]
model = ""    # the Model alias in Kimi Code's config its sessions run on; default blank, for Kimi Code's default_model
effort = ""   # leave blank: Kimi Code takes its thinking from its own config; default blank

[security]
fix = false   # Security runs may fix reproduced findings; default false
close = true   # Security runs may close a finding their fix merged, when fixing is allowed; default true
review = false   # Ticket runs review their change for Security findings; default false
harness = ""   # the Harness for Security runs, unless the command names one, and for every Security review; default blank; blank or missing leaves Security runs on harness.default, or Claude Code if that is missing, and Security reviews on their Command's Harness

[trial]
memory_high = "1G"   # throttle each Trial and Grader scope past this; default 1G
memory_max = "2G"   # kill each Trial and Grader scope past this, voiding the Trial; default 2G
memory_swap_max = "1G"   # swap each Trial and Grader scope may use; default 1G
```

Every key holds its real value, so a Ticket run reading it does exactly what it does with no file. `email.to` has no default, so `setup` suggests one: the public email of your GitHub profile (from `gh api user`), else your global git `user.email`, unless that is a `@users.noreply.github.com` address, which can't receive mail. With neither, `email.to` is the only line written commented out, as above. `setup` never asks `gh` for more scopes, so a private GitHub email is not read, and a Ticket run never looks the suggestion up: `--email` with no address, no matching `email.to_by_repo` entry and no `email.to` still stops the Ticket run. From a terminal (stdin and stderr both terminals), `setup` first asks, on stderr:

1. The Harness for every Ticket run's sessions (`harness.default`), listing only those installed on `PATH`. An unavailable Harness or unknown name is refused and asked again. The default is the configured Harness when installed, else the first installed in `claude`, `codex`, `agy`, `grok`, `muse`, `opencode`, `kimi` order. Then the Model (`harness.<name>.model`) and the Effort (`harness.<name>.effort`) for the Harness chosen only, each defaulting to the User config's, where Enter on none keeps the Harness's own default and `-` clears one. They're checked as a Ticket run checks them (see [Harness, Model and Effort](#harness-model-and-effort)). For Claude, a named Model gets the test call; if Claude refuses it, Setup shows what Claude said and asks the Model and Effort again. For Codex, Setup lists the Models `codex debug models` offers, by slug and display name, then the Efforts the Model chosen supports; each answer is matched regardless of case and written as Codex names it, so `GPT-6.1-Sol` and `Max` are written as `gpt-6.1-sol` and `max`, and a Model or Effort the catalog doesn't have is asked again, with the valid choices. For agy, Setup lists `agy models` and its supported Efforts, checks each answer without a model turn, and writes the canonical names regardless of case. For Grok Build, Setup lists `grok models` and the chosen Model's Efforts from its refreshed cache, and checks each answer against them. Muse proposes `muse-spark-1.3` and checks the answers against its cache, or with a minimal call; a refusal asks for the Model and Effort again. OpenCode proposes no Model and checks the Model and Effort with a minimal standalone call, asking again on a refusal. For Kimi Code, Setup lists the Model aliases `kimi provider list --json` prints and asks for a Model only, since Kimi takes no Effort; an alias its config lacks is asked again. The other Harnesses' sections are left as they are. With no Harness installed here, Setup says so, asks none of this, and leaves the harness settings as they are.
2. `Every Ticket run Self-merges?` (`merge.always`)
3. `Every Ticket run may start a Base fix when the Base branch's CI is red?` (`base.fix`), whatever the Self-merge answer. Pressing Enter keeps the current `base.fix` value.
4. `Every Ticket run first fast-forwards your checkout of the Base branch?` (`launch.pull`)
5. `Triage runs may file ready-for-agent issues by default?` (`triage.allow_ready_for_agent`), off by default. Yes keeps recommended `ready-for-agent` when filing; No changes it to `needs-triage`. Pressing Enter keeps the current setting.
6. Security runs may fix reproduced findings? (`security.fix`), off by default.
7. When fixing is on, Security runs may close a finding their fix merged? (`security.close`), on by default.
8. `Ticket runs review their change for Security findings?` (`security.review`), off by default.
9. Run notifications? (`email.always`). If yes, the address (`email.to`), asked again until it has an `@`, then the sender (`email.from`).
10. With notifications on, the Resend API key, with input hidden. With none saved it asks `Resend API key (input hidden, Enter to skip):`; with one in the [Credentials](#email), `Resend API key (input hidden, Enter keeps the saved one):`, and a new one replaces it. Surrounding spaces are trimmed, and anything that doesn't start with `re_` is asked again. A key you give is saved in the Credentials, `~/.thirdshift/credentials.toml`, created with mode 600 (and `~/.thirdshift` with it) or edited in place, keeping its comments and anything else in it and changing only `resend.key`; `setup` then prints `wrote the Credentials <path>`. The key is never printed, nor written to the User config. Skipping writes no Credentials and says how to add a key later: rerun `thirdshift setup`, or set `RESEND_API_KEY`. With `RESEND_API_KEY` set and not empty, which wins over the Credentials, nothing is asked, and it says the key comes from `RESEND_API_KEY`. With a key found or given, it offers to send a test email (default No), as `thirdshift email-test` does, once the files are written.
11. A Claude setup token, made separately with `claude setup-token`, with input hidden, whether notifications are on or off. Enter skips it, or keeps the saved token; a new one replaces `claude.setup_token` in the Credentials, keeping comments and the Resend key. Saving Credentials sets mode 600. The token is never printed or written to the User config. It is reserved for Trials; a Trial receives it as `CLAUDE_CODE_OAUTH_TOKEN`. Ordinary Runs keep using the Harness's existing login.

For Claude's Model, Setup suggests `default`, `best`, `fable`, `opus`, `sonnet`, `haiku`, `opusplan`, `sonnet[1m]` and `opus[1m]` from [Claude Code's documented model settings](https://code.claude.com/docs/en/model-config#model-aliases). These are suggestions: you can type any Model ID. Enter keeps the current value, or Claude's own default when none is set. The suggestions are maintained with thirdshift against that documentation; Setup does not fetch a live catalog or pin the Model versions the aliases resolve to.

When the saved `security.review` or `security.fix` is on, Setup also prints a Security sandbox probe result. On Linux it starts a real `bwrap` sandbox and tries a connection to a temporary host-loopback listener (no internet), opening the saved User config for writing without changing its contents, and writing a scratch file with a throwaway HOME. A failed check names the capability and prints operator-run commands for installing bubblewrap and granting `/usr/bin/bwrap` user namespaces through AppArmor on Ubuntu; Setup runs none of those commands and still saves the User config. The sandbox has a three-second deadline. With both settings off, no probe runs. Passing checks these capabilities only: Security sessions must still enforce all the audit skill's controls, including credential isolation and resource limits.

Before running target code, each Security session must enforce:

- no external network;
- an empty environment populated from an explicit allowlist with safe values, with scratch-local `HOME`, temporary directories and caches;
- a read-only target and toolchain, with writes only inside scratch; and
- explicit low CPU, memory, process, file-size, disk and wall-clock limits.

If a session cannot enforce every control, Security runs and Security reviews on this machine report findings as needs-validation instead of reproducing them. The User config is already saved by then, and the probe result does not stop Setup.

Pressing Enter takes the default shown, which is the file's current value, or else the setting's default, and for the address the suggested email above. `logs.dir`, `activity.quiet_skips`, `spec.parallel`, `pickup.failure_limit`, `pickup.wait_minutes`, `pickup.order` and `security.harness` are not asked about. Setup adds a missing `security.harness` at its default, blank, with a comment explaining it; a configured Harness is kept. The answers are written like everything else below: in place, keeping your comments. Ctrl-C, SIGTERM or SIGHUP during the questions or a Model/Effort check exits `1` with `interrupted` and writes nothing: neither the User config nor the Credentials. Ordinary and hidden questions stop without another line of input, and hidden input restores the saved terminal settings, including echo. With notifications off, the Resend key is not asked about and stays as it was, so `--email` on a single Ticket run still works. The Claude setup token is offered independently. Credentials a Ticket run would refuse (see [Email](#email)) are refused before any question, exit `1`, and not touched. With no terminal, as from cron or `thirdshift setup </dev/null`, `setup` asks nothing and never writes the Credentials. Either way it prints the file's path on stderr and exits `0` with stdout empty. Over a User config that is already there, `setup` edits it in place: its comments and key order stay, as do the values it didn't ask about, and each key it lacks is added at its default with its comment, so afterwards the file lists every setting this version knows. If `[security]` falls between Harness sections, Setup moves it after them, keeping its values and comments. One that already lists every setting, down to the commented-out `email.to` line, with Security outside the Harness area is left byte for byte as it was. A key added to an inline table, such as `launch = { pull = true }`, gets no comment, since TOML has no place for one there. One a Ticket run would refuse is refused the same way, exit `1`, and not touched. Any argument after `setup` is an argument error (exit `2`).

The first Ticket run on a machine with no User config, started from a terminal, offers Setup before any work, on stderr: `No User config at <path>. Set your defaults now? [Y/n]`. Yes (or Enter) asks the questions above, writes the file, and the Ticket run carries on using your answers; a flag in the command, such as `--no-merge`, `--email` or `--no-email`, still wins over them. No writes every setting at its default, as `setup` with no terminal does, asks nothing about a key, writes no Credentials, says that `thirdshift setup` changes it, and the Ticket run carries on; later Ticket runs find the file and don't offer again. If the file can't be written, stderr gets a `warning:` line and the Ticket run carries on with the defaults. Ctrl-C, SIGTERM or SIGHUP during the offer, the questions or a Model/Effort check exits `1` with `interrupted`, writes nothing and ends the command before any work, with no Run notification. A command thirdshift can't parse exits `2` before any offer. A Ticket run with no terminal, as from cron, CI, `nohup` or an agent's shell, offers nothing, writes nothing, and runs on the defaults, so a later Ticket run from a terminal still gets the offer.

With `merge.always = true`, `thirdshift <Issue URL>` is a Ticket run that Self-merges, and `thirdshift --no-merge <Issue URL>` (or `no-merge`, before or after the URL) leaves that one Ticket run's pull request ready for review.

With `base.fix = true`, every Ticket run may start a [Base fix](#base-fix), as if given `base-fix`, and `thirdshift --no-base-fix <Issue URL>` (or `no-base-fix`, before or after the URL) forbids it for that one Ticket run.

With `launch.pull = true`, every Ticket run brings the Base branch checked out in the directory you start it from (the **Launch directory**) up to date with `origin`, so you no longer `git pull` by hand before each Ticket run. It happens after the pre-flight checks pass and before the worktree is created, as `git merge --ff-only origin/<Base branch>`: fast-forward only, never a merge commit or a rebase, always from `origin`, whatever the branch's upstream or your `pull.*` settings. A progress line on stderr says when it updates the branch; an already up-to-date branch is left quietly as it is. It is skipped when the checked-out branch isn't the Base branch, as in a Continuation whose open pull request targets another base, or on a detached HEAD. If the update can't happen, for example because uncommitted changes are in the way, stderr gets a `warning:` line with git's error and the command to run by hand, your changes are left as they were, and the Ticket run carries on with the same outcome and exit code. The setting only affects your checkout: the Ticket run's worktree starts from `origin/<Base branch>` either way.

With `email.always = true`, every Ticket run sends a [Run notification](#run-notifications) to its repository's `email.to_by_repo` entry, falling back to `email.to`, as if given `--email`, and `thirdshift --no-email <Issue URL>` (or `no-email`, before or after the URL) sends none for that one Ticket run. With `email.unless_merged = true`, with or without `email.always`, every Ticket run sends one only when it did not end merged, as if given `--email-unless-merged`; `--email` on the command line still emails that one Ticket run whatever its outcome, and `--no-email` sends none. Answering no to Setup's Run notifications question turns both off.

`spec.parallel` sets how many Tickets a [Spec run](#spec-runs) runs at once, by default 3. It must be a whole number from 1 up; `parallel <n>` on the command line wins over it for one Spec run.

`pickup.failure_limit` sets the [Failure limit](#the-failure-limit): how many open issues labelled `agent-failed`, failures waiting for you, stop a [Pickup run](#pickup-runs) from taking another, by default 3. It must be a whole number from 1 up. There is no command-line flag for it. The old `pickup.limit` is ignored, with a warning on stderr naming `pickup.failure_limit`.

`pass.command_limit` sets the [Command limit](#the-command-limit): how many Commands running on one repository on this machine stop a Pass starting another, by default 1. It must be a whole number from 1 up. There is no command-line flag for it.

`trial.memory_high`, `trial.memory_max` and `trial.memory_swap_max` cap each Trial and each Grader in its own scope, from `systemd-run --user --scope`. Past `memory_high` the scope throttles. Past `memory_max` its processes are killed together and the Trial is void. `memory_swap_max` bounds its swap. They default to `1G`, `2G` and `1G`, chosen with headroom above #1009's largest observed Harness resident size of about 480 MiB. That snapshot had no builds running; a Trial's footprint beside two building Runs remains unmeasured. Each limit must be a byte count systemd accepts, such as `512M`, `2G` or `infinity`. There is no command-line flag for them. The Experiment suite overrides them with `THIRDSHIFT_TRIAL_MEMORY_HIGH`, `THIRDSHIFT_TRIAL_MEMORY_MAX` and `THIRDSHIFT_TRIAL_MEMORY_SWAP_MAX` for a small test cap. Scopes need your user manager: run `loginctl enable-linger <user>` once, so they work while you are logged out. A logged-out launcher discovers the user's runtime directory if its environment omits it. Without a reachable manager the Experiment stops before dispatch and names the linger step.

`pickup.order` sets which end of the issue numbers a [Pickup run](#pickup-runs) takes its Ready issue from: `lowest-first`, the default, or `highest-first`. Anything else, or anything but a quoted string, stops the pass before any work, naming the file and the key, as a Ticket run would refuse it. `lowest-first` and `highest-first` on the command line win over it for one pass.

`logs.dir` sets the root of the [logs](#logs), with each repository's in its `<owner>/<repo>/` folder, created if missing. It must be an absolute path, `~` or a path starting with `~/`, where `~` stands for `$HOME`. A relative path stops the Ticket run before any work, since the directory a Ticket run is launched from is no base for a setting that holds for every Ticket run.

`logs.waiting_line_minutes` sets how often CI watch, Self-merge and an Experiment's running Trials repeat a waiting line even when nothing changes, in the terminal and the Command log. It defaults to 5 and must be a whole number of minutes from 1 up. CI watch still writes a line whenever the running or total check count changes; Self-merge writes waiting lines while GitHub calculates mergeability; each running Trial writes one saying it is still running, so a long Trial does not make its Experiment Silent.

`inbox.days` defaults to 7 and must be a positive whole number of days. It bounds ended problems GitHub can't speak for in Needs you, and older completions in Resolved: Resolved runs to `inbox.days` after a Command ended, after the later Command started for a row one took up, after a ready row's pull request merged or closed on GitHub, or after the dismissal for a dismissed row. Done always covers one day. A ready Command whose pull request GitHub shows as open stays in Ready for review however old it is; only a row GitHub can't speak for still ages out of Ready for review after `inbox.days`. Security runs retain whether findings were waiting at completion, without their private write-ups; older records lacking this fact do not infer it from the audit's outcome.

`inbox.silent_minutes` defaults to 10 and must be a whole number of minutes from 1 up. If `logs.waiting_line_minutes` is greater than or equal to it, `status` warns on stderr and waiting stages use half the silent time instead. A one-minute silent threshold therefore uses waiting lines every 30 seconds.

`[harness]` chooses the **Harness**, the agent CLI every session of a command runs on, and for each Harness the **Model** its sessions run on and their **Effort**, how hard that Model reasons. See [Harness, Model and Effort](#harness-model-and-effort).

A Ticket run reads the file before any work. One that isn't valid TOML, or that has a key or section thirdshift doesn't know, such as `alway` for `always`, or a value of the wrong type, such as anything but `true` or `false` for `always`, or `0` for `spec.parallel` or `pickup.failure_limit`, stops the Ticket run with an error naming the file and the offending key, so a typo can't silently leave a setting off. `email-test` and `setup` read it the same way. `update`, `version` and `help` never read it, so a broken User config can't block them, and they never offer Setup; nor does `email-test`.

### Harness, Model and Effort

The available Harnesses are Claude Code (`claude`), Codex (`codex`), Antigravity CLI (`agy`), Grok Build (`grok`), Muse Code (`muse`), OpenCode (`opencode`) and Kimi Code (`kimi`).

Every session of a command, its implement session, each Repair and Resume, a Spec review, an Architecture review, each Ticket run and a Base fix, runs on one **Harness**, with one **Model** and one **Effort**. The one exception is a [Security review](#security-review): with `security.harness` set in the User config, it runs on that Harness ([ADR-0021](adr/0021-a-command-may-run-its-security-review-on-another-harness.md)). `harness <name>`, `model <name>` and `effort <level>` (or `--harness`, `--model` and `--effort`) choose them for one command, before or after the Issue URL, and on `architect` (but not with `--plan-only`) and `pickup` too:

```sh
thirdshift https://github.com/<owner>/<repo>/issues/<n> model claude-opus-5-5 effort high
```

For each of the three, the command wins, then the [User config](#user-config), then the default. The Harness's default is `claude`; the Model's and the Effort's are nothing, which leaves them to the Harness, so with no flag and no `[harness]` section sessions run exactly as `claude -p` would. A Model and Effort set in the User config come from the chosen Harness's own section, so `harness claude` over a `codex` default takes `[harness.claude]`, while `model` and `effort` on the command apply to whichever Harness is chosen. Names are passed to Claude Code as given: `--model` and `--effort` when set. Grok Build takes `-m <model>` and `--reasoning-effort <effort>`. Codex takes them as it names them, which the check below settles: `-m <model>` and `-c model_reasoning_effort="<effort>"` when set.

With `harness codex`, every session runs `codex exec --json --dangerously-bypass-approvals-and-sandbox` in the Ticket run's worktree, with stdin set to null, and with `-c project_doc_fallback_filenames=["CLAUDE.md"]`, so Codex reads `CLAUDE.md` where a repository has no `AGENTS.md`. Codex's sandbox is off: on a stock Ubuntu machine it can't start, and commits and pushes from a worktree write outside it, so the worktree is the only boundary, as with Claude's auto mode ([ADR-0012](adr/0012-factory-skills-linked-into-the-worktree-codex-unsandboxed.md)). The Factory skills are linked into the worktree's `.agents/skills/`, kept out of git with `/.agents/skills/thirdshift-*` in `.git/info/exclude`, and each prompt's first line loads its skill as `$thirdshift-<skill>`. `codex exec` kills what the agent left running as it exits, so a session whose turn ends with a command or a sub-agent call still running (started, never completed) gets a Resume, as on Claude: `codex exec … resume <session id>`, with the Model, Effort, bypass flag and `CLAUDE.md` fallback given again, as Codex keeps none of them. An interrupt sends a Codex session SIGINT, the only signal Codex stops cleanly on, before the SIGTERM and SIGKILL every session gets, each 10 seconds apart. Progress lines come from Codex's `item.*` events, the session-ended line gives its token totals, as Codex reports no turns or cost, and the final message is the last `agent_message`. A session whose turn fails (`turn.failed`), or that exits non-zero, fails the Ticket run with Codex's error in the cause; an `error` event Codex retries does not. Each Codex session adds a `trust_level = "trusted"` entry for the repository to `~/.codex/config.toml`, and your `~/.claude/` instructions and hooks don't reach it.

With `harness agy`, every session runs Google **Antigravity CLI** as `agy -p --dangerously-skip-permissions --output-format stream-json`, with `--model` and `--effort` when set, stdin null, and `AGY_CLI_DISABLE_AUTO_UPDATE=true` (agy ignores `=1`). The sandbox is opt-in and is never enabled, so unattended sessions can write the shared `.git` ([ADR-0013](adr/0013-every-harness-runs-unattended-and-fully-trusted.md)). Factory skills are linked into `.agents/skills/`, excluded from git, and loaded by the `/thirdshift-<skill>` first line. agy reads project `AGENTS.md`, `GEMINI.md` and `.agents/rules/`, and user instructions under `~/.gemini/`; it does not read `~/.claude/`. When root `CLAUDE.md` exists and neither `AGENTS.md` nor `GEMINI.md` does, thirdshift adds a `GEMINI.md` link to `CLAUDE.md` and excludes it through `.git/info/exclude`; existing instruction files always win.

agy's `init` supplies the conversation id and `step_update` supplies tool progress. The final `result` supplies the final message, success/error status, error and cumulative usage (including on Resume). `ERROR` or a nonzero exit fails the session with agy's error. A Resume uses `--conversation <id>` with the same flags, Model, Effort and environment; an interrupt sends SIGTERM, then SIGKILL after the grace period. Its start-up can be slow and variable: the research measured 8–95 seconds. No speed assumption or backend retry is made.

Before any work on agy, a named Model or Effort is checked against the free `agy models` catalog, which lists IDs, labels and effort-suffixed variants. IDs, display labels and bare aliases are matched regardless of case, as are Efforts. `model Gemini-3.8-Flash effort Medium` becomes `--model gemini-3.8-flash --effort medium`; `model gemini-3.8-flash-medium` already carries its Effort. A bare alias requires an Effort; a Model or Effort the catalog lacks fails naming valid choices. This check uses null stdin and disables self-update too, without a model turn.

With `harness grok`, every session runs `grok -p <prompt> --always-approve --sandbox off --output-format streaming-messages-json` with stdin set to null and with `GROK_DISABLE_AUTOUPDATER=1` and `GROK_FOLDER_TRUST=0`. The approval flag and disabled sandbox are always explicit, overriding the CLI’s own config and `GROK_SANDBOX`. No repository needs a one-time `grok --trust`: the trust environment override allows its project instructions and skills to load in the Ticket run's worktree. The Factory skills are linked into `.agents/skills/`, excluded from git, and the prompt loads its skill as `/thirdshift-<skill>` on its first line. A Resume repeats the flags and environment with `-r <session id>`. Grok documents no stream notification proving that background work was killed at exit, so thirdshift does not infer an automatic Resume from its tool activity. Grok's Messages stream shares Claude's event shapes, with Grok's tool names and errors; it supplies progress, the session id, final message, turns and cost, or token usage when cost is unavailable. Grok starts shell commands in their own process groups, which thirdshift's tree-stop also stops; the CLI gets SIGTERM before SIGKILL.

Grok reads both `AGENTS.md` and `CLAUDE.md` when both exist, along with `AGENT.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md` and project rules under `.grok`, `.claude` and `.cursor`. It also reads `~/.grok/rules`, `~/.claude/CLAUDE.md` and `~/.claude/rules`; thirdshift writes none of these user-level files. Grok Build uses `~/.grok` for sign-in and sessions (or `GROK_HOME` when set).

Interrupting a Command stops every session's process tree on every Harness, including commands that started their own process group or session. The same owner supervises all Model/Effort checks, from Command startup and terminal Setup: interruption stops the check and its owned commands, even after the CLI exits while its captured output pipes are still open. A cancelled Command check ends before any Claim, worktree or Command log. thirdshift snapshots the descendants with `ps`, sends each process group the Harness's stop signals with a 10-second grace period each, then takes another snapshot before SIGKILL to catch commands started in the meantime. If the CLI exits on an earlier signal, thirdshift kills the remaining commands immediately without another grace period.

Before any work, where an Origin match failure would stop it, and so before the Claim, the worktree and any Command log, a command checks what it chose: the Harness's CLI must be on `PATH`, else it fails naming the CLI and the setting that chose it; and on Claude a named Model gets a minimal test call, `claude -p --model <model>` with the Effort, if any, which must succeed, else the command fails with what Claude said. No test call is made when no Model is named. Claude Code and Codex first check sign-in with the non-billed `claude auth status` and `codex login status`; a signed-out status fails before any Model test call. For other Harnesses without a non-billed sign-in check, sign-in is left to the session; the Security review startup fallback covers those failures. On Codex a named Model and Effort are checked against `codex debug models`, which costs no tokens: each matches regardless of case, a Model by its slug or its display name, and becomes the name Codex takes, so `model GPT-6.1-Sol effort Max` reaches Codex as `gpt-6.1-sol` and `max`. An unknown Model, or an Effort that Model doesn't support (with no Model, one no Model supports), fails naming the valid choices. On Grok Build, `grok models` lists the available Models without a model call and refreshes `models_cache.json` under `GROK_HOME` or `~/.grok`; thirdshift reads that cache for each Model's supported Efforts. Both are matched regardless of case and passed as Grok names them. With no Model named, a named Effort is checked against Grok's current default Model. Unknown Models and unsupported Efforts fail with the valid choices, and an unreadable catalog fails before work. The check has the same null stdin and fixed environment as sessions. What the command records is what the check settled on. A Pass makes these checks only once it has decided not to skip, and a Spec run makes them once for all its Tickets.

With `harness muse`, every session and Resume runs `muse exec --json --yolo`, with stdin null and `MUSE_NO_AUTO_UPDATE=1`. `--yolo` disables approvals and the sandbox and trusts the worktree ([ADR-0013](adr/0013-every-harness-runs-unattended-and-fully-trusted.md)). Muse reads the project's `AGENTS.md`, falling back to `CLAUDE.md`, and also reads `~/.claude/CLAUDE.md`. The Factory skills are linked into `.agents/skills/` and kept out of git. The prompt's first line tells the model to load its `thirdshift-<skill>` with its skill tool. If the stream shows no `read_skill` load of that skill, thirdshift writes a warning to the progress lines and Command log; it neither fails nor retries the session.

Muse's named Model is checked against its cached catalog under `~/.local/share/muse/model-catalog/` when present, matching its id or display label regardless of case. Without that cache, thirdshift makes a minimal test call with the same flags and environment. Effort is checked locally before any call: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` or `ultra`. Model and Effort reach Muse as `--model` and `--reasoning-effort`. Setup proposes `muse-spark-1.3`; leaving the Model unset uses Muse's own default, `muse-spark-1.3-contributor`, which allows content to be used for product improvement.

Muse's session id comes from `stream.id`, and a Resume uses `--session-id <id>` with every flag and environment override again. Progress lines name session starts, tools and errors. After exit, thirdshift reads the last reply and token totals from Muse's own `sessions/<year>/<month>/<day>/<id>/session.jsonl`. Architecture reviews see that last reply alone, rather than Muse's terminal event's joined replies. A missing or unreadable log falls back to the stream text with no usage. `run.terminal.failed` or a non-zero exit fails the Ticket run with Muse's error. An interrupt sends SIGTERM, then SIGKILL after ten seconds if needed.

With `harness opencode`, every session, Resume and preflight check runs `opencode run --standalone --format json --auto`, with the prompt on stdin and `OPENCODE_DISABLE_AUTOUPDATE=1`. Standalone starts a private server in the session's process tree and adds about 2–3 seconds per session; it keeps the work and its commands under thirdshift's interruption handling rather than in the shared service ([ADR-0013](adr/0013-every-harness-runs-unattended-and-fully-trusted.md)). OpenCode reads project `AGENTS.md` and `~/.config/opencode/AGENTS.md`; it never reads `CLAUDE.md` or `~/.claude/CLAUDE.md` itself. When root `CLAUDE.md` exists and `AGENTS.md` does not, thirdshift links `AGENTS.md` to it and excludes that link from git. Factory skills are linked into `.agents/skills/`, and the prompt tells the model to load its skill with the skill tool. A missing successful `skill` load produces a warning without failing or retrying the session.

OpenCode takes the Model id from your provider config, as `<provider>/<model>`, including MiMo-V2.6-Pro when your provider routes it. Model and Effort are passed together as `-m <provider>/<model>#<effort>`; an explicit Effort replaces a variant already in the Model id, and needs a Model set too. Before any work, thirdshift makes a minimal standalone test call with the same stdin, flags and environment. `provider.no-route` identifies a bad Model or Effort without a model turn; a successful check uses a model call because OpenCode has no free catalog without its service. Setup checks its answers the same way, proposing no default Model.

The session id comes from `sessionID` in the stream, and a Resume uses `-s <id>` with every flag and environment override again. OpenCode creates a new session for an unknown id, so thirdshift only resumes an id it read from the stream. Progress comes from `step_start`, `tool_use`, `step_finish` and `error`. After exit, thirdshift reads `opencode session export --standalone <id>`: an exported `failed` outcome fails the Ticket run even with exit 0, the final message is the last assistant message's last text part, and usage and cost are summed over assistant messages to exclude the automatic title call. Input totals include cache reads and writes, output totals include reasoning, and each subtotal is shown. If export fails or is unreadable, the last stream `text` supplies the final message and no usage is shown. A stream error or nonzero exit also fails the Ticket run with OpenCode's error. An interrupt sends SIGTERM through the whole process tree, then SIGKILL after the grace period if needed.

With `harness kimi`, every session runs **Kimi Code CLI** (`@moonshot-ai/kimi-code`, which installs `kimi`) as `kimi --output-format stream-json -p <prompt>`, with `-m <model>` when set, stdin null, `KIMI_CODE_TRUST_WORKSPACE=1`, `KIMI_CODE_NO_AUTO_UPDATE=1` and `KIMI_DISABLE_TELEMETRY=1`. Print mode approves every action itself and refuses `--yolo` and `--auto` beside `-p`; the trust override lets the worktree's project MCP servers start, which an untrusted folder skips ([ADR-0013](adr/0013-every-harness-runs-unattended-and-fully-trusted.md)). Each session also gets `KIMI_CODE_HOME` set: yours when you set it, else `~/.kimi-code`, or the private home's `.kimi-code` where a sandbox gives the session its own `HOME`. Kimi Code reads `AGENTS.md` (and `.kimi-code/AGENTS.md`) from the project root down to the working directory, and `~/.kimi-code/AGENTS.md`; it does not read `CLAUDE.md` or `~/.claude/`. When root `CLAUDE.md` exists and `AGENTS.md` does not, thirdshift links `AGENTS.md` to it and excludes that link from git, as for OpenCode. It loads skills from the project's `.kimi-code/skills/` and `.agents/skills/` and the user's `~/.kimi-code/skills/` and `~/.agents/skills/`. The Factory skills are linked into `.agents/skills/` and kept out of git, and the prompt tells the model to load its skill with its `Skill` tool; a session whose stream shows no successful load gets a warning, without failing or retrying.

A Kimi Model is a model alias in Kimi Code's own config, as `kimi provider list --json` prints it, and reaches Kimi as `-m <alias>`. Before any work, and in Setup, the Model is checked against that list, which costs no tokens; an unknown alias fails naming the configured ones. No Model leaves the choice to Kimi Code's `default_model`. Kimi Code has no Effort flag, so any Effort fails before work: set thinking in Kimi Code's config instead. To run Kimi K3.1 Pro on Fireworks, add Fireworks to Kimi Code's `config.toml` as an OpenAI-compatible provider whose key comes from an environment variable, never written into a repository, and an alias for its Model:

```toml
[providers.fireworks]
type = "openai"
base_url = "https://api.fireworks.ai/inference/v1"
api_key_env = "FIREWORKS_API_KEY"

[models."kimi-k3.1-pro"]
provider = "fireworks"
model = "accounts/fireworks/models/kimi-k3p1-pro"
max_context_size = 262144
```

Then `harness kimi model kimi-k3.1-pro`, with `FIREWORKS_API_KEY` exported. Signing in with `kimi login` instead adds the managed Kimi Code provider's aliases.

Kimi's stream carries assistant and tool messages, which supply the progress lines and the final message, and after a completed turn a `session.resume_hint` with the session id; a Resume runs `kimi --session <id>` with the same flags. The stream carries no usage. After exit, thirdshift reads the session's own record, `wire.jsonl` under `<KIMI_CODE_HOME>/sessions/<workspace>/<id>/agents/<agent>/`, and totals the usage of every `step.end` event of this turn, for the main agent and its subagents, by the Model alias each agent was bound to. A Resume appends to the same record, so only steps from the last user message carrying this session's prompt count. A turn that fails prints no session id; thirdshift then finds the session folder whose record holds that prompt, newest first, so a failed turn's usage still counts. Input totals include cache reads and writes, which are each shown, as Kimi's own `vis` sums them. A session with no `step.end` usage, or no record, shows no usage rather than zero. An `error` line or a nonzero exit fails the Ticket run. An interrupt sends SIGTERM through the whole process tree, then SIGKILL after the grace period if needed.

The Command log's opening lines (`sessions run on claude · claude-opus-5-5 · high`), the Activity log's start line, the pull request's body and the Run notification each name the Harness, Model and Effort, `default model` or `default effort` where the Harness's own is used. In the pull request's body, the Spec PR's included, thirdshift writes the line itself once the opening session has ended, such as `Built with claude 2.1.11 · claude-opus-5-5 · high`, replacing any it wrote there before. The Harness version comes from the same detection as its Session trace: stream metadata when available, otherwise its version command, shared across the Command's sessions and child Runs. An unavailable version is `unknown`. Older Built-with lines without a version still read.

If a Repair or Base fix reports a different Harness version, thirdshift refreshes the open pull request's line before Self-merge so the Run notification matches it.

### Email

thirdshift sends email itself, with one HTTPS request to [Resend](https://resend.com)'s API, so it needs no mail server on the machine and works where SMTP ports are blocked ([ADR 0005](adr/0005-run-notifications-through-resend.md)). It needs a Resend account and an API key:

- **The API key** comes from the **`RESEND_API_KEY`** environment variable when it is set and not empty, and otherwise from the **Credentials**, `~/.thirdshift/credentials.toml`, a file only you should be able to read (mode 600):

  ```toml
  [resend]
  key = "re_..."
  ```

  `thirdshift setup` asks for the key, hidden, and saves it there for you. The environment variable wins, so a CI secret or an `export` overrides the saved key for one command. The Credentials are what let a Ticket run started from cron, `nohup` or an agent's shell find the key, since those read no shell profile. thirdshift never reads the key from the User config, so that file holds no secret.
- **`email.to`** in the [User config](#user-config) is the host's default recipient when the command gives none.
- **`email.to_by_repo`** overrides that recipient for Run notifications in particular repositories, so work and personal repositories on one host can use different inboxes:

  ```toml
  [email]
  always = true
  to = "work@example.com"
  from = "thirdshift@your-verified-domain.example"

  [email.to_by_repo]
  "JacobStephens2/thirdshift" = "personal@example.com"
  ```

  Keys are quoted `owner/repo` names, matched without regard to case. Each value must be a nonblank quoted address; duplicate names differing only in case are refused. You can also write the map inline under `[email]`, for example `to_by_repo = { "JacobStephens2/thirdshift" = "personal@example.com" }`. When editing Setup's existing `to_by_repo = {}` line, replace it with the inline map or remove it before adding `[email.to_by_repo]`; TOML cannot define the same key twice. Setup preserves these routes and leaves them for you to edit by hand. An explicit address after `email` or `email-unless-merged` wins over the repository entry, which wins over `email.to`. A repository entry can supply the address even without `email.to`; it does not itself enable notifications.

  Ticket and Spec runs use the Issue URL's repository. Pickup, Architect, Security and Custom process runs use the Launch directory's GitHub `origin`, including SSH origins. With no matching repository, they use `email.to`. Scoring runs and `email-test` use the host default; pass an explicit address to `email-test` to check another inbox. The sender and Resend key stay shared across repositories.
- **`email.from`** is the sender. Without it, email comes from **`onboarding@resend.dev`**, Resend's shared sender, which only delivers to the address of your own Resend account. To send to any other address, set `email.from` to an address on a domain you have verified with Resend.

To check the setup without starting a Ticket run:

```sh
thirdshift email-test you@example.com   # or just `thirdshift email-test`, to send to email.to
```

It sends one test email, whose subject marks it as a test and whose body names the host, the time and the sender. Before sending, it checks that it has an address (the argument, else `email.to`) and a key (`RESEND_API_KEY`, else the Credentials); if either is missing, it exits `1` naming what's missing and sends nothing. With no key anywhere, it lists every way to give one:

```
no Resend API key. Either:
  - run `thirdshift setup`, or
  - add it to /home/you/.thirdshift/credentials.toml (mode 600):
        [resend]
        key = "re_..."
  - or set RESEND_API_KEY in the environment the Ticket run starts from
    (a crontab line, CI secret, or a shell profile the Ticket run's shell reads)
```

Setup validates the Credentials before asking questions on a terminal. For email, `email-test`, the Console and a Run or a Pass that asks for a notification read them only when `RESEND_API_KEY` is unset or empty. A missing file just means no key from it. The file accepts quoted `resend.key`, `claude.setup_token` and `opencode.api_key` values, and an `[opencode.keys]` table of quoted keys by OpenCode provider name. Invalid TOML, unknown sections or keys (such as `kye`), and values of other types stop the command with exit `1`, naming the file and the offending key, and nothing is sent. An OpenCode Trial's provider key goes there by hand until `setup` asks for it: one per provider under `[opencode.keys]`, such as `fireworks-ai = "…"` and `baseten = "…"`, or a single `api_key` under `[opencode]` for any provider without its own. Each OpenCode session takes the key for the provider its Model names, so two OpenCode sessions on different providers, such as two Graders in a Grader panel, each get their own; without one, an OpenCode Trial fails before its session starts. A Grok Trial signs its own Trials home in once, with `GROK_HOME=~/.thirdshift/trials/grok grok login`; without that login, a Grok Trial fails before its session starts. One that others can read is still used, with a `warning:` line on stderr saying to `chmod 600` it. Nothing is sent to check the key itself. When Resend accepts the email, it prints `accepted by Resend; check your inbox` and exits `0`; that is all it can verify, so check that the email arrives. When Resend refuses it, for example for a bad key or a sender it won't send from, it prints Resend's error text word for word, with where the key came from, and exits `1`. It gives up after 30 seconds without an answer.

#### Run notifications

`--email` (or `email`) asks a Ticket run for a **Run notification**: one email, sent when the Ticket run ends, whatever the outcome. The word after the flag is the address only if it contains `@` and doesn't start with `https://`, so the Issue URL is never taken for it; otherwise the email goes to the matching `email.to_by_repo` entry, falling back to `email.to`. With `email.always = true` in the [User config](#user-config), a Ticket run asks for one without the flag, and `--no-email` (or `no-email`) skips it for that Ticket run; an address after `--email` still wins over both configured recipients. Giving a flag twice, or any two of `--email`, `--email-unless-merged` and `--no-email`, is an argument error.

`--email-unless-merged` (or `email-unless-merged`), optionally followed by an address as `--email` is, asks for a Run notification that is emailed only when the command did not end `merged`, whatever else it ended as. A merged one is still saved beside the [Command log](#logs), with nothing sent, unless it is a [Security run](#security-runs) whose fix left its finding open or whose audit left findings waiting for the Day shift: that one is emailed. It makes the same checks as `--email` before any work.

A Ticket run that asks for a notification, by either flag or by `email.always` or `email.unless_merged`, makes the same checks as `email-test` before any other work: an address is known, and a key is found, in `RESEND_API_KEY` or else the Credentials. If either fails, or the Credentials are broken, the Ticket run stops, exits `1` naming what's wrong (with no key, the message above listing every way to give one), and sends nothing. A Ticket run that asks for no notification never reads the Credentials, so a broken file can't stop it, and `update`, `version` and `help` never read it either. Once they pass, every way the Ticket run ends sends exactly one notification, after its outcome is final and its cleanup done: ready for review, merged, a [Failed ticket run](#failed-ticket-runs) (including a later preflight failure such as an origin mismatch), or interrupted by Ctrl-C, SIGTERM or a closed terminal.

- **Subject**: `[thirdshift] <owner>/<repo>#<n> <issue title>: <outcome>`, where the outcome is `ready for review`, `merged`, `failed`, `interrupted` or `paused`. The title is left out if it can't be read from GitHub.
- **Body**, plain text: a `Result:` line with the same outcome as the subject, so it is readable even when a long issue title hides the end of the subject; immediately followed by one `Issue:` line with the full original Issue URL, including after failure or interruption with no pull request, and a `Title:` line with the issue title when it was read; then the pull request URL (if any), the failure cause (if failed), after an Inherited failure with no Base fix taken its [`Base check:`, `Retry with:` and `Or set:` lines](#an-inherited-failure-links-the-base-branchs-checks), the session trace path (if any), the same one stderr gives, the [Command log](#logs) path as a `Command log:` line, a `Sent by:      thirdshift` line, the hostname and how long the Ticket run took. The body tells everything the subject does, so copying the body alone is enough.

The email's `Built with` line carries the same Harness version as the pull request's line, names the command's configured Harness, Model and Effort and is marked `(configured)`. A `Session models` section lists sessions whose Harness was launched, including failed or interrupted sessions, Resumes and child Ticket runs belonging to that Command. Models evidenced by the Harness's output or retained records are marked `(reported)`, including model switches and delegated Claude answers. When the Harness supplies no model evidence, the requested Model is labelled `(requested; actual model not reported)`, or its default is labelled `Harness default (actual model not reported)`. A listed session proves the Harness was launched; an unconfirmed request does not prove that Model executed. Effort is the session's configured Effort; it does not describe a delegated answer's Effort. Attribution records (`*.models.json`) are kept beside the Session traces; a failure to write or read them is a warning and never changes the Ticket run's outcome.

A [Spec run](#spec-runs) sends at most one notification for the whole Spec, under the same rules, with its checks made once before any Ticket starts. Its subject names the Spec, its `Issue:` line links the parent Spec rather than a Ticket or pull request, its outcome is the Spec run's, and its body, after what a Ticket run's holds (the Spec PR, if any), lists each Ticket's outcome, one line per Ticket as in the summary on stderr, such as `#21 landed with https://github.com/acme/widgets/pull/1` or `#22 blocked by #21`. The Ticket runs inside it never send a notification of their own, whatever the User config says.

An [Architect run](#architect-runs) takes the same flags and the same `email.always` and `email.unless_merged`, and sends [one notification](#one-run-notification) covering its review and the run it dispatched.

A [Pickup run](#pickup-runs) takes the same flags and the same `email.always` and `email.unless_merged` too. One that took an issue sends [one notification](#one-run-notification-for-the-issue-taken), the one the run it dispatched would have sent by hand, and a skipped one sends none.

A notification that can't be sent is a `warning:` line on stderr with Resend's error. It never changes the Ticket run's outcome, stdout or exit code.

### Stopping a Command

`thirdshift stop widgets#7` stops a live Ticket run and waits for its cleanup. It accepts
the same Command names as `show`: `owner/repo#number`, an Issue URL, or a Pass's
`kind-stamp` name. It works from any directory and never prompts. Ended and died
Commands are refused; Stop sends SIGTERM only to the recorded process, with no
forced kill.

Stopping a Spec run ends its Tickets' runs too, saving their unfinished work.
Only the Spec's issue receives Stop labels; its Tickets' labels stay as they
were. A Stop on a Pickup run applies to the issue it took, whether a Ticket run or a
Spec run. A Pass still without an issue, such as an Architect run in its
Architecture review or a Security run in its audit, ends without changing
labels. Stop refuses a Ticket's issue and names the Spec run to stop instead.

By default, Stop leaves the issue for the Day shift: it adds `needs-triage` and
does not put `ready-for-agent` back. It removes `in-progress` when nothing reached
`origin`, and keeps it when an Issue branch or pull request remains. Add
`--requeue` to release the Claim and put `ready-for-agent` back even after a push;
the next Ticket run continues that Issue branch. Ordinary interruption without a Stop
ends the Claim as any other Failed ticket run does: `agent-failed` in place of
`in-progress` when work reached `origin`.

The Stop request is kept beside the Command record with the Unix user who asked
and whether to requeue. The Command writes `<subject> stopped from the CLI by
<who>` to its Activity log before its `ended:` line. Stop prints `still ending`
each minute while cleanup runs, then the outcome and any Issue branch or pull
request left behind. Until then, `thirdshift status` and the Console's Inbox show
the Command as `Stopping`.

### Dismissing a row

A dismissed row's Resolved retention runs from its dismissal. A later GitHub settlement or Command does not restart that clock. Taking the dismissal back restores the other Inbox rules.

`thirdshift dismiss widgets#7` gives a row in Needs you or Ready for review a
**Dismissal**: the row leaves that group, and nothing else changes. It accepts
the same Command names as `show`: `owner/repo#number`, an Issue URL, a Pass's
`kind-stamp` name, or a record's path. Any row in either group can be dismissed,
live ones included: a dismissed live row moves to Working or Landing with its
health line still showing, and its Ticket runs keep running. An ended one goes to
Done, Resolved or History by its age, and Resolved holds it for `inbox.days`
after the dismissal. Dismissing a collapsed failure dismisses every Command it
stands for, and a later failure with that cause starts a row of one. Add
`--undo` to take a dismissal back wherever the row now is. A dismissal holds
until the row turns into a kind its dismissal has not covered: Slow becoming
Silent or Silent becoming Slow brings it back, as does a live Command dying,
failing or ending ready for review. A dismissed Security failure comes back as a
Finding while its Command record says findings wait. Dismissing again adds that
kind to the dismissal. Each kind counts once for the whole row: a Silent Ticket
run that logs and falls Silent again stays dismissed, as does a Spec run when a
second Ticket goes Silent. Its row in Working still says it was dismissed.

Dismissing a row outside Needs you and Ready for review is refused, as is a row
with no Command record and `--undo` on a row that isn't dismissed. The dismissal
is kept beside the Command record with who asked, when, whether from the CLI or
the Console, which of the record's rows it covers, and every kind it covered. The
Command, its issue, labels, Claim and pull request stay as they are, and nothing
is written to GitHub. The Activity log records each dismissal and each one taken
back, naming the Unix user and the CLI. `dismiss --json` reports what it did.

In the Console, any signed-in account can click **Dismiss** on the row in Needs
you or Ready for review, or in Command details beside Stop when available.
With JavaScript, `d` dismisses the selected row and selects the next row; text
fields and open dialogs keep their keys. An inline dismissal shows a temporary
`Dismissed <subject> · Undo` notice. Undo restores that Command's row. Notices
stay while hovered, focused, saving or showing an error. Without JavaScript,
rows retain their full Dismiss form. One click dismisses, with no confirmation
page. A dismissed row also offers **Undo** in Command details.
While either request is pending, its buttons show “Dismissing…” or
“Taking back dismissal…” and stay disabled, including through live updates.
A failed request shows the error and lets you retry. Command details shows each
button's CLI form beside it. Both posts require a session and a valid CSRF token, open
pages update together, and the Activity log names the account's email and the
Console.

### Logs

Export a Command's whole **Trace** for another tool with:

```sh
thirdshift logs acme/widgets#7 --export ./trace
```

This writes `spans.jsonl` and `logs.jsonl` in the directory, creating it if
needed. Both use OpenTelemetry's OTLP JSON Lines format: one export request
per line, with spans and log records in separate files. The spans include the
Command, all its child Ticket runs and their stages, using the Command record's times,
plus every retained Session trace's spans. The log records come from every
Session trace in that Command. All share one trace ID, and every span's parent
is included. Naming a child Ticket run exports its whole owning Command too.

The export stays on the machine; nothing is sent anywhere. Existing export
files are never overwritten. A Command record is required. Missing files, malformed
requests or missing parent spans fail the export before the output files are
published. Wait for a live Command to finish before exporting its complete
Trace; unfinished record intervals retain an unset end time rather than an
invented completion time.

Everything thirdshift logs goes under `~/.thirdshift/logs/`, or the `logs.dir` set in the [User config](#user-config), in a folder per repository, `<owner>/<repo>/`, named for the GitHub repository rather than your checkout, so a fork and its upstream never share one and every checkout or worktree of a repository logs to the same place. thirdshift creates each folder as it needs it, so a repository's first pass needs nothing made by hand:

```
~/.thirdshift/logs/<owner>/<repo>/
├── activity.log              the Activity log
├── audits/                   each Security audit's report, with its evidence
├── security-reviews/         each Security review's private report of old findings
└── commands/
    ├── architect/            <stamp>~<token>.log and Session traces
    ├── pickup/               <n>-<stamp>~<token>.log and Session traces
    ├── secure/               <stamp>~<token>.log and Session traces
    └── issue/                <n>-<stamp>~<token>.log and Session traces
```

The folder already names the repository, so no file name repeats it. `audits/` and `security-reviews/` hold vulnerability evidence, so keep the logs private (see [Security runs](#security-runs)). A **Session trace** records one session's events and timed work in two OTLP JSON Lines files: `.logs.jsonl` holds a log record for every Harness event as it arrives, including its raw output; `.spans.jsonl` holds the Session, model-call and tool-call spans as they end. Sessions write these files, Model evidence and any review reports; they no longer write the raw Session log. All of a Command's Session traces share its **Trace** identity, including child Ticket runs:

```
~/.thirdshift/logs/<owner>/<repo>/commands/issue/<n>-<stamp>~<token>-implement.logs.jsonl
~/.thirdshift/logs/<owner>/<repo>/commands/issue/<n>-<stamp>~<token>-implement.spans.jsonl
~/.thirdshift/logs/<owner>/<repo>/commands/issue/<n>-<stamp>~<token>-repair-<i>.logs.jsonl
~/.thirdshift/logs/<owner>/<repo>/commands/architect/architect-<stamp>~<token>-architecture-review.logs.jsonl
```

Session traces share the owning command's folder, stamp and owner token: a Pickup run's dispatched Ticket run logs in `commands/pickup/`, an Architect run's in `commands/architect/`, and a Security run's in `commands/secure/`. Tickets and nested Base fixes inherit that same ownership too.

Each Command record and child run records its Process in `process_name`,
`process_kind` (`built-in` or `custom`) and `process_hash` (the lowercase SHA-256
of the file's exact bytes). Session traces carry the same facts as
`thirdshift.process.name`, `thirdshift.process.kind` and `thirdshift.process.hash`
attributes. Ticket runs, including child Ticket runs, record `ticket-run` and
the compiled-in file's hash by default. A `run-published-issue` Step that selects
a Custom process records that name, Custom kind and loaded file's hash on its
child instead. Custom processes record the file loaded for that
run, so editing it changes the next run's hash. Spec runs record `spec-run`,
Architect runs record `architect-run`, and Security runs record `security-run`,
each with its compiled-in file's hash. A run with no Process file has no hash.
Older records can omit these fields. Status, the Console,
the Activity log and Run notifications keep their existing run-type names.

When a Command that produces a [Run notification](#run-notifications) ends, its subject and body are saved beside its Command log as `<Command log stem>.notification.txt`, whether or not email is enabled. For example, `7-20261003T120000-0400~aB3cD4eF5gH6iJ7k.log` has `7-20261003T120000-0400~aB3cD4eF5gH6iJ7k.notification.txt` beside it. The file starts with `Subject: <subject>`, then a blank line and the exact plain-text email body. A Pickup run writes one for the issue it took, and a Spec run writes one covering its Tickets; dispatched Ticket runs, Ticket runs inside a Spec run and Base fixes write none of their own. A skipped Pass writes none. A failed write produces a `warning:` line and leaves the outcome unchanged. These files are not included in `thirdshift logs` or the Console's log inventory.

A Resume is logged as its session's kind plus `-resume`, e.g. `implement-resume.logs.jsonl`.

A **Command log** is everything one command printed, stderr and stdout in the order printed, while the terminal still shows all of it. Its folder is the command typed: `thirdshift <Issue URL>`, a Ticket run or a Spec run, in `issue/`, `thirdshift pickup` in `pickup/`, named for the issue it took, and `thirdshift architect` in `architect/`. A Spec run's covers its Tickets' runs, a Ticket run's covers its [Base fix](#base-fix), and a Pass's covers the Spec run or Ticket run it dispatched: none of those keeps one of its own. So `ls -t ~/.thirdshift/logs/acme/widgets/commands/pickup/*.log | head` lists the recent passes on acme/widgets that took an issue. A command keeps its Command log once it starts work: a Pickup run, Architect run or Security run skipped before doing any work keeps none, nor does a Ticket run that fails before it starts work, as on the [Origin match](#what-a-ticket-run-does). A Custom process started with no issue that is skipped keeps a Command record whose outcome is `skipped`, beside the Command log of the lines it held. `setup`, `email-test`, `update`, `version` and `help` never keep one. Lines printed before the Command log's name is known, such as a Pickup run's lines on the issues it [passed over](#why-an-issue-was-passed-over) before it took one, are written first, and once it is created a progress line says `logging this command to <path>`. A Command log that can't be written produces one `warning:` line on stderr. A failure confined to the Command log leaves the outcome, stdout and exit code unchanged; if the shared folder also prevents writing a Session trace, the Ticket run fails before starting that session.

The stamp is the local time the command started, with its UTC offset, as in `20261003T120000-0400`, in the machine's time zone, or `TZ`'s if set, so it agrees with `date` and `ls -l`. A command's Command log and all of its Session traces, its Tickets' runs' and its Base fix's included, share that one stamp, so they sort together and each can be found from the other. When a Ticket run fails, stderr ends with the path of the Session trace of the session its cause came from, the place to start looking, then that of its Command log. A failed implement session, Spec review or Repair names its own log, as does a [Security review](#security-review) whose hold is reported only after later Repairs. A cause that came from no session, such as red CI with the Repairs used up, a Declined CI fix, the upstream-move budget, a Harness check or a git or GitHub error, names the most recent Session trace. A Spec run whose Tickets are not done names the Session trace of the one Ticket whose Ticket run failed, and none if several did, as no single session caused it; each failed Ticket's line gives its own. The Command log's closing `session trace:` line and the [Run notification](#run-notifications) give the same path.

Command logs and Session traces insert `~<token>` immediately after the stamp. The random token gives each Command its own storage even when start times agree; its Command record uses the exact Command-log stem followed by `.command.json`. Model sidecars (`.models.json`), review reports (`.standards` and `.spec`) and review summaries (`.review-summary.json`) use the Session stem before `.logs.jsonl`, for example `7-<stamp>~<token>-implement.models.json`. The Command record names the log-records file; Silent watches that file grow, and the Waterfall reads the trace spans. Human Command names stay the same, and start stamps remain display and grouping facts. A matching stamp alone does not attach a tokenless Session to a new Command: a record reference or exact Model evidence must establish that ownership. Converted traces and older Command records remain readable without renaming; a record naming the former raw file resolves to its log-records file. Readers no longer accept the old Session-log format, and the one-time `logs --convert` and `--remove-converted` commands have been retired. A failed Command-log writer retains its allocated owner; if allocation itself failed, a Session fails with that cause instead of choosing a shared timestamp-only filename.

The code review writes `summary.json` beside its reports with finding counts by Standards and Spec, including findings later fixed or declined. At Ticket run completion, the review's originating Session stage keeps these in its Run metrics as `review_findings`, with `standards` and `spec` counts. Missing or invalid summaries are `null`, and an unavailable axis is `null` rather than zero. A Resume updates that same review's summary; another review keeps its own counts. `show --json` reads these retained counts without parsing report prose. A release changing this Factory skill needs an Experiment once #977 exists. A standards report, a spec report or that summary is kept beside the Session trace only when the review reports directory is a real directory and the report is a regular file inside it. A symlink, whether the directory or a report, is refused in a progress line and the session's outcome stays as it is. A missing report is skipped.

The **Activity log**, `activity.log`, is a short running record of what the factory did on the repository ([ADR-0011](adr/0011-thirdshift-keeps-a-per-repository-activity-log.md)). A Ticket run, a Spec run or a Pass writes a line when it starts work, naming its Command log, and one when it ends, with its outcome; a Ticket run you type by hand writes them too, and the run a Pass dispatched, a Spec run's Tickets and a Base fix write none of their own. A skipped Pass writes a line only when its reason differs from the last line of its own kind, so a repository that sits idle shows one line, not one per pass, and the first skip after a pass that did work always shows: that is when the repository went idle. A warning about the [User config](#user-config), such as an ignored `pickup.limit`, is written as `User config warning: <warning>` by the first Command on the repository to see it, and again only when it differs from the last such line, though every Command prints it on stderr. Every line starts with the local date and time:

```
2026-10-03 02:00:01 Pickup run skipped: no Ready issue on acme/widgets
2026-10-03 09:30:01 Pickup run #41 started: commands/pickup/41-20261003T093001-0400~aB3cD4eF5gH6iJ7k.log
2026-10-03 09:52:17 Pickup run #41 ended: PR https://github.com/acme/widgets/pull/42 is merged
2026-10-03 10:00:01 Pickup run skipped: no Ready issue on acme/widgets
```

Each line is appended whole, so passes that run at once on one repository never garble it. One that can't be written is one `warning:` line on stderr, and the command carries on as for a Command log. thirdshift never rotates it: collapsed skips keep it small. Existing logs, including Session traces in `<owner>/<repo>/sessions/` and logs from before the per-repository layout, are not moved.

With `quiet_skips = true` in the `[activity]` section of the [User config](#user-config), a skipped Pass prints nothing on stdout or stderr, its dated first line included, except a warning about the User config itself, such as an ignored `pickup.limit`. It keeps its last-fired time and writes an Activity log line only when the reason changes. A pass that does work, or fails, prints as ever, so a scheduler's log file catches only what went wrong. Without it, a skipped pass prints as it always has, for a pass you type by hand.

## Foreign commits in a Ticket run that Self-merges

<a name="foreign-commits-in-a-merge-run" id="foreign-commits-in-a-merge-run"></a>

A Ticket run that Self-merges merges only code an agent wrote or reviewed. If someone else pushes to the Issue branch during the Ticket run, their **Foreign commits** are reviewed before they can be merged:

1. Each round of step 6 starts by fetching the Issue branch from `origin`. Any new commits there are merged into the Ticket run's branch, by fast-forward or a merge commit, never a rebase, each logged on stderr as `merging new commit <sha> from origin/<branch>`. Foreign commits that arrive while CI runs on a green head send the Ticket run round again rather than on to the merge. A merge that conflicts with the Ticket run's own work gets a conflict Repair.
2. A **review Repair** then runs `/thirdshift-code-review` with the head thirdshift last knew as the Ticket run's own as the fixed point. The agent fixes the findings it agrees with, adds the rest to the pull request body's "Unaddressed findings" section marked as coming from the Foreign commits, and pushes.
3. The round goes on as usual: the Base branch is merged in, CI watched, and the merge tried once the head is green.

Review Repairs are logged as `repair-<i>`, numbered with the other Repairs, count against the cap of 5 Repairs, and get a Resume like any session. A round that picks up Foreign commits counts against the same 5, like a Base branch move. A Ticket run that spends either budget fails.

A Ticket run without `merge` does none of this: it never fetches someone else's commits into its branch.

## Base fix

A Base branch whose CI is broken fails every Ticket run on it with an Inherited failure. To have a Ticket run fix the Base branch itself and carry on, give it `base-fix` (or `--base-fix`), before or after the URL:

```sh
thirdshift base-fix https://github.com/acme/widgets/issues/7
```

To allow it for every Ticket run on a machine, set `base.fix` in the [User config](#user-config); `no-base-fix` (or `--no-base-fix`), before or after the URL, then forbids it for one Ticket run. Giving either flag twice, or `base-fix` together with `no-base-fix`, is an argument error.

When the Ticket run's only red checks are Inherited failures and the Base branch has not moved since, a Ticket run allowed to then starts a **Base fix**, at most one per Ticket run ([ADR-0008](adr/0008-inherited-failures-fail-the-run.md)):

1. thirdshift looks for an open issue labelled `base-fix`, other than the Ticket run's own, whose title names the same Base branch and every one of those checks. If there is one, another Ticket run's Base fix is already under way, and the Ticket run waits on that one instead: see [One Base fix per Base branch](#one-base-fix-per-base-branch).
2. Otherwise, thirdshift opens an issue from a fixed template, with no agent session: titled `CI red on <base>: <check>[, <check>…]`, its body naming the checks with their URLs on the Base branch, the Base branch and its short sha, and the Ticket run's pull request, labelled `base-fix` and `ready-for-agent`. A label the repository lacks is added to it first.
3. It starts a child `thirdshift` on that issue from the same Launch directory, as a Ticket run that Self-merges into the Ticket run's Base branch, whatever the Ticket run's own goal. Its progress lines are relayed with a `#<n>: ` prefix, after `starting Base fix #<n> into <base>: <issue URL>` and `waiting on Base fix #<n>`. The Base fix sends no Run notification, makes no [Claim](#the-claim) on its issue, treats every red check as its own to fix rather than as an Inherited failure, and never starts a Base fix of its own.
4. Once the Base fix has merged, and its Self-merge has closed its issue, the Ticket run merges the Base branch in again and watches CI, and goes on as usual: ready for review, or merged in a Ticket run that Self-merges.

If the Base fix fails, the Ticket run is a [Failed ticket run](#failed-ticket-runs) with the cause `Base fix <issue URL> failed: <its cause>`. If the checks are still Inherited failures once the Base fix has merged, there is no second one, and the cause is `CI red on <check>, which also fails on <base> at <short sha>, even after Base fix <issue URL> merged; fix <base> first`. The Ticket run's last progress lines include `Base fix: <issue URL> merged`, or `not merged`, and its own [Run notification](#run-notifications) has the same `Base fix:` line.

On a Spec, `base-fix`, `no-base-fix` or the User config's `base.fix` holds for each Ticket run, whose Base fix goes into the Spec branch, its Base branch, and for the Spec PR, whose Base fix goes into the Base branch. Tickets running at once that meet the same Inherited failure share one Base fix: the first starts it, and the others wait on it. A Ticket run sends no Run notification, so the Spec run reports its Base fix: a Ticket that landed after one has `#<n> landed with <PR URL>, after Base fix <issue URL> merged`, or `closed` for one it waited on, as its line in the Tickets checklist and in the Spec run's Run notification, and one whose Base fix failed has the cause naming the issue.

### One Base fix per Base branch

A Ticket run that finds an open Base fix issue for its Base branch and checks starts none of its own. After `waiting on Base fix #<n>, already open: <issue URL>`, it waits for that issue to close, as the Base fix's Self-merge leaves it, then merges the Base branch in again and watches CI. Waiting is the Ticket run's one Base fix: if the checks are still Inherited failures once the issue has closed, the cause is `CI red on <check>, which also fails on <base> at <short sha>, even after Base fix <issue URL> closed; fix <base> first`, and its Run notification's `Base fix:` line says `closed`, or `not closed` if the Ticket run ended first.

An issue that covers more checks than the Ticket run's counts; one for another Base branch, or that leaves out one of the Ticket run's checks, does not. The wait has no time limit: a Base fix issue from another clone or machine that nobody is working on has to be closed, or the Ticket run interrupted, by hand.

Ticket runs from one Launch directory, as a Spec run's Tickets are, look for the issue and write it one at a time, under a lock in the clone's git directory, so those that meet the same Inherited failure at once get one Base fix issue and one Base fix. There, a Ticket run also knows whether a Base fix started from that Launch directory is still running:

- A Ticket run waiting on one that fails, leaving its issue open, fails too, with the cause `Base fix <issue URL> ended with its issue still open`.
- A Ticket run that finds the issue open after that Base fix has ended starts it again on the same issue, as its one Base fix, after `Base fix #<n> is open but no longer running; starting it again into <base>: <issue URL>`. It continues the Base fix's Issue branch, as any Ticket run on an issue with one does: see [Continuation](#continuation).

Across clones and machines the look is only a best-effort lock, and two Ticket runs that look at the same moment may each start a Base fix.

Without `base-fix` or `base.fix`, or with `no-base-fix`, an Inherited failure fails the Ticket run as described in [What a Ticket run does](#what-a-ticket-run-does), and the Ticket run says [where the checks fail on the Base branch](#an-inherited-failure-links-the-base-branchs-checks), offering a Base fix if nobody decided against one.

## Continuation

Running thirdshift again on an issue picks up where the last Ticket run stopped ([ADR-0002](adr/0002-existing-issue-branch-means-continue.md)). It looks at the highest-numbered Issue branch:

- **No Issue branch yet**: a fresh Ticket run creates `issue-<n>` from the Base branch.
- **The branch exists with no pull request, or an open one**: the Ticket run is a **Continuation**. It checks out that branch, and the agent builds on its commits instead of starting over, then creates the pull request or updates the open one. With an open pull request, that pull request's base is the Base branch, whatever you have checked out.
- **The branch's pull request was merged or closed**: finished work is never reopened. The Ticket run starts fresh on the next number, `issue-<n>-branch-2`, `-3`, and so on. A number counts as used even if GitHub deleted the branch after merging.

So you can retry a Failed ticket run with the same command, or start an issue on one server and continue it on another.

A Ticket run is not idempotent: re-running builds on whatever is already on the branch, including a Failed ticket run's work-in-progress commit.

## Failed ticket runs

<a name="failed-runs" id="failed-runs"></a>

A **Failed ticket run** is one that ends, including by Ctrl-C or a closed terminal, without an open pull request from its Issue branch that targets the Base branch, is mergeable and has passing CI, or, for a Ticket run that Self-merges, without that pull request merged. Causes include the session exiting non-zero, no pull request or one with the wrong base, running out of Repairs, CI red only on **Inherited failures** (`CI red on <check>[, <check>…], which also fails on <base> at <short sha>; fix <base> first`), a CI-fix Repair that finds nothing on the branch to fix (a **declined CI fix**: the head is unchanged after it, and its one Check re-run left CI red or could not happen), and a Base branch that keeps moving while CI runs, or in a Ticket run that Self-merges, an Issue branch that keeps getting Foreign commits.

A Failed ticket run:

1. Commits any uncommitted work as `thirdshift: failed ticket run (<reason>)`, with a timestamp and the hostname, and pushes the Issue branch, so nothing is lost. If the branch has no changes against the Base branch, nothing is pushed.
2. Converts its open pull request, if any, back to a draft, so a pull request only claims to be ready when the factory stands behind it. The next successful Continuation marks it ready again. The exception is a policy refusal of a Ticket run asked to merge: the pull request is ready, mergeable and green and only the Self-merge could not happen, so it stays ready for review, and no failure commit is pushed onto the head whose CI was watched. This includes **review required**: a review blocks the merge, so thirdshift skips the merge attempt and another Repair round. stderr and the Run notification say `PR <url> needs an approving review before it can merge; it is ready for review`, with `review required` as the notification outcome. The Ticket run exits `1`, prints the PR URL on stdout, takes `in-progress` off with nothing put back, and cleans up as usual. The same applies to a Spec run's Spec PR.
3. Cleans up as usual, prints the reason to stderr and exits non-zero. If the push failed, the worktree and local Issue branch are kept instead, and stderr names the branch, its head commit and the worktree path, so you can recover the work or push it by hand.
4. Releases its [Claim](#when-the-claim-ends), unless it is a failed Security fix, if it left nothing on `origin`: no Issue branch and no pull request. Otherwise `agent-failed` takes the place of `in-progress` in one label edit, for the [Failure limit](#the-failure-limit), unless only a hold kept its ready pull request from merging, which takes `in-progress` off and adds nothing.
5. Posts its Recovery on the issue as a comment, when it labelled the issue `agent-failed`, as below.

### The Recovery comment

A Failed ticket run, Failed spec run or failed [Custom process](#custom-processes) that leaves its issue `agent-failed` posts one comment on it, so you can act on the failure from GitHub alone:

```
This comment was generated by AI.

thirdshift's Run on this issue failed, so it waits for the Day shift.

- Cause: claude exited 3
- Stopped at: Implementation
- Preserved: Issue branch `issue-7` on origin, with pull request https://github.com/acme/widgets/pull/12
- Machine: night-host

Put `ready-for-agent` back to retry.
```

A Spec run adds a `Progress:` line with its Tickets landed, and one that failed after its Spec PR changed under it says to decide the Spec's Base branch and Spec branch before putting `ready-for-agent` back. A run that failed before its work began says `Stopped at: Start, before any work began`. The cause is built only from what thirdshift knows: a failed session's own diagnostic, which its agent can write, is left out, so `claude exited 3` is shown without the text the Harness reported. The comment has no local paths, any in the cause shown as `<local path>`, and no continue command: those stay on the machine's stderr, Command log and Run notification. A Run that fails again on the same issue posts again, so the issue keeps a history of its attempts, and the next Continuation's session reads it with the issue. Nothing is posted when the failure releases its Claim, so a retry loop can't fill the issue with comments, nor for a failed Security fix, whose Recovery stays in its private advisory, nor after a [Stop](#stopping-a-command). A comment that can't be posted is a `warning:` line on stderr, `could not comment on #<n> with how its run ended; the run's outcome is unchanged`, and the Run ends as it would have.

Merges, never rebases or force-pushes: a branch worked on from several servers never loses history.

### An Inherited failure links the Base branch's checks

A Ticket run that fails on Inherited failures with no Base fix taken says more after its cause, on stderr and in its [Run notification](#run-notifications): a `Base check:` line for each of those checks, with its URL on the Base branch commit, as a [Base fix](#base-fix) issue lists them, or the name alone for a check with no URL. If nobody decided against a Base fix, with neither `base-fix` nor `no-base-fix` given and no `base.fix = true` in the [User config](#user-config), it also offers one: a `Retry with:` line with the command that starts the Ticket run again with `base-fix` added, keeping the `merge`, `email` and `parallel` flags it was given, and an `Or set:` line naming `base.fix`:

```
thirdshift: 03:12:40 CI red on test, which also fails on main at 362b9ca; fix main first
thirdshift: 03:12:40 Base check: test: https://github.com/acme/widgets/actions/runs/1/job/2
thirdshift: 03:12:40 Retry with: thirdshift https://github.com/acme/widgets/issues/7 base-fix
thirdshift: 03:12:40 Or set: base.fix = true in ~/.thirdshift/config.toml, to allow a Base fix for every Ticket run on this machine
thirdshift: 03:12:40 session trace: ~/.thirdshift/logs/acme/widgets/commands/issue/7-….logs.jsonl
thirdshift: 03:12:40 command log: ~/.thirdshift/logs/acme/widgets/commands/issue/7-….log
```

A Ticket run given `no-base-fix` gets the `Base check:` lines and no offer. A Ticket run that had its one Base fix gets neither: its `Base fix:` line already says what happened. The cause itself, and so the failure commit's message, is the same in every case, and no other cause adds a line.

In a [Spec run](#spec-runs), a Ticket run says this on its own stderr, relayed with its `#<n>: ` prefix, and the command it offers is the Spec run's, with `base-fix` added. The Spec run's summary and its Run notification show the Ticket's cause alone. After an [Architect run](#architect-runs), the command offered is `thirdshift <plan URL>` with the dispatched run's flags and `base-fix`, since another Architect run would start a new review rather than take that plan up again.

## Spec runs

A **Spec** is an issue with sub-issues, its **Tickets**. `thirdshift <Issue URL>` on a Spec is a **Spec run**: it works through the Tickets in the order their GitHub "blocked by" links allow, each **Ticket run** Self-merging into the **Spec branch**, then leaves one **Spec PR** from the Spec branch into the Base branch ready for review ([ADR-0006](adr/0006-spec-runs-merge-tickets-into-a-spec-branch.md)). An issue with no sub-issues is an ordinary Ticket run.

A Spec run makes the [Claim](#the-claim) on the Spec, as a Ticket run does on its issue: the Spec is labelled `in-progress`, in place of `ready-for-agent`. Its Tickets' runs change no label on their Tickets. The Claim [ends](#when-the-claim-ends) as a Ticket run's does: it is released if the Spec run fails with no Spec branch on `origin` and no Spec PR, except for a failed Security fix, swapped for `agent-failed` if it fails otherwise, handed back with `ready-for-agent` if it is only waiting, except for a Security fix, removed with nothing put back when the Spec PR is ready for review, and removed once a Self-merge of the Spec PR has left the Spec closed. The Spec branch is pushed before the first Ticket starts, so a Failed spec run that got as far as its Tickets is labelled `agent-failed`, unless it is only waiting.

The Spec PR opens as a draft as soon as the first Ticket lands, titled from the Spec, with `Closes #<spec>` and a Tickets checklist: one line per Ticket, ticked once it is done, with its pull request, or saying it is running, failed, blocked or unready. thirdshift rewrites the checklist between its `<!-- thirdshift:tickets -->` markers as each Ticket starts and ends, leaving the rest of the body as it is. Once every Ticket is done, the **Spec review** rewrites the body, and thirdshift puts the checklist back, appending it if the markers are gone, before marking the Spec PR ready.

An Unready Ticket's checklist and Command log line also name its open blockers, marking those outside the Spec and those labelled `ready-for-agent`. For example: `#24 unready: labelled ready-for-human; blocked by #99 (outside the Spec; ready-for-agent)`. The Spec run reports outside blockers but never starts them. Its Command record retains the Ticket and open blocker titles read with the graph, visible in `thirdshift show <command> --json`. Titles are best effort: `null` means no title was captured, including in older records; `show` does not fetch missing titles from GitHub.

The Spec review session reviews the whole Spec branch against the Base branch and the Spec. Once it is marked ready, the Spec PR goes through the same step 6 as a Ticket run's pull request, with the Spec as the issue and the Spec branch as the Issue branch: the Base branch is merged in (never rebased), CI watched, and a conflict or red CI handed to a Repair, within the same budgets, with the same Check re-run after a CI-fix Repair that leaves the head unchanged. Inherited failures are told apart the same way everywhere: the Spec PR's against the Base branch, and a Ticket's against the Spec branch, its Base branch, with the cause shown on the Ticket's line of the checklist.

Tickets always merge into the Spec branch, whatever the command or the User config says. `merge` (or `--merge`, or `merge.always = true` without `no-merge`) applies to the Spec PR alone: the Spec run ends with the Self-merge of the Spec PR into the Base branch, then deletes the Spec branch on `origin` and closes the Spec if the merge did not. Without it, the Spec run ends with the Spec PR ready for review. A Spec PR that fails from the Spec review on follows the [Failed ticket run](#failed-ticket-runs) rules for its pull request, back to draft unless only the Self-merge could not happen (a policy refusal), and the Spec run exits `1`.

A Spec run takes every Ticket it can reach. A Ticket runs once it is open, has every blocker closed, and is not an **Unready Ticket**: an open Ticket labelled `ready-for-human`, `needs-info`, `wontfix` or `needs-triage`. An open Ticket with no triage label is taken. A Ticket with sub-issues of its own is never run either, and is reported as unready. A blocker outside the Spec counts once it is closed. The graph is read again from GitHub whenever a Ticket run ends, so removing a label, adding a Ticket or closing one by hand takes effect in the same Spec run.

A Ticket whose Ticket run fails is not tried again in that Spec run, and stops only the Tickets it blocks; every other Ticket it can reach still runs. Nor do Unready Tickets, Tickets blocked by an open issue outside the Spec, or Tickets in a cycle of "blocked by" links run, nor any Ticket downstream of them.

Independent Tickets run at once, up to 3 by default. Whenever a Ticket run ends, the Spec run reads the graph from GitHub again and starts ready Tickets until the limit is reached. To change the limit for one Spec run, add `parallel <n>` (or `--parallel <n>`) before or after the URL; `spec.parallel` in the [User config](#user-config) sets it for every Spec run on the machine:

```sh
thirdshift parallel 5 https://github.com/acme/widgets/issues/20   # up to 5 Tickets at once
thirdshift --parallel 1 https://github.com/acme/widgets/issues/20 # one at a time
```

`parallel` followed by `0`, a negative number or anything but a whole number, or given twice, is an argument error (exit `2`). `parallel` on an issue with no sub-issues stops the Ticket run before any work, since there are no Tickets to run at once. The Tickets' runs share the Launch directory: they create their worktrees there one at a time, and a git command that finds a lock file held by another waits and tries again.

When nothing is left to run and any Ticket is not done, the Spec run is a **Failed spec run**: it leaves the Spec PR a draft, its checklist showing what's missing, prints its URL on stdout (if any Ticket has landed, so there is one), exits `1`, and lists on stderr each Ticket that landed, with its pull request, and each one not done, with why:

```
thirdshift: 03:12:40 #21 failed: claude exited 1 (session trace: ~/.thirdshift/logs/acme/widgets/commands/issue/21-….logs.jsonl)
thirdshift: 03:12:40 #22 blocked by #21
thirdshift: 03:12:40 #23 landed with https://github.com/acme/widgets/pull/1
thirdshift: 03:12:40 #24 unready: labelled needs-info; blocked by #99 (outside the Spec; ready-for-agent)
thirdshift: 03:12:40 #25 blocked by #99 (outside the Spec; ready-for-agent)
thirdshift: 03:12:40 #26 in a cycle: #26 blocked by #27 blocked by #26
thirdshift: 03:12:40 #27 in a cycle: #27 blocked by #26 blocked by #27
thirdshift: 03:12:40 Tickets not done: #21 (failed: claude exited 1), #22 (blocked by #21), #24 (labelled needs-info; blocked by #99 (outside the Spec; ready-for-agent)), #25 (blocked by #99 (outside the Spec; ready-for-agent)), #26 (in a cycle: #26 blocked by #27 blocked by #26), #27 (in a cycle: #27 blocked by #26 blocked by #27)
```

A Failed spec run is **only waiting** when no Ticket failed or was interrupted, every Ticket not done is an Unready Ticket, is outside the Spec's repository, or is blocked only by issues outside the Spec and by Tickets that are only waiting themselves, and every open Ticket in the Spec's repository passes the Trusted account check a Ticket gets before it starts. Handing the Spec back labels it `ready-for-agent` again, which would excuse an earlier untrusted edit of a Ticket, so a Ticket that fails that check, or can't be checked, makes the Spec run a failure, with the reason on stderr and in its cause, as `Tickets not done: …; not handed back, as Ticket #<n>: …`. Nothing is broken: the Tickets wait on you, or on other work. Its Spec is [handed back](#when-the-claim-ends) with `ready-for-agent` in place of `in-progress`, with no `agent-failed`, so it doesn't count toward the [Failure limit](#the-failure-limit). A Pickup run passes it over while it has no Startable Ticket, and continues it once you clear a Ticket's gate or a blocker closes, without your handing the Spec back too. A cycle of "blocked by" links is a failure, not waiting, since nothing will unblock it until someone reshapes the Tickets, and any failed or interrupted Ticket makes the whole Spec run a failure, even when other Tickets only wait. A Spec run that is only waiting still exits `1` and reports `Tickets not done` as above.

A Spec PR closed, merged or retargeted while the Spec run is working through its Tickets, as when the Day shift reshapes the Spec onto another Base branch, ends the Ticket loop. The Spec run checks its captured Spec PR before it starts each Ticket and whenever it writes the Tickets checklist; once the check fails it starts no further Ticket, waits for the Tickets already running, and fails with `the Spec PR <url> was closed under this Spec run` (or `merged`, or `retargeted from <base> to <other>`). It prints no Recovery command, since one would resume the Spec branch the Spec just left: decide the Spec's Base branch and Spec branch before starting it again. A Ticket started once the Spec PR was open checks it again just before its Self-merge, as does a Base fix that Ticket starts into the Spec branch, and fails with the same cause, its pull request back to a draft, rather than merge into a Spec branch the Spec has left. A Ticket started before the first landing opened the Spec PR has nothing to check and Self-merges as before.

Running the Spec again picks up where the last Spec run stopped. The Spec branch is on `origin`, so the Spec run continues it ([ADR-0002](adr/0002-existing-issue-branch-means-continue.md)) and updates its draft Spec PR rather than opening another. Closed Tickets are done and not run again, and a Ticket that failed still has its Issue branch and draft pull request, so its Ticket run is a [Continuation](#continuation) into the Spec branch. With every Ticket closed, the Spec run goes straight to the Spec review and the Spec PR. With every Ticket closed and no Spec branch, as when the Spec was done some other way, it stops with `every Ticket is closed and there is no Spec branch; nothing to do` and exits `1`, creating no branch or pull request and leaving the Spec open.

## Fix runs

Use a **Fix run** when a delivered pull request needs its Base branch merged in,
a merge conflict resolved or CI repaired. On Ready for review rows with CI red
or Merge conflict, the Console offers **Start Fix run** with confirmation of the
pull request, repository and owning machine. It requires current `run` permission
and a known Launch directory on that machine, and uses its User config and CLI
defaults. The Console shows the returned Command or failure; after an uncertain
response, check Inbox and logs before retrying. **Copy fix command** remains on
the row and in Command details. Starting a Fix run takes up earlier waiting Inbox rows on that pull request,
whether or not they name the same issue. Other later Commands on that pull
request make the same hand-off.

From a clone of the pull request's repository:

```sh
thirdshift fix https://github.com/you/widgets/pull/42
thirdshift fix 42 merge
thirdshift fix 42 --no-merge base-fix harness codex model gpt-6.1-sol effort high
thirdshift fix
thirdshift fix base main --author colleague
```

A Fix run accepts an open pull request by a Trusted account, ready or draft,
with or without a linked closing issue. Origin match, fork, closed/merged and
untrusted-author checks happen before work. The Launch directory's checked-out
branch does not choose the Base branch: the pull request does.

With no pull request target, `thirdshift fix` is a **Pass**. It searches open,
non-draft, same-repository pull requests targeting the Launch directory's
checked-out branch, or `base <branch>` / `--base <branch>`, in ascending number
order. Only Trusted accounts are eligible; `--author <login>` / `author <login>`
restricts selection to that account, which must itself be trusted. Neither
`base` nor `author` can be combined with a targeted PR.

Without `--author`, the Pass first checks the selected Base branch's tip on
`origin`. A failed first push-workflow attempt with failed jobs gets one
failed-jobs re-run; the Pass logs it on stderr and continues to PR selection
without waiting. Pending Base branch checks, including external checks, skip
only this maintenance step, as does an occupied Base branch CI reservation.
An existing repair branch or PR also skips only this step. Each maintenance
skip and its reason appear on stderr and in the repository Activity log,
including when no eligible PR is found.
Persistent red CI, or a failure that cannot be re-run, starts a CI-fix session
in a Worktree on `fix-<base>-<short-sha>`, from that origin tip. Delivery opens
`Fix CI on <base>: <check>[, <check>…]` targeting the Base branch, treats every
red check as its own to fix, and follows the usual merge and email flags and
User config. A PR already opened from that branch, including an `in-progress`
or failed draft PR, prevents another repair for that commit. An existing repair
branch also prevents another attempt if PR creation failed. When the opening
session fails after leaving work, preservation publishes it as a draft repair
PR and offers its Fix Recovery command. Overlapping hosts
share the Base branch CI reservation without holding back unrelated PR fixes.
A Pass that starts a Base branch CI repair ends with that Run's outcome.
A successful Self-merge closes open
`CI red on <base>` reports and Base fix issues naming that Base branch.

The Pass selects the first PR with a Merge conflict or CI red on its current
head. It skips `in-progress` PRs, pending CI without a Merge conflict, and
mergeable PRs with green or absent CI. It reserves and rechecks each candidate;
if another machine reserved it first, it continues to the next candidate.
At the repository's Command limit, or with no eligible PR it can reserve,
it exits `0`, prints a skip reason on stderr, records an Activity log skip
when the reason changes, and sends no Run notification. A failed Fix run
leaves a draft, so later Passes skip it until the Day shift makes it ready.

The Built-in process `fix-run` is `delivery` followed by `self-merge`.
`thirdshift processes` lists it; `thirdshift process show fix-run` prints it.
It reserves `refs/thirdshift/reservations/<PR number>` on origin and adds
`in-progress` to the pull request until the run ends. Review runs use the same
reservation. A busy reservation is refused; a crashed owner's reservation needs
the Day shift to confirm it stopped before releasing it.

Delivery checks out the head branch in a Worktree, marks a draft ready, merges
the Base branch, pushes and watches CI. Conflict, CI-fix and Foreign-commit review
Repairs receive `.thirdshift-review-input.md`: the PR title and body, linked
closing issues and only Trusted account comments. The file is refreshed before
each session, including a Resume. A title or body edit to one of those closing
issues by an account that is not a Trusted account, made since a few minutes
before the Fix run started, fails the run instead of starting that session.
Repairs share the usual five-session cap,
Check re-run and optional Base fix. A Fix run starts no implementation or initial
Standards/Spec review session.

`merge` / `--merge` and `no-merge` / `--no-merge` override `merge.always`.
Self-merge also requires recorded agent authorship or review by the GitHub
account thirdshift acts as, covering the exact adopted head. A completed Ticket,
Spec or Base CI Delivery records its delivered head for later Fix runs, as a
Review run records the head it reviewed. Simply repairing an adopted PR without
an opening review does not grant that evidence. Without it, Delivery still repairs
the PR and checks CI, then holds Self-merge with the PR ready for review. Run
`thirdshift review <PR URL>` before retrying the Fix run with `merge`; a Fix run
never adds an opening review session for an existing PR. A newly authored Base
branch CI fix has its own CI-fix session instead of adopting another PR's head.
This preserves [ADR 0004](adr/0004-self-merge-by-thirdshift-not-github-auto-merge.md)'s reviewed-code gate.
`base-fix` / `--base-fix` and `no-base-fix` / `--no-base-fix` override `base.fix`.
`harness`, `model` and `effort` use the usual command and User config precedence.
`email [<address>]`, `email-unless-merged [<address>]` and `no-email` (also with
`--`) override `email.always` and `email.unless_merged`. Command records, logs,
Activity log lines and Run notifications identify a **Fix run**.

Success prints `PR <url> is ready for review` or `PR <url> is merged`.
Failure or interruption preserves uncommitted work as
`thirdshift: failed fix run (<reason>)`, pushes unpublished work and drafts the
PR. A Self-merge refused with a mergeable, green PR leaves it ready.
Recovery offers `thirdshift fix <PR URL>` with the original flags. An unchanged
Repair creates no empty failure commit. A PR closed or merged during the run
stops further publication; a PR made draft during Repair stays draft.

## Review runs

From a clone of the pull request's repository:

```sh
thirdshift review https://github.com/you/widgets/pull/42
thirdshift review https://github.com/you/widgets/pull/42 --recommend-only
thirdshift review https://github.com/you/widgets/pull/42 harness codex
thirdshift review https://github.com/you/widgets/pull/42 security-review
thirdshift review --author colleague
```

For cron, `thirdshift review --author <login>` takes the lowest-numbered eligible
open pull request by that author, one per invocation. The Pass form requires
`--author`; it cannot be combined with a PR URL. It skips drafts, forks,
authors who are not Trusted accounts, pull requests labelled `in-progress`,
and heads already named as `reviewed_head` or `pushed_head` in a Review run's
marker posted by the GitHub account thirdshift acts as. It also skips a pull
request based on another open pull request until that base's current head has
been reviewed. New commits make a head eligible
again. With no waiting pull request, or at the Command limit, it exits `0`
without a session or Run notification. `--recommend-only` works on this form too.
An unrecoverable local branch or occupied worktree is skipped so later waiting
pull requests can run. The Pass saves a conflict fingerprint under
`~/.thirdshift/review-conflicts/` and sends one failure notification per state;
an unchanged conflict only logs a skip. Changed refs or checkout state allow a
new notification. Naming the PR URL explicitly still fails with preservation advice.

If a reviewed base received fixes that the upper pull request does not yet
contain, the upper pull request's comment says it needs updating before merge.
thirdshift leaves that update to the author, without merging or rebasing the stack.

A Review run reserves its pull request on `origin`, labels it `in-progress`
while it runs, and removes that label when it ends, including failure or
interruption. After a crash, the Day shift must confirm the owner stopped before
releasing its origin reservation and label. The Sweep removes `in-progress`
from closed pull requests.

A **Review run** refuses forks, drafts, closed or merged pull requests and
authors who are not **Trusted accounts**, explaining why before starting a
session. It checks out the pull request's captured head on its own branch in a
worktree and reviews only its change against its own base. A retained Review
worktree can be recovered when its durable ownership token and directory
identities still match, its captured head is the PR's current head, and it has
only clean committed fixes descending from that head. Recovery discards leftover
untracked validation artifacts and reruns review and delivery with the preserved
commits. Recommendation retries restart that owned checkout at the captured head.
Uncommitted tracked edits, unfinished Git operations, locked checkouts, changed
ownership evidence and other local branches are preserved for human attention.

The session gets the pull request body, linked closing issues and comments from
Trusted accounts only. The linked issues are the Spec; without one, the body is
the Spec and the posted comment says it used the pull request body alone.
Without `--recommend-only`, the session addresses findings using the same rules
as a Ticket run: it runs each behavior finding's test or command before deciding,
fixes reproduced failures and keeps the tests. It commits fixes, and thirdshift
pushes them to the pull request's own head branch without force. The comment
lists what it fixed and every **Unaddressed finding**, with the code, plan
decision, ADR or focused run that refutes it. Decisions left to the Spec or
Day shift link a `needs-triage` issue. With a linked issue, a departure explained
only by the pull request body is left as an Unaddressed finding citing that
reason, without filing a triage issue.

After addressing findings, the review session runs the repository's agent-instruction
final validation in its Review run worktree. Configure extra commands in the
[User config](#user-config) for suites you want every review to attempt:

```toml
[review.commands_by_repo]
"you/widgets" = ["npm run test:slow", "npm run test:integration"]
```

Keys are quoted `owner/repo` names, matched without regard to case; each value is
an ordered list of nonblank shell commands. Replace Setup's `commands_by_repo = {}`
line with an inline map, or remove that line before adding the subsection above.
Setup preserves configured commands. The session runs every listed command after
fixes, in addition to the repository's final validation; a failed command does not
skip the rest. With no matching list, or an empty list, it still runs the final
validation the repository's agent instructions require. The posted comment names
each command, what passed, what failed and what could not run, with reasons.
A suite those instructions say is invalid from a worktree is reported **not run
against the branch**, never as passing; thirdshift does not run it in the Launch
directory as a substitute. `--recommend-only` performs the same validation after
reviewing, without addressing findings or changing the branch.

`security-review` (or `--security-review`), or `[security] review = true`, adds
a **Security review** after the review-and-address Step. `no-security-review`
overrides the setting. It uses `security.harness` and the usual fallback,
fixes reproduced introduced vulnerabilities, and its commits are pushed with
the other fixes. The comment lists any Security finding left unfixed or an
incomplete review. Pre-existing findings stay in private records.

If a Security review or another later editing Step commits more changes,
Delivery repeats final validation and the configured extra commands on that
head before pushing. Its comment adds the new head and those validation results.
When that report includes text from a private Security report, Delivery posts
`Validation results withheld: the report included private Security review material.`
instead of the session's text.

After publishing, addressing Review runs and pull-request Custom processes
watch GitHub checks and commit statuses on the exact delivered full head, even
when there were no fixes to push. Pending CI must finish before the Run can
report ready for review; absent CI counts as passing after the usual grace
period. Failed reads and unresolved red CI end failed, with check evidence in
the comment and Run notification. Inherited failures get no Repair: fix the
Base branch first.

The branch's own failures can start up to five CI-fix Repairs across Delivery;
a Custom process may lower that cap. Each Repair validates its final commit
with the repository instructions and configured extra commands before thirdshift
publishes it and watches its CI. One CI watch retains the usual Abandoned-job
and Check re-run allowances across all heads. An unchanged Repair gets its one
eligible Check re-run and then fails if still red, without another session on
that head. Repair reports receive the same private Security-material filtering.

Review runs never merge or rebase the author's branch or stack, force-update
history, replace the pull request or Self-merge. A concurrent change to the
captured PR's identity, head, base or eligibility stops waiting or publication;
green CI on an older head cannot authorize readiness. A final merge conflict
ends failed and asks the author to update the branch. `--recommend-only`
remains report-only: it starts no CI-fix Repairs or branch modification.

If the branch moves before delivery or rejects the push because it moved,
thirdshift leaves it alone and posts the findings, describes the proposed fixes
and says the branch moved. The fixes remain in the local worktree. A changed base
or eligibility stops publication. The hidden comment marker names the reviewed
head and, when fixes were pushed, the head after the push.

`--recommend-only` fixes nothing and pushes nothing. It posts the findings with
the reviewed-head marker; a changed head stops publication too. A Ticket run's
own review still happens inside its implement session.

`--recommend-only` skips the Security review, even when requested, so it stays
read-only.

Command records, the Activity log, `status` and Run notifications call it a
Review run. Email and Harness, Model and Effort flags follow the other Commands.
The Inbox keeps a successful review under **Ready for review** until GitHub shows
the pull request merged or closed. Failed reviews appear under **Needs you**.

Inspect the Built-in process with `thirdshift process show review-run`. Copy it
to `~/.thirdshift/processes/my-review.toml` to start a Custom process with
`thirdshift process my-review pull-request <PR URL>`. A `pull-request` worktree
declares this input; `review-and-address` reviews it and addresses findings, and
an optional `security-review` Step follows the editing Steps before `delivery`
pushes fixes and posts the comment. Custom pull-request Processes can
also run skill and command Steps on that checkout. Command Steps receive `THIRDSHIFT_PULL_REQUEST_URL` and
the filtered input is in `.thirdshift-review-input.md`. This version keeps these
Steps sequential and requires `review-and-address` before a final `delivery`.

## Architect runs

`thirdshift architect` starts an **Architect run**: the factory looks for architecture work itself, with no **Issue URL**, publishes a plan for the top opportunity, and implements it. Start it from a clone of the repository, on the **Base branch**, or name the Base branch with `base <branch>`:

```sh
cd ~/repos/widgets
thirdshift architect                              # review the whole codebase, then run the plan
thirdshift architect "the Spec run"               # point the review at an area
thirdshift architect merge parallel 2             # merge the plan's pull request, two Tickets at once
thirdshift architect base-fix                     # the run the plan is dispatched as may start a Base fix
thirdshift architect "the Spec run" --plan-only   # publish the plan, mark it ready and stop
thirdshift architect base main                    # review main and run the plan on it, whatever branch the clone is on
thirdshift architect --email you@example.com      # email how the Architect run ended
```

The focus is optional free text, given as one argument, anywhere among the flags; it goes into the Session prompt. `architect` is a command only as the first argument.

After its Command limit, the lock of its kind and skip gates, the Architect run
carries out the Built-in process in `processes/architect-run.toml`: `architecture-review` →
`run-published-issue`. The file owns that sequence; the Architect run keeps its
name, progress lines, logs, endings, Run notification, Console view and Recovery.
Use `thirdshift process show architect-run` to read or copy the file.

`merge`, `no-merge`, `base-fix`, `no-base-fix`, `parallel <n>`, `harness <name>`, `model <name>` and `effort <level>` (or the same with dashes) are for the run the plan is dispatched as, and mean what they do for `thirdshift <Issue URL>`, so none of them is ever read as the focus. The [Harness, Model and Effort](#harness-model-and-effort) are the Architecture review's too. `--plan-only` stops the Architect run once the plan is marked ready, and dispatches nothing. `email` or `email-unless-merged`, optionally followed by an address, and `no-email` (or the same with dashes) are for the Architect run's own [Run notification](#one-run-notification), with or without `--plan-only`. The word after `email` or `email-unless-merged` is the address only if it contains `@`, so a focus without one is never taken for it.

`base <branch>` (or `--base <branch>`) names the Architect run's **Base branch**, so the branch your clone has checked out stops mattering: start it from a clone on another branch, on a detached HEAD, or with uncommitted changes. The Architecture review's worktree starts at the head of `<branch>` on `origin`, and the run the plan is dispatched as takes `<branch>` as its Base branch too: a Ticket run's **Issue branch**, or a Spec run's **Spec branch**, is branched off it, and the pull request or **Spec PR** targets it. It goes before or after the focus and the other flags, `--plan-only` included, and the word after it is always the branch, never the focus. Without `base`, the Base branch is the branch checked out. `base` is a flag of a Pass only: `thirdshift <Issue URL>` doesn't take it. It is what lets an Architect run be started [on a schedule](#on-a-schedule).

A second focus, a repeated flag, `merge` with `no-merge`, `base-fix` with `no-base-fix`, any two of `email`, `email-unless-merged` and `no-email`, `parallel` without a whole number from 1 up, `base` with no branch after it, any other argument starting with a dash, or an empty focus is an argument error (exit `2`). So is `merge`, `no-merge`, `base-fix`, `no-base-fix` or `parallel` with `--plan-only`, since nothing is dispatched for them to apply to.

An Architect run:

1. Makes the checks a Ticket run makes that don't need an issue, before creating anything: `origin` is a GitHub repository, git has a `user.name` and `user.email`, HEAD is not detached, and the Base branch exists on `origin` with your local copy not ahead of it. With `base <branch>`, a detached HEAD is fine, since the checkout no longer picks the Base branch, and the other two checks are made on `<branch>`: `base branch <branch> does not exist on origin; push it first with: git push --set-upstream origin 'refs/heads/<branch>:refs/heads/<branch>'` when that branch exists locally (the command quotes the actual refspec safely), or `local <branch> is <n> commit(s) ahead of origin/<branch>; push them first`. If `<branch>` is absent both locally and on origin, the error instead says to create or obtain it first, or select a valid Base branch; no push command is suggested. Preflight makes no push, checkout or branch creation. There is no **Origin match**, since there is no Issue URL: the repository is the one `origin` names. If the repository is at its Command limit, or another Architect run runs on it, it is [skipped](#the-command-limit) here, and if not, it is skipped when an earlier [Architect plan is still open](#one-architect-plan-at-a-time), and if not, when an [Architect idea waits for triage](#an-architect-idea-waits-for-triage), and if not, when the repository has a [Ready issue or an issue that would be Ready once settled](#a-ready-issue-goes-first). With `launch.pull = true` in the [User config](#user-config), it then fast-forwards your checkout of the Base branch, as a Ticket run does, and so only when the Base branch is the branch checked out: with `base <branch>` from a clone on another branch, your checkout is left alone.
2. Creates a git worktree next to your clone, named `<repo>-architect`, detached at the head of the Base branch on `origin`, with no **Issue branch**. Your checkout, its uncommitted changes and its untracked files are never touched or scanned. Only an Architect run uses that name, and only one runs on a repository at a time, so a worktree there is one a killed Architect run left behind, which this one removes; a [Security run](#security-runs) beside it reviews in `<repo>-security`.
3. Runs the **Architecture review** there: a headless session on the Harness, with the **Factory skills** loaded, started with the [Architecture review prompt](../prompts/architecture-review.md). It looks for deepening opportunities, skips any an open issue already covers, and takes the top recommendation. If it is Strong, the review publishes it as the plan, labelled `needs-triage`: a **Spec** with **Tickets**, or a single Ticket when one session is enough. It may edit files in the worktree to check an idea, but commits and pushes nothing. It ends its final message with one line naming the plan: `Architecture review plan: <Issue URL>`. thirdshift reads only that line. With [no Strong candidate](#no-strong-candidate) the line names another issue, which thirdshift labels an **Architect idea** when that issue is in this repository, and steps 5 to 7 are skipped.
4. Removes the worktree once the session ends, whatever the outcome. The temporary directory the Factory skills were written out to goes as the Architect run ends.
5. Checks the plan: the issue is in this repository, is open, was created after the Architect run started, and carries no other label that says it is not agent work (`ready-for-human`, `needs-info` or `wontfix`).
6. Reserves the plan on `origin`, as a [Pickup run](#pickup-runs) reserves the Ready issue it takes, then marks it ready, in one request: `needs-triage` is swapped for `ready-for-agent`, the plan is labelled `architect-plan`, the mark a later Architect run finds an open **Architect plan** by, and its other labels are kept. thirdshift adds that label, never the agent, and first creates it if the repository has none. A Spec's Tickets are left as the review labelled them, without `architect-plan`. The reservation, `thirdshift/pickup/<plan number>`, holds through the dispatched run's ending, or with `--plan-only` until the plan is marked ready, then is released as a Pickup run releases its own, so a Pickup run beside it that finds the plan Ready in between passes it over. If another run already holds it, the Architect run fails, changing no label.
7. Dispatches the plan, unless given `--plan-only`, exactly as `thirdshift <plan URL>` would from the same clone on the Architect run's Base branch: a [Spec run](#spec-runs) when the plan has sub-issues, a Ticket run otherwise. Its Base branch is the Architect run's, so with `base <branch>` it is `<branch>`, not the branch checked out. `merge` and `no-merge` apply to the Spec PR or the Ticket run's pull request, `parallel <n>` to the Spec run, and `base-fix` and `no-base-fix` to whether that run may start a [Base fix](#base-fix), as if given to that command, and the [User config](#user-config) sets what they leave unsaid: `merge.always`, `spec.parallel`, `base.fix`, `launch.pull` and `logs.dir`. The Architecture review itself never watches CI, so a Base fix can only happen in the dispatched run. It makes the [Claim](#the-claim) as that command would too: once its checks pass, the plan's `ready-for-agent` is swapped for `in-progress`, and the plan keeps `architect-plan`. The one difference is that it sends no [Run notification](#run-notifications) of its own, whatever `email.always` says: the Architect run sends [the one](#one-run-notification).

The dispatched run's ending is the Architect run's: its exit code, its pull request's URL alone on stdout, and its last line on stderr, `PR <url> is ready for review` or `PR <url> is merged`. If it fails, the Architect run fails as that Failed ticket run or Failed spec run does, with the cause, the session trace and the Command log on stderr and the pull request's URL on stdout if it left one. The plan stays open and `architect-plan`, and is labelled `agent-failed` in place of `in-progress` unless the run left nothing on `origin` and so [released its Claim](#when-the-claim-ends), for `thirdshift <plan URL>` to take up again: no later Architect run [retries it](#one-architect-plan-at-a-time). `parallel <n>` on a plan that is a single Ticket fails the same way as it does for `thirdshift <Issue URL>` on an issue that isn't a Spec: `parallel is only for a Spec, and #<n> has no sub-issues`, exit `1`, before any implementing and before the Claim, with the plan left `ready-for-agent`, to run without it.

With `--plan-only`, it instead exits `0` with the plan's URL alone on stdout, and `plan <url> is ready for an agent` as stderr's last line. Read or edit the plan, then run it with `thirdshift <Issue URL>`. The plan is labelled `architect-plan` here too, so until it is finished or closed the next Architect run is [skipped](#one-architect-plan-at-a-time).

Progress lines on stderr say when the review starts, which plan it reported, when the labels are swapped, and when the plan is dispatched: `dispatching the plan <url>, as thirdshift <url> would`. The dispatched run's own progress lines follow. With no Strong candidate, the last line says which issue the Architect run ended on instead.

A review session that fails or is interrupted, a final message without one of the lines the prompt asks for, a plan that fails a check, or an idea issue outside the repository at origin ends the Architect run as a failure: exit `1`, nothing on stdout, the cause on stderr and then the paths of the session trace and the Command log. Nothing is dispatched and no label is changed, so a plan the review did publish stays `needs-triage`, without `architect-plan`, for you to finish or close, and doesn't skip the next Architect run. An idea outside the repository is refused before it is viewed. A review that finds no deepening opportunity at all has no issue to name, so it ends without one of those lines and the Architect run fails this way too; its session trace says what it looked at.

### One Run notification

An Architect run asked for a [Run notification](#run-notifications), by `email` or by `email.always = true` in the [User config](#user-config) without `no-email`, sends exactly one, whatever its outcome, with or without `--plan-only`, unless it is skipped. A skipped Architect run, [however](#the-command-limit) [it](#one-architect-plan-at-a-time) [is](#an-architect-idea-waits-for-triage) [skipped](#a-ready-issue-goes-first), sends none, even when asked, so a schedule can start one every few minutes without flooding your inbox: its line is in the log its scheduler keeps. It makes a Ticket run's checks before any other work all the same, an address and a Resend API key, and stops with exit `1` if either is missing, so a run that would have been skipped fails on them too. The email goes after the outcome is final and printed, and a failed send is only a `warning:` line on stderr: it changes neither the exit code nor stdout.

- **Subject**: `[thirdshift] <owner>/<repo> Architect run: <outcome>`. With a dispatched run, the outcome is that run's: `ready for review`, `merged`, `failed`, `interrupted` or `paused`. Without one, it is the review's: `plan published` (with `--plan-only`), `idea filed`, `idea already filed`, `review failed` (also for a plan that fails a check, or an idea outside the repository at origin) or `interrupted`. The repository is left out if `origin` doesn't name one on GitHub.
- **Body**, plain text: a `Result:` line with the same outcome as the subject; a `Command:      Architect run` line and a `Repository:` line naming the repository, when known; a `Review:` line saying how the Architecture review ended, with the URL of the plan or idea issue it named (`plan published: <url>`, `idea filed: <url>`, `idea already filed: <url>`, `failed` or `interrupted`); a `Description:` line with that issue's title, when known, so you can see what the review proposed without opening the link; when the plan was dispatched, a `Dispatched:` line with that run's outcome; then what a Ticket run's notification holds, for the dispatched run or else the failed review: the pull request URL (if any), the failure cause (if failed), with the [lines after it](#an-inherited-failure-links-the-base-branchs-checks) of a dispatched run that failed on an Inherited failure, a `Base fix:` line for a dispatched run that started or waited on a [Base fix](#base-fix), the session trace path (if any), the `Command log:` path (if any), the `Sent by:` line, the hostname and how long the Architect run took. After a dispatched Spec run, it ends with a line per Ticket, as a Spec run's notification does.

The body also includes a `Strength:` line for a completed Architecture review: `Strong`, `Worth exploring` or `Speculative`. A published plan is always `Strong`; for an idea, including one already filed, the rating comes from this review's final message. If the review omits the rating or reports an unrecognized value, the line says `not reported`. Failed or interrupted reviews have no strength line.

### No Strong candidate

Only a Strong top recommendation becomes a plan. When the review's top recommendation is Worth exploring or Speculative, it publishes no plan. When the issue it names is in the repository at origin, the Architect run ends in one of two ways, both a success, with or without `--plan-only`: exit `0`, with one issue's URL alone on stdout. thirdshift labels that issue an **Architect idea** and dispatches nothing: there is nothing to run.

- **An idea issue.** The review files its top recommendation as one issue labelled `needs-triage`, for the **Day shift** to flesh out, and ends its final message with `Architecture review idea: <Issue URL>`. stdout carries the idea issue's URL, and stderr's last line is `no Strong candidate: the Architecture review filed the idea <url>`.
- **Already filed.** An open issue already covers that recommendation, so the review files nothing and ends its final message with `Architecture review already filed: <Issue URL>`. stdout carries that issue's URL, and stderr's last line is `no Strong candidate: <url> already covers the Architecture review's top recommendation, so it filed nothing`.

Either way, thirdshift refuses that issue unless it is in the repository at origin, before viewing it or changing its labels. A refusal fails the Architect run as a failed review does: exit `1`, nothing on stdout, and the cause on stderr, `the issue <url> is not in the repository at origin <origin>`. When the issue is in that repository, including an already-filed issue created before the Architect run, thirdshift puts `architect-idea` and `needs-triage` on it, in one request that keeps its other labels, with a progress line saying so: `labelling #<n> an Architect idea: adding needs-triage and architect-idea`. thirdshift adds `architect-idea`, never the agent, and first creates it if the repository has none, as it does `architect-plan`. `needs-triage` goes back on an issue that already covered the idea even if it had been triaged, `ready-for-human` say, since the factory again takes it for the best next move. If thirdshift can't label the issue, the Architect run fails as a failed review does, with the cause on stderr, `could not label the Architect idea #<n>: <why>`, and in its [Run notification](#one-run-notification).

### An Architect idea waits for triage

An Architect idea means the factory has run out of Strong ideas, so while any Architect idea is open and still labelled `needs-triage`, every later Architect run on the repository is skipped, before any review, instead of filing the next weaker idea or landing on the same issue again. Both labels count in any case, as every label rule does. The check comes after the [Command limit](#the-command-limit) and the [open Architect plan](#one-architect-plan-at-a-time) check, so with both an open plan and a waiting idea, the skip reports the plan:

- **stdout** carries each waiting Architect idea's URL, one a line, newest first.
- **stderr** carries one progress line naming each of them as waiting for triage, several joined by `; `: `Architect idea #<n> "<title>" is waiting for triage: <Issue URL>`.
- **Exit code** `0`: skipped is not a failure. No agent session starts, and nothing else is done.

Any triage decision releases the pause: take `needs-triage` off, whatever replaces it (`ready-for-agent`, `ready-for-human`, `needs-info`, `wontfix` or nothing), or close the issue. The issue keeps `architect-idea`, which only counts alongside `needs-triage`. An idea triaged `ready-for-agent` then goes first under the [Ready issue check](#a-ready-issue-goes-first), even while it is settling, if it meets every other Ready issue condition, so the next Architect run is skipped for it in turn, until a Pickup run, or you, takes it.

### A Ready issue goes first

Work a human shaped goes ahead of the factory's own: while the repository has a **Ready issue**, or an issue that meets every Ready issue condition except settling, every Architect run on it is skipped, before any review. A Spec qualifies with a Startable Ticket, or with every Ticket closed and a Spec branch on `origin` that can be continued under [ADR-0002](adr/0002-existing-issue-branch-means-continue.md): the latest branch has no PR or an open PR. Its hand-back and every other Ready issue condition still apply. A [Pickup run](#pickup-runs) still waits until the issue has settled before taking it. The check comes last, after the [Command limit](#the-command-limit), the [open Architect plan](#one-architect-plan-at-a-time) check and the [waiting Architect idea](#an-architect-idea-waits-for-triage) check, so with an open plan or a waiting idea as well, the skip reports that instead. It is only the search: an Architect run makes no [Sweep](#the-sweep) and holds no [Failure limit](#the-failure-limit), which are the Pickup run's.

- **stdout** carries the URL of the lowest-numbered issue that is Ready or would be Ready once settled, whether it has settled or not.
- **stderr** carries [a line on each issue labelled `ready-for-agent`](#why-an-issue-was-passed-over) passed over before it, then one progress line naming it: `Ready issue #<n> "<title>" goes first: <Issue URL>`, or, while it is settling, `Ready issue #<n> "<title>" goes first once it settles: <Issue URL>`.
- **Exit code** `0`: skipped is not a failure. No agent session starts, and nothing else is done.

An issue passed over for any reason other than settling never skips an Architect run: one that carries a Claim, has an open blocker or an untrusted edit, is a Ticket inside a Spec, is a Spec with open Tickets but no Startable Ticket, is an all-closed Spec without a resumable Spec branch, or is a Base fix's issue, among the rest of the rule. Those get their lines on stderr all the same, and the Architect run goes on. With `pickup.wait_minutes = 0`, there is no settling wait and the check is unchanged. Security runs still check only for settled Ready issues.

The rule doesn't ask whether anything will take the Ready issue. A `ready-for-agent` issue that you mean to run by hand, on a repository with no Pickup line in its crontab, keeps every Architect run on it from starting until you run it, which makes the Claim, or take the label off.

### The Command limit

A **Pass** is a command started with no Issue URL that decides before any work whether it is skipped. The **Command limit**, `pass.command_limit` in the [User config](#user-config), 1 by default, is how many live **Commands** on one repository on one machine skip a Pass there. Every live Command counts: each Pass, its dispatched Spec run or Ticket run included as part of it, and each Ticket run, Spec run or Custom process started by hand with an issue. Only a Pass is ever skipped: a Command started on an **Issue URL** always runs, even at the limit, but it fills a slot, so scheduled Passes back off while you work. A Pass skipped for the limit prints its reason as a progress line on stderr, prints nothing on stdout, and exits `0`. Skipped is not a failure. A skipped Pass does nothing else: no launch pull, no worktree, no agent session, and no issue filed or labelled.

The reason says how many Commands are running and what the limit is, such as `at the Command limit on <owner>/<repo>: 1 Command is running, pass.command_limit is 1` at the default limit, or `at the Command limit on acme/widgets: 2 Commands are running, pass.command_limit is 2`, which tells it apart from a skip for the [Failure limit](#the-failure-limit).

Passes of different kinds share the repository up to the limit: Pickup runs, a Custom process started with no issue, one [Architect run](#architect-runs) and one [Security run](#security-runs) can run side by side. Two Architect runs, or two Security runs, never run on one repository at once: each of the two holds a lock of its kind under the same directory as the slots, and another of its kind is skipped while it is held, with `an Architect run is already running on <owner>/<repo>` (or `a Security run`). A Pickup run and a Custom process take no such lock. An Architect run reviews in its worktree `<repo>-architect` and a Security run in `<repo>-security`, so neither ever removes the other's live worktree as one left behind. Each reserves the plan or the fix it dispatches on `origin` before marking it ready, as a Pickup run reserves the Ready issue it takes, so that a Pickup run beside it never takes the same issue.

The repository is the one `origin` names, so two clones of one repository count as the same, and the limit counts no other repository: Commands on different repositories run at the same time, whatever each one's count. Load across the whole machine is for the [`[resources]`](#host-resources) memory and load waits. A Custom process started with no issue, and whose file declares no Issue-branch worktree, is a Pass for this rule only: it does not take an Architect run's Ready-issue or Architect-idea gates. Its skip keeps a Command record whose outcome is `skipped`. A file that declares an Issue-branch worktree is refused when no issue is given, before any session, rather than skipped.

Each live Command holds a slot: an operating-system lock on a file under `~/.thirdshift/command-slots/<owner>/<repo>/`, taken after a Pass's checks in step 1, or as a Ticket run started on an Issue URL opens its Launch directory, and held until its process exits. A Pass counts the slots held and takes one under a short lock, so two Passes starting together can't both take the last. The operating system releases a slot when its process ends for any reason, a crash, a kill or a reboot included, so there is never a stale slot to clear: the next Pass on the repository runs normally. The files themselves stay, and mean nothing on their own. Every newer Pass also holds a shared lock on the file a thirdshift from before the Command limit locks exclusively, under `~/.thirdshift/architect-locks/`. An older Pass cannot start until all newer Passes end. An older Pass holding that file counts as one Command and keeps every newer Pass out, even above a Command limit of 1: the newer Pass is skipped for the limit if full, or with `an older thirdshift's Pass is running on <owner>/<repo>` otherwise. This preserves the older binary's exclusive access through an update. A review worktree that a killed Architect run, or Security run, left behind is removed by the next of its kind.

To run more at once on a machine big enough for it, raise the limit:

```toml
[pass]
command_limit = 2
```

Each Command beyond the first runs its own sessions and builds in its own worktree, so a higher limit costs Harness quota, memory and CPU on this machine. Pair it with the [`[resources]`](#host-resources) waits, which hold new sessions back while the machine is busy, whatever the count. The Command limit must be a whole number from 1 up; `0`, a negative or fractional number, or a quoted value stops every Command before any work, naming the file and the key.

A skipped Architect run sends no [Run notification](#one-run-notification), even when asked, and neither does a skipped Pickup run ([sends none](#one-run-notification-for-the-issue-taken)). Both make the notification's checks before the slot is counted all the same, so a broken setup fails the pass with exit `1` rather than being skipped.

### One Architect plan at a time

An Architect run is also skipped while an earlier **Architect plan** is still open, so a new refactor is never planned while the last one is unfinished: its pull request waiting for review, its run failed, or its plan published with `--plan-only` and not started.

thirdshift marks every Architect plan with the label `architect-plan`, in step 6: the Spec, or the standalone Ticket, never a Spec's Tickets. Once it holds its slot, and before the launch pull, the worktree and the Architecture review, an Architect run lists the repository's open issues labelled `architect-plan`. If there are any, it is skipped:

- **stdout** carries each open Architect plan's URL, one a line, newest first.
- **stderr** carries one progress line naming each of them with the command that picks it up, several joined by `; `: `Architect plan #<n> "<title>" is still open: pick it up with thirdshift <plan URL>`.
- **Exit code** `0`: skipped is not a failure. No agent session starts, and nothing else is done.

It applies to every Architect run, with or without `--plan-only`, and no flag overrides it. The rule is released by finishing the Architect plan, since merging its work closes the issue, by closing the issue, or by removing its `architect-plan` label. The check reads GitHub, so unlike the Command limit it holds across machines.

An Architect run never retries or dispatches an existing Architect plan. One whose dispatched run failed stays open for you: run `thirdshift <plan URL>` to continue whatever branch and pull request it left, or apply `ready-for-agent` to hand it back to Pickup after settling. The other Ready issue gates still apply. What isn't labelled `architect-plan` never counts here: a plan that a failed or interrupted review left `needs-triage`, or an [Architect idea](#no-strong-candidate), which [pauses Architect runs](#an-architect-idea-waits-for-triage) by its own rule, only while it waits for triage.

The check comes after the Command limit so that the plan of an Architect run that is still running, labelled already while its Spec run or Ticket run goes on, is reported as [already running](#the-command-limit), `an Architect run is already running on <owner>/<repo>`, not as an unfinished plan. A skipped run sends no [Run notification](#one-run-notification), even when asked: its stdout carries the open Architect plans' URLs, and its stderr line their commands.

### On a schedule

thirdshift has no scheduler of its own: the operating system's scheduler runs the ordinary command. This crontab entry, written for a Linux machine with cron, starts an Architect run every night at 02:00. Add it with `crontab -e`, with your own paths in place of `/home/you` and `~/repos/thirdshift`:

```
PATH=/home/you/.local/bin:/home/you/.cargo/bin:/usr/local/bin:/usr/bin:/bin
0 2 * * * cd ~/repos/thirdshift && thirdshift architect base main >> ~/.thirdshift/logs/cron.log 2>&1
```

- **`PATH`** is set because cron doesn't read your shell profile, and `thirdshift`, the Harness's CLI (`claude` unless you chose another), `gh`, `git` and the repository's build tools must all be found. List every directory that holds one, written out in full: cron expands neither `~` nor `$HOME` on that line. `type thirdshift claude gh git` in your own shell shows where they are.
- **`cd`** makes a clone of the repository the **Launch directory**, as for a hand-typed Architect run, and **`base main`** names the [Base branch](#architect-runs), so the branch checked out in the clone doesn't matter: it runs from the clone you work in, whatever you left it on.
- **With a Pickup line on the same minutes**, add `&& sleep 20` between `cd` and `thirdshift architect`, as in the [whole crontab](#a-pickup-run-on-a-schedule) below. This gives the Pickup run a 20-second head start to take its [slot](#the-command-limit) before the Architect run counts the slots.
- **One line per repository, at different hours**, so the Architect runs don't compete for the machine. thirdshift keeps no list of repositories.
- **The log file** takes everything the command prints. A failure before the [Run notification](#one-run-notification)'s checks have passed, such as a broken [User config](#user-config), a missing Resend key or a bad argument, shows up only there: no email is sent for it. Use one fixed file for every line, in a folder that already exists, such as `~/.thirdshift/logs/`: the shell opens it before thirdshift starts, so a line whose folder is missing never starts the command, and nothing reports it. What each pass did on its repository is in that repository's [Activity log](#logs), in folders thirdshift creates itself, and with `activity.quiet_skips = true` the log file holds no skips at all.
- **The Harness's CLI and `gh` must already be logged in** for the user the schedule runs as, with git able to push, as the [Prerequisites](#prerequisites) say. Without a terminal an Architect run behaves as it does from one, except that it never offers Setup.

The command's flags and the User config decide what a scheduled Architect run does, as for a hand-typed one: with `merge.always` it merges the Architect plan's pull request, and without it the pull request is left for review. These are the cautious variants, whatever the User config says:

```
0 2 * * * cd ~/repos/thirdshift && thirdshift architect base main no-merge >> ~/.thirdshift/logs/cron.log 2>&1
0 2 * * * cd ~/repos/thirdshift && thirdshift architect base main --plan-only >> ~/.thirdshift/logs/cron.log 2>&1
```

The first leaves the pull request for you to review, and the second stops at the Architect plan, for you to read and run with `thirdshift <Issue URL>`.

A scheduled Architect run is skipped when the repository is at its [Command limit](#the-command-limit), a Pass's Spec run or Ticket run counted, or another Architect run is still running there, when an [Architect plan is still open](#one-architect-plan-at-a-time), when an [Architect idea waits for triage](#an-architect-idea-waits-for-triage), or when the repository has a [Ready issue](#a-ready-issue-goes-first), so a `ready-for-agent` issue with no Pickup line to take it holds off every night until you run it: no new refactor is planned until last night's Architect plan is closed or loses its `architect-plan` label. Merging its pull request closes it; if its run failed, pick it up with `thirdshift <plan URL>` first. Closing the pull request alone leaves the Architect plan open. A skip exits `0`, so the scheduler sees no failure, and the repository's [Activity log](#logs) has the line that says why, as does the log file unless `activity.quiet_skips` is set. With Run notifications on, by `email.always = true` in the User config or `email` on the line, an Architect run that did work sends one email, and a skipped one sends none, so a crontab line can fire every few minutes, as for [Architect runs every few minutes](#architect-runs-every-few-minutes), without flooding your inbox. A night without an email means it was skipped, or failed before the notification's checks passed: look in the log file.

Any scheduler that runs the command works; a systemd user timer needs lingering on (`loginctl enable-linger`) to fire while you are logged out. Inside a Linux VM on Apple Silicon macOS, use Linux cron or a systemd user timer directly, with `gh` and the Harness authenticated inside the VM. These schedules use the Linux logins and have no macOS Keychain restrictions. Keep the VM running and the Mac awake for schedules to fire.

### Architect runs every few minutes

<a name="weeding" id="weeding"></a>

Start **Architect runs every few minutes** to clear what features leave behind in a codebase as they land, with nobody starting each pass, so each one begins as soon as the last one's Architect plan is merged. thirdshift still never schedules itself ([ADR-0009](adr/0009-the-operating-system-schedules-thirdshift.md)): it is the line from [On a schedule](#on-a-schedule), fired every five minutes instead of nightly, with `merge.always = true` in the [User config](#user-config) so each Architect plan's pull request is merged without waiting for you:

```
PATH=/home/you/.local/bin:/home/you/.cargo/bin:/usr/local/bin:/usr/bin:/bin
*/5 * * * * cd ~/repos/thirdshift && thirdshift architect base main >> ~/.thirdshift/logs/cron.log 2>&1
```

The `PATH` line, the `cd` and `base main` and the logins are as in [On a schedule](#on-a-schedule). Set `activity.quiet_skips = true` in the User config too, so the skips leave the log file alone: each is in the repository's [Activity log](#logs), once per change of reason.

Most passes are skipped, and that is what paces frequent Architect runs. A pass is skipped while:

- **a run is still going**: the repository is at its Command limit, a Pass's Spec run or Ticket run counted, or another Architect run is running there ([The Command limit](#the-command-limit));
- **an Architect plan is open**: one whose pull request waits for review, one whose run failed, or one published with `--plan-only` and not yet built ([One Architect plan at a time](#one-architect-plan-at-a-time));
- **an Architect idea waits for triage**, since the factory has run out of Strong ideas ([An Architect idea waits for triage](#an-architect-idea-waits-for-triage));
- **the repository has a Ready issue**, so work a human shaped goes first ([A Ready issue goes first](#a-ready-issue-goes-first)).

A skip exits `0` and sends no email, even with Run notifications on, so the scheduler sees no failure and your inbox only hears of passes that did work. The repository's [Activity log](#logs) has the line that says why, once for each change of reason. An Architect plan whose run failed stays open, so frequent Architect runs pause for the **Day shift** until you pick it up with `thirdshift <plan URL>`, close it, or take its `architect-plan` label off; an Architect idea pauses it until you triage the idea.

On a repository that also has a [Pickup line](#a-pickup-run-on-a-schedule), put `--plan-only` on the frequent Architect run line instead: the Architect run publishes the Architect plan and marks it ready, and a Pickup run builds it as an ordinary Ready issue, under the [Failure limit](#the-failure-limit), and merges it with `merge.always`, as in the [whole crontab](#a-pickup-run-on-a-schedule) below.

## Security runs

`thirdshift secure` starts a **Security run**, report-only by default: it audits the **Base branch** at its head on `origin` and records each **Security finding** privately as a draft repository security advisory. Start it from a clone on the Base branch, or name that branch from any checkout:

```sh
thirdshift secure
thirdshift secure base main harness claude
thirdshift secure base main harness codex model gpt-6.1-sol effort high
```

After its Command limit, the lock of its kind and skip gates, the Security run
executes the Built-in `security-run` file: `security-audit` → `reproduce-findings` → `fix-findings` →
`close-findings`. Read it with `thirdshift process show security-run` and
validate it with `thirdshift process check security-run`. The file owns the
sequence; sessions, progress, logs, Run notifications and the Security run name
stay the same.

The command takes the Harness, Model and Effort words and the shared Pass words (`merge`, `no-merge`, `base-fix`, `no-base-fix`, `parallel`, `email`, `email-unless-merged`, `no-email`, `security-fix`, `no-security-fix`, `security-close` and `no-security-close`, with or without dashes). After recording findings, it tries to reproduce each untriaged one in a fresh throwaway worktree at the recorded audited commit, and keeps the outcome, severity when reproduced, notes and test in the private record. It preserves findings already triaged by the Day shift. It never publishes an advisory.

Fixing is off by default. `security-fix` on the command or `fix = true` under `[security]` allows one fix; `no-security-fix` overrides the setting. Both words are accepted on every command that starts Ticket runs and passed to those Ticket runs. With fixing allowed, a Security run takes the most severe reproduced finding still awaiting a fix before auditing, with ties in private-record order. After an audit reproduces findings, it goes on to the most severe one.

Closing is on by default when fixing is allowed. `no-security-close` on the command or `close = false` under `[security]` leaves the finding open after fixing; `security-close` overrides that setting. After a dispatched fix ends merged, the run re-runs the private record's proof-of-concept test against the merged Base branch in the reproduction sandbox. When the test now passes, the run names the merged pull request in the private record and closes it: a draft advisory through its description and state, a finding issue with a comment naming the pull request before it is closed. A fix left ready for review closes nothing, and a test that still fails, or cannot run, leaves the record open with a private note of what happened; a failed close never changes the fix's outcome. A closed record is never picked up as waiting or as the next fix.

A publishing session reads the private record and follows the reproduction's fix-size decision: a single **Ticket**, or a **Spec** with **Tickets** through `thirdshift-to-spec` and `thirdshift-to-tickets`. Every new issue is terse, saying only what the fix changes and linking the private record. thirdshift checks all the issues, reserves the top issue on `origin` as a [Pickup run](#pickup-runs) reserves the Ready issue it takes, failing if another run holds it, swaps the top issue's `needs-triage` for `ready-for-agent`, adds `security-fix` to every fix issue (creating the label when missing), records the fix link privately and dispatches its **Ticket run** or **Spec run**. The Security run ends as that run ends, including a **Ticket run** that Self-merges when asked by the command or the User config.

On a public repository, thirdshift checks issues created during the publishing session's window before creating the staged issue or Spec, and again after linking a Spec's Tickets. The second sweep skips the staged Spec and its Tickets. Each other issue's title and body face the same public-text check as staged text: they must link the private record and include none of its private write-up lines or test text. Issues that fail are closed and fail the Security run. Issues that pass are left open, named in the **Activity log**, and do not fail the run. The time window alone does not establish who created an issue.

On a private repository, the finding's own issue is the fix's Ticket or Spec, keeping its write-up and proof-of-concept. A one-session fix needs no publishing session or second issue: thirdshift marks the finding's issue ready and dispatches it. For a bigger fix, the publishing session adds terse Tickets as that issue's native sub-issues, with their blocking links.

A failed fix keeps its **Claim**, even if it pushed nothing, and stays open for the **Day shift**. No later Security run or Pickup run retries it. Security runs pause while that fix's issue is open; closing the issue lets them go on.

`email` or `email-unless-merged`, optionally followed by an address, or `email.always` or `email.unless_merged` in the User config asks for one **Run notification** when the Security run ends, whether the audit succeeded, failed or was interrupted. `no-email` overrides the default. The notification says how the audit ended and lists each finding it recorded or matched to an existing private record: its severity when known, title and private link. It includes no finding write-up, trace or evidence, since it passes through Resend. When the Security run dispatches a fix, the notification lists that finding under `Addressed by the pull request:`, or under `Fix attempted, not fixed:` when the fix failed or was interrupted, and its audit's other findings under `Recorded, waiting for the Day shift:` while their records wait for triage, else under `Also recorded by the audit:`. Findings left waiting put the Security run in the Inbox's Needs you; the fixed one does not. Its `Audit:` line then says how the audit ended, or `not run` when it fixed an earlier finding without auditing; the `Result:` and `Pull request:` lines tell how the fix ended. When a fix merged, it also says which finding was closed by which pull request, or that the finding was left open and why. Detailed failure causes stay in the local logs; the notification gives the audit's status and log paths. A recording failure still lists the records reached before it failed. When a run leaves a reproduced finding unfixed and neither the command nor the User config decided against fixing, its notification and stderr offer both `thirdshift secure security-fix` and `fix = true` under `[security]`. With `no-security-fix`, or the setting turned off, it offers nothing. A skipped Security run sends none. The usual address and Resend API key checks run before the skip checks or any work; a failed send is a warning and never changes the run's outcome.

If a Security run fails before its audit starts, its Run notification says `Result: pre-audit failed` and `Audit: not started`. A Base branch missing both locally and on `origin` gives `Cause: Base branch not found`. A branch present only locally, a detached HEAD with no Base branch named, or local Base branch commits absent from `origin` gets a fixed Base branch Cause too. GitHub failures keep their fixed dependency or rate-limit Cause; other failures say `pre-audit checks failed`. Raw diagnostics stay on the machine; the notification says which host and start time to check on stderr.

A Security run chooses its Harness from the command's `harness` word, then `[security] harness` in the User config, then `harness.default`, then Claude Code. When `security.harness` is blank or missing, it uses `harness.default`; when `harness.default` is also missing, it uses Claude Code. Model and Effort come from the chosen Harness's own `[harness.<name>]` section, with command words taking precedence. For example, `harness claude` overrides `[security] harness = "codex"` and uses `[harness.claude]`.

Codex security sessions and their Resumes set `agents.max_concurrent_threads_per_session=8` and ask for fresh sub-agents with `fork_turns: "none"`, so the skill's verifiers stay independent.

A Security run checks its gates in order: the [Command limit](#the-command-limit) and another Security run on the repository running on the machine, a **Ready issue**, a failed Security fix whose issue is still open, then an unchanged **Base branch** since the last completed Security audit. A **Security finding** waiting for the **Day shift** is not a gate: a draft advisory with no severity, an open finding issue with `needs-triage`, or a reproduced finding while fixing is disabled holds off no audit. When an audit finds such a finding again and its reproduction has completed, reproduced with a severity or not reproduced, thirdshift keeps that outcome and starts no reproduction session for it; the Run notification lists it with its known severity. A finding whose reproduction never ran, failed, was refused or was interrupted is reproduced again, and a finding the Day shift graded keeps its grade. The audited commit comes from the skill's own `run-metadata.json` under the audit root, with no separate state file. A skip exits `0`, starts no session, keeps no Command log and sends no Run notification; its reason goes into the repository's **Activity log** only when it changes, with the usual `activity.quiet_skips` behavior. Before starting work, thirdshift checks the chosen Harness and that **Node.js** is on `PATH`, since the embedded skill's report validators require it.

The Security audit runs in a throwaway worktree, `<repo>-security` next to your clone, detached at origin's Base branch head, leaving the Launch directory and local work untouched, including when `launch.pull` is set. The fix's publishing session and the close's recheck use it too. Only a Security run uses that name, and only one runs on a repository at a time, so the one beside an [Architect run](#architect-runs), which reviews in `<repo>-architect`, never removes the other's worktree. Its Session prompt runs `thirdshift-security-audit` in full audit mode with the `quick` profile, auditing the whole repository except vendored and third-party code. It names a `SECURITY.md` or conventional threat-model document when present, reads compatible earlier runs and ends `incomplete` instead of asking for input.

Each audit keeps a new output directory under `<logs.dir>/<owner>/<repo>/audits/`, outside the worktree. The audit artifacts and private advisory descriptions contain evidence; keep the logs directory private. thirdshift runs both embedded validators before recording anything. A missing final line, an incomplete session or an invalid report fails the run and names its Session trace. Command logs and Session traces are in `commands/secure/`; Session traces are named `secure-<stamp>~<token>-security-audit.logs.jsonl`; the Activity log records the start and ending as for other Passes.

A finding's title becomes the advisory summary. Its description preserves its write-up, trace, evidence and validation plan, with the fingerprint and audited commit. thirdshift claims no severity, CWE or affected version range. It uses the package in the repository's manifest, or the `other` ecosystem when none is identified. Matching fingerprints in any advisory state are kept rather than recorded again. Rejected candidates stay in the local report and produce no advisory. Draft advisories require GitHub repository security manager or administrator access. On a private repository whose advisory endpoint is unavailable, the private record is an issue labelled `security-finding` and `needs-triage`. It is never replaced by a public finding issue.

### Security review

`security-review`, or `review = true` under `[security]`, enables one guidance review after a Ticket run's opening session, a Spec run's Spec review, or a Review run's review-and-address Step, before Delivery pushes. A Spec run reviews every Ticket against its Spec branch and the whole Spec branch against its Base branch once. `no-security-review` overrides the setting. Both words, with or without dashes, are accepted on Review runs and commands that start Ticket runs and follow dispatched Ticket runs and Base fixes. `--recommend-only` skips the Security review. Setup asks about the setting; it is off by default.

The review runs on `[security] harness` when that is set, with that Harness's own `[harness.<name>]` Model and Effort, wherever it runs: in a Ticket run, each Ticket, on a Spec run's Spec PR, in a Review run or in a Base fix. The command's `harness`, `model` and `effort` words choose the Harness of every other session, and don't change the review's; there is no word for the review's Harness. With `security.harness` blank or missing, the review runs on the Command's Harness. Every other session, Repairs and Resumes after the review included, stays on the Command's Harness.

Before any session, a command checks its review's Harness with the same PATH, Model, Effort and sign-in checks as its own. If a non-default review Harness can't be used, the review falls back to `harness.default`, or Claude Code when blank, with that Harness's own configured Model and Effort. A single `warning:` line names both Harnesses and the reason. If the review Harness is already the default, or the fallback also fails its check, the command fails at preflight. A Spec run checks before any Ticket starts and hands the settled choice to all Tickets and the Spec PR. With Security review off, no review Harness is checked. A Pass checks it only if it may dispatch a Ticket run: a Security run that only audits, or `architect --plan-only`, does not.

If a non-default review Harness passes preflight but returns a Harness error before any turns or tokens, thirdshift warns in the same way and retries the review once on the default Harness. A failure on the default, a model refusal or a failure after work starts is not retried. Each attempt keeps its own Session trace and `.models.json`; the retry uses `security-review-fallback`, also selected by `logs --session security-review`. Those records, the Command log and the Run notification name the Harness each attempt actually ran on; the `Built with` line still names the Command's. A Continuation reads `security.harness` again and applies these checks again.

The session reads the relevant attack-class guidance and supporting code without delegated auditors or the full audit workflow. It fixes only findings reproduced by a failing proof-of-concept test, keeps that test and commits the fix. Unaddressed introduced findings appear under Security in the PR's Unaddressed findings. A Ticket run or Spec run asked to Self-merge leaves the PR ready for review and fails with the findings named if any remain, or if the review was refused or incomplete. A Ticket run or Spec run not asked to merge records the outcome and continues. An old finding, whose proof-of-concept also fails at the pinned merge base, is reported in a private file under the repository's logs (`security-reviews/`). thirdshift records it as a draft advisory, or a `security-finding`/`needs-triage` issue on a private repository, reusing existing fingerprints and preserving the Day shift's grades. New records include scored reproduction and fix-size metadata so a later Security run can take the fix when allowed. Its details stay out of the PR and it does not hold Self-merge; fixing belongs to a separate Security run. The separate Security audit retains its full audit workflow.

### Security runs on a schedule, with fixing allowed

<a name="fencing" id="fencing"></a>

Start **Security runs on a schedule, with fixing allowed** to find and fix vulnerabilities with nobody starting each pass. thirdshift never schedules itself ([ADR-0009](adr/0009-the-operating-system-schedules-thirdshift.md)). This Linux crontab entry starts one every five minutes; use your own paths, with `claude` and `gh` already logged in and Git able to push:

```cron
PATH=/home/you/.local/bin:/usr/local/bin:/usr/bin:/bin
*/5 * * * * cd /home/you/repos/widgets && thirdshift secure base main harness claude security-fix >> /home/you/thirdshift-secure.log 2>&1
```

Each pass yields to a **Ready issue**, so work the **Day shift** shaped goes first. It is skipped while the repository is at its [Command limit](#the-command-limit) or another Security run is running there, while a fix has failed and its issue stays open, or while the Base branch is unchanged and no fix is waiting. A failed fix pauses scheduled Security runs for the Day shift until its issue is closed; it is never retried by a later Security run or Pickup run. Findings waiting for triage hold off no audit, and a finding found again is not reproduced again once its reproduction has completed. With fixing allowed, a reproduced finding is fixed before the next audit.

A skip exits `0` and sends no Run notification. Its reason appears in the **Activity log** once per change of reason. Set `activity.quiet_skips = true` in the [User config](#user-config) to keep those skips out of the scheduler's log. `merge` on the command, or `merge.always = true` in the User config, lets each fix's Ticket run merge its pull request; otherwise it stays ready for review.

## Pickup runs

`thirdshift pickup` starts a **Pickup run**: one pass, with no **Issue URL**, that takes the lowest-numbered **Ready issue** in the repository and runs it, so that an issue you have already marked ready needs no command typed for it. Start it from a clone of the repository, on the **Base branch**, or name the Base branch with `base <branch>`:

```sh
cd ~/repos/widgets
thirdshift pickup                      # take the lowest-numbered Ready issue and run it
thirdshift pickup merge parallel 2     # merge its pull request; two Tickets at once if it is a Spec
thirdshift pickup base main no-merge   # run it on main, whatever branch the clone is on, and leave its pull request for review
thirdshift pickup highest-first        # take the highest-numbered Ready issue instead, for that one pass
```

Pickup has no Built-in process file. It selects and reserves the Ready issue,
then starts `ticket-run` or `spec-run` as a command on that Issue URL would.

Which end of the issue numbers the pass takes is its order: `lowest-first` by default, `highest-first` with `pickup.order = "highest-first"` in the [User config](#user-config), or for one pass with `lowest-first` or `highest-first` on the command, which wins over the User config. Two schedules working through the same queue from opposite ends, one with each order, collide less often; the reservation below still protects either choice.

A Ready issue is an open issue that:

- is labelled `ready-for-agent`: an issue without the label is never taken;
- has none of the labels that make an **Unready Ticket**, `ready-for-human`, `needs-info`, `wontfix` and `needs-triage`, so a contradictory label errs on the side of not running;
- carries no [Claim](#the-claim): it is not labelled `in-progress`;
- is not a sub-issue. A sub-issue is a **Ticket** of a **Spec**, and is never run on its own, whatever the Spec's labels: it is reached through its Spec, when the Spec is itself a Ready issue, so its work always goes through the **Spec branch**. Labelling one Ticket never promotes its Spec, either;
- is not labelled `base-fix` or `security-fix`: the Ticket run that opened a [Base fix](#base-fix)'s issue, or the Security run that dispatched a fix, owns it. A failed Security fix is still passed over if GitHub prevented its Claim from being made;
- has no open blocker, by GitHub's "blocked by" links, never the text of its body. Once every blocker is closed, it can be taken;
- either was never started (no **Issue branch** on `origin` and no pull request from one, open, merged or closed), or you handed it back by applying `ready-for-agent` at or after its last [Claim](#the-claim) ended. A Spec whose Spec run ended only waiting is handed back by thirdshift the same way, unless its title or body was edited by an account that is not a Trusted account. For started work, the full label history must show an earlier `in-progress` application and its removal, with `ready-for-agent` applied at that removal's timestamp or later. A swap made in one edit counts in either listed order; a new Claim applied at the same timestamp leaves the issue Claimed. Work never Claimed, or without that hand-back, stays with you. An eligible branch with no PR or an open PR follows the existing [Continuation](#continuation) rule; merged or closed PRs follow ADR 0002 and start a fresh numbered branch. This is deliberate hand-back, not automatic retries;
- if it is a **Spec** whose **Tickets** are all closed, its Spec run can continue its Spec branch on `origin` under [ADR-0002](adr/0002-existing-issue-branch-means-continue.md): the latest numbered branch is present, with no PR or an open PR. The dispatched Spec run goes straight to the Spec review and the Spec PR's Delivery and Repair loop, without running a Ticket again. A PR without its branch, or a retained branch whose latest PR is closed or merged, does not qualify. Without a resumable branch, waiting never makes it a Ready issue: close it, or take its `ready-for-agent` off;
- is settled: by default, five minutes have passed since the latest of `ready-for-agent` being applied to it, a sub-issue being added to it or removed, and a "blocked by" link being added to it or removed. So a Spec is not taken while its Tickets are still being attached. These are read from the issue's timeline, since adding a sub-issue does not change the issue's update time, and `pickup.wait_minutes` in the [User config](#user-config) sets the window in whole minutes from 0 up, within the supported duration range; 0 disables waiting. An Architect run also waits for an issue that meets every other Ready issue condition while it is settling. A later pass takes the issue once it has settled;
- if it is a **Spec** with open Tickets, has a **Startable Ticket**: an open Ticket in the Spec's repository, with no sub-issues, no open blocker and none of the labels that make an Unready Ticket. That is the rule a [Spec run](#spec-runs) picks its next Ticket by, as if nothing were running yet, so a Spec whose open Tickets all wait on you, such as one whose last open Ticket is `needs-info`, is passed over rather than Claimed for a Spec run that could start nothing and would fail. This applies to a Spec handed back with `ready-for-agent` too. A Spec with one Startable Ticket is taken, and the Spec run handles its other Tickets as usual. Once a Ticket becomes startable, because its Unready label comes off or its blocker closes, a later pass takes the Spec. Its Tickets are read only for a Spec that meets every other condition.

A Pickup run:

1. Makes the checks an [Architect run](#architect-runs) makes, before anything else but the [Run notification](#one-run-notification-for-the-issue-taken)'s own: `origin` is a GitHub repository, git has a `user.name` and `user.email`, HEAD is not detached unless `base <branch>` names the Base branch, and the Base branch exists on `origin` with your local copy not ahead of it. A check that fails stops the pass with exit `1`, before any label is read or changed.
2. Takes a slot on the repository, and is [skipped](#the-command-limit) if the repository is at its Command limit on the machine.
3. Checks the Base branch's latest push CI on `origin`, filing a [CI-red Ticket](#when-the-base-branch-stays-red) when needed, then takes `in-progress` and `agent-failed` off the repository's closed issues: the [Sweep](#the-sweep).
4. Counts the repository's open issues labelled `agent-failed`, taking `in-progress` off each, as part of the Sweep, and `agent-failed` off each one you handed back, and is skipped if the repository is at its [Failure limit](#the-failure-limit).
5. Lists the repository's open issues labelled `ready-for-agent`, in its order (lowest number first by default, highest number first with `highest-first`), and takes the first that is a Ready issue, saying so on stderr: `taking Ready issue #<n> "<title>", as thirdshift <Issue URL> would`. Each one it passes over on the way gets [a line saying why](#why-an-issue-was-passed-over). One issue a pass: the rest wait for the next.
6. Atomically reserves the selected issue on `origin`, then rechecks that it is still Ready and no Claim has been made since selection. If another Pickup run, or an Architect run or Security run dispatching its own plan or fix, holds the reservation, the issue ceased to be Ready, or an intervening Ticket run has already taken it and returned it to Ready, it says `#<n> is reserved by another run or is no longer Ready`, with the reservation ref to inspect if it stays reserved, releases any reservation of its own, and searches again for the next Ready issue past that one in its order, reserving and rechecking it the same way. Only when none it can reserve is left is the pass skipped, with exit `0`, no Claim, no session and no notification. So two Pickup runs that select the same issue both find work when the repository has two Ready issues. This also protects two hosts using the same GitHub identity, with settling disabled or clocks out of sync.
7. Dispatches it exactly as `thirdshift <Issue URL>` would from the same clone on the Pickup run's Base branch: a [Spec run](#spec-runs) when the issue has sub-issues, a Ticket run otherwise. That run makes the Claim, so the issue's `ready-for-agent` is swapped for `in-progress` and no later pass takes it again. The reservation lasts through the dispatched run's ending, including failed-work preservation and Claim ending, then is released with an exact ownership check, even after interruption.

Every Pickup host must run a version that honors reservations. The reservation branch is `thirdshift/pickup/<issue-number>`. An [Architect run](#architect-runs) takes the same reservation for the plan it dispatches, and a [Security run](#security-runs) for its fix, before marking it ready; direct Issue URL commands keep their existing behavior. A crash or an uncertain remote failure can leave a reservation behind. Before releasing one, confirm its host's Command has stopped. Inspect `git ls-remote origin refs/heads/thirdshift/pickup/7`, fetch that ref, and read its commit message for the host, launch path, process and start time. `Host:` records the OS hostname (`unknown` if unavailable); older reservations have no host field and remain valid. Then delete it with the observed SHA as an exact lease: `git push --force-with-lease=refs/heads/thirdshift/pickup/7:<observed-sha> origin :refs/heads/thirdshift/pickup/7`. Never delete a live owner's reservation or remove one on a timer. Repository permissions must allow creating and deleting these branches. See [ADR 0017](adr/0017-pickup-reserves-issues-on-origin.md).

`merge`, `no-merge`, `base-fix`, `no-base-fix`, `parallel <n>`, `harness <name>`, `model <name>` and `effort <level>`, with or without dashes, are for the dispatched run, and mean what they do for `thirdshift <Issue URL>`, as do `email` or `email-unless-merged`, optionally followed by an address, and `no-email` for the Pickup run's [Run notification](#one-run-notification-for-the-issue-taken). The [User config](#user-config) sets what they leave unsaid: `merge.always`, `base.fix`, `spec.parallel`, `email.always`, `email.unless_merged`, `launch.pull` and `logs.dir`. A User config a Ticket run would refuse stops the pass the same way, before any check. `parallel <n>` applies when the Ready issue is a Spec and is ignored, with no error, when it isn't, unlike on an Issue URL: the command can't know which it will take. `base <branch>` (or `--base <branch>`) names the Base branch as it does for [`architect`](#architect-runs), and the dispatched run takes it: its Issue branch or Spec branch is branched off `<branch>`, and its pull request targets it. With `base <branch>`, a Pickup run started [on a schedule](#a-pickup-run-on-a-schedule) runs from the clone you work in, whatever branch you left it on.

`lowest-first` and `highest-first`, with or without dashes, are for the Pickup run itself: they set its order for that one pass, winning over `pickup.order`. `secure` and `thirdshift <Issue URL>` take neither.

`pickup` is a command only as the first argument, and takes nothing but those flags, each at most once: a focus, `--plan-only`, an Issue URL, a repeated or contradictory flag, or any other argument is an argument error (exit `2`).

The dispatched run's ending is the Pickup run's: its exit code, its pull request's URL alone on stdout, and its last line on stderr, `PR <url> is ready for review` or `PR <url> is merged`. If it fails, the Pickup run fails as that [Failed ticket run](#failed-ticket-runs) or Failed spec run does. After an [Inherited failure](#an-inherited-failure-links-the-base-branchs-checks), the command it offers is `thirdshift <Issue URL>` with the dispatched run's flags and `base-fix`, since another Pickup run needs you to remove its Claim and then apply `ready-for-agent` before it can take started work again.

A pass is **skipped** when the repository is at its [Command limit](#the-command-limit), when the repository is at its Failure limit, when the repository has no Ready issue, or when every Ready issue it found was reserved or stale: it exits `0` with stdout empty and a reason on stderr. The last says `no Ready issue on <owner>/<repo> it can reserve, past #<n>`, naming each issue it tried and its reservation ref to inspect if it stays reserved, after each one's own line. Skipped is not a failure. A skipped pass starts no agent session, makes no Claim, and sends no Run notification. One skipped for the Command limit changes no label at all; the others have made the Sweep, whose lines come before the reason.

### When the Base branch stays red

After taking a Command slot, Pickup reads the latest push workflow run for its Base branch in the repository named by `origin`. A failed first attempt immediately requests one re-run of its failed jobs, names the run and jobs on stderr, and files nothing on that pass. Later attempts are never re-run by Pickup. A refused or impossible re-run warns and proceeds directly to ordinary filing.

If the re-run also fails, Pickup waits 30 minutes from that attempt's completion, then opens a Ticket titled `CI red on <base>`, labelled `bug`. Its body names the failing commit and links the run and its attempts. Job names and log lines stay out of the title, the body, and a comment on an open CI-red Ticket. You write the task and apply `ready-for-agent` before a Pickup run can take it. An open CI-red Ticket in `needs-info` does not block a new report. Another open CI-red Ticket suppresses a second Ticket, even across Base branches, but receives the new evidence as a comment when the failing commit differs, at most once per commit. That comment names the commit and the attempts.

If the same commit passes after a failed attempt, Pickup immediately files a **Flaky-test Ticket** titled `Flaky CI on <base>: <failed jobs>`, labelled `flaky-test`, `bug` and `ready-for-agent`. It records both attempt URLs and the failed attempt's jobs and test lines. Only one report is filed per failed attempt, including after the report closes, and an open Flaky-test Ticket naming the same test suppresses another. Its Ticket run uses the recorded failure as evidence and goes straight to implementation, removing dependence on timing or scheduling, or the race exposed by the test, without requiring reproduction on demand or ending with `needs-info` for lack of it. Other bug Tickets keep their ordinary diagnosis path. A green first attempt or an unfinished latest run files nothing.

A Flaky-test Ticket follows the ordinary Ready issue rules, including settling and the Failure limit: this pass or a later one can take it. A CI-red Ticket waits until you write its task and apply `ready-for-agent`. Filing does not hold Self-merges, and runs only in Pickup, never in a Ticket run, Spec run or Architect run. A failure to read CI or publish the Ticket is a warning; Pickup continues its ordinary search and dispatch.

Concurrent hosts serialize evidence reads, re-running, filing and commenting with `refs/heads/thirdshift/pickup/ci-red` on `origin`, using the same empty-create and owner-token release leases as issue reservations. An occupied reservation skips only these CI actions. After a crash, confirm its owner has stopped before releasing it with the exact observed SHA, as for the numbered reservation described above. CI evidence and issue deduplication must be readable before filing. A CI-red Ticket does not read job logs. Unreadable job logs leave Flaky-test filing for another pass.

### The Failure limit

A Pickup run or Triage Pass takes nothing while the repository is at its **Failure limit**: as many open issues the factory failed on, labelled `agent-failed`, as the limit, which is 3 unless you set it. Three failures in a row on one repository usually mean a broken Base branch or Harness, not three bad issues, so the factory stops spending sessions on the rest of the backlog until you look. A failed Triage run leaves `ready-for-human` and `agent-failed`; that still waits for you until you put `ready-for-agent` back, remove `agent-failed`, or close it. A pull request that is ready for review, or merged, never counts: the factory keeps working while reviews wait.

- thirdshift labels an issue `agent-failed`, in place of `in-progress`, when a [Failed ticket run](#failed-ticket-runs) or a Failed spec run [leaves work on `origin`](#when-the-claim-ends), whoever started it: a Pickup run, an Architect run, a Security run, or you on its Issue URL. A failed Security fix is labelled too, even with nothing on `origin`, as is an issue a failed [Custom process](#custom-processes) left work on `origin` for. stderr says `labelling #<n> agent-failed, in place of in-progress, so it waits for the Day shift`. The label is added to the repository if it lacks it, and labelling finishes after Ctrl-C, as ending the Claim does; a failure is a `warning:` naming the command to run by hand.
- Nothing is labelled when the Claim is released because nothing of the run is on `origin`, when a [Spec run](#spec-runs) ended only waiting, when a [Stop](#stopping-a-command) ended the run, when a policy, security or merge hold held a Self-merge and left its pull request ready, or when a bug Ticket run ended with `needs-info`.
- The label comes off when you act on the failure, in one of three ways ([ADR 0029](adr/0029-in-progress-marks-only-a-live-run.md)). Put `ready-for-agent` back to retry: before it counts, each Pickup run or Triage Pass takes `agent-failed` off every open issue that has `ready-for-agent` again and doesn't count that issue, saying `taking agent-failed off #<n>, which the Day shift handed back` on stderr. Take `agent-failed` off yourself to take the failure over. Removing `ready-for-human` alone is not acknowledgement. Or close the issue, and the [Sweep](#the-sweep) takes it off. The issue's next Claim takes it off too. An open issue labelled `agent-failed` with neither `in-progress` nor `needs-triage` is not taken over: a failure leaves it that way, so it still counts. A failure to take the label off a handed-back issue is a `warning:` line, and the issue is still not counted.
- `pickup.failure_limit` in the [User config](#user-config) sets the limit, a whole number from 1 up, by default 3. `failure_limit = 1` stops at the first failure. There is no command-line flag for it.
- At or over the limit, the pass is skipped: exit `0`, stdout empty, no Run notification, and the reason on stderr names every counted issue, lowest number first, along with the limit, such as `at the Failure limit on acme/widgets: #924, #936 and #953 are labelled agent-failed, pickup.failure_limit is 3`. No Ready issue is looked for, and no session is started.
- If the issues can't be counted, the pass stops with exit `1` and `gh`'s error.
- The old `pickup.limit` counted every Claim, pull requests waiting for review included. It is accepted and ignored, whatever its value: each Command warns of it on stderr, naming `pickup.failure_limit`, and the repository's [Activity log](#logs) records the warning once per change. Remove the line; a later release will refuse it as an unknown key. See [ADR 0026](adr/0026-pickup-counts-failures-and-passes-share-a-repository-up-to-a-command-limit.md).

### The Sweep

In the **Sweep**, each Pickup run or Triage Pass, once it holds its slot and before it counts, lists the repository's closed issues labelled `in-progress` or `agent-failed` and takes both labels off each, so an issue whose pull request you merged by hand doesn't look taken, or failed, for ever. It also removes `in-progress` from closed pull requests. As it counts the [Failure limit](#the-failure-limit), it also takes `in-progress` off every open issue labelled `agent-failed`, since no Run is live on a failure: that brings issues failed before `in-progress` came off at a Run's end in line, and keeps them so.

- Only `in-progress` and `agent-failed` are removed, in one request per issue: the closed issue's other labels stay. stderr says `taking in-progress off #<n>, which is closed`, or `taking in-progress and agent-failed off #<n>, which is closed`.
- On an open issue labelled `agent-failed`, only `in-progress` comes off, and its other labels stay: stderr says `taking in-progress off #<n>, which is labelled agent-failed`. The issue still counts towards the Failure limit unless it was handed back, when `agent-failed` comes off in the same request: `taking in-progress and agent-failed off #<n>, which the Day shift handed back`.
- It runs on every pass that gets a slot, one that is then skipped for the Failure limit or for having no Ready issue included, and not on one skipped for the Command limit.
- A failure, to list the closed issues or to take the labels off one, open or closed, is a `warning:` line on stderr, such as `warning: could not take in-progress off #<n>: <gh's error>`, and the pass carries on: the next pass tries again.

### Why an issue was passed over

Each open issue labelled `ready-for-agent` that a pass looks at and does not take gets one line on stderr, naming the issue and the first reason that applies, in the order of the Ready issue rule above. The lines come before the line that says what the pass did, so the cron log explains why nothing started:

```
thirdshift: 03:00:01 Pickup run starting, 2026-10-03 -0400
thirdshift: 03:00:02 #18 labelled needs-info
thirdshift: 03:00:02 #19 labelled in-progress
thirdshift: 03:00:03 #21 is a Ticket of #20, which is not ready
thirdshift: 03:00:03 #26 labelled base-fix
thirdshift: 03:00:04 #30 blocked by #29
thirdshift: 03:00:05 #31 started: issue-31 is on origin; no ready-for-agent hand-back after the last Claim ended
thirdshift: 03:00:06 #32 started: PR https://github.com/acme/widgets/pull/37; no ready-for-agent hand-back after the last Claim ended
thirdshift: 03:00:06 #33 every Ticket is closed
thirdshift: 03:00:07 #34 not settled: labelled ready-for-agent less than 5 minutes ago
thirdshift: 03:00:07 #35 not settled: a sub-issue added or removed less than 5 minutes ago
thirdshift: 03:00:08 #36 not settled: a "blocked by" link added or removed less than 5 minutes ago
thirdshift: 03:00:09 #38 has no Ticket that can start: #39 labelled needs-info; #40 blocked by #39; #41 blocked by #12 (outside the Spec)
thirdshift: 03:00:09 no Ready issue on acme/widgets
```

A line with `blocked by` names every open blocker. A Ticket's line names its Spec: the Ticket runs when its Spec does. A Ticket whose Spec is a Ready issue gets no line: its Spec is taken, by this pass or a later one. A started issue without a recorded hand-back gets the `started` line. Even with a hand-back, a Spec with every Ticket closed is passed over with `every Ticket is closed` unless its latest Spec branch on `origin` can be continued, with no PR or an open PR. A Spec whose later Ticket read is empty is still passed over. One with open Tickets but no Startable Ticket gets `has no Ticket that can start`, naming each open Ticket and why it can't start: the Unready label it has, the open issues blocking it, `has sub-issues` or `outside the Spec's repository`. When a later issue is a Ready issue, the lines on the earlier ones are printed and it is taken:

```
thirdshift: 03:00:01 Pickup run starting, 2026-10-03 -0400
thirdshift: 03:00:02 #18 labelled needs-info
thirdshift: 03:00:03 #20 blocked by #17
thirdshift: 03:00:04 taking Ready issue #22 "Sharpen the widgets", as thirdshift https://github.com/acme/widgets/issues/22 would
thirdshift: 03:00:04 logging this command to ~/.thirdshift/logs/acme/widgets/commands/pickup/22-20261003T030001-0400~aB3cD4eF5gH6iJ7k.log
```

### One Run notification for the issue taken

A Pickup run asked for a [Run notification](#run-notifications), by `email` or by `email.always = true` in the [User config](#user-config) without `no-email`, sends exactly one when it took a Ready issue (asked by `email-unless-merged` or `email.unless_merged`, only when the dispatched run did not merge): the notification the Spec run or Ticket run it dispatched would have sent started by hand. An address after `email` wins over the Launch directory repository's `email.to_by_repo` entry, which wins over `email.to`.

- **Subject**: that run's, `[thirdshift] <owner>/<repo>#<n> <issue title>: <outcome>`, naming the issue taken, with the outcome `ready for review`, `merged`, `failed`, `interrupted` or `paused`.
- **Body**: that run's too: what a Ticket run's notification holds, with `Issue:` immediately after `Result:` linking the issue it took, then its `Title:` (the parent Spec when it dispatched a Spec run), and after a Spec run a line per Ticket. The time it gives is the whole pass's, the search for the Ready issue included.

The email goes after the outcome is final and printed, and a failed send is only a `warning:` line on stderr: it changes neither the exit code nor stdout. The dispatched run sends no notification of its own, whatever the User config says, as with an [Architect run](#one-run-notification), nor do a Spec run's Ticket runs.

A skipped pass sends no notification, even when one was asked for: a pass every half hour would otherwise send dozens a day. A skipped Architect run sends none either.

The notification's checks, an address and a Resend API key, are made before any other work on every pass, before the checks in step 1, the Command limit and any label read or changed. A broken setup therefore stops the pass with exit `1`, naming what is missing, even a pass that would have been skipped, so it shows in the scheduler's log on the first pass, not only once an issue is ready. A pass that asks for no notification makes none of these checks.

### A Pickup run on a schedule

thirdshift has no scheduler of its own ([ADR-0009](adr/0009-the-operating-system-schedules-thirdshift.md)): the operating system's scheduler runs the ordinary command, one pass each time. This crontab entry, written for a Linux machine with cron, starts a pass every half hour. Add it with `crontab -e`, with your own paths in place of `/home/you` and `~/repos/widgets`:

```
PATH=/home/you/.local/bin:/home/you/.cargo/bin:/usr/local/bin:/usr/bin:/bin
*/30 * * * * cd ~/repos/widgets && thirdshift pickup base main >> ~/.thirdshift/logs/cron.log 2>&1
```

The `PATH` line, the `cd` and `base main`, the log file's directory, the logins the Harness's CLI and `gh` need, and schedulers other than cron are as for an Architect run: see its [On a schedule](#on-a-schedule). What differs for a Pickup run:

- **The interval** sets how soon a Ready issue is taken and how much work is started: a pass takes one issue, so `*/30` starts at most one every half hour. A pass lasts as long as the run it dispatched, and the passes that fire meanwhile are skipped, so at the default [Command limit](#the-command-limit) of 1 the schedule builds one issue of a repository at a time on a machine, and the first pass after it ends takes the next, unless the repository is by then at its [Failure limit](#the-failure-limit): at 3 failures left for you, or the `pickup.failure_limit` you set, the passes take nothing until you have dealt with one. A pull request left for review never holds them back. An issue you have just labelled also waits five minutes by default, or the `pickup.wait_minutes` you set, until it is settled. A Ticket run you start by hand on an Issue URL never waits for a pass, but it fills a slot, so at the limit it makes one skip. Raise `pass.command_limit` to let a repository's passes overlap.
- **One line per repository.** thirdshift keeps no list of repositories. Each Pass on one repository skips at its [Command limit](#the-command-limit), 1 by default, so both lines can go in one crontab and, by default, two Passes never build that repository at once. Passes on different repositories do run at the same time: give their lines different minutes, such as `15,45`, if they would compete for the machine.
- **A pass is skipped** when the repository is at its [Command limit](#the-command-limit), when the repository has no Ready issue, and when it is at its Failure limit. A skip exits `0`, so the scheduler sees no failure, and sends no email, even with Run notifications on. The repository's [Activity log](#logs) records a skip when its reason changes. Unless `activity.quiet_skips` is set, the log file holds each skip's line too, and before the line of a pass that found no Ready issue, as before the line of one that took an issue, [why each issue was passed over](#why-an-issue-was-passed-over). A pass skipped for the Command limit or the Failure limit looks at no issue, so it has no such lines.
- **A Run notification**, by `email.always = true` or `email.unless_merged = true` in the [User config](#user-config), or `email` or `email-unless-merged` on the line, is sent [only for an issue taken](#one-run-notification-for-the-issue-taken). So a day without email doesn't say the passes are running: a pass that fails before it takes an issue, on a broken User config, a missing Resend key or a failed check, shows up only in the log file.

A whole crontab with both frequent Architect runs and a Pickup run on one repository looks like this, with `activity.quiet_skips = true` in the User config, every line sending its output to the one log file, which catches only what went wrong, so `tail ~/.thirdshift/logs/acme/widgets/activity.log` shows what the factory has been doing on the repository lately:

```
# cron reads no shell profile: list every directory that holds thirdshift, claude, gh, git and the build tools
PATH=/home/you/.local/bin:/home/you/.cargo/bin:/usr/local/bin:/usr/bin:/bin

# Architect runs every five minutes: an Architect run publishes each Architect plan, and a Pickup run builds it
*/5 * * * * cd ~/repos/widgets && sleep 20 && thirdshift architect base main --plan-only >> ~/.thirdshift/logs/cron.log 2>&1

# Pickup runs, every half hour
*/30 * * * * cd ~/repos/widgets && thirdshift pickup base main >> ~/.thirdshift/logs/cron.log 2>&1
```

For one Architect run a night instead of every few minutes, put the nightly line from [On a schedule](#on-a-schedule) in place of the frequent Architect run line: a repository needs one or the other, since both lines start Architect runs at different intervals. Adding a repository is adding its lines. Add the lines with `crontab -e` rather than by joining files, and end each with a newline: a line run together with the comment after it, such as `... 2>&1# Edit this file`, is a shell syntax error, so cron fires it but the pass never starts and nothing reaches its log.

The command's flags and the User config decide what a pass does with the issue it takes, as for a hand-typed `thirdshift <Issue URL>`: with `merge.always` it merges the pull request, and without it the pull request is left for review. This is the cautious variant, whatever the User config says:

```
*/30 * * * * cd ~/repos/widgets && thirdshift pickup base main no-merge >> ~/.thirdshift/logs/cron.log 2>&1
```

An issue whose run failed with work on `origin` is [labelled `agent-failed` in place of `in-progress`](#when-the-claim-ends) and waits for the **Day shift**, with the Issue branch and any draft pull request the run left: no later pass takes it, and it counts towards the [Failure limit](#the-failure-limit) until you hand it back, take `agent-failed` off or close it. To send it round again by hand, run `thirdshift <Issue URL>` from the clone, with the Base branch checked out, since that command takes no `base <branch>`: it picks up where the failed ticket run stopped, as a [Continuation](#continuation) does. To hand it back to Pickup instead, apply `ready-for-agent`: after settling, a pass can continue it if every other Ready issue gate still permits it, and takes `agent-failed` off first. Applying the ready label strictly before the last Claim ends does not hand it back. For an ordinary Ticket run, the one failure a later pass does retry is one that left nothing on `origin`, such as a usage limit or an expired login: its Claim is released, so the issue is a Ready issue again once it has settled. A failed Security fix is always left for the Day shift, even with nothing on `origin`.

When shaping issues with `to-spec` and `to-tickets` from [mattpocock/skills](https://github.com/mattpocock/skills), keep a **Spec** labelled `needs-triage` until every **Ticket** is published, attached as a sub-issue and linked to its blockers; then replace it with `ready-for-agent`. A Spec with no Tickets yet looks exactly like a standalone Ticket, so a pass would start a plain Ticket run on it. A Spec reaches the Base branch only through its Spec PR, once every Ticket is done, so keep out of it any Ticket that needs a release, deployment or host install of the Spec's own earlier Tickets: split the Spec there, with a `ready-for-human` issue for the release blocked by the first Spec and blocking the second. This repository's Day shift follows the publication procedure in [`docs/agents/triage-labels.md`](agents/triage-labels.md), required by [`AGENTS.md`](../AGENTS.md), which overrides the imported skills' defaults and survives their updates. The settling window (five minutes by default) is only a second line of defence: it covers Tickets attached within minutes of the label, not a Spec left labelled and without Tickets for longer.

## Triage runs

With no issue or `--file`, `thirdshift triage [base <branch>]` is an unattended **Pass** when stdin is a terminal or reaches EOF without non-whitespace text. This includes `/dev/null` under cron. Non-empty piped stdin remains a Report, read before command startup. An explicitly named empty Report file is an error.

```sh
thirdshift triage
thirdshift triage base release </dev/null
# In crontab, from the repository's Launch directory:
*/5 * * * * cd /srv/widgets && thirdshift triage base main
```

A Triage Pass checks the [Command limit](#the-command-limit), runs the [Sweep](#the-sweep), clears `agent-failed` from open issues the Day shift has acted on, and checks `pickup.failure_limit`. It then selects one open `needs-triage` issue in `pickup.order` (lowest number first by default). Each issue passed over gets a progress line explaining why: another triage state (`ready-for-agent`, `ready-for-human`, `needs-info`, `wontfix`), `in-progress`, `agent-failed`, sub-issues of its own, or an untrusted author or title/body edit. It reserves the first eligible issue on origin and rechecks its state and trust; a reserved or stale issue is passed over for the next candidate. The selected issue is triaged in place as below. With `--recommend-only`, a Pass still reserves its selection but makes no Claim or publication.

A skipped Triage Pass exits `0`, prints nothing on stdout and sends no Run notification. Its reason is recorded in the Activity log only when it changes; `activity.quiet_skips` also suppresses terminal output. A Pass that takes an issue keeps its Command log and Session trace, records the Triage run in the Activity log and sends the configured Run notification.

To investigate an existing open issue in place, name its Issue URL or number, optionally followed by `base <branch>`:

```sh
thirdshift triage 123
thirdshift triage https://github.com/acme/widgets/issues/123 base release
thirdshift triage 123 --recommend-only
```

The Base branch defaults to the Launch directory's checked-out branch. The issue must belong to that repository, have a Trusted-account author and have no title or body edits by other accounts. Any current triage state is accepted. The session receives `.thirdshift-issue.md` with the title, body and only Trusted-account comments. Combining an issue with `--file` is refused.

Before the session starts, thirdshift downloads up to ten unique images from Markdown images and HTML `img` tags in the trusted body and comments. Only HTTPS URLs on `github.com` or subdomains of `githubusercontent.com` are eligible. Each download has a 30-second timeout and a 20 MiB limit; failures and excess images produce warnings and the investigation continues. Successful images are kept under `.thirdshift-issue-images/` in the throwaway worktree, with their original URLs and local paths appended to `.thirdshift-issue.md`, so the session can inspect them with `--read-machine` too.

Unless `--recommend-only` is given, thirdshift reserves the issue on origin and replaces its prior triage state and `agent-failed` with an `in-progress` Claim. It posts one AI-attributed comment with the Agent Brief, investigation and questionnaire, or wontfix explanation, preserves existing category labels (adding the recommendation's category only when none exists), and replaces the Claim with the resulting state. `wontfix` closes the issue. A duplicate can also get a cross-reference comment on the other open issue. Splits into several Tickets or a Spec go to `ready-for-human` with a questionnaire proposing the split. Without readiness permission, recommended `ready-for-agent` becomes `ready-for-human` with a notice in the Agent Brief. The recommendation's issue entry and Run notification name the existing issue's URL.

An error or interruption ends that Claim with `ready-for-human` and `agent-failed`. `thirdshift stop` instead uses `ready-for-human` without `agent-failed`; `thirdshift stop --requeue` uses `needs-triage` without `agent-failed`. The origin reservation is released after cleanup. `--recommend-only` checks the recommendation against GitHub and prints its JSON without reserving, claiming or publishing.

Give a Report on standard input or with `--file` from the repository's Launch directory:

```sh
printf '%s\n' 'The deploy canary fails with an empty cache.' | thirdshift triage
thirdshift triage --file report.txt
thirdshift triage --read-machine --file report.txt
thirdshift triage --recommend-only --file report.txt email alerts@example.com
```

Both Report forms also accept `base <branch>`, for example `thirdshift triage --file report.txt base release` or `printf '%s\n' 'Investigate cache misses.' | thirdshift triage base release`. Without it, the Base branch is the Launch directory's checked-out branch.

For a pasted multi-line Report, such as a chat thread or email, use a single-quoted heredoc:

```sh
thirdshift triage <<'EOF'
Alex: The deploy canary can't start with an empty cache.
Sam: $CACHE_DIR is set, but `cache warm` still fails.
EOF
```

Quoting the opening delimiter (`'EOF'`) passes the Report verbatim: apostrophes, dollar signs (`$`) and backticks stay literal, without shell variable expansion or command substitution. Keep the closing `EOF` on its own line, without quotes; if the Report contains that exact line, choose a different delimiter at both ends.

The embedded `thirdshift-triage` Factory skill investigates the Base branch on origin in a throwaway worktree. It follows its own recommendation without waiting for a person and keeps source and Git history unchanged. Before filing, it searches the repository's open issues. When an issue already covers the Report, thirdshift comments there instead of filing a duplicate. The comment quotes the Report with its source and adds new investigation evidence, leaving the existing issue's labels unchanged. Otherwise, thirdshift files the shaped issues. With `--recommend-only`, it writes nothing to GitHub and names the issue it would comment on or the issues it would file. It still reads GitHub to make the checks filing makes, so a recommendation filing would refuse fails under `--recommend-only` too. It records evidence and limitations. It starts no Ticket run.

Each filed issue starts with an AI-generated disclaimer and quotes the Report verbatim in a collapsed section naming standard input or the file path. Separate problems become separate cross-linked issues, each with exactly one repository category label and one state label. A problem that needs credentials or production access to confirm is `ready-for-human`, with the reason in its body. A `wontfix` issue is closed once filed, as the Day shift's triage closes one, with a comment saying the Triage run recommended it.

For a `needs-info` or `ready-for-human` issue, the embedded `thirdshift-to-questionnaire` skill writes a questionnaire addressed to whoever has the answer. It asks only what the repository could not answer, with enough context to forward. thirdshift includes it in the issue body and as readable text in the Run notification, ready for the Day shift to forward. It never contacts a reporter outside the repository. Other outcomes get no questionnaire. With `--recommend-only`, the questionnaire stays in the proposal and notification without being posted.

By default, a recommendation of `ready-for-agent` becomes `needs-triage`, with a note saying what was recommended. Give `--allow-ready-for-agent` to keep it, or enable the default in `thirdshift setup`, which sets `allow_ready_for_agent = true` under `[triage]` in the User config. thirdshift enforces this permission when filing. This can make the issue eligible for a later Pickup run; the Triage run itself only files it.

Standard output is one JSON object with `category`, `state`, `issues` (titles, bodies and a `questionnaire` when a person must answer), `investigation`, and, when an existing issue covers a problem, `comments` (issue URLs and comment bodies). Filed issues also include their URL and applied category and state. After filing completes, the final progress lines on stderr list every issue filed or commented on, one link per line; the Run notification includes the same readable list. With `--recommend-only`, issues and comments remain proposals, including each existing issue's URL. The Run notification presents the investigation, issue titles with their category and state, comment target URLs and any questionnaires as readable text. It omits the full recommendation JSON and issue and comment bodies; the full result remains on stdout. The notification is saved locally and emailed when `email` or the User config asks. Harness, Model and Effort flags work as for other Commands. An explicitly named empty Report file explains how to supply one. An incomplete session recommendation fails the Command, as does one GitHub would refuse: a comment on an issue that is closed or in another repository, or a category that is not one of the repository's labels or is a factory label such as `agent-failed`.

If publication fails partway, links to issues already filed or commented on still appear after the failure diagnostics and in the Run notification. Proposed writes that failed get no link in that list.

When triaging an existing issue labelled `security-finding`, the Run notification carries only its recorded title and link. Investigation text, questionnaires and failure diagnostics stay on the private issue or in local output and logs, including when triage fails; they are not emailed through Resend.

The Command record, Activity log, `status` and Run notification name it a **Triage run**. A Report or explicitly named issue always takes a Command slot, even above the Command limit; unattended Triage Passes honour that limit. Its worktree is removed when it ends. The session is instructed to investigate read-only within that worktree; it uses the ordinary trusted Harness launch, without an additional filesystem sandbox.

Add `--read-machine`, or name the repository in `read_machine` under `[triage]` in the User config (`read_machine = ["acme/widgets"]`), to let the session read outside the worktree, subject to the OS account's normal read permissions. This opt-in requires Bubblewrap (`bwrap` on `PATH`) and working Linux user namespaces. The sandbox mounts the host filesystem read-only and makes only the throwaway worktree writable; scratch files stay there. A private Harness home inside it holds copies of the usual settings and file-based login, so session state and login refreshes leave the originals unchanged. The network stays available for the Harness and read-only GitHub queries. Unix-domain sockets are refused, so a host service cannot write for the session. TCP stays available. The session keeps Git history and GitHub unchanged; thirdshift publishes its proposed issues and comments unless `--recommend-only` was given. If the sandbox cannot start, the Triage run fails with its diagnostic instead of running unsandboxed. Without either, the launch and worktree-only prompt stay as before.

## Scoring runs

`thirdshift score` starts a Scoring run from any directory. It searches the
configured GitHub owners for merged pull requests whose bodies contain the
`<!-- thirdshift:built-with -->` marker, excluding work whose issue carries
`security-fix`. Its first window looks back seven days; each later window starts
at the previous saved window's end and ends at this Command's start. Boundaries
are inclusive at the start and exclusive at the end, so work is sampled once.

Configure the owners before the first run. Setup writes these defaults and
preserves existing values; it does not ask Scoring questions:

```toml
[scoring]
owners = []                 # GitHub users or organizations; configure before score
sample_size = 10            # maximum weekly sample size (historical 20 are additional)
harness = "claude"          # Grader's Harness
model = ""                  # set an explicit Model before grading a sample
fallback_harness = "codex"   # second Grader, when the first matches the Run's Model
fallback_model = ""         # set an explicit independent Model for the second pair
```

The sample is drawn randomly across the Harness and Model pairs in the Built-with
lines. Each saved window records its seed and sampled pull requests, including
their repository, merge date, Harness, Model, Effort and version when present.
Samples are private under `~/.thirdshift/evals/scoring/`. `thirdshift scores`
lists them by ISO week; `thirdshift scores --json` returns the saved windows and
their samples. Each new window's `packets` directory holds one numbered folder
per sampled pull request: `packet.json` and `repository/`. The JSON holds the
issue title and body from its edit history at merge time, the merged diff, the
pull request title and body, and CI check names and conclusions. Built-with and
Claude Code's Generated-with lines are removed from this text for every Harness.
The repository contains the merge commit's files with Git metadata and
attribution lines removed, so
neither commit messages nor later history reach the Grader. Unavailable
historical issue text fails the Command rather than substituting a later
revision.

A model Grader scores each packet in the Experiment sandbox, with the repository
read-only. It gives five independent pass/fail Scores with reasons: Correct,
Scoped, Tested, Honest and Standards. Honest checks only the pull request's
claims against its diff and CI. Scores are retained on each sampled pull request,
with the Grader's Harness and Model; local work also links to its Run's Command
record. Both `scores` formats withhold model Scores until all five human Scores
are saved for that pull request. Revealed Scores include each criterion's
calibration: `calibrated`, `matches` and `compared` in JSON.

Scoring samples, Bug-origin proposals and settlements, and read-time Run metrics
share retained pull-request attribution. Matching ignores ASCII letter case and
trailing slashes. Latest means the greatest parsed RFC 3339 instant, including
UTC offsets; ties use greatest lexical record path, then greatest Command name.
An unparseable start sorts before every valid time, with the same path/name ties.
Selection follows the captured Command ownership tree, including dispatched work,
nested Ticket runs and Base fixes. It does not admit orphaned child records.

The first Scoring run also draws 20 past pull requests across Harness and Model
pairs, or all eligible work if fewer than 20 exist. They are marked `for_you`
and graded too. They can predate the weekly window; overlaps with that week's
draw are graded once. Later runs mark two from each ISO week's samples for you
(or as many as available); reruns in the same week do not add another two.

Use `thirdshift scores <pull request> --mine [--json]` with a sampled pull request URL,
or a number that identifies only one sampled repository's pull request. It asks
for pass or fail and a nonempty reason for Correct, Scoped, Tested, Honest and
Standards. The model's Scores stay hidden in ordinary views and during entry.
All five of yours are saved together before the model's appear beside them;
`--json` returns that saved result as JSON. EOF or interruption
leaves any previous Scores unchanged. Only one Scoring run or human scoring
session can write at once. `thirdshift scores <pull request> [--json]` shows
that pull request; omit it to list samples by week.

Each criterion is calibrated when at least 18 of the last 20 distinct pull
requests you and the model both scored agree on pass/fail. Fewer than 20 paired
pull requests means uncalibrated. The rolling order is when you completed your
Scores; reasons are retained but not compared. Every criterion stands on its
own, so one that stays uncalibrated does not hold up the others.

Set an explicit `scoring.model`: a blank default cannot establish that the
Grader differs from the Run's Model. When the first Model matches the Built-with
line (ignoring case), the second Harness/Model pair is used; if it also matches
or is blank, grading fails without starting that Grader.

A Claude or Codex quota window at 85%, or a Claude rejection, stops grading
immediately. Claude warnings continue when all readable windows are below 85%;
a warning with no readable utilization still stops grading. Completed Scores
are checkpointed individually. The next `score` command scores the retained
remainder before drawing a new window; completed pull requests are never graded
again. Other Harnesses have no verified
warning protocol yet. Grader sessions use bwrap and socat on Linux; if isolation
cannot start, grading fails and the sample remains pending. As for Experiments,
`THIRDSHIFT_TRIAL_NO_SANDBOX=1` selects the pass-through launcher for fake Harness
tests or an explicit emergency override.

Every closed `bug` issue also gets a proposed Bug origin, whoever fixed it,
except issues labelled `security-fix`. The first run that writes proposals
looks through all closed bugs, including those older than the sample window;
later runs use the previous proposal window's end. Existing saved samples
without proposals do not skip this backfill.

A short session on the configured Scoring Harness and Model uses the Eval
sandbox and memory caps to inspect the fix and only its earlier Git history.
It names an introducing commit only when that history establishes one;
otherwise it records no commit and explains why. A closure without a linked
fix records no commit. GitHub's commit-to-PR associations map a named commit
to its merged pull requests, then to a local Run's Command record when present
or the PR's Built-with line. Human work can have no Run. Multiple historical
PR associations are retained without choosing between them.

The saved window's `bug_origins` list contains these proposals and their
evidence; `thirdshift scores --json` includes it. Session artifacts stay in
the window's private `packets/origins/` directory. Proposals count for nothing
until the Day shift settles them. A plan-limit warning stops Scoring
before another proposal starts and advances no window; retry `thirdshift score`
to analyze that window again. A search failure also advances no window. A
Bug-origin session that fails, times out or leaves no proposal records that
bug with no commit and says why; the window keeps every other proposal and
publishes the failed session's artifacts with them, and the Day shift settles
that bug by hand. A proposal that points outside the session's workspace or
names a commit outside the fix's history still advances no window.

`thirdshift bug-origins [<issue>] [--json]` lists origins and their state:
`proposed`, `confirmed` or `rejected`. Use an issue URL, or a number when it
identifies exactly one bug across the retained repositories. A settlement
changes the latest proposal for that bug and retains its original evidence.
`--confirm` needs exactly one proposed pull request; `--correct <pull request>`
confirms a different merged pull request in the bug's repository, given its
URL or number. Corrections have `state: "confirmed"` and `settlement.corrected:
true`. `--none` rejects it. Each action also accepts `--json`. Unknown or
ambiguous origins and incomplete GitHub evidence fail without settling anything.
Settlement uses the same machine-wide writer lock as Scoring and human Scores.

A confirmed origin retains its chosen pull request and Run, when known. Each
local Run's `thirdshift show <command> --json` includes
`command.run_metrics.confirmed_bug_origins`, derived from the latest decisions;
rejected and unsettled origins contribute zero. Correcting an origin moves
its attribution to the chosen Run, without rewriting old Command records.
The saved local record path and Command name remain authoritative: if that pair
is missing or belongs to a different pull request, metrics count no match rather
than substituting another Continuation. Only absent or cross-host attribution
uses latest local selection.

Confirmation also creates a private `proposed` Eval task in the `code-review`
suite, creating the suite with its usual dependencies when absent. Its local
repository pins the PR head and its historical merge-base, separately from
the merge tree and later fix. The target's parent at merge time excludes
upstream changes already merged into the PR branch; preserved linear heads
use the first PR commit's parent. It carries the originating issue at merge
time, or the PR body when no issue was linked, and a draft catch criterion
based on the proposal's evidence. Review and
refine that criterion before `thirdshift evals approve code-review <task>`.
Until approval, preparation and Experiments exclude it. Repeated confirmation
keeps the same Eval task, including edits and approval. Rejecting or correcting
an already confirmed origin withdraws its old unapproved proposal, including
prior occurrences of a reopened and reclosed bug; a task the
Day shift independently approved stays in the suite. Security fixes cannot be
selected as origins. Confirmation checks the bug's current labels and refuses
`security-fix`, including a proposal saved before that label. All these files
stay in private Eval storage on this host.

The Command record and Command log live under
`<logs.dir>/JacobStephens2/thirdshift/commands/scoring/`, with start and end lines
in that repository's Activity log. The Command appears in the Inbox, can be
Stopped with `thirdshift stop <command>`, and a failure lands in Needs you.
Another Scoring run on the machine is skipped without recording a Command.
A failed or interrupted search advances no window. Pull-request searches
exceeding GitHub's 1,000-result limit fail visibly rather than saving an incomplete
window. Closed-bug searches split their time ranges to cover larger backfills;
more than 1,000 closures in one second fail visibly without advancing the window.

Your operating system can schedule it weekly, for example:

```cron
0 3 * * 1 /usr/local/bin/thirdshift score >> /tmp/thirdshift-cron.log 2>&1
```

## Building from source

This Markdown is the source for the site's manual. After changing it, run `cd site && npm ci && npm run docs` from a repository checkout and commit `site/docs/index.html` in the same pull request. `cd site && npm test` checks that the generated page is current and readable in a browser; the deployed site needs no build step.

Building needs the Rust toolchain. From a clone of this repository:

```sh
cargo install --path .
```

`cargo install` puts the binary in `~/.cargo/bin`. To update it, pull and reinstall:

```sh
git checkout main && git pull
cargo install --path .
```

If the shell installer also put a copy in `~/.local/bin`, typing `thirdshift` runs whichever copy comes first on your `PATH`, and the installer's copy often does. To see every copy, in the order the shell tries them:

```sh
type -a thirdshift
```

To run the build from source, give its path, as in `~/.cargo/bin/thirdshift <Issue URL>`, or put `~/.cargo/bin` first on your `PATH`, for example in `~/.bashrc`:

```sh
export PATH="$HOME/.cargo/bin:$PATH"
```

`thirdshift version` can't tell the two apart: a build from `main` reports the last released version until the next release bumps it.

Editing a skill in `skills/` has no effect until you rebuild and reinstall ([ADR-0001](adr/0001-rust-binary-with-embedded-skills.md)).

The [Prompts and skills page](https://thirdshift.app/prompts/) is generated from the prompts, the `claude` and `codex` arguments and the skills, and each Session prompt is also generated as a Markdown file in [`prompts/`](../prompts), with a [`README.md`](../prompts/README.md) that lists them with the `claude` and `codex` command lines. `cargo test` fails until they are regenerated after a change to any of them. Regenerate the page and `prompts/` with `UPDATE_PROMPTS=1 cargo test prompts_page`, which also deletes any file in `prompts/` that it doesn't generate.

The integration tests swap in a fake `gh`, `claude`, `codex`, `agy`, `grok`, `muse`, `opencode` and `kimi`, from [`tests/fakes.rs`](../tests/fakes.rs). The first test that needs them builds them with `rustc` (the one on `PATH`, or `$RUSTC`), so the suite needs nothing else on `PATH` beyond `git` and `bash`.

### The Rust version

[`rust-toolchain.toml`](../rust-toolchain.toml) pins the exact Rust version this repository builds with, and the `rustfmt` and `clippy` components CI runs. `rustup` reads it, so `cargo` in a checkout, CI, the release builds and the crates.io publish all use that version, and `rustup` installs it the first time it is needed. No workflow names a version of its own. The file is not in the crates.io package, so `cargo install thirdshift` builds with whatever Rust the machine has.

A newer Rust arrives as a pull request that changes `channel` in that file, so it runs through CI before `main` builds with it. Dependabot opens that pull request within a week of a stable release ([`.github/dependabot.yml`](../.github/dependabot.yml)). To move the pin by hand, set `channel` to the new version in full, patch number included, run the three checks CI runs, and open a pull request with the change and whatever the new compiler's lints asked for:

```sh
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
```

## Releasing

Run `scripts/release.sh` on Linux. It refuses other hosts before fetching,
writing Git refs or calling GitHub. On macOS, use an Ubuntu 24.04 Linux VM
such as Lima; on Windows, use WSL2.

The release script skips Experiments by default, printing a note. Opt in with
`scripts/release.sh --with-experiment 0.4.0`, adding `--with-experiment` again
on each resume that should run an Experiment.

With `--with-experiment`, before pushing anything, the script runs
`thirdshift experiment --release <commit> --yes` using this checkout's runner and private Eval suites,
so the Experiment prints its cost without asking about it.
It evaluates the content commit beneath the version-only bump, so reruns use
the same Experiment even before a bump branch exists. It pins that commit in a
local Git ref before starting, so a merge to `main` during interruption does
not change the Candidate on restart. If a release tag now on `main` is not an
ancestor of that pin, the script selects a new base. It also rechecks that the
requested version is higher than `main` before reusing a pin, refusing if not.
The pin is removed after the branch push,
when the pushed bump retains the selection. A pass carries on;
a fail or inconclusive Verdict shows each suite's accuracy and wrong-finding
intervals and asks `release anyway? [y/N]`, including without `--review`.
The summary lists every Advisory suite and its own Verdict. All suites advisory
gives inconclusive and asks the same question.
Only `y` or `yes` continues; EOF or any other answer stops. Pending borderline
and decisive Scores are listed with their recheck commands and polled until
you have rechecked them. No touched suite or a last release with no Trial flag
prints a note and carries on. An interrupted invocation resumes its saved
Trials. A pushed bump branch is checked again before opening its PR, and an
open or merged bump PR before tagging. An already pushed tag waits for publication before merging
an open PR, skipping the Experiment unless recovering with a newer green base. Python 3 is needed to read the Experiment results.

The release base is the newest commit on `main` whose latest push `CI` run
succeeded, strictly newer than and descending from the last release tag on
`origin/main`. A green commit from before that tag merged into `main` cannot
qualify. The script uses a qualifying commit immediately even
if the tip's CI is pending or failed. If none qualifies, it waits for a run to
succeed, still considering older pending commits when `main` moves. The
Experiment's Candidate is that release base. The tag names exactly that content
plus the version bump, so merges to `main` during a release do not change what
is measured or shipped.

From a clone of this repo, signed in to `gh` and the User config's default Harness, run the release script with the new version:

```sh
scripts/release.sh 0.4.0
```

It works from `origin/main` in a temporary worktree, so your checked-out branch and uncommitted changes don't matter and aren't touched. It opens a pull request from `release-<version>` that bumps the version in `Cargo.toml` and `Cargo.lock` and nothing else. Its body is a summary of the release, then the version diff. The User config’s default Harness, with its configured Model and Effort (Claude Code when no default is set), writes the summary from the version diff and the title, number and body of each pull request merged between the last release tag and the release base, following the prompt in [`scripts/release-summary.md`](../scripts/release-summary.md). The script uses `cargo run` in this checkout to share thirdshift’s config parser and Harness adapters, and runs the summary in a temporary directory without Factory skills. Because pull request titles and bodies are contributor-editable, no Harness gets its session permission bypass, and each runs with as few tools as its CLI allows. Claude runs with no tools. Codex runs read-only and sandboxed, with its shell, MCP, web, app, plugin, browser and hook tools off. Grok gets only its to-do tool. OpenCode refuses every tool call. Muse has no shell, writes or web, and one model step. agy denies every tool that needs a permission, though it can still read files. Kimi Code runs an agent whose tool list is empty, with the release input as its instructions in a file beside the prompt. A summary that tries a refused tool usually comes back empty, so the script falls back as below. If the config is invalid, the chosen Harness fails, or it returns no summary, the script warns and uses GitHub's generated notes as the summary instead, with a note saying so. It writes the summary before it pushes anything. With `--review` (`scripts/release.sh --review 0.4.0`), it then prints the summary and asks `[y]es / [e]dit / [n]o`: `y` carries on, `e` opens the summary in `$EDITOR` and carries on with what you save, and `n` stops with no branch, pull request or tag pushed. Without `--review`, only a failed or inconclusive Experiment prompts. It waits for the pull request's checks, tags the bump commit at the head of `release-<version>` as `v<version>` and pushes the tag. Pushing the tag starts the release workflow (below). The script waits for that workflow on the bump commit, printing the run's URL so you can watch it. Only after the workflow succeeds does it merge the bump PR into `main` with a merge commit, preserving the tagged commit in main's history even if other content has arrived. If that merge fails, the published release stands: it names the open PR for the Day shift to merge and still exits `0`. CI's run on `main` for the merge isn't waited for. The script prints the GitHub Release's URL last. It prints a line on stderr for each step, stamped with the local time as `HH:MM:SS` as thirdshift's own progress lines are, so a long wait can be told from a stalled one. If the PR checks fail, it stops before tagging and leaves the pull request open and untagged. If the release workflow fails, it exits `1`, naming the failed jobs and run URL, leaving the tag in place and the PR open and unmerged. Recovery happens when you run the script again with the same version. Neither wait has an overall timeout.

Before it pushes anything, it refuses a release that can't be cut and says why: a version that isn't plain `X.Y.Z` (no leading `v`), a version that isn't higher than the one in `Cargo.toml` on `origin/main`, or a `v<version>` tag that already exists locally or on origin. A resumed PR must belong to origin and match its branch tip while open. Its tree (or a pushed branch without a PR) must be exactly the version bump in `Cargo.toml` and `Cargo.lock` from its merge base; extra content is refused even when already tagged.

If it's interrupted, run it again with the same version: it picks up the existing branch or pull request and carries on from the first step not yet done. With `--review`, it asks about a new summary before opening a pull request for a branch already pushed. It opens a PR for a pushed branch, waits for its checks, tags the bump head, waits for publication, then merges the PR. A PR already merged is still tagged at its bump head. Once the tag is on that head, it says the release is already tagged and resumes the release workflow: it waits for a run still going, or merges the open bump PR immediately when the workflow succeeded or the GitHub Release already exists, then prints the Release URL and exits `0`.

An untagged pushed branch or open bump PR is re-cut if its content base does
not descend from the last release tag now on `origin/main`, excluding its own
tag. After validating the existing version-only bump, the script rechecks that
the requested version is higher than `main` and waits for a green base
descending from that release tag. It prints the new base, runs the Experiment
when requested, regenerates the summary and version diff, force-pushes the
branch, and updates an open PR's body or opens its PR before waiting for checks
on the new head. With `--review`, declining the new summary exits `1` before
moving the branch or changing the PR body. Tagged and merged releases keep
their existing resume behavior.

On resume after a completed failed release workflow with no GitHub Release yet, the script looks for the newest `main` commit newer than the bump commit's parent whose latest push `CI` run succeeded. When one exists, it re-cuts `release-<version>` from that commit: it runs the release Experiment when `--with-experiment` is passed, regenerates the summary and version diff (honoring `--review`), force-pushes the new bump commit to the branch, updates the open PR body, waits for its new checks, then force-pushes `v<version>` to the new bump commit. An old merged bump gets a new bump PR. The summary and Experiment exclude the unpublished tag and retain the prior release boundary; release Experiments accept `--baseline <ref>` for this recovery. It waits for the new release workflow before merging. A recovery stopped between pushing the branch and moving the tag resumes that checked version bump. If no newer green commit exists, it automatically runs `gh run rerun --failed <run id>`, prints a stamped progress line, and waits for the rerun before merging. A published GitHub Release is never re-cut: its branch and tag are never moved. If the publication check cannot be completed, the script refuses and moves nothing. A tag on an unrelated commit is still refused. You can stop either wait with Ctrl-C and run the script again to continue.

The tag starts the release workflow, generated by [`dist`](https://github.com/axodotdev/cargo-dist) from `dist-workspace.toml`, with the event policy applied by `python3 scripts/generate-release.py` (`--check` verifies freshness). It builds the two Linux musl binaries and the installer, smoke-checks that the `x86_64` binary starts on Rocky Linux 9 and in WSL2 with Ubuntu 24.04, checks the `aarch64` binary's static linking and version on Ubuntu, and only then publishes the GitHub Release. It then publishes the same version to crates.io, skipping it if it is already there, and finally replaces the Release's body with the bump pull request's summary, then notes generated from the merged pull requests, then the install instructions. [`scripts/release-notes.sh`](../scripts/release-notes.sh) builds that body; for a tag pushed by hand, with no bump pull request summary, it is the generated notes and the install instructions alone.

## Credits and license

thirdshift is released under the [MIT License](../LICENSE).

Most Factory skills in `skills/` are adapted from Matt Pocock's [mattpocock/skills](https://github.com/mattpocock/skills), changed to run headless with no human in the loop. They are used under the MIT License; its copyright notice is kept in [`skills/LICENSE`](../skills/LICENSE) and is embedded in the binary and written out with the skills on every Ticket run. The `thirdshift-pr` skill also reproduces part of Dex Horthy's `show-me` skill; see [`skills/thirdshift-pr/CREDITS.md`](../skills/thirdshift-pr/CREDITS.md).

The `thirdshift-security-audit` Factory skill is copied from Cloudflare's [security-audit-skill](https://github.com/cloudflare/security-audit-skill) at commit `c1c8a8c`, with only its frontmatter name changed. It is used under the MIT License; Cloudflare's copyright notice and licence are kept in [`skills/thirdshift-security-audit/LICENSE`](../skills/thirdshift-security-audit/LICENSE), with the upstream repository and full commit in [`CREDITS.md`](../skills/thirdshift-security-audit/CREDITS.md). Both are embedded and written out with the skill.