Instance key provision (L21): plan report, rev 3

Status: rev 3 of the plan is written and committed. It answers Astra's round 2 (CODEX-PLAN-INSTANCE-KEY-R2.md) under Paul's rulings R-A to R-F, which are the plan's rulings 19 to 24. Nothing is pushed.

• Branch: instance-key-build, worktree /home/paulca/amadan.net/carlos/platform/.claude/worktrees/instance-key-provision
• Plan: docs/superpowers/plans/2026-10-10-instance-key-provision.md, rev 3, commit 3947e1d9
• Tasks: 7, then the final verification. Task 5 is now the adoption verb and its publication, and is mounted nowhere on main. Task 7 lost ConfiguredInstanceKey.

Dispositions (round 2)

| # | Finding | Disposition | |---|---|---| | R2-1 | A configured key still bypasses the refusal (configured A, own B) | Accepted: source (c) dropped; configured keys need an adoption record too | | R2-2 | Configuration evidence neither identifies nor pins the key | Accepted: the record names the key by digest; the pin carries it; the install verifies it | | R2-3 | An adoption record outlives its writer | Accepted: the record binds host, incarnation, session and generation from the agent's launch state; every admission starts with none | | R2-4 | No publication on the running session; O6 not gated | Accepted: hostfiles.PlatformRelay onto the session's publisher; O6 a gate in O4 | | R2-5 | Moves leave the record behind | Accepted: O7 with the exact lists; O6 does not ship before O7 | | note | The record is tenant-forgeable | Answered by ruling 19 (trusted-helper assertion) | | R1-6 | The merge option | Closed: withdrawn by Astra |

Counts: 5 accepted, 0 declined. One note answered, one round 1 finding closed.

What changed in the code

• instancekey: the record is now version 2 and writer-bound (Binding, ParseAdoption, Binds). New: the sources (SourcePlatform, SourceConfig, SourceOf) and VerifyDelivered for the install.
• ClaimLaunchSnapshot gains InstanceKeySHA256 and InstanceKeySource, read from the same two files as the env; the identity is unchanged.
• The adoption verb (MountInstanceKeyAdoption) takes its writer, key digest and source from an AdoptionLaunch that O6 builds per launch. It is no longer mounted on legacy launches.
• New hostfiles.PlatformRelay stages a platform item on a running publisher without blocking the caller.
• O2' for stage B is now (a) or (b'), with the pinned key in PinObject.InstanceKey. It replaces stage B's own rev 3 KeyEvidence reader.

How it was checked

• Every Go block in Tasks 1 to 7 was built in a scratch copy, then rebuilt task by task in a second copy, with go vet and gofmt -l clean after each task. Both copies ended byte-identical. The plan's blocks were then extracted back out of the document and compared with the scratch files, byte for byte.
• go build for windows, darwin and linux/arm64 of activator, host, hostfiles, instancekey and appconfig, and go vet on darwin: clean.
• Tests run, niced: - all new tests; - the activator Seed, Start, Prepare, Control, Schedule, Claim and LaunchEnvironment families, with the sandbox off for sockets; - the host claim and env report tests; - all of instancekey, hostfiles, moves and moves/archive.

All passed. The full go test ./internal/host/ -run Claim also passed, in 1112 seconds. It exceeds go test's default 10-minute timeout on this shared box because of an existing 30,000-delivery test (TestClaimCompletedProducersBoundStopAndRetry, 1015 seconds), so the plan's sandbox note now says to pass -timeout 30m.

• O2' was compiled and run against stage B at 919662d2, in a scratch copy with internal/instancekey added. go build ./internal/... and go vet were clean, and go test ./internal/hostrelocate/ passed: 17 evidence cases, plus every existing pinner test.
• Scratch copies are deleted. The shared $TMPDIR/gocache is untouched.

The rastrillo addendum

The helper reports on every process start (at most once per process), and the body adds "source": "platform" | "config", copied from a new agent-set $CARLOS_INSTANCE_KEY_SOURCE. It is in the plan's "Ask for rastrillo #66" section, ready to post.

Top concerns

