@bongos/core 1.19.882 → 1.19.884

package/docs/recipes/devbox-app-windows-test.md

@@ -1,128 +0,0 @@
-# Hardware-verifying the Dev Box app on Windows (Parallels runbook)
-
-The app's logic is covered by the stub self-test (`OTB_DEVBOX_AUTOFLOW`, see
-`devbox-app/README.md`), but four things only a real Windows session can
-prove: the UAC elevation write of the Claude Desktop connection file, the
-`icacls` SSH-key lock, native notifications + tray behavior, and the full
-switch-on → <redacted> → switch-off loop. This runbook walks a
-tester through all of them in ~20 minutes. Written for **Windows 11 in
-Parallels on an Apple-silicon Mac** (that's ARM64 Windows — use the ARM
-build); everything applies unchanged to a physical PC.
-
-## 0. Setup
-
-- Windows 11 VM up to date; **Claude Desktop for Windows** installed inside
-  the VM and signed in.
-- A GitHub account that's an approved builder (the test account
-  @largekristensen-svg is ideal — it has lived the broken flow).
-- Sign into the builders' hall once in the VM's browser (Edge/Chrome
-  *inside* Windows, not the Mac side): `https://builders.example.com`.
-- Parallels quirks that bite this test:
-  - Do the whole test **inside the VM** — if the pairing browser tab opens on
-    the macOS side you're testing the wrong machine's cookies.
-  - Windows "Do not disturb" / Focus suppresses toast notifications — turn it
-    off (Settings → System → Notifications) or step 5 can't be judged.
-  - The VM clock must be right (Parallels usually syncs it) — TLS and the
-    10-minute pairing TTL both care.
-
-## 1. Download + install (tests: branded redirect, SmartScreen path)
-
-1. In the VM browser: `https://example.com/downloads/devbox/win-arm64`
-   (Parallels = ARM64 Windows; on an Intel PC use `win-x64`).
-2. Expect the browser to warn about an uncommon download — keep it.
-3. Run the installer. **SmartScreen will interpose** (unsigned until blocker
-   [#18](https://example.com/builders#/task/18)'s Windows half): "Windows protected your PC" → **More info** → **Run
-   anyway**. ✅ Record that this matches the onboarding copy's wording.
-4. One-click install; the app launches itself and the panel window opens.
-   ✅ The tray (bottom-right, may be behind the ^ chevron) shows the
-   container icon.
-   - ARM64 check: Task Manager → Details → `OTB Dev Box.exe` → the
-     Architecture column should say **ARM64**, not x64-emulated (column may
-     need enabling via right-click on the headers).
-
-## 2. Pairing sign-in (tests: app-pair flow on Windows)
-
-1. Click **Sign in through the hall**. ✅ The default browser opens
-   `/builders/pair?code=XXXX-XXXX`; the code on the page matches the code in
-   the panel.
-2. Click **Approve — sign the app in as me**. ✅ Within ~5s the panel flips
-   to signed-in (the @login shows in the header) with no further input.
-3. ✅ A "Signed in" toast notification appears.
-4. ✅ `%USERPROFILE%\.config\otb\gds-session.json` now exists.
-
-## 3. SSH key + Claude Desktop connection file (tests: icacls, UAC write)
-
-Right after sign-in the app generates/registers the key and asks to install
-the Claude Desktop connection file:
-
-1. In PowerShell:
-   ```powershell
-   icacls $env:USERPROFILE\.ssh\otb_builder
-   ```
-   ✅ Exactly one ACE — your user with full control. **No** `BUILTIN\Users`
-   or `Everyone` lines (the 644-key bug the old flow shipped).
-2. ```powershell
-   Get-Content $env:USERPROFILE\.claude\settings.json
-   ```
-   ✅ Contains an `sshConfigs` entry `name` = "Example Dev Box",
-   `sshHost` = `root@box-<your-login>.dev.example.com`. Since v1.0.3
-   (#910) THIS per-user file is what makes the environment appear in the
-   picker — written with **no elevation**; "✓ Claude Desktop is linked"
-   refers to it.
-3. ✅ A **UAC prompt** may also appear once — that's the OPTIONAL hardening
-   layer (the system `managed-settings.json` host allowlist, written to both
-   `C:\Program Files\ClaudeCode\` and `C:\ProgramData\ClaudeCode\`).
-   Declining it does NOT break the link — the panel must still show
-   "✓ Claude Desktop is linked".
-
-## 4. The switch (tests: box lifecycle end-to-end)
-
-1. Flip the switch ON. ✅ Status walks `Raising thy box…` (a first-ever box
-   shows the one-time Archon-approval wait instead — the panel says so).
-2. ✅ Within ~3 min: status **ON**, host/size rows fill in, a "Your dev box
-   is ready" toast fires, the tray icon switches to the filled variant.
-3. ✅ **Open the browser terminal** works (ttyd page, user `otb`, password
-   from the panel's copy row).
-4. ✅ `Get-Content $env:USERPROFILE\.ssh\known_hosts` contains fresh
-   `box-<login>.dev.example.com` lines (the app replaces them each
-   activation — the Desktop ssh2 fix). Since v1.0.2 (#909) the panel shows
-   this live: "✓ Box identity pinned" (it retries by itself while the box's
-   SSH service boots; a stuck "not pinned yet" row has a **Retry now**
-   button). If it never pins, read the app log:
-   `Get-Content $env:APPDATA\otb-devbox-app\devbox.log -Tail 30`.
-
-## 5. Claude Desktop connect (the step the old flow could never reach)
-
-1. **Restart Claude Desktop** inside the VM (it reads managed-settings at
-   launch).
-2. Code tab → Environment picker. ✅ **"Example Dev Box"** is listed.
-3. Select it. ✅ It connects with **no host-verification error** (this is the
-   known_hosts fix paying off) and lands in `/workspace`.
-4. Ask Claude something trivial (`ls`) to prove the session is live.
-
-## 6. Switch off + idle behavior
-
-1. Flip the switch OFF. ✅ `Resting thy box…` → OFF within ~2 min; tray icon
-   back to outline; "Your dev box closed" toast.
-2. (Optional, 15 min) Flip ON, never connect, walk away. ✅ The box
-   self-reclaims (~10–15 min idle sweep) and the panel flips itself off with
-   the "closed after sitting idle" notification — the app deliberately sends
-   no keep-alive.
-3. Quit via tray right-click → Quit. Relaunch. ✅ Still signed in (no
-   re-pairing), state re-syncs.
-
-## Recording results
-
-File outcomes against the verification task in Bongos. For any failure
-grab: the panel state, `%TEMP%`/console output if launched from a terminal
-(`& "$env:LOCALAPPDATA\Programs\OTB Dev Box\OTB Dev Box.exe"` shows logs),
-the relevant PowerShell output from steps 3–4, and a screenshot. The fastest
-diagnosis channel is the box-side state: `GET /api/gds/box/me` via
-`node scripts/gds/api.js` from any authed checkout.
-
-## Known-unsigned caveats (until blocker #18 lands)
-
-SmartScreen "Run anyway" (step 1) and the unsigned-publisher UAC dialog
-(step 3) are EXPECTED today. When the Windows signing decision lands (Azure
-Trusted Signing vs EV cert), re-run steps 1 and 3 — both prompts should then
-name the verified publisher, and the SmartScreen interstitial disappears.

package/docs/recipes/work-on-a-task-from-your-dev-box.md

@@ -1,122 +0,0 @@
-# Work on a task from your dev box
-
-> Your dev box serves your **rank scope**: Metic+ boxes carry the **whole repo**;
-> newcomer (starter) boxes carry the safe starter surface. Task-scoped slices are
-> **paused** per [ADR 0193](../adr/0193-pause-task-scoped-box-slices.md) (the
-> machinery from [ADR 0148](../adr/0148-task-scoped-box-source-access.md) remains;
-> `BOX_TASK_SCOPE=on` re-enables it). Your GitHub token never leaves the server —
-> see "How git works on a box" below, and
-> [ADR 0150](../adr/0150-box-first-boot-bringup-vendored-instances.md) for how the
-> box comes up.
-
-## TL;DR
-
-In your dev box's terminal:
-
-```bash
-/builder-start          # see what you can claim
-/builder-claim <N>      # claim task N (locks it to your session)
-/builder-sync           # pull the latest main onto the box right now
-# …work in /workspace…
-/builder-ship           # smoke + review, then land + deploy — awards credits
-```
-
-That's the whole loop. `/builder-sync` pulls fresh code within seconds instead of
-waiting for the box's ~10-minute refresh.
-
-## How git works on a box — read this BEFORE diagnosing "stuck"
-
-The box holds **no stored git credential, ever** — and that is the design, not a
-fault ([ADR 0055](../adr/0055-server-mediated-branch-publish.md)):
-
-- **Reads are server-mediated, per request.** Every remote git operation goes
-  through `/usr/local/bin/otb-git-credential`, which asks the control plane
-  (`GET /box/source-access`) for a **short-lived, read-only** credential. The
-  server checks your **live** rank + status on every single request — demotion or
-  deactivation cuts off the next fetch instantly.
-- **`git push` always fails with 403 here — by design.** The read credential
-  cannot write. Landing code is the server's job: `/builder-ship` uploads your
-  work, opens the PR, and lands it. Never try to fix the 403 by embedding a
-  token or editing git config.
-- **Source refreshes from `main` every ~10 minutes** (the `box-source-fetch`
-  cron; log at `/tmp/box-source-fetch.log`). `/builder-sync` runs the same fetch
-  on demand.
-- **If a remote git op says `could not read Username`, or the sync log shows
-  401:** the box's Bongos session expired. Run `/builder-reauth`, then
-  `/builder-sync`. That is the whole fix.
-
-The box writes these same facts to `/workspace/CLAUDE.local.md` on every sync, so
-a Claude session on the box loads them automatically (the file is gitignored and
-box-written — don't edit it).
-
-## The model — what's on your box
-
-- **Metic and above:** the full repo in `/workspace` — same tree as a laptop
-  clone, refreshed from `main` by the sync cron.
-- **Below Metic (starter):** the starter surface — methodology (`CLAUDE.md`,
-  `.claude/`), build tooling (`scripts/`, `src/bongos/`), `docs/`, `infra/`,
-  `tests/`, and the sandbox-runnable product code. Rank, checked live by the
-  server, is what bounds a box — not the task you claimed
-  ([ADR 0193](../adr/0193-pause-task-scoped-box-slices.md)).
-
-## Step by step
-
-### 1. Connect to your box
-
-If you haven't yet, run **`/builder-connect`** (or follow the
-[dev-box lifecycle recipe](builder-box-lifecycle.md)) to raise and connect to your
-box, then **`/builder-setup`** once on the box to sign the Bongos CLI in. The browser
-terminal drops you into `/workspace` — the one working folder.
-
-> **`bongos shell` / `bongos code` sync on connect (BV1.R101).** Connecting with
-> either verb runs the source fetch for you first, so you land in `/workspace`
-> already fresh. (The browser terminal drops you straight into `/workspace`; run
-> `/builder-sync` there if you want the latest immediately.)
-
-### 2. See what you can claim — `/builder-start`
-
-Lists the tasks that are `ready` and parallel-safe against everyone else's active
-claims. Pick one.
-
-### 3. Claim it — `/builder-claim <N>`
-
-Locks task N to your session so no parallel session collides with your work.
-
-### 4. Freshen the code — `/builder-sync`
-
-Re-runs the box's source fetch immediately so `/workspace` is on the current
-`main` before you branch. (The ~10-minute cron does this on its own as a
-backstop.) Off a box there's nothing to sync — your source is your local
-checkout — and the command tells you so.
-
-### 5. Work — in `/workspace`
-
-One folder, always. When you switch tasks, keep working in place.
-
-### 6. Ship — `/builder-ship`
-
-Runs the smoke tests and the review gate, then lands + deploys and awards credits.
-
-## Switching tasks
-
-One box, one working folder, one active claim at a time (the server enforces
-one-claim-per-session). To move to a different task:
-
-1. `/builder-ship` (or `/builder-release`) the current claim.
-2. `/builder-claim <M>` the new one — and keep working in `/workspace`.
-
-## Notes + gotchas
-
-- **`tests/` is on every box** — a starter box can run the suite for the code it
-  holds (tests live in the top-level `tests/`, not inside `modules/<key>/`).
-- **Idle boxes park, they don't die.** After ~2 hours of no activity the box is
-  **parked**: a snapshot is kept and the droplet is destroyed, so compute billing
-  stops and a wake restores your filesystem. Only weeks of staying parked lead to
-  reclaim (with a warning first). Still: **ship or commit before you step away** —
-  a snapshot is a safety net, not a workflow.
-- **`/builder-sync` is idempotent** — safe to re-run; it just does, on demand, what
-  the cron does on its schedule.
-- **A fresh box comes up with the code already cloned.** If a box ever comes up
-  *bare* (no code, no terminal), that's the packaging bug
-  [ADR 0150](../adr/0150-box-first-boot-bringup-vendored-instances.md) fixed on the
-  control plane — flag it rather than working around it.