From 53ef113c4dd0132777be5c9c3dae45ed0b17b276 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 15 Nov 2026 17:00:02 -0800 Subject: [PATCH] pa-lab: draft user pages for the planned features --- lab/server/GUIDE.md | 17 +++++++------ lab/server/README.md | 7 ++++++ lab/server/guide/actions.md | 37 ++++++++++++++++++++++++++++ lab/server/guide/app-lifecycle.md | 16 +++++++++++++ lab/server/guide/saves.md | 20 ++++++++++++++++ lab/server/guide/start-checks.md | 40 +++++++++++++++++++++++++++++++ lab/server/guide/worker.md | 14 +++++++++++ 7 files changed, 144 insertions(+), 7 deletions(-) create mode 100644 lab/server/guide/actions.md create mode 100644 lab/server/guide/app-lifecycle.md create mode 100644 lab/server/guide/saves.md create mode 100644 lab/server/guide/start-checks.md create mode 100644 lab/server/guide/worker.md diff --git a/lab/server/GUIDE.md b/lab/server/GUIDE.md index 6cc720690b..209aa05f97 100644 --- a/lab/server/GUIDE.md +++ b/lab/server/GUIDE.md @@ -55,13 +55,16 @@ retried request safe, and an event log. None of it presses buttons yet. ## What comes next -| Slice | What you would get | -|---|---| -| 4 (rest) | FRLG AutoStory's start checks listed and run before any press (fork #488) | -| 5 | Leased actions: an agent asks to run or stop a program; the server checks the program's start checks first and refuses on a failed one, and refuses whenever you hold the console. Every action gets exactly one record. | -| 6 | Save facts: the server knows which save is on the console and refuses a run that would start from the wrong one; run records become readable | -| 7 | The server launches and supervises the lab app itself, so a build always starts with the right profile | -| 8 | Optional: a local worker for routine operations | +Each feature has a user page, marked **DRAFT** until it is built and switched on. The drafts +are updated as each piece lands. + +| Slice | What you would get | Page | +|---|---|---| +| 4 (rest) | Every program lists what it needs before it starts; FRLG AutoStory's list is next (fork #488) | [start-checks.md](guide/start-checks.md) | +| 5 | Leased actions: an agent asks to run or stop a program; the server refuses whenever you hold the console, and (5b) when a start check fails. Every action gets exactly one record. 5a is built in #592, not switched on. | [actions.md](guide/actions.md) | +| 6 | Save facts: the server knows which save is on the console and refuses a run that would start from the wrong one; run records become readable | [saves.md](guide/saves.md) | +| 7 | The server launches and supervises the lab app itself, so a build always starts with the right profile | [app-lifecycle.md](guide/app-lifecycle.md) | +| 8 | Optional: a local worker for builds and test runs | [worker.md](guide/worker.md) | ## Limits diff --git a/lab/server/README.md b/lab/server/README.md index 111f461e8d..1d550342cf 100644 --- a/lab/server/README.md +++ b/lab/server/README.md @@ -293,3 +293,10 @@ every event after an active cursor (one used in the last 7 days), every event of and every pending record; finished records go after 7 days. A cursor behind the compacted range is refused (`invalid_arguments`, field `after_seq`, `evidence.compacted_through`), never served with a silent gap. + +## User pages + +`GUIDE.md` is the user-facing overview; `guide/*.md` has one page per feature, marked DRAFT +until it is built and switched on. A PR that builds or switches on part of a feature updates +its page in the same PR: the status line at the top, the tool tables, and the DRAFT banner when +the feature is done. diff --git a/lab/server/guide/actions.md b/lab/server/guide/actions.md new file mode 100644 index 0000000000..a986f0e5f8 --- /dev/null +++ b/lab/server/guide/actions.md @@ -0,0 +1,37 @@ +> **DRAFT.** This page describes a feature that is only partly built. It is updated as each piece lands. +> Status (2026-11-15): Slice 5a (`run_program`, `stop_program` under a lease) is built in [#592](https://github.com/dayfine/Arduino-Source/pull/592), not merged and not switched on. Slice 5b (preflight, options, `cfr_batch`, a console soak) is not built. + +# Actions: agents start and stop programs through the server + +Today agents act on console B through lab scripts. With actions, an agent asks pa-lab instead, +and the server decides whether it may. + +## How it works for you + +- **You always win.** Clicking Start or Stop in the app gives you the console. Any agent + request in flight fails, and new ones are refused until you release it. +- **An agent must hold the console first.** It takes a time-limited lease; without one, or + after it expires, every action is refused. +- **One action, one record.** Each request has an id. Retrying the same id returns the first + answer and never starts or stops twice. Every action is in the event log. +- **Refusals say why**, for example: you hold the console; another program is running; the app + is not running; the selected panel is a different program; the controller is not ready. + +## Tools + +| Tool | What it does | Status | +|---|---|---| +| `acquire_console` / `renew_console` / `release_console` | take, extend and give back the lease | built (control plane) | +| `run_program(panel)` | start the selected program once | built in #592, not switched on | +| `stop_program()` | stop it once; stopping when nothing runs is a no-op, not an error | built in #592, not switched on | +| `preflight_program(panel, options)` | load candidate options, run the program's [start checks](start-checks.md), then put your options back; `run_program` will need its token | planned (5b) | +| options on `run_program` | run with options other than the panel's current ones | planned (5b) | +| `cfr_batch(lines)` | a short allowlisted controller batch, for debugging only; marks the save as unknown | planned (5b) | + +There is deliberately no "switch game" tool: the app cannot yet pick a game on HOME by name. + +## Switching it on + +The session connection (`.mcp.json`) stays read-only until you decide otherwise. The plan: +5b adds preflight; a soak on console B shows every action has exactly one record; then actions +are enabled one program family at a time. diff --git a/lab/server/guide/app-lifecycle.md b/lab/server/guide/app-lifecycle.md new file mode 100644 index 0000000000..3f2c8a6d04 --- /dev/null +++ b/lab/server/guide/app-lifecycle.md @@ -0,0 +1,16 @@ +> **DRAFT.** This page describes a feature that is not built yet. It is updated as it lands. +> Status (2026-11-15): planned (Slice 7). Today `labrun.sh` launches the lab app. + +# The server runs the lab app + +## What you will get + +- **The right build, the right way, every time.** The server launches the lab app itself, with + the lab profile, the audio settings and the build you picked, and refuses anything else + (no more running a build without `--profile`). +- **Crash handling.** It notices a crash or a hung app, records it, and refuses to start a + second copy. It only ever stops the app it started. +- **You keep an escape hatch.** You can still launch or quit the app yourself; the server sees + that and stands back. +- **Agents stop launching apps directly.** After a soak, agents ask the server instead of + running `labrun.sh` or writing to the app's inbox. diff --git a/lab/server/guide/saves.md b/lab/server/guide/saves.md new file mode 100644 index 0000000000..17ae617815 --- /dev/null +++ b/lab/server/guide/saves.md @@ -0,0 +1,20 @@ +> **DRAFT.** This page describes a feature that is not built yet. It is updated as it lands. +> Status (2026-11-15): planned (Slice 6). `console://B/save` exists and usually says `unknown`. + +# Save facts: knowing which save is on the console + +Most lab mistakes that cost real progress are about the save: starting a checkpoint run from +the wrong save, or a hand session moving the player after the last save. + +## What you will get + +- **The server knows the save.** When a program saves (AutoStory and RNG programs first), it + records where and when. `console://B/save` then shows `known`, with the checkpoint or place. +- **It notices when that stops being true.** Anything that can change the game without a + recorded save (you playing, a controller batch, an unhooked program) marks the save + `stale`, with the reason. Only another recorded save makes it `known` again. +- **Runs check it first.** The `save_at(place)` [start check](start-checks.md) refuses a run + whose start does not match the known save. +- **Run records you can read.** Each run ends as one record (passed, failed, or stopped and by + whom), with checkpoint results, RNG hits and links to failure screenshots, shown through the + server's resources and events. diff --git a/lab/server/guide/start-checks.md b/lab/server/guide/start-checks.md new file mode 100644 index 0000000000..7073024119 --- /dev/null +++ b/lab/server/guide/start-checks.md @@ -0,0 +1,40 @@ +> **DRAFT.** This page describes a feature that is only partly built. It is updated as each piece lands. +> Status (2026-11-15): the check list and `describe_program` are built ([#485](https://github.com/dayfine/Arduino-Source/pull/485), [#511](https://github.com/dayfine/Arduino-Source/pull/511), [#512](https://github.com/dayfine/Arduino-Source/pull/512)); FRLG AutoStory's list is a design note ([#488](https://github.com/dayfine/Arduino-Source/pull/488)); the server does not yet run the checks before a start (that is [actions.md](actions.md), Slice 5b). + +# Start checks: what a program needs before it presses anything + +Every program can declare a short, named list of things that must be true before it starts: +the game is in front, the screen has no black border, a party slot is free, the save is the +one the program expects. Each check has a name and a one-line "needs" sentence, and none of +them presses a button, resets, saves or changes an option. + +## What you get + +- **Read what a program needs without running it.** Ask for `describe_program` on a panel + and you get its options (keys, types, defaults, allowed values) and its start checks with + their "needs" lines. +- **One list guards both doors.** The same list runs when you click Start in the app and when + an agent asks the server to start a run, so a bad setup is refused the same way either way, + before any reset. +- **Clear refusals.** The first failing check stops the start with a message saying which + check failed and what it needs. + +## Checks you will see + +| Check | Needs | +|---|---| +| `game_open` | the program's game is in front, not HOME, user select or a black screen | +| `black_border` | the picture fills the screen (no black border) | +| `free_party_slots(n)` | at least n empty party slots (FRLG RNG gift/egg) | +| `save_at(place)` | the save on the console is the one this run starts from (needs [saves.md](saves.md)) | + +Program-specific checks sit beside the program: for example a Sweet Scent user in the last +slot, or enough Safari advances. A program without a list says `unsupported`; that never +counts as passing. + +## Planned lists + +| Program | Checks | +|---|---| +| FRLG RNG | `black_border`, then `free_party_slots(1)` (gift, egg); Sweet Scent user last (wild); Safari advances ≥ 4000 | +| FRLG / BDSP / PLZA AutoStory | `game_open`; the start checkpoint is chosen and visible; `save_at(start checkpoint)`; LANGUAGE matches the game | diff --git a/lab/server/guide/worker.md b/lab/server/guide/worker.md new file mode 100644 index 0000000000..8255d0b26e --- /dev/null +++ b/lab/server/guide/worker.md @@ -0,0 +1,14 @@ +> **DRAFT.** This page describes an optional feature that is not built yet. It is updated if it lands. +> Status (2026-11-15): planned (Slice 8), optional. + +# Local worker for routine operations + +A separate process that runs heavy local jobs (builds, test runs) as queued tickets, with the +existing guards: the heavy-work gate, the disk floor, `-j4` and `nice`. + +## What you will get + +- Builds and tests queue instead of colliding; refusals say why (disk low, memory, a console + run in progress). +- A console run is never slowed down or stopped by a build. +- It does not touch GitHub, PRs or worktrees, and the existing daily cleanup jobs stay.