1. The helper cannot know the source by itself. A platform key and a configured key both arrive as $CARLOS_INSTANCE_KEY. The plan has the agent deliver CARLOS_INSTANCE_KEY_SOURCE beside it (agent-owned, part of O6) for the helper to echo, and the agent checks the echo against its own launch state. If Paul would rather not add a variable, the source field could be dropped from the request, because the agent already knows the source.
2. Nothing writes a record until O6 and O7 land. The verb is built and tested but mounted nowhere: legacy launches have no writer session to bind to, and claim launches have no control socket. Platform-key and configured-key apps therefore do not relocate until claim Plan 9 Group D (O6) and the moves change (O7) ship, in that order. That is the explicit refusal of ruling 23.
3. A configured key's digest is published. A config record puts the SHA-256 of a configured secret in the data bucket. That reveals nothing for a random key; a weak, hand-typed key could be guessed against it. It is listed as a follow-up.
4. Stage B has its own diverging O2' in plan text. Its rev 3 (919662d2) has the KeyEvidence reader, with presence-only config evidence and the export parser. Stage B's planner must replace that step with this plan's O2' and rewrite its ruling 55, as O2' says.
5. One report lost to box loss inside the publisher's bound. A box lost within that bound (a second by default) after the first adoption loses that report. The pin then refuses until a later session re-reports. That is safe, but worth knowing.

Rev 3.1 (Astra round 3)

Round 3 found no P1. Rev 3.1 fixes the two remaining findings; both are accepted.

• R3-1 (P2), the replica exclusion at delivery. Ruling 25: fileEnvFor, the composition every launch path uses, drops CARLOS_INSTANCE_KEY for a replica row. That covers Start, Seed, the nested prepare, LaunchEnvironment and the claim snapshot. The helper's step 2 then has nothing to return, so no rastrillo change is needed. It is in the new Task 3b; Task 4's snapshot uses it and names no key for a replica.
• R3-2 (P3), the dependency order. The follow-ups now say O7 ships before O6.
• Effect on stage B: O2' and its test are unchanged, and nothing stage B consumes changes. The moves env report for a replica no longer lists the key, on the source and the target alike.

How it was checked:

• The plan's Go blocks were extracted from the document, rebuilt into a tree and compared byte for byte with the tested scratch tree. They matched.
• go vet and gofmt were clean. Builds for darwin, windows and linux/arm64 were clean.
• The new tests were run, sandbox off for sockets: - TestReplicaLaunchIsHandedNoInstanceKey: real replica Start and Seed, with a configured key, a pre-existing env key and both, plus a home-row control case; - TestNestedReplicaPrepareIsHandedNoInstanceKey: run and seed roles; - TestClaimReplicaLaunchIsHandedNoInstanceKey.

They pass with the activator and host launch families. With the strip removed, the replica launch test fails in all three cases.

• Scratch copies are deleted, and $TMPDIR/gocache is kept.

Residual: a replica on a claim launch before O6 has no control socket. It sees step 4, as before L21, and is still handed no key.

