foundation/documentation/sessions/HANDOVER.md

# HANDOVER — next-session prompt (paste into a fresh context)

> Living doc: overwritten each handover. The durable record is the dated
> `SESSION_*` files. Latest state = `SESSION_2026-07-01_002.md`.

---

Continue the **olsitec-foundation** build. You are the **Lead Agent, HIGH-RISK / INFRA mode**.

## Required reads (in `~/work/olsitec-foundation/foundation/`)
1. `documentation/sessions/SESSION_2026-07-01_002.md` ← current state + known gaps + next steps
2. `documentation/sessions/SESSION_2026-07-01_001.md` ← the prior session (gaps closed, T11/T13/T14-core)
3. `documentation/contracts/CONTRACT_001–004` + `decisions/ADR_004,005,006,007`
   (**ADR-007** is the control-plane mechanism the whole egg runs on — read it first)
4. `.forgejo/workflows/README.md` ← the ecosystem-CI reusable-workflow contract + the Forgejo-11 caller quirk
5. `documentation/999_testing.md` ← the operator's acceptance-test plan (now implemented)

## Where things stand
**The egg is LIVE; T11/T13/T14 are DONE; the ecosystem CI (999_testing) is built and validated.**
Six containers on `foundation-net` (postgres/rustfs/vault/caddy/forgejo/runner), all healthy.
`https://forge.olsitec.net`=200; `git clone git@git.olsitec.net:olsitec/foundation.git` works; origin is
Forgejo (master default). Backups age-encrypted + restore-verified (RustFS + offsite); DR scripted (`dr/`).
Working tree clean on `master`.

**CI on the runner, all green:**
- `ci.yml` (preflight + typecheck), `pulumi-preview.yml` (read-only drift/PR check),
  `backup-verify.yml` (weekly + dispatch; RESTORE VERIFY PASS from offsite).
- `ecosystem-selftest.yml` — semantic-release bump sequence (1.0.0→1.1.0→1.1.1→2.0.0→3.0.0) +
  eslint/yamllint non-zero-exit gates.
- `.forgejo/workflows/reusable-*.yml` (node-build, docker-build, lint, semantic-release) — the
  ecosystem-CI reuse layer. Downstream repos call them as
  `uses: olsitec/foundation/.forgejo/workflows/<x>.yml@master`. **Forgejo-11 quirk:** the calling job
  MUST set `runs-on` (omitting it → silently zero runs; removed by a v15 upgrade) and use the SHORT
  cross-repo ref (not a full URL). See `.forgejo/workflows/README.md`.

`cd bootstrap && ./run.sh up` is idempotent and now also publishes `pulumi stack export` to RustFS
(`bootstrap/state-publish.sh`) so the state-dependent CI has Pulumi state.

## Operating essentials
- **VM**: `204.168.234.72`, admin SSH **:222**, key `~/.ssh/foundation-test_ed25519` (also the Forgejo
  operator key). Git endpoint :22 (scp-form) + :2222.
- **Deploy**: `cd bootstrap && ./run.sh up`. Master passphrase: `pass olsitec-foundation/PULUMI_CONFIG_PASSPHRASE`.
- **Vault reboot**: `bootstrap/vault-unseal.sh`. **Backup**: `backup/backup.sh [ts]`; **restore-verify**:
  `backup/restore.sh <ts> [rfs|off]`. **DR**: `dr/restore-to-fresh-vm.sh` (+ `dr/RUNBOOK.md`).
- **Forge admin**: `platform-admin` / Vault `foundation/forgejo/service-credentials:forgejoAdminPassword`.
  (If you change the admin password in the UI, the API steps that set CI secrets need the new value.)
- **CI image**: built on the VM (`/tmp/ci-image`, from `containers/ci-image/Dockerfile`), tag
  `foundation-ci:latest`, used locally by the runner (`force_pull:false`). Rebuild on toolchain change:
  `scp` the Dockerfile + `docker build -t foundation-ci:latest .` on the VM.
- **CI secrets** (repo-scoped on `olsitec/foundation`, set via the admin API): `PULUMI_CONFIG_PASSPHRASE`,
  `SSH_PRIVATE_KEY`, `RUSTFS_ACCESS_KEY`, `RUSTFS_SECRET_KEY`.

## Watchouts (HIGH-RISK)
- `pulumi-preview` shows a benign perpetual `~sshOpts` diff (the operator vs CI key path differ in the
  docker provider) — informational; preview exits 0 on diffs by design. Don't add `--expect-no-changes`.
- `up --refresh` shows pessimistic `~triggers` replaces on the vault command chain (a preview artifact,
  idempotent if applied). The VM sshd throttles bursts of docker-over-SSH → use `--parallel 1` for refresh,
  or raise MaxStartups before wiring refresh into CI.
- Never print/commit the passphrase, Vault root token, or unseal keys (D2). Don't `pulumi up` the prod
  `olsicloud4-*` stacks, and don't `up` the `provision` stack against the LIVE VM (it would recreate it).
- The runner holds the host Docker socket (root-equivalent). **R5 is deferred** (operator OK'd trusted
  first-party CI on it) — fence it to a separate VM before any UNTRUSTED workflow. Commit atomically per task.

## Next work (pick up here)
1. **Package registry (Stage-2)** — populate the Forgejo package registry so cross-repo `@olsitec` deps
   resolve: publish `olsicrypto`, `svelte-common`, … Then validate `docker-build` end-to-end for the two
   registry-blocked candidates (**C1 seaspots-homepage**, **C5 token-service**) — pass an npmrc via the
   action's `build-args`. (C2/C3/C4 already validated.)
2. **R5 fence** — separate privileged runner VM (or socket-less DinD), labelled, before untrusted repos.
3. **T15** — `index.ts` orchestration polish (phase marker still `T10-runner`) + Gate A/B comments +
   `docs/DAY-ZERO-TIMELINE.md`.
4. **Hardening** — pin floating refs (`IMAGE_REGISTRY` PIN_DIGEST, `IMAGE_RUSTFS` `latest`, `IMAGE_CI` tag);
   pre-bake pulumi plugins into `foundation-ci` (drop preview's per-run auto-install); register in Olsitec
   MCP (D6); a Forgejo v15 upgrade would drop the reusable-workflow caller `runs-on`/short-ref quirks.

Validate each task live (VM `./run.sh up` + the runner for CI) and commit per task.