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
Sage, 2026-10-22. Draft 1 for Mos. Sources: `agents/sage/work/q175-sso/DESIGN.md` sections 5 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
its N1 follow-up have landed. Vikunja #412, Gitea #385.
Sage, 2026-10-22. Draft 2 for Mos, after mos-1245. Sources: `agents/sage/work/q175-sso/DESIGN.md` sections 5
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, mos-1197 and mos-1245. Rows 192 (phase 1), 200 (`activate --sso`)
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
After the 10-24 re-pin is verified, and only when Jason starts the window (mos-1197). Nothing below runs
before his start. The copy pinned at 10-24 already carries phase 1, so its loader accepts a config with or
without `console`.
Only when Jason starts the window (mos-1197). Nothing below runs before his start. The 10-24 re-pin
condition is met: W12 passed on 7247d80c7 at 22:27:13Z (mos-1245). This plan names 7247d80c7, which already
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
- 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.
- The config.json writes are Jason's or, on his window start, an agent's for the `console` key only
(design section 10 step 4). config.json is user-authored, so Q173 doesn't cover these writes. Jason's go
has to name them, and the window doesn't start without it.
- Config writes 1 and 2 (steps 4 and 8) are an agent's, `console` key only, each with a backup first and
a validate after. Mos's message to Jason at the window start names them. If Jason says he'll write them
himself, steps 4 and 8 become his and nothing else changes (mos-1245 (a)).
## Values
@@ -36,31 +55,35 @@ without `console`.
## Steps
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;
`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
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.
4. Config write 1 (backup from step 1): add `console.sso` with the values above and one subject
must run from 7247d80c7, or be shown never to re-read config. Step 4 waits until the list is clean.
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`
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>`.
Then the same command without `--plan`, the same way earlier re-pins handled the Console. `--send`
carries over from the pointer, since nothing passes `--no-send` (mos-1195). The tester is the private
socket from row 196 (`--tester-socket`), not design section 5's `--tester-port 7333`. The `--plan` output
names every flag it drops (`--auth-header`, `--allow-user`, any proof pair) and every flag it carries. The
run stops if `--sso` or `--send` is missing or a forward-auth flag remains. Mos or Jason starts the Console
(decision 102). No agent starts it.
5. First `scripts/stack-release.sh activate 7247d80c7 mosaic-stack --sso --send --plan`. Its from line must
name 7247d80c7 (`--expect-from` is for `--units external` only, so the live user units refuse it as a
usage error). Then the same command without `--plan`, the same way earlier re-pins handled the
Console. The tester stays the private socket from row 196 (`--tester-socket`). The `--plan` output
names every flag it drops (`--public-host`, `--auth-header`, `--allow-user`) and every flag it carries.
The run stops if `--sso` or `--send` is missing or a forward-auth flag remains. Mos or Jason starts the
Console. No agent starts it.
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
and checks that `iss=` is the issuer above. The sub goes into the window record, not into any message.
8. Config write 2 (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`.
7. Jason's first sign-in (A8). It refuses `subject-unknown`. An agent reads `sub=` from that one log line,
checks that `iss=` is the issuer above, and records that the refused sub is not the placeholder. The sub
goes into the window record, not into any message.
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.
10. Unsigned write refused (mos-1195): an agent POSTs one Console write to `127.0.0.1:7332` with no cookie
and no auth header. Expect 401 `sign-in required`, and the bus event count stays unchanged. No agent
sends `X-authentik-username` to the live Console (design section 8).
10. Unsigned write refused (mos-1195), within Q173 (mos-1245 (c)): an agent acts as an anonymous client,
not as Jason. It POSTs one Console write to `127.0.0.1:7332` with no cookie and no auth header, and
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>`,
`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
@@ -75,19 +98,22 @@ without `console`.
## Stops
- 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).
## Rollback
1. Restore config.json from the latest backup, which removes `console` (or holds the placeholder state).
2. Then roll the pointer back with `scripts/stack-release.sh rollback` (previous distinct copy). An older
loader refuses a config that holds the key, so rolling back in the other order stops the bus and seats.
3. STATE after a rollback reads config.json and confirms the key is absent when the target copy predates
phase 1.
## Open for Mos
- Does Jason's window start cover both config writes (steps 4 and 8) by an agent, or does he write them?
- Does the placeholder sub in step 4 work for Mos? The only alternative is Jason giving his sub before
the window, and A8 chose the log line instead.
- Under step 10, is a loopback POST with no cookie to the live Console within Q173?
1. Same-copy re-activate (mos-1245 R1): `scripts/stack-release.sh activate 7247d80c7 mosaic-stack --no-sso
--plan`, then the same without `--plan`. R1 asked for `--expect-from 7247d80c7`, but `--expect-from` is
for `--units external` only and the live units are user units, so the plan's from line must name
7247d80c7 instead. The `--plan` output must show the pre-window Console flags from the step 1 pointer backup: `--port 7332 --public-host
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.
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.
3. STATE after the rollback reads config.json, the unit's Console flags and the pointer.
4. Last resort only, and it waits for Jason: `scripts/stack-release.sh rollback` goes to the previous
distinct copy, 4429a104f at schema 3i. The store has been at 3j since 21:59Z on 10-21, so that rollback
needs `--restore`, and any events after the backup make it Jason's call (header condition 3).