Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 205 additions & 3 deletions .scratch/grill-with-docs/711-live-runs.md

Large diffs are not rendered by default.

26 changes: 25 additions & 1 deletion CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ One running record per repository of what the factory did there: a line when a *
_Avoid_: cron log, pass log, history

**Console**:
The web page a machine serves that shows every **Command** started on it, live ones first, with each one's child **Runs**, their stages and their logs, and from which a live Command can be stopped. Each machine serves its own, behind a sign-in. It does nothing the CLI can't do: every view and action it offers is also a command.
The web page a machine serves that shows every **Command** started on it, opening on its **Inbox**, with each one's child **Runs**, their stages and their logs, and from which a live Command can be stopped. Each machine serves its own, behind a sign-in. It does nothing the CLI can't do: every view and action it offers is also a command.
_Avoid_: dashboard, floor, UI, web UI

**Command record**:
Expand All @@ -250,3 +250,27 @@ _Avoid_: user, login
**Console log**:
One running record per machine of what happened to its **Console accounts**: sign-ins, failed sign-ins, codes sent, passwords set and sign-outs, each naming the account. What people did to **Commands** goes in the **Activity log** instead, and what they only looked at is recorded nowhere.
_Avoid_: audit log, access log

**Inbox**:
The **Console**'s first page, and `thirdshift status`'s order: a machine's **Commands** grouped by what each asks of the **Day shift**. **Needs you** comes first. Ready for review holds Commands that ended ready, with a pull request waiting. Landing holds live Runs at CI watch or **Self-merge**. Working holds every other live Command. Done holds Commands that ended in the last day, and Resolved holds older ones with nothing waiting. Commands older still are only in the history.
_Avoid_: dashboard, feed, queue

**Needs you**:
The **Inbox**'s first group: what won't come right unless the **Day shift** acts. Live problems come first, **Silent** then **Slow** Runs, and then the ended ones: a Command that died, one that failed, a **Stop** that left its issue `needs-triage`, and a **Security finding** waiting on a decision. An ended one leaves when a later Command on the same issue starts on the machine, or once it is older than the period the **User config** sets. Nothing else clears it, since the **Console** does nothing the CLI can't.
_Avoid_: alerts, attention, triage queue

**Silent**:
A live **Run** whose **Session log** and **Command log** have both stopped growing for longer than the silent time the **User config** sets, 10 minutes unless set: it may be stuck. Stages that wait on something else, such as CI watch, write a line at intervals while they wait, so silence means the same thing in every stage. A stall is silence, not a long stage: a Run that is past its **Usual range** but still logging is **Slow**.
_Avoid_: stalled, stuck, hung

**Slow**:
A live **Run** whose stage has gone past the top of that stage's **Usual range** while its logs keep growing. It is still working; it only needs a look, unlike a **Silent** one.
_Avoid_: late, overdue, stalled

**Usual range**:
How long a stage usually takes in a repository: the middle half of that stage's times over the repository's recent **Command records** on the machine, shown only once there are enough of them. It is what makes a Run **Slow**.
_Avoid_: average, baseline, estimate

**Theme**:
How the **Console** looks, its colours, fonts, shapes, effects and motion, over a layout that every Theme shares. thirdshift comes with some, and a user can make their own. Choosing one changes how the page looks, never what it shows.
_Avoid_: skin, style, variant
5 changes: 3 additions & 2 deletions docs/adr/0016-the-console-is-a-long-running-reader.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# The Console runs all the time, but only reads and does what the CLI does

ADR 0009 rejected a long-running `thirdshift watch`: it has to be kept alive, it keeps running the old binary after `thirdshift update`, and when it hangs nobody notices. The **Console** needs something listening, so `thirdshift console` runs all the time, on 127.0.0.1, behind the machine's own Caddy or Apache. It stays within the spirit of ADR 0009 for three reasons:
- **It never starts work.** Every Command is still started by the operating system's scheduler or by a person, and the Console's only action, **Stop**, is the CLI's `thirdshift stop`.
- **It never starts work.** Every Command is still started by the operating system's scheduler or by a person. The Console's actions are **Stop**, which is the CLI's `thirdshift stop`, and setting its own look, which is `thirdshift console theme` and `thirdshift console sections` (amended 2026-10-19, #711 Q46).
- **It survives updates.** It re-executes itself when `thirdshift update` replaces the binary.
- **A hang costs no work.** A Console that hangs loses no Run; the next request shows it's down.

Expand All @@ -18,5 +18,6 @@ It reads what each Command writes about itself, its **Command record** and its l
## Consequences

- `console install` writes a system unit that runs as the user, the same way other long-running apps are kept on both machines today. It prints a script for `sudo` that writes the unit and the proxy's site file.
- Every view and action on the page is also a CLI command with `--json`, and a test pairs them. Agents use the CLI, not the page, and no HTTP API is promised to anyone.
- Every view and action on the page is also a CLI command with `--json`, and a test pairs them.
- The only part of the User config the page writes is its own look, under `[console]`: the chosen **Theme** and the hidden sections. It never writes the allowlist, the addresses or any other section, so a signed-in browser can't change who may sign in. Agents use the CLI, not the page, and no HTTP API is promised to anyone.
- Async code (axum on tokio) lives only inside the Console. The rest of thirdshift stays blocking.
14 changes: 14 additions & 0 deletions docs/adr/0018-the-console-has-one-layout-and-themes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# The Console has one layout, and its looks are Themes made of tokens

The #711 prototypes tried eighteen looks for the **Console**. Two layouts drew the most interest, and they were the same inbox under different looks: one plain, one in thirdshift.app's press style. So the Console has one layout, the **Inbox** and its pages, and every look is a **Theme**. A Theme is a set of tokens: colours, fonts, shape, effects and motion. It may not change what the page shows, its order, or where things are. The default is Focus, which follows the system's light or dark setting. Plain, Press, Signal, Garden and Factory ship beside it, and a user can make, export and import their own.

## Considered Options

- **Several layouts, one per look** (a garden bed, a press line, a grid). Rejected. Every layout would need its own tests, phone checks and keyboard model. A layout tied to the garden metaphor would also have to be redrawn whenever the metaphor moves.
- **One look and no Themes.** Rejected. The plain and press looks were each wanted for different moods, and a user with their own style would have no way to have it.

## Consequences

- Every built-in Theme is checked for AA text contrast, and Focus is also checked for APCA. A user's Theme is theirs to check.
- Motion belongs to the layout, not the Theme. It is reserved for thirdshift's activity: a Theme can change how a live Command moves, but it can't make anything else move.
- Once people have exported Themes, the token set becomes a format to keep: new tokens need defaults, so older Themes keep importing.
Loading
Loading