docs: Q175 phase 2 window plan, draft 2 after mos-1245 (#385, Vikunja 412)

R1 same-copy rollback, 7247d80c7 named, placeholder stop, step 10 aimed at a
tester-owned thread, agent config writes. Names the tool gap: activate has no
--send and no --no-sso, and --expect-from is external-units only.
This commit is contained in:
jason.woltje committed 2026-10-21 19:33:57 -05:00
1 parent 02da6a2ae4
commit 92be0db025
1 file changed
+66 -40
+66 -40
View File
@@ -1,24 +1,43 @@
# Plan: Q175 phase 2 window, the live Console switches to --sso # Plan: Q175 phase 2 window, the live Console switches to --sso
Sage, 2026-10-22. Draft 1 for Mos. Sources: `agents/sage/work/q175-sso/DESIGN.md` sections 5 and 10 Sage, 2026-10-22. Draft 2 for Mos, after mos-1245. Sources: `agents/sage/work/q175-sso/DESIGN.md` sections 5
(phase 2 order, rollback, Jason-gated steps), Mos's C1 condition (mos-0977, b416d2ede), Jason's phase 2 and 10 (phase 2 order, rollback, Jason-gated steps), Mos's C1 condition (mos-0977, b416d2ede), Jason's phase 2
answers (Q209, mos-1216, mos-1217), mos-1195 and mos-1197. Rows 192 (phase 1), 200 (`activate --sso`) and answers (Q209, mos-1216, mos-1217), mos-1195, mos-1197 and mos-1245. Rows 192 (phase 1), 200 (`activate --sso`)
its N1 follow-up have landed. Vikunja #412, Gitea #385. and its N1 follow-up have landed. Vikunja #412, Gitea #385.
## Blocked on a tool gap
Two steps need `scripts/stack-release.sh` flags that don't exist at 02da6a2ae:
- `activate` has `--no-send` but no `--send`. The live pointer holds no `--send`: the 10-20 19:29:56Z
re-pin of 490e2771d gave `--no-send`, and every activation since has carried it off. So step 5 can't turn
`--send` on (mos-1195).
- `activate` has no way to turn `--sso` off. Without `--sso`, `sso_base` carries it from the pointer
(`sso: carried`), and `check_target` refuses the pointer's own copy as `already-active`. The pre-window
flags (`--public-host`, `--auth-header`, `--allow-user`) have no activate option either. So R1's
same-copy rollback can't run.
The fix is one small row: `activate --send` and `activate --no-sso`. `--no-sso` takes the Console flags
from the rollback set of the activation that turned `--sso` on, the way `sso_base` already does for a
rollback to a copy without `--sso`, and it keeps `--send` and the tester as the pointer has them.
test-release.sh gets cases for both, and the reviewer is a seat other than Sage. It lands and is re-pinned
before the window. The steps below assume it.
## When ## When
After the 10-24 re-pin is verified, and only when Jason starts the window (mos-1197). Nothing below runs Only when Jason starts the window (mos-1197). Nothing below runs before his start. The 10-24 re-pin
before his start. The copy pinned at 10-24 already carries phase 1, so its loader accepts a config with or condition is met: W12 passed on 7247d80c7 at 22:27:13Z (mos-1245). This plan names 7247d80c7, which already
without `console`. carries phase 1, so its loader accepts a config with or without `console`. If another re-pin lands before
Jason starts, the plan names the copy live at that point, and step 3 runs against it.
## Who ## Who
- Sage or Darkwing runs the agent steps under Q173: backup first, STATE report after. - Sage or Darkwing runs the agent steps under Q173: backup first, STATE report after.
- Mos or Jason starts and restarts the Console. - Mos or Jason starts and restarts the Console (decision 102).
- Jason signs in, sends and signs out. - Jason signs in, sends and signs out.
- The config.json writes are Jason's or, on his window start, an agent's for the `console` key only - Config writes 1 and 2 (steps 4 and 8) are an agent's, `console` key only, each with a backup first and
(design section 10 step 4). config.json is user-authored, so Q173 doesn't cover these writes. Jason's go a validate after. Mos's message to Jason at the window start names them. If Jason says he'll write them
has to name them, and the window doesn't start without it. himself, steps 4 and 8 become his and nothing else changes (mos-1245 (a)).
## Values ## Values
@@ -36,31 +55,35 @@ without `console`.
## Steps ## Steps
1. Backups: the bus store, the release pointer, the Console unit and config.json, each copied 0600 into 1. Backups: the bus store, the release pointer, the Console unit and config.json, each copied 0600 into
a new dated directory, with sha256 recorded. a new dated directory, with sha256 recorded. The pointer backup records the pre-window Console flags
the rollback restores.
2. Slot shape check (A6), without printing or copying the value: `stat` shows mode 0600 and the owner; 2. Slot shape check (A6), without printing or copying the value: `stat` shows mode 0600 and the owner;
`wc -l` is 1; `tr -cd '\r' <slot | wc -c` is 0; the last byte is a newline (`tail -c1 | od -An -c`). `wc -l` is 1; `tr -cd '\r' <slot | wc -c` is 0; the last byte is a newline (`tail -c1 | od -An -c`).
3. Straggler check (C1): list every running process, unit and timer that reads config.json, with the 3. Straggler check (C1): list every running process, unit and timer that reads config.json, with the
copy it runs from (`/proc/<pid>/exe` and cwd links, `systemctl --user list-units`, `list-timers`). Each one copy it runs from (`/proc/<pid>/exe` and cwd links, `systemctl --user list-units`, `list-timers`). Each one
must run from the 10-24 copy, or be shown never to re-read config. Step 4 waits until the list is clean. must run from 7247d80c7, or be shown never to re-read config. Step 4 waits until the list is clean.
4. Config write 1 (backup from step 1): add `console.sso` with the values above and one subject 4. Config write 1 (agent, backup from step 1): add `console.sso` with the values above and one subject
`{ "sub": "pending-first-sign-in", "name": "jason.woltje" }`. `scripts/mosaic-config.mjs validate` `{ "sub": "pending-first-sign-in", "name": "jason.woltje" }`. `scripts/mosaic-config.mjs validate`
reads it back before anything starts. reads it back before anything starts.
5. First `scripts/stack-release.sh activate <10-24 copy> mosaic-stack --sso --plan --expect-from <10-24 copy>`. 5. First `scripts/stack-release.sh activate 7247d80c7 mosaic-stack --sso --send --plan`. Its from line must
Then the same command without `--plan`, the same way earlier re-pins handled the Console. `--send` name 7247d80c7 (`--expect-from` is for `--units external` only, so the live user units refuse it as a
carries over from the pointer, since nothing passes `--no-send` (mos-1195). The tester is the private usage error). Then the same command without `--plan`, the same way earlier re-pins handled the
socket from row 196 (`--tester-socket`), not design section 5's `--tester-port 7333`. The `--plan` output Console. The tester stays the private socket from row 196 (`--tester-socket`). The `--plan` output
names every flag it drops (`--auth-header`, `--allow-user`, any proof pair) and every flag it carries. The names every flag it drops (`--public-host`, `--auth-header`, `--allow-user`) and every flag it carries.
run stops if `--sso` or `--send` is missing or a forward-auth flag remains. Mos or Jason starts the Console The run stops if `--sso` or `--send` is missing or a forward-auth flag remains. Mos or Jason starts the
(decision 102). No agent starts it. Console. No agent starts it.
6. The start line shows one provider, the issuer and `subjects 1`. No secret value, no sub. 6. The start line shows one provider, the issuer and `subjects 1`. No secret value, no sub.
7. Jason's first sign-in (A8). It refuses `subject-unknown`. An agent reads `sub=` from that one log line 7. Jason's first sign-in (A8). It refuses `subject-unknown`. An agent reads `sub=` from that one log line,
and checks that `iss=` is the issuer above. The sub goes into the window record, not into any message. checks that `iss=` is the issuer above, and records that the refused sub is not the placeholder. The sub
8. Config write 2 (new backup first): replace the placeholder with Jason's sub, so the list holds that one goes into the window record, not into any message.
subject only. Validate. Mos or Jason restarts the Console. The start line shows `subjects 1`. 8. Config write 2 (agent, new backup first): replace the placeholder with Jason's sub, so the list holds
that one subject only. Validate. Mos or Jason restarts the Console. The start line shows `subjects 1`.
9. Jason signs in, sends one message and signs out. 9. Jason signs in, sends one message and signs out.
10. Unsigned write refused (mos-1195): an agent POSTs one Console write to `127.0.0.1:7332` with no cookie 10. Unsigned write refused (mos-1195), within Q173 (mos-1245 (c)): an agent acts as an anonymous client,
and no auth header. Expect 401 `sign-in required`, and the bus event count stays unchanged. No agent not as Jason. It POSTs one Console write to `127.0.0.1:7332` with no cookie and no auth header, and
sends `X-authentik-username` to the live Console (design section 8). the body names a tester-owned thread, so a wrong 2xx reaches no live seat. It expects 401
`sign-in required` with the bus event count unchanged, and it writes nothing else. No agent sends
`X-authentik-username` to the live Console (design section 8).
11. Forged header refused: on a scratch Console from the same copy (`serve --sso --port <scratch>`, 11. Forged header refused: on a scratch Console from the same copy (`serve --sso --port <scratch>`,
`MOSAIC_CONFIG` at a scratch config with a scratch dataRoot and a dummy slot, issuer an unreachable `MOSAIC_CONFIG` at a scratch config with a scratch dataRoot and a dummy slot, issuer an unreachable
loopback host, no `--send` and no tester), a request with `X-authentik-username` and no cookie loopback host, no `--send` and no tester), a request with `X-authentik-username` and no cookie
@@ -75,19 +98,22 @@ without `console`.
## Stops ## Stops
- Any refusal in steps 2-6 or 8: stop, keep the backups, and roll back as below. Never edit around it. - Any refusal in steps 2-6 or 8: stop, keep the backups, and roll back as below. Never edit around it.
- While the placeholder is the only subject, any sign-in that creates a session is a stop and a
rollback (mos-1245 (b)).
- Step 10: any result other than 401 with the event count unchanged is a stop, and it goes to Mos.
- Two failures in the window: stop and report to Mos (mos-0823). - Two failures in the window: stop and report to Mos (mos-0823).
## Rollback ## Rollback
1. Restore config.json from the latest backup, which removes `console` (or holds the placeholder state). 1. Same-copy re-activate (mos-1245 R1): `scripts/stack-release.sh activate 7247d80c7 mosaic-stack --no-sso
2. Then roll the pointer back with `scripts/stack-release.sh rollback` (previous distinct copy). An older --plan`, then the same without `--plan`. R1 asked for `--expect-from 7247d80c7`, but `--expect-from` is
loader refuses a config that holds the key, so rolling back in the other order stops the bus and seats. for `--units external` only and the live units are user units, so the plan's from line must name
3. STATE after a rollback reads config.json and confirms the key is absent when the target copy predates 7247d80c7 instead. The `--plan` output must show the pre-window Console flags from the step 1 pointer backup: `--port 7332 --public-host
phase 1. mosaic.woltje.com --auth-header X-authentik-username --allow-user jason.woltje --tester-socket`. `--send`
follows the pointer. A plan that differs is a stop. Mos or Jason restarts the Console.
## Open for Mos 2. Restore config.json from the step 1 backup, which removes `console`. 7247d80c7 loads config with or
without the key, so the order of 1 and 2 doesn't matter on this copy.
- Does Jason's window start cover both config writes (steps 4 and 8) by an agent, or does he write them? 3. STATE after the rollback reads config.json, the unit's Console flags and the pointer.
- Does the placeholder sub in step 4 work for Mos? The only alternative is Jason giving his sub before 4. Last resort only, and it waits for Jason: `scripts/stack-release.sh rollback` goes to the previous
the window, and A8 chose the log line instead. distinct copy, 4429a104f at schema 3i. The store has been at 3j since 21:59Z on 10-21, so that rollback
- Under step 10, is a loopback POST with no cookie to the live Console within Q173? needs `--restore`, and any events after the backup make it Jason's call (header condition 3).