docs: sequence the two-user VM demo against MI1 S2's first-subject pin (#407)

[pdettori]

Fixes #407.

Decision

MI1 S2's first-subject pin makes MOCA_TENANCY=single serve only the first subject and refuse the rest with 403 single_tenant_deployment. Switching to MOCA_TENANCY=multi is only honest after S5, because until then users share sandbox containers on the container tier. So the two-user VM demo is sequenced:

• Until S5: run it at v0.5.1, under single with no pin.
• From S5: run it on main under MOCA_TENANCY=multi, with one owned sandbox per user.

Changes

• MI1 spec:
  • §6.6 records the sequencing.
  • It also states that setup-vm.sh adds no refusal of its own, since it can't tell how many people will log in. The control plane's 403 is the refusal, and its message names MOCA_TENANCY=multi.
  • §10.3 points deploy/vm at §6.6.
• MI1 §12.2: requires an S2 test that checks for exactly 403 / single_tenant_deployment. It also checks that the first subject is still served after a restart and that multi never writes the pin. When the test lands, the runbooks will quote its name.
• docs/demos/vm-two-user-acceptance.md and docs/demos/vm-multi-user-demo.md: the tenancy statement at the top, "Notes and limits" and the fix-list row now name the tag and the refusal code.
• deploy/vm/README.md: a new item under "What round one does not claim".

After merge

Tag the merge commit:

git tag -a v0.5.1 <merge-sha> -m "last release before MI1 S2 (two-user VM demo, #407)"
git push upstream v0.5.1

The existing v0.5.0 (41ce3eb) stays where it is. It predates #463's sandbox git identity, which the multi-user demo relies on (fix list item 5).

Still to do in S2: re-pin both runbooks and quote the pin test's name. Both are written into MI1 §12.2.

🤖 Assisted-By: Claude Code

[ingpaolodettori-dev]

Summary

This is a docs-only decision record for #407. The two-user VM demo runs at v0.5.1 under single until MI1 S5, then on main under multi. The decision is written into MI1 §6.6/§10.3/§12.2, both VM runbooks and deploy/vm/README.md, and the statements agree across all five places. I checked the claims against the repo: v0.5.0 is 41ce3eb and predates #463's merge (6831e9d); no pin code exists yet (no single_tenant_deployment outside docs); and the §9.1, §6.6 and §10.3 cross-references and the runbook step anchors (0a, 1d, Act 3/Act 5) all resolve. Nothing blocks. The suggestions are below.

Author: pdettori (MEMBER, maintainer)
Areas reviewed: Docs (MI1 spec, docs/demos/vm-two-user-acceptance.md, docs/demos/vm-multi-user-demo.md, deploy/vm/README.md)
Agent/IDE config (.claude/.vscode): none
Commits: 1 commit, all signed-off: yes
CI status: passing (all 13 checks)

Non-inline notes

• v0.5.1 doesn't exist until someone tags the merge. Both runbooks now say git checkout v0.5.1, which fails until the post-merge git tag step in the PR body is done. Please tag right after merging, or say "if not yet tagged, use <merge-sha>" in 0a.
• Fixes #407 will close the issue while two of its asks are still open. Re-pinning both runbooks at S2 and the S2 pin test are written into §12.2 but not done. Consider Refs #407 plus a follow-up issue tracked under S2, so the re-pin isn't lost once #407 is closed.
• The multi-user demo's fix-list row 5 (vm-multi-user-demo.md:735, "The guest has no git identity … #415") and the 4d narrative at :588 still describe the pre-#463 behaviour. The PR picks v0.5.1 over v0.5.0 specifically because #463 fixed that, so row 5 should read "Fixed (#463)", and 4d's "Expected" may change. Those lines are outside the diff, so this isn't an inline comment.

[ingpaolodettori-dev]

suggestion: The refusal's message naming MOCA_TENANCY=multi conflicts with the paragraph above it. Between S2 and S5, multi on the container tier is the posture this section calls not honest (users share sandbox containers, §9.1), and nothing refuses it at startup until S5's owner-binding checks (§10.1's relay row). An operator who follows the 403 hint on a deploy/vm box in that window gets exactly that posture. Consider having the message (and §12.2's exact-value test at :776) also say that the container tier needs S5's owner binding, or point to §6.6 / the runbook, rather than naming multi as the fix outright.

[pdettori]

Agreed, fixed in 26513e0. §6.6 no longer has the message offer multi as the fix. It now says that serving a second user needs MOCA_TENANCY=multi with one owned sandbox per user, which on the container tier is S5, and it cites §6.6. The §12.2 exact-value test now checks that conditional wording instead of a bare multi.

[pdettori]

Addressed in 26513e0:

• v0.5.1 not tagged yet: both runbooks now say to check out docs: sequence the two-user VM demo against MI1 S2's first-subject pin (#407) #465's merge commit if the tag isn't there yet. The tag goes on that same commit right after merge.
• Row 5 and 4d in vm-multi-user-demo.md: row 5 now reads "Fixed (fix(remote-worker): bake a system git identity into the sandbox image #463): /etc/gitconfig in the image". 4d keeps the 2026-10-01 run record, and says that the failed first commit (exit=128) predates fix(remote-worker): bake a system git identity into the sandbox image #463 and that the first commit now succeeds. fix(remote-worker): bake a system git identity into the sandbox image #463 covers both tiers: the image's system gitconfig, and build-snapshot.sh's check on the P4 rootfs.
• Refusal message naming multi: answered inline.
• Fixes vs Refs: keeping Fixes #407, as the maintainer decided. The decision VM demo: MI1 S2's first-subject pin will refuse the second user — sequence it against the two-user demo #407 asked for is made. The two remaining asks, re-pinning the runbooks and the exact-code pin test, only become actionable once S2 is underway, and MI1 §12.2 now carries both as S2 requirements: "When this test lands, the two VM runbooks quote its name next to the code (VM demo: MI1 S2's first-subject pin will refuse the second user — sequence it against the two-user demo #407)." The S2 implementer works from that section, so a separate tracking issue would only duplicate it.

[ingpaolodettori-dev]

Incremental review of b985c5b..26513e0 (docs only). Everything from the previous review is handled:

• §6.6 no longer has the 403 message offer multi as the fix. It makes multi conditional on per-user owner binding (S5 on the container tier) and cites §6.6, and the §12.2 exact-value test wording matches.
• Both runbooks fall back to #465's merge commit until v0.5.1 is tagged.
• vm-multi-user-demo.md fix-list row 5 now reads "Fixed (#463)", and 4d notes that #463 removes the first-commit failure.
• Keeping Fixes #407 is a reasonable call, since the re-pin and the pin test are now S2 requirements in MI1 §12.2.

I checked consistency across the head: no remaining text says the 403 "names MOCA_TENANCY=multi", and the v0.5.1/S5 sequencing agrees in the spec, both runbooks and deploy/vm/README.md.

Author: pdettori (MEMBER — maintainer)
Agent/IDE config (.claude/.vscode): none
Commits: 2, all signed-off
CI: passing (13/13)