gosalyn: row 229 design round 2 for Webby webby-0148: the settings.json allowlist is three keys a fresh /login writes, written in Mosaic code with httpProxy and the path and command keys refused by name and a sha256 bump test on pi's setter names, models-store.json and keybindings.json now refuse, auth.json.lock is the only allowed dir, pi-login runs --offline and --no-session in an empty temporary cwd with a 229b allowlist test, the contents check runs before preflight, and creativeHumanOnly covers the fallback (R1, R2, N1-N5)

agents/gosalyn/work/queue-229/DESIGN.md

@@ -0,0 +1,331 @@
+# Row 229 design: a per-instance pi agent dir for Chet's Codex login (#428, Gitea #1730)
+
+Design round 2, Gosalyn, 2026-10-22, for Webby's webby-0148 (R1, R2, N1-N5). Brief:
+`docs/plans/2026-10-20_case2-rows.md`, "Brief: row B, a per-instance pi agent dir for Chet's Codex login
+(#428)". Base: `refactor` at aca16404c. Pi is the pinned
+`@earendil-works/pi-coding-agent` in the repository's `node_modules`. Cites into pi are
+`node_modules/@earendil-works/pi-coding-agent/dist/...` (`pi:`) and
+`node_modules/@earendil-works/pi-ai/dist/...` (`pi-ai:`).
+
+This is a design. Nothing in it is built or tested. The brief's gate holds: no build row starts until
+the live check in section 9 passes, run with Jason's or Mos's go, after 10-27. Mos ruled that "starts
+after 10-27" covers the build and the live check, not the design, and that the check gates every build
+row (mos-1306). Mos asks Jason for the go when the build rows are ready.
+
+## 0. Summary
+
+- Each pi instance whose route uses provider `openai-codex` gets its own agent dir,
+  `<dataRoot>/pi-agents/<business>/<instance>/`. The host makes it with the same checks as a thread store:
+  a real directory, owned by the bus user, mode 0700, no symlink in the path.
+- The launcher binds that dir read-write at the same path into the session and sets
+  `PI_CODING_AGENT_DIR` to it through the pi module's `env()`. No other instance's session sees it.
+- Pi refreshes in place under its own file lock. The new tokens are on the host disk when the run ends,
+  so the next run starts with them.
+- No tool in the session can read the dir. The gate holds every path tool to the workspace, and a role
+  with `bash` refuses at launch with `pi-agent-dir-shell`.
+- Before each launch the host checks the dir's contents against a short allowlist: `auth.json`, its
+  `auth.json.lock` dir, and a `settings.json` holding only the three keys a fresh `/login` writes. Pi
+  reads `models.json`, `models-store.json` and `settings.json` from the agent dir, and any of them could
+  send the token elsewhere or run a command. Anything outside the allowlist refuses `pi-agent-dir-unsafe`.
+- The pi module's preflight runs `pi auth check --provider openai-codex --no-refresh --json` against the
+  dir. No login refuses `pi-login-missing`, and a broken file refuses `pi-login-invalid`.
+- The human logs in with a new `mosaic pi-login <business> <instance>`. It runs pi's own `/login` with
+  the dir set, `--offline`, `--no-session` and an empty temporary cwd, so Mosaic gets its own fresh
+  grant and pi writes nothing else there. It never copies Hermes's `auth.json`.
+- Chet's route has no fallback by default (mos-1306). A fallback would quietly move him back onto Bean's
+  Z.ai key.
+- Two build rows: 229a, the store, the checks, the bind, the env, the preflight and the tests. 229b, the
+  login command and the README.
+
+## 1. Facts at aca16404c
+
+Pi side:
+- `getAgentDir()` returns `PI_CODING_AGENT_DIR`, else `~/.pi/agent` (`pi:config.js:421`). `auth.json`,
+  `settings.json`, `models.json`, `themes/`, `tools/`, `bin/`, `prompts/`, `sessions/` and `pi-debug.log`
+  all sit under it (`pi:config.js:430-462`), and so do `models-store.json`
+  (`pi:core/models-store.js:30`), a cached provider catalog, and `keybindings.json`
+  (`pi:core/keybindings.js:301`).
+- `checkProviderAuth` builds a model runtime, and `ModelRuntime.create` loads `models.json` from the
+  agent dir (`pi:core/model-runtime.js:76`). So the auth check itself reads `models.json`.
+- Interactive mode downloads `fd` and `rg` into `<agentDir>/bin/` when they are missing
+  (`pi:modes/interactive/interactive-mode.js:699-705`, `pi:utils/tools-manager.js:300-330`) unless
+  `PI_OFFLINE` is set, which `--offline` does (`pi:main.js:440-444`, `pi:utils/tools-manager.js:13`).
+  Without `--no-session` it makes `<agentDir>/sessions/` (`pi:core/session-manager.js:242-252`).
+- A fresh interactive start writes `lastChangelogVersion` to `settings.json`
+  (`pi:modes/interactive/interactive-mode.js:918`). A first `/login` then selects the provider's
+  default model with `persist: true` (`:4766`), which writes `defaultProvider` and `defaultModel`
+  (`pi:core/settings-manager.js:470-476`). `enabledModels` changes only when scoped models are set
+  (`pi:core/agent-session.js:1272-1285`), and a fresh dir has none. No settings write runs outside
+  interactive mode.
+- `AuthStorage` writes `auth.json` with mode 0600 only when it creates the file
+  (`pi:core/auth-storage.js:14-15`). It never fixes the mode of an existing file. It takes a
+  proper-lockfile lock before a refresh write (`:39`, `:85`), which is the directory `auth.json.lock`
+  beside the file, and writes with `writeFileSync` (`:66`, `:140`). The lock is a sibling path, so the
+  dir itself must be writable. A file-only bind isn't enough.
+- pi-ai refreshes under a double-checked lock and treats a token with less than 5 minutes left as
+  expired (`pi-ai:...resolve.js:62-74`). Two sessions sharing one dir therefore serialize their refreshes.
+- The `openai-codex` OAuth client has a browser flow with a callback on `localhost:1455` and a device-code
+  flow at `auth.openai.com/codex/device` (`pi-ai:auth/oauth/openai-codex.js:26-33`). A refresh posts
+  `grant_type=refresh_token` (`:125-140`), and the response carries a new refresh token. The old one is
+  then spent.
+- Startup migrations write into the agent dir only when legacy files exist there: `oauth.json`, session
+  files in the dir root, `commands/`, `tools/` (`pi:migrations.js:17-63`, `:76-129`, `:161-177`).
+  `settings-manager.js:101` writes `settings.json` when a setting changes.
+- `pi auth check --provider <p> [--json] [--credentials] [--no-refresh]` (`pi:cli/auth-command.js:5`,
+  `:23-25`). `checkProviderAuth` (`pi:cli/auth-check.js:5-34`) returns `ready`, `not_ready` or `invalid`.
+  It builds its model runtime with `allowModelNetwork: false` (`:43-49`). With `--no-refresh` it only
+  checks that a credential is present: a revoked refresh token still reads `ready`. It prints no
+  credential unless `--credentials` is given. `auth print-bearer-token` and `print-api-key` print
+  secrets, and Mosaic never runs them.
+
+Mosaic side:
+- `binds()` lists every mount and says why (`packages/seat/src/sandbox.mjs:102-131`). The thread store
+  binds read-write at `:119-125`. `sandboxArgv` sets `HOME` to the run's own `home/` (`:163-166`).
+- `threadStore()` makes `<dataRoot>/threads/<business>/<thread>/` and refuses a symlink, a non-directory,
+  another owner or any group or other mode bit (`packages/seat/src/session.mjs:59-72`). `ENV_ALLOW`
+  doesn't list `PI_CODING_AGENT_DIR` (`:83-88`).
+- The launcher's check order is at `packages/cli/src/launcher.mjs:1-40`. One instance per thread runs at
+  a time (`:289`, `registry.running(b.id, instance, thread)`), so a thread instance such as Chet can run in
+  two threads at once. Preflight is `harness.preflight({ env })` (`:333`). A failed primary preflight
+  takes the stated fallback (`:334-345`, row 65). The thread store is made at `:388-394`, mounts at `:456`,
+  the session file with `harnessEnv: bundle.env` at `:461-484`, the paths at `:486-495`.
+- The pi module's `preflight()` checks only the binary (`packages/plugins/harness/pi/index.mjs:33-37`).
+  `env({ policy, tools, session })` builds the harness env (`:63-71`). The adapter runs pi with
+  `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-approve` and `--offline`
+  (`adapters/pi/adapter.sh:104-123`).
+- The gate refuses a path tool whose path is outside the workspace (`packages/harness/src/gate.mjs:79-83`,
+  `:152`). Chet's role, `roles/companion.json`, has tools `["read","web"]`.
+
+## 2. Where the dir lives and who can read it
+
+`<dataRoot>/pi-agents/<business>/<instance>/`. A new seat function `agentStore(dataRoot, business,
+instance)` in `session.mjs`, beside `threadStore()`, makes each level with mode 0700 and the same refusal:
+a symlink, a non-directory, another owner or any 0077 mode bit refuses `pi-agent-dir-unsafe`. Business and
+instance must match `ID_PATTERN` and hold no `..`.
+
+The dir belongs to the instance, not the thread. Chet's threads share one login, and pi's lock keeps
+their refreshes apart (section 1). Only the bus user can read it on the host. A seat that shares the bus
+uid can read it too, which is the same exposure the thread stores and the bus's own credential files
+have today (case 2 r11 B1). This row doesn't change that.
+
+Which routes get one. The pi module exports `agentStore({ provider })`, true for `openai-codex`. The
+launcher asks the primary route's module, and the fallback's if one is taken. A module without the hook
+gets no dir. A provider key route such as Bean's Z.ai keeps working exactly as today.
+
+## 3. How the launcher mounts it
+
+After step 5 picks the route and before the bwrap check:
+1. If the module says the route needs a store, the launcher calls `agentStore()`. A refusal stops the
+   launch with its code.
+2. The contents check in section 5 runs.
+3. The module's preflight runs with the dir (section 6).
+4. `paths` gains `agentStore`, and `binds()` adds one entry:
+   `{ kind: "rw", src: dir, why: "the instance's pi agent dir, its own login, kept across runs (row 229)" }`.
+   It binds at the same path, so the path pi sees is the host path.
+5. The session object passed to `bundle` gains `agentDir`, and the pi module's `env()` adds
+   `PI_CODING_AGENT_DIR: session.agentDir` when it is set. It reaches pi through `session.harnessEnv`,
+   which the runner spreads into the adapter's env. `ENV_ALLOW` doesn't change, so no host value of
+   `PI_CODING_AGENT_DIR` ever passes.
+
+The preflight signature changes to `preflight({ env, agentDir })`. Every other module ignores the new key,
+so their behaviour doesn't change. The adapter contract in `adapters/README.md` gains one line for it.
+
+## 4. How a refresh survives the run
+
+Pi writes the refreshed `auth.json` into the bound dir, which is the host dir. Nothing copies it in or out.
+A run that dies mid-write leaves pi's lock behind. Pi's lock goes stale on its own timer. The contents
+check in section 5 accepts a lock entry and never deletes one, so the host never breaks a lock a running
+session holds.
+
+Two clients on one grant would race: a refresh spends the old refresh token, and the other client's next
+refresh fails. Mosaic avoids that by never sharing a grant. `mosaic pi-login` makes a new one (section 7).
+Hermes keeps its own grant. Whether OpenAI revokes an older grant when a new one is made, or limits grants
+per account, I don't know. Section 9's live check exists to find out.
+
+## 5. What the session can read, and what the dir may hold
+
+The session's tools:
+- `read` and every other path tool go through the gate, which refuses a path outside the workspace. The
+  agent dir is outside it.
+- `web` sends a URL and gets text back. It has no file argument.
+- `bash` would reach the dir, since pi itself must open it. A role whose tool list has `bash`, or a route
+  with the harness's built-in shell, refuses `pi-agent-dir-shell` at launch. The same check runs in
+  `validate` for the role file, so the conflict shows before a launch.
+- The pi process reads the dir. That is the point of the bind.
+
+The dir's contents. Pi reads more than `auth.json` from the agent dir. A `models.json` there can set a
+provider's base URL, which would send the OAuth token to another host, and `models-store.json` is a
+cached catalog of the same kind. `settings.json` is worse than it looks. Every dangerous setting is a
+key pi knows, so a check against pi's own key set would pass all of them (webby-0148 R1):
+- `httpProxy` applies to every request pi makes, the Codex bearer and the refresh POST included
+  (`pi:main.js:455`, `:685`)
+- `packages`, `extensions`, `skills`, `prompts` and `themes` name code or text to load
+- `shellPath`, `shellCommandPrefix`, `npmCommand`, `externalEditorCommand` and `sessionDir` name a
+  command to run or a place to write
+
+`--no-extensions` and the other flags turn discovery off, but this design doesn't rest on them alone.
+Before each launch the host lists the dir and allows only:
+- `auth.json`, a regular file, mode 0600, owned by the bus user. Pi sets 0600 only when it creates the
+  file, so this check is what holds the mode
+- `auth.json.lock`, a directory, owned by the bus user. It is the only directory allowed, and the check
+  never deletes it (section 4)
+- `settings.json`, a regular file of at most 4 KiB that parses to a plain object, empty or with only
+  these keys: `lastChangelogVersion`, a string of at most 32 characters matching
+  `^\d+\.\d+\.\d+[0-9A-Za-z.+-]*$`, `defaultProvider`, exactly `openai-codex`, and `defaultModel`, a
+  string of at most 64 characters matching `^[A-Za-z0-9._-]+$`. These are the keys a fresh `/login`
+  writes (section 1). Any other key refuses, `httpProxy` and the paths and commands above by name
+
+Anything else refuses `pi-agent-dir-unsafe` and names the entry: `models.json`, `models-store.json`,
+`keybindings.json`, `extensions/`, `tools/`, `bin/`, `themes/`, `prompts/`, `skills/`, `sessions/`,
+`pi-debug.log`, `oauth.json`, a symlink, a device, or any other file or directory. Round 1 allowed
+`models-store.json` and `keybindings.json`. Round 2 refuses both: the first can carry a base URL like
+`models.json`, and nothing in a headless run or a login needs the second. Nothing in the session can
+create a refused entry, because no session tool reaches the dir. The check guards against a human
+copying a whole `~/.pi/agent` in by hand, and against a login that wrote more than it should.
+
+The settings allowlist is the three keys above, written in Mosaic's code, not read from pi. A test pins
+the sorted list of `SettingsManager` setter names in the pinned package by its sha256, so a pi bump that
+adds, drops or renames any setting fails the suite, and the human reviewing the bump re-checks the three
+keys before re-pinning.
+
+## 6. How a launch with no login refuses
+
+The pi module's `preflight({ env, agentDir })`, after the binary check, runs when `agentDir` is set:
+
+```
+node <pi bin> auth check --provider openai-codex --no-refresh --json
+```
+
+It runs only after the section 5 contents check passes, because the auth check loads `models.json` from
+the dir (section 1). It uses `PI_CODING_AGENT_DIR=<agentDir>`, `HOME` and the cwd both set to one empty
+temporary dir made with `mkdtemp` under the scratch tmp and removed afterwards, and `PATH` from the
+system. It runs on the host with a 10-second timeout. Never `--credentials`. Results:
+- exit 0, `ready`: pass
+- exit 1, `not_ready`: `pi-login-missing`, with the message "run `mosaic pi-login <business> <instance>`"
+- exit 2, `invalid`, a timeout or any other exit: `pi-login-invalid`
+
+The check never refreshes, so a launch never spends a refresh token on the host. That leaves one gap I
+can't close without a network call: a revoked or expired refresh token still reads `ready`. Pi then
+fails the first turn when its refresh fails, and the turn's failure is visible in the run record. The
+fix is the same login command. I chose `--no-refresh` over a refresh at preflight because a host-side
+refresh would race a running session of the same instance.
+
+Fallback. Row 65 lets a failed primary preflight take the stated fallback. Chet's route ships with none
+(mos-1306). A fallback onto Bean's Z.ai key would make a lost login silent: Chet answers on another
+provider and Melanie can't tell. Without one, the launch refuses with the preflight's code. A human can
+still add a fallback through `routes.set`. No agent path can: Chet is a `companion` instance, a creative
+definition (`packages/business/src/vocabulary.mjs:207`), and `creativeHumanOnly`
+(`packages/business/src/launch-settings.mjs:13-17`, called for routes at `:293`) refuses
+`organization-creative-human-only` unless the actor is the business file's human. The tester is not
+that human, though `routes.set` is a tester verb (`packages/cli/src/broker.mjs:139`). This row only
+makes none the default.
+
+## 7. The login command (229b)
+
+`mosaic pi-login <business> <instance>` in `packages/cli`, a human verb:
+1. Refuses unless the instance's primary route is pi with provider `openai-codex`
+   (`pi-login-not-needed`), and unless the instance isn't running (`instance-running`).
+2. Calls `agentStore()` and runs the contents check.
+3. Moves an existing `auth.json` out of the dir, to
+   `<dataRoot>/pi-agents/<business>/.replaced/<instance>-<UTC>.json` at 0600, so every login is a fresh
+   grant and the contents allowlist doesn't grow. It never reads or copies `~/.pi/agent` or Hermes's
+   files.
+4. Runs interactive pi on the attached terminal with `PI_CODING_AGENT_DIR=<dir>`, `HOME` and the cwd
+   both set to one empty temporary dir under the scratch tmp, and these flags: `--offline`, so pi
+   downloads no `fd` or `rg` into `<dir>/bin/` and sends no telemetry, `--no-session`, so it makes no
+   `<dir>/sessions/`, and the `--no-extensions`, `--no-skills` and `--no-prompt-templates` the adapter
+   uses. `--offline` doesn't block `/login`: it sets `PI_OFFLINE` and skips the version check and the
+   catalog refresh, and the OAuth flow makes its own requests. The command tells the human to type
+   `/login`, choose OpenAI Codex and pick the device code flow, since the callback on `localhost:1455`
+   won't reach a browser on another machine.
+5. Afterwards runs the section 5 contents check, then the section 6 check, and prints only their
+   status. A login that left any entry outside the allowlist refuses `pi-agent-dir-unsafe` here, before
+   any launch.
+
+The command prints no token. `.replaced/` gets the `agentStore()` checks. It can't collide with an
+instance dir, since `ID_PATTERN` doesn't allow a leading dot.
+
+`reset.sh` wipes the data root, and the login with it. The README says so.
+
+## 8. Files the build touches
+
+229a:
+- `packages/seat/src/session.mjs`: `agentStore()`, the contents check
+- `packages/seat/src/sandbox.mjs`: the `agentStore` bind in `binds()`
+- `packages/cli/src/launcher.mjs`: the store, the check and the preflight argument after step 5, the
+  `pi-agent-dir-shell` refusal, `paths.agentStore`, `agentDir` on the session
+- no change to `packages/harness/src/bundle.mjs`, which already passes `{ ...session, ...model }` to `env()`
+  (`:375`), so `agentDir` on the launcher's session reaches the module
+- `packages/plugins/harness/pi/index.mjs`: `agentStore()`, the preflight, `PI_CODING_AGENT_DIR` in `env()`
+- `adapters/README.md`: the `agentDir` preflight key
+- the role validator for `pi-agent-dir-shell`
+- tests in `packages/seat/tests`, `packages/cli/tests`, `packages/plugins/harness/pi/tests`
+
+229b:
+- `packages/cli/src/pi-login.mjs` and its dispatch
+- `packages/cli/README.md`
+- tests in `packages/cli/tests`
+
+## 9. The live check (the gate)
+
+Run after 10-27, with Jason's or Mos's go, on Chet's real ChatGPT login. A human does the login.
+1. Hermes answers as Chet. Record the time.
+2. `mosaic pi-login` for Chet. The status reads `ready`.
+3. Launch Chet on the new route. Run one turn.
+4. Force a Mosaic refresh. The human edits only `expires` in Mosaic's `auth.json` to a past time, then
+   runs one more turn. It succeeds, and `auth.json` changed. After steps 2, 3 and 4 the record lists the
+   dir's entry names, and each passes the section 5 check.
+5. Hermes answers again. This is the check that Mosaic's refresh didn't revoke Hermes's grant.
+6. Wait for Hermes's own next refresh, at least one access-token lifetime, then run a Mosaic turn. This is
+   the check the other way.
+7. The record lists each step's time and result, and never a token.
+
+Any failure stops the row. The answer then goes to Jason: Chet waits until Hermes stops, or he moves
+alone. No build row starts before step 6 passes.
+
+## 10. Tests the build rows carry
+
+229a:
+- `agentStore()` refuses a symlinked level, a wrong owner, a 0750 dir and a `..` id
+- the contents check passes the allowed set and refuses each listed entry, `models-store.json`,
+  `keybindings.json`, `bin/` and `pi-debug.log` included, and a second directory beside
+  `auth.json.lock`
+- `settings.json` passes when absent, `{}` and with the three allowed keys. It refuses each of
+  `httpProxy`, `packages`, `extensions`, `skills`, `prompts`, `themes`, `shellPath`,
+  `shellCommandPrefix`, `npmCommand`, `externalEditorCommand` and `sessionDir` by name, a
+  `defaultProvider` other than `openai-codex`, a non-string or overlong value, an array, a file over
+  4 KiB and a file that doesn't parse
+- `auth.json` at 0644 refuses, so a file that pi didn't create still meets the mode
+- the bump test: the sha256 of the sorted `SettingsManager` setter names in the pinned package matches
+  the pinned value, so any change to pi's settings key set fails it
+- a `models.json` in the dir refuses `pi-agent-dir-unsafe` before the fake pi bin runs. The fake bin
+  records each call, and the record is empty
+- the preflight's fake pi bin records its cwd and `HOME`, which are the same empty temporary dir
+- the tester's `routes.set` adding a fallback to Chet's route refuses `organization-creative-human-only`
+- a companion role with `bash` refuses `pi-agent-dir-shell`
+- `binds()` adds the entry only when `agentStore` is set
+- `env()` sets `PI_CODING_AGENT_DIR` only when `agentDir` is set
+- a host `PI_CODING_AGENT_DIR` never reaches the session
+- preflight maps exit 0, 1, 2 and a timeout to pass, `pi-login-missing` and `pi-login-invalid`. A fake
+  pi bin records its argv, which must hold `--no-refresh` and never `--credentials`
+- a route with no store gets no bind and no preflight change. Bean's route is unchanged
+- Chet's route with a failed preflight and no fallback refuses with the preflight's code
+- a mutant without the contents check fails, and so does one without the shell refusal
+- every test uses `mktemp -d` under the scratch tmp, never `/tmp`, and no real login
+
+229b:
+- `pi-login` refuses a non-codex route and a running instance
+- it moves an existing `auth.json` out of the dir, never reads `~/.pi/agent`, and prints only the status
+- its fake pi bin records argv, which holds `--offline` and `--no-session`, and a cwd that is an empty
+  temporary dir
+- after a fake login that writes `auth.json`, `auth.json.lock/` and a `settings.json` with the three keys,
+  the dir holds only allowlisted entries and the command reports `ready`
+- a fake login that also writes `bin/fd` or `sessions/` makes the command refuse `pi-agent-dir-unsafe`
+
+## 11. Open items
+
+- Whether OpenAI revokes or caps grants per account. Section 9 answers it.
+- Whether pi's request-time refresh works under the adapter's flags. I read nothing that blocks it.
+  `--offline` affects only the model catalog (`pi:core/model-runtime.js:88`). Section 9 step 4 proves it.
+- Whether a real `/login` on the pinned pi writes only the three settings keys. Section 1 reads it from
+  the code. Section 9's dir listings prove it, and a fourth key there stops the row for a design change.