crossbar/docs/plans/v2/README.md

# v2 implementation plan: learned context, the context guard, wake-on-LAN, identity

> **For the implementing model:** do not work from this file. The owner gives you one task file at
> a time (`01-…` to `05-…`). This file is the index for the owner and the reviewer.

**Goal:** `PLAN.md` §4b and §10 v2. The poller learns each host's context size from `/props`; a
prompt that cannot fit the leased host's per-slot context moves to one where it fits or is
refused with a clear 400; a route whose hosts are all down can wake a sleeping host by
wake-on-LAN and wait for it; a route can be restricted to named tailnet peers.

**Architecture:** `health.Status` gains `NCtx`/`Slots` (task 01); the proxy gains the guard
(task 02); two new small packages, `wake` (magic packets + a waiter, task 03) and `identity`
(whois resolver, checker, middleware, task 04); config gains `identity`, `[hosts.x.wake]`,
`routes.x.peers`; `main` wires the waker and the middleware (task 05).

**How this plan was made:** acceptance tests first, from `PLAN.md`; no reference implementation.
Every given test compiled against a panic-only skeleton of the names in the tasks (`go vet`
clean). The given tests were walked against the task rules and against the other given files
(helpers, line limits, `main.go` call sites) before handover — the v1 findings list is the
reason.

**Tech stack:** as v1; no new module. `identity`'s production resolver shells out to
`tailscale whois --json`, which exists on every fleet host.

## Global constraints

- Everything in `AGENTS.md`. Branch `v2`. One task, one fresh OpenCode session, one commit.
- Bodies never logged. Type assertions two-valued. Files under 400 lines.
- Given files are copied and never edited; some **replace** earlier ones (the task says so).

## Tasks

| # | File | Delivers | Tests that define it |
|---|---|---|---|
| 01 | `01-props.md` | `Status.NCtx`, `Status.Slots`, `PerSlotCtx()`; `/props` in the poll; hosts view shows them | `health/props_test.go` |
| 02 | `02-ctxguard.md` | prompt-size estimate; move or 400; `X-Crossbar-Ctx` | `proxy/ctxguard_test.go` |
| 03 | `03-wake.md` | `internal/wake`: magic packet, `Send`, `Waker` | `wake/wake_test.go` |
| 04 | `04-identity.md` | `internal/identity`: whois parse, checker, header mode, middleware; config `identity`/`peers`/`wake` | `identity/*_test.go`, `config/config_v2_test.go` |
| 05 | `05-wiring-smoke.md` | proxy wakes on no-host; `main` wires waker + middleware; given fakeupstream/smoke/example; README | `make smoke` |

## For the owner

`tools/run-plan.sh docs/plans/v2` from a clean checkout on `master`.

## For the reviewer: after task 05

1. Five task commits with the trailer; given files byte-identical; protected files untouched.
2. `make gate`, `make smoke`.
3. Probe: a `/props` that returns 200 with a huge body (bounded read); a MAC with an unusual
   separator in config; `identity = "tailscale"` on a host where `tailscale` is not on PATH
   (must log and refuse the gated routes, never allow); two routes, one gated one open, from
   the same peer; a wake target whose broadcast address is unroutable (503 within `wait`, no
   hang); the guard with a body of exactly `MaxBody`.
4. Findings under "Reviews" in `docs/implementer-log.md`, by fault.

## Changes during the run

- 2026-09-25, task 01: the new `/props` poll lands on the v1 fake upstream's `/` catch-all, which
  counts hits, so two v1 proxy tests with exact hit counts failed. Ornith implemented the task
  correctly, did not touch the protected file, and stopped with a `stopped` row — exactly the
  procedure. Owner's fault (T19 once more: a new task changed what an earlier given file
  measures, and the pre-handover walk missed it). `helpers_test.go` is now a v2 given file that
  answers `/props` without counting it; resumed.
- 2026-09-25, task 02: my `TestStickyLeaseSurvivesGrowthUntilItDoesNotFit` "grew" the conversation
  by enlarging the *first user message*, which by the fingerprint spec makes it a different
  conversation — so the test demanded `reused` for a new key. Ornith diagnosed it exactly ("turn
  2's fp differs from turn 1's, yet the test expects reuse") and the session ended on a
  malformed tool call. Test fault (mine): later turns are now appended after the first user
  message. Resumed from the working tree.
- 2026-09-25, learned from titan's router (llama-server b10964) while v2 ran: in router mode a
  plain `GET /props` answers `n_ctx: 0` (`role: router`), and `GET /props?model=X` **autoloads X**
  when `models_autoload` is on — the same trap as `/slots?model=X`. Task 01's poller therefore
  learns nothing on a real router and the guard stays inert there. Follow-up for v2.1: query
  `/props?model=X` only for models `/v1/models` lists as loaded, never for others. Not a defect
  in what the tasks asked for; a gap in what the owner knew when writing them.
- 2026-09-25, task 05, first session: ended after 12 seconds. It misspelled the repository path
  (`/home/kyle/src/crossar/Makefile`), the sandbox refused the out-of-repository read, and it
  ended its turn — the sixth refusal-ending tonight, this one triggered by its own typo. Model
  fault; no change to the task. Restarted.
- 2026-09-25, task 05, second session (30 min in, wiring written, smoke check 3 failing): the given
  `tools/smoke.sh` passed a 300 KB prompt as one `curl -d` argument, which Linux caps at 128 KiB
  per argv element, so check 3 could never pass. Test fault (mine): the body now goes through a
  file (`-d @file`). Ornith diagnosed it correctly. Resumed from the working tree with the
  corrected script.
- 2026-09-25, task 05, third session: `TestParallelAndQueue` (v1 given `limiter_test.go`) failed
  once under full-suite `-race` load with `after releases: inflight 1 queued 0`. Test fault
  (mine): the third acquirer sent its result before its deferred release ran, so the final
  count check could observe one slot still held. The given file now releases before reporting.
  Ornith found it and measured the flake rate rather than editing the protected file.