Rev 4 (Astra round 4, Paul's ruling 26)

Round 4 found two P2s in rev 3.1's replica strip; both are accepted. Paul decided that a replica gets its home's key (ruling 26, which replaces rulings 17 and 25).

• The strip is reverted. A replica's env is composed like any other, so a replica sharing its home's configured key keeps it.
• replicaKeyGate, an agent-side check, runs on every replica launch (Start, Seed, the nested prepare and the claim launch source): - a delivered key must match the home key's digest; - a keyless replica starts only with a control socket, where the helper refuses at step 3; - with no socket, the agent refuses the launch itself, so the app never reaches the helper's mint fallback.
• Pre-roll check. Rollout step 1 is new: it compares each replica's key digest with its home's before any box is upgraded, and records matches in CARLOS_REPLICA_HOME_KEYS. Rollout step 6's wording is corrected.
• New obligation O8 (replica placements, #162). A replica record names no home, the home-to-replica mirror is the app's own, and no box can read another region's data bucket. So handing a keyless replica its home key's value needs a placement change. Until O8 lands, the fallback is the gate's reliable refusal.
• Effect on stage B: O2' and its test are unchanged. SnapshotClaimLaunch can now return ErrReplicaKey for a replica, and LaunchEnvironment is as in rev 3 again.

How it was checked:

• Code blocks: the plan's blocks, rebuilt from the document, match the tested scratch tree byte for byte. go vet and gofmt are clean, and builds for darwin, windows and linux/arm64 are clean.
• Tests through a real launch: the replica tests run the test binary as the app, executing rastrillo e3ea08de's resolution and its documented caller. - With no control socket: a keyless replica is refused and no app runs; the home's key runs and seals with it; a differing or unlisted key is refused. - With a socket (sandbox off): the helper refuses with ErrNoInstanceKey. - With the gate disabled, the app reports "minted". That is Astra's failure, so the test catches it.
• Other paths tested: the nested prepare (run and seed), the claim launch source, and the env-var parser.
• Regression runs: the activator launch families, run with the sandbox off, pass. So do the targeted host tests and all of instancekey and hostfiles.
• Scratch copies are deleted, and $TMPDIR/gocache is kept.

Rev 5 (Astra round 5, Paul's rulings 27 and 28)

All three findings are accepted: two P2s and a P3, all about replicas.

• R5-1, ruling 27: a configured key is never changed in place. - The procedure. The rollout's operator note gives the coordinated procedure for a configured-key change on an app with replicas: stop the replicas, drop their list entries, change the key, sync, re-check, then start them. - The safety net. A replica's configured key must match its list entry, which only the pre-roll check writes. It must also match what the bucket's configuration renders now (ReplicaConfigKey over appconfig.ConfiguredKeyDigest). - Why the fresh read matters. It is cheap, it needs no O8, and it closes Astra's case: the home updated while the replica's box had not synced yet. With it removed, the test fails. - Residual. A change only on the home (a hand-edited home env, or a key configured per host) is documented by a test and left to the procedure, or to O8.
• R5-2, ruling 28: O8 delivers platform-minted keys only. A home whose key exists only in configuration is deferred, and its keyless replica is refused (tested).
• R5-3: ParseHomeKeys errors name the entry's position and the reason, never its text. The agent's logging path is tested.
• IK-1: unchanged. No IK-1 symbol changes in name, signature or behaviour. Only ParseHomeKeys's error text changed, and stage B does not use it. O2' is unchanged.

How it was checked:

• Code blocks: the plan's blocks, rebuilt from the document, match the tested scratch tree byte for byte. go vet and gofmt are clean, and builds for darwin, windows and linux/arm64 are clean.
• Tests: the activator launch families, run with the sandbox off, pass. So do the targeted host tests and all of instancekey, hostfiles, appconfig, moves and moves/archive.
• Scratch copies are deleted, and $TMPDIR/gocache is kept.

Rev 5.1 (Astra round 6)

Both P2s are accepted. Task 1's code is unchanged; it is built and reviewed on this branch.

• R6-1, ruling 29: the replica gate decides on the launch's own read. instanceEnvLayer returns the env and its key's layer from one read, every gate call passes that layer, and the gate reads no env file. - The interleaving test (TestReplicaGateDecidesOnTheLaunchesOwnRead) has a hook rewrite <host>.config.env between the launch's read and the gate, as a config sync can. The launch is refused. - Red check: with rev 5's second read restored, the app ran with the stale key.
• R6-2, ruling 30: read on each launch. The list moves from the agent's environment (never re-read by a running agent) to /etc/carlos/replica-home-keys. - The pre-roll check writes the list whole and renames it into place. The agent reads it at every replica launch and keeps no copy, so no restart is needed. A restart would bounce every instance on the box. - The procedure keeps replicas stopped throughout, and checks the file before the key changes.
• Coordinator notes: - Task 1's blocks are now the branch's code, from c568c13b to e8487c3a: the canonical-only ParseAdoption, the ParseEnv test, the two doc comments and TestEmptyOwnInstanceKeyShadowsNothing. - Rollout step 3 has the mixed-version moves readiness note: roll every box before any configured key matters.
• IK-1: unchanged by this revision. O2' and its test were re-run against stage B's tip b9a753f0 with the reviewed instancekey, and pass.

How it was checked:

• Code blocks: rebuilt from the document on top of the branch, they match the tested tree byte for byte, and Task 1's blocks equal the branch's files. go vet and gofmt are clean, and builds for darwin, windows and linux/arm64 are clean.
• Tests: the activator launch families, run with the sandbox off, pass. So do the targeted host tests and all of instancekey, hostfiles, appconfig, moves and moves/archive.
• Scratch copies are deleted, and $TMPDIR/gocache is kept.