docs: lock remote delegation contract and WS8 tracking

2026-05-02 11:29:49 +01:00 · 2026-02-13 22:05:50 +00:00
parent bf2fff44b8
commit 186a019b3b
28 changed files with 2835 additions and 16 deletions
--- a/documentation/short-term/coordination/ad_hoc_ticket_queue.md
+++ b/documentation/short-term/coordination/ad_hoc_ticket_queue.md
@@ -0,0 +1,33 @@
+# Ad-hoc Ticket Queue
+
+Use this queue when user/operator approves ticket tracking for ad-hoc
+requests.
+
+## Ticket ID Format
+
+- `ADHOC-YYYYMMDD-<NN>`
+- example: `ADHOC-20260212-01`
+
+## Status Values
+
+- `open`
+- `in_progress`
+- `blocked`
+- `done`
+- `declined` (used only when user explicitly declines tracking after
+  suggestion)
+
+## Queue
+
+| Ticket ID | Requested UTC | Requested By | Scope Summary | Linked Goal/WS | Owner | Status | Next Action | Evidence |
+|---|---|---|---|---|---|---|---|---|
+| ADHOC-20260212-01 | 2026-02-12 18:30 UTC | operator | Establish ad-hoc ticket reflex and replan handling protocol | GOAL-001/governance | arch:codex | done | monitor adoption in future sessions | `documentation/short-term/README.md`, `documentation/short-term/coordination/workstream_board.md`, `documentation/short-term/coordination/handoff_log.md` |
+| ADHOC-20260212-02 | 2026-02-12 20:04 UTC | operator | Standardize GitLab credential home + secure propagation contract for future agent bootstrap | GOAL-001/WS3-WS7 | arch:codex | done | execute ADHOC-20260212-03 remote/repo bootstrap against standardized credential contract | `AGENTS.md`, `documentation/short-term/README.md`, `documentation/short-term/active/GOAL-001-lxd-codex-hardware-ci.md`, `documentation/short-term/coordination/handoff_log.md`, `/workspaces/codex-infra-agent/AGENTS.md` |
+| ADHOC-20260212-03 | 2026-02-12 20:04 UTC | operator | Push new Codex agent repos to GitLab and define bootstrap checkout flow against those remotes | GOAL-001/WS3-WS7 | arch:codex | done | proceed with GOAL-001 role assignment/delegation gates for WS4+ using published remotes and bootstrap contract | `documentation/short-term/README.md`, `documentation/short-term/active/GOAL-001-lxd-codex-hardware-ci.md`, `documentation/short-term/coordination/handoff_log.md`, `/workspaces/codex-infra-agent/README.md`, `/workspaces/codex-runner-agent/README.md` |
+
+## Usage Rules
+
+1. Agent should ask user if ad-hoc request should be tracked.
+2. If user says `yes`, create/update a row here before major execution.
+3. If user says `no`, do not create a ticket row; log
+   `ticket_tracking=declined` in handoff instead.
--- a/documentation/short-term/coordination/delegations/GOAL-001_WS8_blocker_runner_push_retry_danger_packet.md
+++ b/documentation/short-term/coordination/delegations/GOAL-001_WS8_blocker_runner_push_retry_danger_packet.md
@@ -0,0 +1,51 @@
+# GOAL-001 / WS8 Blocker Packet: Push Retry (danger-full-access) (runner:codex)
+
+Purpose: retry pushing the runner repo local WS8 commits to origin from
+the runner VM **outside the restricted sandbox**.
+
+Notes:
+- Previous attempts ran under a restricted execution environment where:
+  - `sudo` was blocked by `no new privileges`
+  - network reachability tests failed
+- This retry must be executed with `codex exec --sandbox danger-full-access`
+  so the agent can access the VM’s real network and privileges.
+
+## Tasks
+
+Completion rule:
+- this blocker is not cleared until the runner repo changes are pushed
+  to `origin/main` and the pushed commit SHA is reported.
+
+1. Confirm network + DNS from the runner VM (evidence):
+   - `getent hosts git.lecsys.net || true`
+   - `ping -c 1 -W 1 git.lecsys.net || true`
+   - `curl -fsS http://git.lecsys.net/ >/dev/null && echo ok_http || echo fail_http`
+   - `git ls-remote http://git.lecsys.net/runner/runner-agent.git HEAD`
+2. Reconcile with `origin/main` before pushing (avoid unsafe force):
+   - `git -C /home/runner/workspaces/codex-runner-agent fetch origin`
+   - `git -C /home/runner/workspaces/codex-runner-agent status --porcelain`
+   - `git -C /home/runner/workspaces/codex-runner-agent log --oneline -n 15`
+   - `git -C /home/runner/workspaces/codex-runner-agent log --oneline --decorate origin/main..HEAD || true`
+   - `git -C /home/runner/workspaces/codex-runner-agent log --oneline --decorate HEAD..origin/main || true`
+   - If `HEAD..origin/main` is non-empty, prefer `git pull --rebase` and
+     re-run the checks above.
+   - Do not use `--force` unless explicitly required and safe; if it is
+     required, prefer `--force-with-lease` and record the justification
+     + before/after SHAs in evidence.
+3. Push all local commits on `main`:
+   - `git -C /home/runner/workspaces/codex-runner-agent status --porcelain`
+   - `git -C /home/runner/workspaces/codex-runner-agent log --oneline -n 10`
+   - `git -C /home/runner/workspaces/codex-runner-agent push origin main`
+   - if non-interactive auth is required, use the role PAT contract
+     (`runner.env`) and a PAT-backed push method; do not paste secrets
+     into logs
+4. Evidence + coordination:
+   - write `documentation/evidence/runner_ws8_push_retry_<timestamp>.log`
+     capturing the above command outputs and push result
+   - append a runner handoff line with:
+     - `context=runner-live`, `action_type=execute`
+     - pushed commit SHA range and evidence path
+
+## Completion
+
+- `git push origin main` succeeds and commits appear on `origin/main`
--- a/documentation/short-term/coordination/delegations/GOAL-001_WS8_blocker_runner_push_unblock_packet.md
+++ b/documentation/short-term/coordination/delegations/GOAL-001_WS8_blocker_runner_push_unblock_packet.md
@@ -0,0 +1,54 @@
+# GOAL-001 / WS8 Blocker Packet: Unblock Runner Push (runner:codex)
+
+Objective: unblock `git push origin main` from the runner VM so WS8
+topology work can be pushed and reported by commit SHA.
+
+This is not a separate workstream from WS8; it is a WS8 blocker-clearing
+packet.
+
+Context (from arch side):
+- `git.lecsys.net` resolves to `192.168.10.75` from the arch environment
+- runner VM error was: `Could not resolve host: git.lecsys.net`
+
+## Tasks (runner VM)
+
+Completion rule:
+- this blocker is not cleared until the runner repo changes are pushed
+  to `origin/main` and the pushed commit SHA is reported.
+
+1. Capture DNS diagnostics (evidence):
+   - `getent hosts git.lecsys.net || true`
+   - `cat /etc/resolv.conf || true`
+   - `ip -4 addr && ip route`
+2. Attempt to reach GitLab by IP (evidence):
+   - `curl -fsS http://192.168.10.75/ >/dev/null && echo ok_ip_http || echo fail_ip_http`
+3. Fix name resolution, preferring least-invasive:
+   - If `getent hosts git.lecsys.net` fails, try adding a host entry:
+     - idempotent edit: only add if missing
+     - line: `192.168.10.75 git.lecsys.net`
+     - command suggestion:
+       - `sudo sh -c 'grep -q \"^192\\.168\\.10\\.75[[:space:]]\\+git\\.lecsys\\.net$\" /etc/hosts || echo \"192.168.10.75 git.lecsys.net\" >> /etc/hosts'`
+   - If `sudo` is unavailable/non-functional:
+     - stop and report blocker `operator_required=yes` and recommend
+       delegating to `infra` to fix runner VM DNS.
+4. Verify name resolution works:
+   - `getent hosts git.lecsys.net`
+   - `curl -fsS http://git.lecsys.net/ >/dev/null && echo ok_name_http || echo fail_name_http`
+5. Push runner repo commits:
+   - `git -C /home/runner/workspaces/codex-runner-agent status --porcelain`
+   - `git -C /home/runner/workspaces/codex-runner-agent log --oneline -n 5`
+   - `git -C /home/runner/workspaces/codex-runner-agent push origin main`
+   - if non-interactive auth is required, use the role PAT contract
+     (`runner.env`) and a PAT-backed push method; do not paste secrets
+     into logs
+6. Evidence + coordination:
+   - write one evidence log capturing key outputs:
+     - `documentation/evidence/runner_ws8_push_unblock_<timestamp>.log`
+   - append runner handoff line:
+     - `context=runner-live`, `action_type=execute`
+     - include pushed commit SHA(s) and the evidence path
+
+## Completion Criteria
+
+- `git push origin main` succeeds from runner VM
+- runner handoff log includes the push success and evidence path
--- a/documentation/short-term/coordination/delegations/GOAL-001_WS8_infra_blockers_packet.md
+++ b/documentation/short-term/coordination/delegations/GOAL-001_WS8_infra_blockers_packet.md
@@ -0,0 +1,52 @@
+# GOAL-001 / WS8 Infra Blockers Packet (infra:codex)
+
+Goal: unblock `GOAL-001/WS8` by fixing infra-scope dependencies for the
+runner VM:
+
+- pass through at least 2 real USB serial devices so runner sees stable
+  `/dev/serial/by-id/*` identities
+- ensure runner VM can resolve and reach `git.lecsys.net` (DNS/routing)
+
+This is a blocker-clearing packet for WS8, not a separate workstream.
+
+Hard rules:
+- execute only in infra scope (host/LXD/VM/networking). Do not clone or
+  edit the product repo (`squeezelite-esp32`).
+- prefer least-invasive, reversible fixes; capture evidence.
+
+## Deliverables (infra repo)
+
+1. Evidence log (commit this) capturing:
+   - current runner VM network/DNS status relevant to `git.lecsys.net`
+   - USB passthrough configuration and the resulting `/dev/serial/by-id`
+     view inside the runner VM
+2. A short infra handoff entry (`context=infra-live`) summarizing:
+   - what changed
+   - whether runner VM can now push to GitLab
+   - whether runner VM now sees >=2 `/dev/serial/by-id/*` devices
+
+## Tasks (infra)
+
+1. Runner VM reachability for GitLab (evidence):
+   - verify runner VM can resolve and reach `git.lecsys.net`
+     (DNS + routing).
+   - if name resolution is broken, fix it at the correct layer
+     (VM DNS config, LXD network config, host resolver/DHCP), preferring
+     reversible changes.
+2. USB passthrough (evidence):
+   - identify at least 2 target USB serial devices on the host
+   - configure passthrough into the runner VM
+   - verify inside the runner VM that `/dev/serial/by-id/*` contains
+     stable identities for both devices
+
+## Evidence naming
+
+- `documentation/evidence/infra_ws8_blockers_<timestamp>.log`
+
+## Completion criteria
+
+- runner VM can resolve/reach `git.lecsys.net` (or infra reports the
+  remaining hard blocker and whether `operator_required=yes`)
+- runner VM sees >=2 serial devices with stable `/dev/serial/by-id/*`
+  identities
+
--- a/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_closeout_continue_packet.md
+++ b/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_closeout_continue_packet.md
@@ -0,0 +1,39 @@
+# GOAL-001 / WS8 Runner Closeout Continue Packet (runner:codex)
+
+thread_ref=WS8-CLOSE-20260213A
+
+Use this only if the main closeout packet was interrupted mid-run.
+
+Goal: finish the remaining closeout steps, commit evidence/coordination,
+and push to `origin/main` using a PAT-backed non-interactive method.
+
+Hard rules:
+- execute inside runner VM repo only:
+  - `/home/runner/workspaces/codex-runner-agent`
+- do not commit `config/hut_slots.json`
+
+## Tasks
+
+1. Validate slot resolution:
+   - `p1=$(scripts/hut_slot_resolve.sh hut-01); test -e "$p1"`
+   - `p2=$(scripts/hut_slot_resolve.sh hut-02); test -e "$p2"`
+   - record `hut-01` and `hut-02` by-id strings in the handoff summary
+2. Lock selftest evidence (commit this):
+   - `scripts/hut_lock_selftest.sh | tee documentation/evidence/runner_hil_topo_lock_selftest_<timestamp>.log`
+3. Update runner coordination:
+   - set `HIL-TOPO-001` to `done` with evidence paths
+   - fix stale WS8/push row (credentials are now configured and pushes work)
+   - append runner handoff log entry:
+     - `context=runner-live`, `action_type=execute`, `operator_required=no`
+     - `thread_ref=...`
+     - evidence paths
+     - next action: `POWER-CTL-001`
+4. Commit + push:
+   - stage evidence + coordination only
+   - commit (small message)
+   - push via `/home/runner/.local/bin/gitlab_push_origin_main.sh`
+5. Report back:
+   - pushed commit SHA
+   - evidence paths
+   - selected hut-01/hut-02 by-id identities
+
--- a/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_closeout_packet.md
+++ b/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_closeout_packet.md
@@ -0,0 +1,60 @@
+# GOAL-001 / WS8 Runner Closeout Packet (runner:codex)
+
+thread_ref=WS8-CLOSE-20260213A
+
+Goal: bring `GOAL-001/WS8` to completion by finishing runner workstream
+`HIL-TOPO-001` with real slot identities (>=2 `/dev/serial/by-id/*`),
+updating runner coordination, and pushing the resulting commit(s) to
+`origin/main`.
+
+Hard rules:
+- execute inside runner VM repo only:
+  - `/home/runner/workspaces/codex-runner-agent`
+- do not commit local slot mapping file:
+  - `config/hut_slots.json` must remain ignored
+- completion requires:
+  - evidence committed, coordination updated, and a pushed SHA on
+    `origin/main` (local-only progress does not count)
+
+## Tasks
+
+1. Verify device count:
+   - list `/dev/serial/by-id/*`
+   - if fewer than 2 entries exist: stop and report `blocked` with
+     `by_id_count=<n>` and the exact missing dependency.
+2. Inventory evidence (commit this):
+   - run:
+     - `scripts/hut_inventory.sh | tee documentation/evidence/runner_hil_topo_inventory_<timestamp>.log`
+3. Slot mapping (local-only, do not commit):
+   - update `config/hut_slots.json` to map:
+     - `hut-01` -> one stable `/dev/serial/by-id/*`
+     - `hut-02` -> a different stable `/dev/serial/by-id/*`
+   - validate:
+     - `scripts/hut_slot_resolve.sh hut-01` resolves and target exists
+     - `scripts/hut_slot_resolve.sh hut-02` resolves and target exists
+4. Lock evidence (commit this):
+   - run:
+     - `scripts/hut_lock_selftest.sh | tee documentation/evidence/runner_hil_topo_lock_selftest_<timestamp>.log`
+5. Runner coordination:
+   - update `documentation/coordination/workstream_board.md`:
+     - set `HIL-TOPO-001` to `done` once the above is satisfied
+     - ensure any stale WS8/push rows reflect current state (push is no
+       longer blocked if PAT is configured)
+   - append `documentation/coordination/handoff_log.md` entry with:
+     - `context=runner-live`, `action_type=execute`, `operator_required=no`
+     - `thread_ref=...`
+     - evidence paths
+     - pushed SHA (after push)
+     - next action: `POWER-CTL-001`
+6. Commit + push:
+   - stage only tracked changes (evidence + coordination), not
+     `config/hut_slots.json`
+   - commit with a small message (WS8 closeout)
+   - push to `origin/main` using a PAT-backed non-interactive method
+     (do not paste secrets into logs). If available, use:
+     - `/home/runner/.local/bin/gitlab_push_origin_main.sh`
+7. Report back to arch:
+   - pushed commit SHA
+   - evidence paths
+   - by-id identities chosen for `hut-01` and `hut-02`
+
--- a/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_handshake_push_packet.md
+++ b/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_handshake_push_packet.md
@@ -0,0 +1,59 @@
+# GOAL-001 / WS8 Runner Handshake + Push Packet (runner:codex)
+
+thread_ref=WS8-PUSH-20260213A
+
+Goal: drive WS8 to a pushed state (commit SHA visible on `origin/main`)
+and report back with evidence. This packet is safe to run repeatedly.
+
+Hard rules:
+- execute inside runner VM repo only:
+  - `/home/runner/workspaces/codex-runner-agent`
+- do not leak secrets into logs, repo files, or handoff summaries
+- completion requires a pushed SHA on `origin/main` (not just local commits)
+
+## Tasks
+
+1. Handshake (record in runner handoff summary):
+   - `thread_ref=...`
+   - current `HEAD` SHA and branch
+   - what you believe is the best next step and why
+2. Collect non-secret diagnostics (evidence log):
+   - `getent hosts git.lecsys.net || true`
+   - `curl -fsS http://git.lecsys.net/ >/dev/null && echo ok_http || echo fail_http`
+   - `git -C /home/runner/workspaces/codex-runner-agent remote -v`
+   - `git -C /home/runner/workspaces/codex-runner-agent status --porcelain`
+   - `git -C /home/runner/workspaces/codex-runner-agent fetch origin`
+   - `git -C /home/runner/workspaces/codex-runner-agent log --oneline --decorate -n 10`
+   - `git -C /home/runner/workspaces/codex-runner-agent log --oneline --decorate origin/main..HEAD | head -n 50 || true`
+3. Credential gate (do not print secrets):
+   - expected credential file:
+     - `${XDG_CONFIG_HOME:-$HOME/.config}/codex/credentials/gitlab/git.lecsys.net/runner.env`
+   - if missing or `GITLAB_USER`/`GITLAB_PAT` is empty:
+     - create the directory + a template file with correct perms
+       (`0700` dir, `0600` file)
+     - stop and report `operator_required=yes` with the exact path that
+       needs to be filled
+4. Push:
+   - once `runner.env` has non-empty `GITLAB_USER` and `GITLAB_PAT`,
+     push non-interactively without storing credentials in git config.
+   - recommended approach:
+     - use an ephemeral `http.extraheader` basic auth header built in
+       memory and run:
+       - (optional) `git -c http.extraheader="Authorization: Basic <...>" fetch origin`
+       - `git push origin main`
+   - if available, you may use an approved local helper script that
+     performs a PAT-backed push without persisting credentials in git
+     config (for example `/home/runner/.local/bin/gitlab_push_origin_main.sh`)
+5. Evidence + coordination:
+   - write:
+     - `documentation/evidence/runner_ws8_push_handshake_<timestamp>.log`
+   - append a runner handoff log line with:
+     - `context=runner-live`, `action_type=execute`
+     - `thread_ref=...`
+     - pushed SHA(s) (or remaining blocker)
+     - evidence path
+
+## Completion Criteria
+
+- `origin/main` contains the WS8 commits (push succeeded), and runner
+  handoff includes pushed SHA(s) + evidence path.
--- a/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_inventory_refresh_packet.md
+++ b/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_inventory_refresh_packet.md
@@ -0,0 +1,50 @@
+# GOAL-001 / WS8 Runner Packet: Inventory Refresh After USB Passthrough (runner:codex)
+
+thread_ref=WS8-USB-INV-20260213A
+
+Goal: after infra USB passthrough changes, refresh WS8 inventory evidence
+and report whether runner now has >=2 stable `/dev/serial/by-id/*`
+devices for `hut-01` + `hut-02`.
+
+Hard rules:
+- execute inside runner VM repo only:
+  - `/home/runner/workspaces/codex-runner-agent`
+- do not commit local slot mapping file:
+  - `config/hut_slots.json` must remain ignored
+- commit hygiene: if any tracked files are changed (evidence/coordination),
+  commit and push them to `origin/main` from the runner VM and report the
+  pushed SHA; local-only progress does not count.
+
+## Tasks
+
+1. Inventory evidence:
+   - run `scripts/hut_inventory.sh` and capture a new evidence log:
+     - `documentation/evidence/runner_hil_topo_inventory_<timestamp>.log`
+2. Slot mapping status:
+   - if there are >=2 `/dev/serial/by-id/*` entries:
+     - populate local `config/hut_slots.json` with `hut-01` + `hut-02`
+       using stable by-id paths
+     - validate:
+       - `scripts/hut_slot_resolve.sh hut-01`
+       - `scripts/hut_slot_resolve.sh hut-02`
+   - else (only 0 or 1 device visible):
+     - do not fake identities
+     - record explicit blocker: "need >=2 serial devices passed through"
+3. Coordination:
+   - update runner `documentation/coordination/workstream_board.md`:
+     - keep `HIL-TOPO-001` status `blocked` until >=2 devices exist
+     - reference the new inventory evidence log
+   - append runner `documentation/coordination/handoff_log.md` entry with:
+     - `context=runner-live`, `action_type=execute`, `operator_required=no`
+     - `thread_ref=...`
+     - inventory evidence path
+     - current device count observed
+     - next action (infra/operator attach + pass through a 2nd device if missing)
+4. Commit + push:
+   - commit and push the new evidence + coordination updates (not `hut_slots.json`)
+   - report pushed commit SHA
+
+## Completion
+
+- new inventory evidence is committed+pushed, and runner coordination reflects
+  current device count and blocker/next action accurately.
--- a/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_packet.md
+++ b/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_packet.md
@@ -0,0 +1,65 @@
+# GOAL-001 / WS8 Delegation Packet (runner:codex)
+
+Scope: implement `GOAL-001/WS8` by completing runner workstream
+`HIL-TOPO-001` (multi-HUT topology and slot mapping).
+
+Hard rule: execute inside the runner VM runner repo only
+(`/home/runner/workspaces/codex-runner-agent`). Do not rely on any local
+`/workspaces/codex-runner-agent` copy on the dev machine.
+
+Completion rule (commit hygiene):
+- WS8 is not complete until changes are committed and pushed to
+  `origin/main` from the runner VM, and the pushed commit SHA is
+  reported back. Local-only progress does not count.
+
+## Deliverables (runner repo)
+
+1. Slot mapping schema + example:
+   - `config/hut_slots.example.json`
+   - `.gitignore` that ignores `config/hut_slots.json`
+2. Inventory + resolver:
+   - `scripts/hut_inventory.sh` (captures `/dev/serial/by-id`)
+   - `scripts/hut_slot_resolve.sh hut-XX` (reads `config/hut_slots.json`)
+3. Per-slot locking:
+   - `scripts/hut_lock_exec.sh hut-XX -- <cmd...>` using `flock`
+   - `scripts/hut_lock_selftest.sh` proving:
+     - same-slot serializes
+     - different-slots can run concurrently
+4. Topology doc:
+   - `documentation/hil_topology.md`
+5. Evidence logs (commit these):
+   - `documentation/evidence/runner_hil_topo_inventory_<timestamp>.log`
+   - `documentation/evidence/runner_hil_topo_lock_selftest_<timestamp>.log`
+6. Local config (do not commit):
+   - `config/hut_slots.json` with at least `hut-01` + `hut-02` mapping to
+     stable `/dev/serial/by-id/...` symlinks.
+
+## Execution Checklist (runner VM)
+
+1. Confirm repo is clean:
+   - `git -C /home/runner/workspaces/codex-runner-agent status --porcelain`
+2. Implement deliverables above; ensure scripts are executable.
+3. Run:
+   - `scripts/hut_inventory.sh | tee documentation/evidence/runner_hil_topo_inventory_<timestamp>.log`
+   - `scripts/hut_lock_selftest.sh | tee documentation/evidence/runner_hil_topo_lock_selftest_<timestamp>.log`
+4. Populate local slot mapping (ignored file):
+   - copy `config/hut_slots.example.json` -> `config/hut_slots.json`
+   - replace `serial_by_id` with real paths from `/dev/serial/by-id`
+   - validate:
+     - `scripts/hut_slot_resolve.sh hut-01`
+     - `scripts/hut_slot_resolve.sh hut-02`
+5. Commit + push all tracked changes (do not commit `config/hut_slots.json`):
+   - include commit SHA in runner handoff entry
+6. Update runner coordination:
+   - `documentation/coordination/workstream_board.md`: set `HIL-TOPO-001`
+     to `done` with evidence paths
+   - `documentation/coordination/handoff_log.md`: append one line with:
+     - `context=runner-live`, `action_type=execute`, `operator_required=no`
+     - commit SHA(s), evidence paths, and next action (`POWER-CTL-001`)
+
+## Report Back (to arch)
+
+Return:
+- pushed commit SHA
+- evidence paths
+- summary of discovered slots (`hut-01`, `hut-02`) and their `/dev/serial/by-id` identities
--- a/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_pushfix_packet.md
+++ b/documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_pushfix_packet.md
@@ -0,0 +1,24 @@
+# GOAL-001 / WS8 Delegation Packet: Runner Push Fix (shim) (runner:codex)
+
+This file exists to resolve a filename collision/ambiguity in WS8
+delegation references.
+
+Use the purpose-specific WS8 packets instead:
+
+- Primary WS8 implementation:
+  - `GOAL-001_WS8_runner_packet.md`
+- WS8 push blocker (DNS/name resolution + push):
+  - `GOAL-001_WS8_blocker_runner_push_unblock_packet.md`
+- WS8 push retry requiring real VM network/privileges:
+  - `GOAL-001_WS8_blocker_runner_push_retry_danger_packet.md`
+
+If you are the runner role and you received this shim:
+
+1. Pick the correct packet above based on current blocker symptoms.
+2. Execute it inside the runner VM repo:
+   - `/home/runner/workspaces/codex-runner-agent`
+3. In the runner handoff summary, include:
+   - `thread_ref=<value if provided by arch>`
+   - pushed commit SHA(s) (or remaining blocker)
+   - evidence path(s)
+
--- a/documentation/short-term/coordination/delegations/README.md
+++ b/documentation/short-term/coordination/delegations/README.md
@@ -0,0 +1,21 @@
+# Delegation Packets
+
+Packets in this folder are prompts meant to be fed to `codex exec -` on
+remote role machines (typically via SSH transport).
+
+Naming conventions:
+- `GOAL-001_WS8_runner_packet.md`: primary WS8 implementation packet
+- `GOAL-001_WS8_runner_pushfix_packet.md`: shim for a past filename
+  collision; points at the real WS8 push blocker packets
+- `GOAL-001_WS8_infra_blockers_packet.md`: infra-scope packet for WS8
+  blockers (runner VM DNS/routing, USB passthrough)
+- `GOAL-001_WS8_runner_handshake_push_packet.md`: runner packet to
+  handshake, verify credentials gate, and push WS8 commits with evidence
+- `GOAL-001_WS8_runner_inventory_refresh_packet.md`: runner packet to
+  refresh inventory evidence after USB passthrough and report device count
+- `GOAL-001_WS8_runner_closeout_packet.md`: runner packet to finish WS8
+  (inventory + slot mapping validation + lock selftest), commit, and push
+- `GOAL-001_WS8_runner_closeout_continue_packet.md`: runner packet to
+  continue closeout if an earlier closeout run was interrupted
+- `GOAL-001_WS8_blocker_*.md`: WS8 blocker-clearing packets (do not
+  represent separate workstreams)
--- a/documentation/short-term/coordination/handoff_log.md
+++ b/documentation/short-term/coordination/handoff_log.md
@@ -0,0 +1,68 @@
+# Handoff Log
+
+Use this log for short handoffs between agents/sessions.
+
+Format:
+
+```text
+YYYY-MM-DD HH:MM UTC | agent/session | goal/workstream | context | action_type | operator_required | summary | next action | blocker (optional)
+```
+
+Field values:
+
+- `context`: `arch-local` | `infra-live` | `runner-live`
+- `action_type`: `scaffold` | `delegate` | `execute` | `replan`
+- `operator_required`: `yes` | `no`
+
+Ticket tracking convention:
+
+- If request is tracked: include `ticket_id=<id>` in summary.
+- If user declines tracking: include `ticket_tracking=declined` in
+  summary.
+
+Legacy note:
+- Older lines without these fields are valid historical entries.
+- New entries must include all fields.
+
+Entries:
+
+```text
+2026-02-13 22:04 UTC | arch:codex | GOAL-001/WS8 | arch-local | execute | no | Runner VM now has >=2 stable `/dev/serial/by-id/*` devices (inventory evidence `runner_hil_topo_inventory_20260213_215705_utc.log`) and lock selftest evidence `runner_hil_topo_lock_selftest_20260213_215839_utc.log`; runner repo `main` has new closeout commits (`2ebd4da`, `c03a9a0`) but push/fetch to `git.lecsys.net` is blocked by HTTP Basic access denied using current runner PAT (`runner.env`) | operator: refresh runner PAT with `write_repository` and update runner VM `runner.env`; runner: run `~/.local/bin/gitlab_push_origin_main.sh` and report pushed SHA; then mark WS8 `done` | DEP:valid runner GitLab PAT
+2026-02-13 21:13 UTC | arch:codex | GOAL-001/WS8 | arch-local | execute | no | Cleared infra/runner execution path: fixed infra credential perms on LXD host (codexsvc now in `lxd` group), enabled USB passthrough for the first CP210x device (vendorid=10c4 productid=ea60), restarted runner VM and installed Ubuntu kernel 6.14.0-36 on runner so `/dev/serial/by-id/*` maps to `/dev/ttyUSB0`; runner produced inventory evidence `runner_hil_topo_inventory_20260213_211129_utc.log` showing by_id_count=1 and pushed refresh commit `runner/runner-agent@ce16c27` | infra/operator: attach + pass through a 2nd serial device; runner: rerun inventory + complete hut-01/hut-02 local mapping + lock selftest evidence if needed; then mark WS8 done | DEP:2nd USB serial device availability
+2026-02-13 20:26 UTC | arch:codex | GOAL-001/WS8 | arch-local | execute | no | Runner GitLab credentials updated (runner.env now has non-empty PAT) and runner successfully pushed WS8 commits to GitLab: `runner/runner-agent` `main` advanced `6255908..bbad5d5` (push output captured on runner). WS8 remains blocked only on infra USB passthrough (runner VM still lacks `/dev/serial/by-id`) | infra/operator: pass through >=2 serial devices; runner: rerun inventory + complete local slot mapping and evidence | DEP:infra USB passthrough + DEP:operator LXD permissions (codexsvc not in lxd group)
+2026-02-13 14:20 UTC | arch:codex | GOAL-001/WS8 | arch-local | replan | yes | Security hygiene: operator pasted GitLab account passwords into a chat transcript; treat them as compromised. Do not use or re-share; rotate passwords and revoke/rotate tokens/sessions as appropriate. WS8 remains blocked on provisioning a runner GitLab PAT in `/home/runner/.config/codex/credentials/gitlab/git.lecsys.net/runner.env` (no secrets in logs) | operator: rotate leaked GitLab passwords; create runner PAT and populate runner.env; rerun WS8 push packet | DEP:operator credential rotation + PAT provisioning
+2026-02-13 14:12 UTC | arch:codex | GOAL-001/WS8 | arch-local | execute | yes | Took ownership of WS8 closure: removed local role-repo collisions (repos quarantined), added infra blocker packet, and executed runner remote-codex handshake/push gate; runner VM resolves `git.lecsys.net` and produced evidence `/home/runner/workspaces/codex-runner-agent/documentation/evidence/runner_ws8_push_handshake_20260213T141012Z.log`, but push remains blocked because `/home/runner/.config/codex/credentials/gitlab/git.lecsys.net/runner.env` exists with empty `GITLAB_USER`/`GITLAB_PAT`; runner VM still has no `/dev/serial/by-id` (USB passthrough not done). Local runner `main` is now ahead in range `33ef496`..`bbad5d5` | operator: fill runner PAT file (no secrets logged); operator/infra: enable USB passthrough (>=2 serial devices) to runner VM; then rerun `GOAL-001_WS8_runner_handshake_push_packet.md` on runner and `git push origin main` | DEP:operator credentials + DEP:infra USB passthrough (codexsvc not in lxd group)
+2026-02-13 13:51 UTC | arch:codex | governance/ownership | arch-local | replan | no | Refined closure contract: `arch:codex` may stop early only when a pivot is required or a problem-solving loop is stalled, and must first record `replan` (pivot) or explicit `blocked` (stall) with concrete next actions and required new information | apply this exception consistently without weakening closure accountability | none
+2026-02-13 13:48 UTC | arch:codex | governance/ownership | arch-local | replan | no | Locked ownership closure rule: when `arch:codex` is asked to take ownership, it must drive the task/workstream to successful closure (`done`) or explicit `blocked` with concrete blockers/owners/operator gate/next action; "prepared a packet" is not closure | apply closure rule to GOAL-001/WS8 and future remote-role workstreams | none
+2026-02-13 13:30 UTC | arch:codex | GOAL-001/WS8 | arch-local | execute | no | Quarantined local non-authoritative role repo clones to prevent collisions: moved `/workspaces/codex-infra-agent` and `/workspaces/codex-runner-agent` into `/workspaces/.quarantine_remote_role_repos/20260213T132921Z/` (also stored tar snapshots); added `GOAL-001_WS8_infra_blockers_packet.md` for infra-scope VM DNS/USB passthrough and tightened runner push-retry packet to avoid unsafe force pushes | delegate infra packet to `infra:codex`, then delegate push unblock/retry to `runner:codex`; once pushed, resume WS8 inventory + slot mapping | none
+2026-02-13 13:12 UTC | arch:codex | GOAL-001/WS12 | arch-local | replan | no | Added new workstream WS12 to evaluate Codex App Server as a structured alternative to SSH transport for remote-role prompting, targeting better parallel multi-step threading and context reuse; current SSH remains bootstrap/break-glass transport | implement WS12: document App Server option and define minimal prototype plan + role boundaries | none
+2026-02-13 04:45 UTC | arch:codex | GOAL-001/WS8 | arch-local | execute | yes | executor=remote_codex Prompted `runner:codex` on runner VM to implement WS8/HIL-TOPO-001 and attempt push; runner created local commits `33ef496`..`1d1e412` (topology + evidence + coordination) and produced auth diagnostics evidence `/home/runner/workspaces/codex-runner-agent/documentation/evidence/runner_ws8_push_retry_20260213T044210Z.log`, but push remains blocked due to missing non-interactive GitLab credentials on runner VM (`runner.env` absent) and no `/dev/serial/by-id` HUT passthrough yet | operator: provision runner PAT file (`runner.env`) on runner VM; infra: pass through at least 2 USB serial devices; runner: `git push origin main` and re-run inventory to produce real slot mapping | DEP:operator credential provisioning + DEP:infra USB passthrough
+2026-02-13 04:28 UTC | codex | GOAL-001/WS11 | arch-local | replan | no | Added GOAL-001 WS11 to explicitly track long-run grounding of the remote delegation mechanism (credential storage + transport + `executor=remote_codex` prompting) so future tickets can reliably maintain the `arch:codex` <-> `runner:codex` link | implement WS11 by promoting the stable invocation contract into `documentation/agents/` (no secrets) and keeping the short-term version as a working draft | none
+2026-02-13 04:09 UTC | arch:codex | GOAL-001/WS8 | arch-local | replan | no | Strict boundary enforced: `arch` must not execute/modify runner repo locally; all runner workstreams execute via `runner:codex` on runner VM and report back by commit SHA + evidence; any local `/workspaces/codex-runner-agent` copy is non-authoritative | delegate WS8 packet to `runner:codex` and await runner-side implementation evidence | none
+2026-02-13 04:09 UTC | arch:codex | GOAL-001/WS8 | arch-local | delegate | no | executor=remote_codex Delegate WS8 to `runner:codex` using `documentation/short-term/coordination/delegations/GOAL-001_WS8_runner_packet.md` (HIL-TOPO-001: topology + slot mapping + `flock` locks + evidence); commit+push and report commit SHA + evidence paths back to arch | runner: execute delegation packet and append runner-context handoff entry with commit SHA | none
+2026-02-12 22:31 UTC | runner:codex | GOAL-001/WS7 | runner-live | execute | no | executor=ssh_direct Runner repo first commit/push completed from runner VM to GitLab `runner/runner-agent` main: `fed6ce9` (docs commit hygiene contract), `6255908` (WS7 evidence + handoff) | proceed to GOAL-001/WS8 by defining HUT topology/labels and evidence/lock strategy in runner repo | none
+2026-02-12 22:10 UTC | codex | GOAL-001/WS7 | arch-local | execute | no | executor=remote_codex Runner-side Codex completed WS7 bootstrap: cloned runner repo to `/home/runner/workspaces/codex-runner-agent`, captured first heartbeat, and wrote a runner smoke report JSON | proceed to GOAL-001/WS8 by defining HUT topology/labels and evidence/lock strategy in runner repo | none
+2026-02-12 22:01 UTC | codex | GOAL-001/WS7 | arch-local | delegate | no | executor=remote_codex Delegated WS7 to `runner:codex`: bootstrap runner workspace under `/home/runner/workspaces/codex-runner-agent`, clone runner repo, capture first heartbeat evidence, and append first runner-context handoff entry | run runner-side codex exec for WS7 bootstrap tasks and return evidence paths + next action | none
+2026-02-12 21:42 UTC | codex | GOAL-001/WS6 | arch-local | execute | yes | executor=ssh_direct Operator confirmed Codex login completed on runner VM; WS6 can be marked done and runner ownership can shift to `runner:codex` for remote execution | start GOAL-001/WS7 from runner repo on the runner VM (first heartbeat + first runner-context handoff entry) | none
+2026-02-12 21:34 UTC | codex | GOAL-001/WS6 | arch-local | execute | yes | executor=ssh_direct Installed Node/npm and `codex-cli` on runner VM `codex-runner-01` and verified `codex --version` runs over SSH; interactive login still required | operator: SSH to runner VM and run `codex login`, then report success so WS6 can be marked done and runner ownership can move to `runner:codex` | DEP:operator interactive login
+2026-02-12 21:26 UTC | codex | GOAL-001/WS4-WS5 | arch-local | execute | no | executor=ssh_direct Completed runner VM provisioning (codex-runner-01) and established non-interactive SSH reachability (LAN IP) with evidence captured under `/workspaces/codex-infra-agent/documentation/evidence/` | proceed to GOAL-001/WS6 runner Codex authentication (operator-assisted) using the now-reachable runner VM | none
+2026-02-12 20:45 UTC | codex | GOAL-001/WS4 | arch-local | execute | yes | Ran infra first-heartbeat discovery on LXD host `192.168.10.201` (evidence log captured) but cannot run `lxc` as `codexsvc` due to LXD unix socket permission denied and lack of sudo | operator: add `codexsvc` to `lxd` group (or grant sudo), re-login/refresh session, then retry `lxc list` and proceed with runner VM provisioning | DEP:operator permission fix on LXD host
+2026-02-12 20:26 UTC | codex | GOAL-001/WS4-delegation | arch-local | delegate | no | Delegated GOAL-001 WS4/WS5 ownership to `infra:agent` and advanced infra role activation to `assigned` (pending first heartbeat) | from `/workspaces/codex-infra-agent`, claim `VM-PROV-001` and produce first heartbeat evidence + runner VM spec/SSH identity | none
+2026-02-12 20:19 UTC | codex | GOAL-001/ad-hoc-gitlab-bootstrap | arch-local | execute | no | ticket_id=ADHOC-20260212-03 Created/pushed agent repos to GitLab remotes (`infra/infra-agent`, `runner/runner-agent`) and published bootstrap checkout/verification flow; ADHOC-20260212-03 marked done | continue GOAL-001 by assigning live `infra:<agent-id>` owner and starting WS4 runner VM provisioning with repo bootstrap contract | none
+2026-02-12 20:10 UTC | codex | GOAL-001/ad-hoc-credential-contract | arch-local | execute | no | ticket_id=ADHOC-20260212-02 Standardized GitLab credential-home/auth/verification contract for `git.lecsys.net` across AGENTS + short-term governance docs; unblocked follow-on ticket ADHOC-20260212-03 | execute ADHOC-20260212-03 by configuring/pushing infra + runner repos with documented bootstrap checkout flow | none
+2026-02-12 20:04 UTC | codex | GOAL-001/ad-hoc-intake | arch-local | replan | yes | ticket_id=ADHOC-20260212-02,ADHOC-20260212-03 Tracked user ad-hoc requests for GitLab credential-home standardization and subsequent repo push/bootstrap flow; linked second item as blocked on credential readiness | await operator credential setup details, then execute ADHOC-20260212-02 followed by ADHOC-20260212-03 | DEP:operator credential setup pending
+2026-02-12 18:32 UTC | codex | GOAL-001/governance-ad-hoc | arch-local | replan | no | ticket_id=ADHOC-20260212-01 Added mandatory ad-hoc ticket reflex: agents should suggest ticket tracking on user ad-hoc requests and follow user yes/no decision path across board/template/start-here/AGENTS + queue docs | use ad-hoc queue by default for user-approved tracking requests | none
+2026-02-12 18:30 UTC | codex | GOAL-001/governance-replan | arch-local | replan | no | Added formal course-correction protocol for user-driven reprioritization/easier-path/intermediate-quest changes, including trigger examples and required board/goal/handoff updates | apply this protocol when operator requests sequencing/path adjustments, even without hard prerequisites | none
+2026-02-12 18:16 UTC | codex | GOAL-001/governance | arch-local | scaffold | no | Added anti-confusion governance controls across board/template/startup docs: role activation state machine, concrete-owner gate for remote `in_progress`, mandatory handoff context/action/operator fields, delegation checklist, and role-prefixed evidence convention | use new handoff format for all future entries and update remote role activation states as owners are assigned | none
+2026-02-12 16:55 UTC | codex | GOAL-001/WS3-correction | Clarification: WS3 completion was performed by `arch:codex` as bootstrap scaffolding (creating the infra repo/governance skeleton), not by a live delegated `infra` session; delegation boundary remains intact | assign `infra:<agent-id>` and start WS4 from infra context | WS4 blocked until infra owner assignment
+2026-02-12 16:33 UTC | codex | GOAL-001/WS3 | Completed WS3 by creating dedicated infra repository at `/workspaces/codex-infra-agent`, initialized git repo, added platform-agnostic `AGENTS.md` with discovery-first startup and hard no-product-repo-clone boundary, and added infra coordination board/handoff files | assign an `infra:<agent-id>` owner and execute GOAL-001 WS4 runner VM provisioning | none
+2026-02-12 16:10 UTC | codex | GOAL-001/WS3-planning | Refactored governance to role-based ownership (`arch`/`infra`/`runner`), expanded GOAL-001 with readiness workstreams (infra bootstrap, runner VM provisioning, SSH, auth, runner bootstrap) before hardware topology, and updated board/template/start-here/ci-lane rules accordingly | execute GOAL-001 WS3 by bootstrapping infra repo + AGENTS/board/handoff; then delegate WS4 to infra role | OPERATOR support needed later for runner Codex auth and optional local GitLab onboarding
+2026-02-12 15:26 UTC | codex | GOAL-001/WS2 | Completed WS2: claimed board ownership, documented v1 layer-aware invocation/report contracts, ran Layer1 smoke via `build-scripts/lxd_remote.sh heartbeat`, and published evidence (`test/build/log/lxd_ws2_smoke_20260212.log`, `test/build/log/lxd_ws2_report_20260212.json`) | claim GOAL-001 WS3 and define runner labels, slot identity mapping, and lock routing | none
+2026-02-12 15:25 UTC | codex | GOAL-001/WS2 | Claimed WS2 on board and added concrete v1 contracts in GOAL-001 for layer responsibility, invocation schema, report schema, guardrail defaults, and minimum puppet-layer repo files | run one WS2 smoke job using the new invocation/report fields and attach resulting log + structured report | none
+2026-02-12 15:22 UTC | codex | GOAL-001/WS2 | Clarified GOAL-001 control model: CI lanes vs puppet layers are orthogonal; added explicit Layer 0/1/2 responsibilities, separate-repo portability target, and Layer 1 AGENT discovery-first/no-codebase-edit constraints in goal doc | claim GOAL-001 WS2 on board and draft concrete remote invocation/report schema + layer-specific AGENT skeletons in infra repos | none
+2026-02-12 15:04 UTC | codex | GOAL-001/WS1 | Completed WS1: validated key-based non-interactive SSH to LXD host, added `build-scripts/lxd_remote.sh` wrapper with strict failure semantics, and captured heartbeat evidence in `test/build/log/lxd_ws1_heartbeat_ok_20260212.log` and failure-path evidence in `test/build/log/lxd_ws1_heartbeat_fail_workdir_20260212.log` | claim GOAL-001 WS2 and define remote job invocation/reporting contract | none
+2026-02-12 14:49 UTC | codex | GOAL-002 | Marked GOAL-002 as parked after accidental kickoff; all GOAL-002 workstreams set to blocked with GOAL-001 dependency | resume GOAL-002 once GOAL-001 is implemented and LXD backend is available, then restart WS1 inventory | DEP:GOAL-001 backend unavailable
+2026-02-12 14:46 UTC | codex | GOAL-002/WS1 | Claimed WS1 and executed slot inventory probe; workspace has no visible serial devices (evidence: test/build/log/hut_slot_inventory_20260212.log) | run inventory probe on hardware-attached LXD HIL host and record `hut-XX` -> `/dev/serial/by-id/...` + platform mapping | no HUT serial devices exposed in current session
+2026-02-12 00:00 UTC | codex | GOAL-002/GOAL-003 | Added active goal specs and board workstreams for HUT surfacing and doc lint CI strategy | assign owners and execute WS1 in each goal | none
+2026-02-12 00:00 UTC | bootstrap | GOAL-001 | Goal scaffold created | assign WS owners and start WS1 | none
+```
--- a/documentation/short-term/coordination/workstream_board.md
+++ b/documentation/short-term/coordination/workstream_board.md
@@ -0,0 +1,141 @@
+# Workstream Board
+
+Last updated: 2026-02-13
+
+Use this table as the live status board for active short-term goals.
+
+Mission critical focus:
+- `GOAL-001/WS8` Multi-HUT hardware CI topology (runner lane enablement)
+
+| Goal ID | Workstream | Owner | Status | Blockers | Next Action |
+|---|---|---|---|---|---|
+| GOAL-001 | WS1: Infrastructure SSH + Codex passthrough | arch:codex | done | none | none (completed) |
+| GOAL-001 | WS2: Multi-agent operating model | arch:codex | done | none | none (completed) |
+| GOAL-001 | WS3: Infrastructure agent bootstrap | arch:codex | done | none | none (completed) |
+| GOAL-001 | WS4: Runner VM provisioning | infra:agent | done | none | Evidence recorded in infra repo (VM-PROV-001). |
+| GOAL-001 | WS5: Runner SSH reachability | infra:agent | done | none | Evidence recorded in infra repo (RUNNER-SSH-001). |
+| GOAL-001 | WS6: Runner Codex authentication | arch:codex | done | none | Operator completed `codex login` on runner VM; ready to activate `runner:codex` execution |
+| GOAL-001 | WS7: Runner agent bootstrap | runner:codex | done | none | Evidence: `/home/runner/workspaces/codex-runner-agent/documentation/evidence/runner_first_heartbeat_20260212_2209_utc.log`, `/home/runner/workspaces/codex-runner-agent/documentation/evidence/runner_smoke_report_20260212_2209_utc.json`; GitLab: `runner/runner-agent@fed6ce9`, `runner/runner-agent@6255908` |
+| GOAL-001 | WS8: Multi-HUT hardware CI topology | runner:codex | blocked | MISSION_CRITICAL: runner VM now has >=2 stable `/dev/serial/by-id/*` devices and WS8 closeout commits exist locally (`runner/runner-agent@c03a9a0`), but push/fetch to GitLab is blocked by HTTP auth failure (runner PAT appears invalid or missing `write_repository`) | operator: refresh `runner` PAT with `write_repository` and update runner VM `runner.env`; runner: run `~/.local/bin/gitlab_push_origin_main.sh` to push `main`, then report final pushed SHA and mark WS8 `done` | Runner evidence (local): `/home/runner/workspaces/codex-runner-agent/documentation/evidence/runner_hil_topo_inventory_20260213_215705_utc.log`, `/home/runner/workspaces/codex-runner-agent/documentation/evidence/runner_hil_topo_lock_selftest_20260213_215839_utc.log` |
+| GOAL-001 | WS9: Power-cycle control with Home Assistant relay | runner:codex | blocked | DEP:GOAL-001/WS8 pushed to GitLab and slot mapping completed (hut-01 + hut-02 stable) | After WS8 push unblocked: define lock protocol and HA service contract | - |
+| GOAL-001 | WS10: Parallel branch/agent workflow | arch:codex | pending | none | Define worktree strategy, artifact routing, and branch policy |
+| GOAL-001 | WS11: Long-Run Remote Delegation Grounding | arch:codex | pending | none | Promote remote delegation + credential + transport invocation contract into long-lived docs (`documentation/agents/`) and keep an explicit “arch<->runner link” procedure (no secrets) so future tickets can reliably delegate to `runner:codex` |
+| GOAL-001 | WS12: Codex App Server Transport (evaluate -> prototype -> implement) | arch:codex | pending | none | Create `documentation/agents/remote_transport_lock.md` and run WS12 as a gated workflow; once locked, implement the locked mechanism and keep SSH as break-glass fallback unless retired |
+| GOAL-002 | WS1: HUT slot inventory + identity | unassigned | blocked | DEP:GOAL-001/WS8 runner topology not yet implemented | Resume after GOAL-001 WS8; run slot inventory on runner/HIL host |
+| GOAL-002 | WS2: HW-BOOT-001 execution harness | unassigned | blocked | DEP:GOAL-001/WS8 runner topology not yet implemented | Resume after GOAL-001 WS8; define canonical flash/reboot/monitor flow |
+| GOAL-002 | WS3: Per-slot surfacing runs | unassigned | blocked | DEP:GOAL-001/WS8 runner topology not yet implemented | Resume after GOAL-001 WS8; execute per-slot HW-BOOT-001 |
+| GOAL-002 | WS4: Worklist + matrix sync | unassigned | blocked | DEP:GOAL-001/WS8 runner topology not yet implemented | Resume after GOAL-001 WS8; sync worklist/matrix with slot outcomes |
+| GOAL-003 | WS1: Upstream docs lint gate | unassigned | pending | none | Define required markdown lint scope and failure policy |
+| GOAL-003 | WS2: Local agent gardening loop | unassigned | pending | none | Define agent task contract for docs maintenance runs |
+| GOAL-003 | WS3: Progressive doc discovery | unassigned | pending | none | Ensure agents can discover context without large upfront reads |
+| GOAL-003 | WS4: Lint evidence + handoff format | unassigned | pending | none | Standardize report fields for lint before/after and residuals |
+
+## Status Values
+
+- `pending`: not started
+- `in_progress`: actively being worked
+- `blocked`: waiting on dependency or decision
+- `done`: completed and verified for that workstream (does not by itself mean the parent goal is complete)
+
+## Owner Governance
+
+- Owner format: `<role>:<agent-id>` (examples: `arch:codex`,
+  `infra:tbd`, `runner:tbd`).
+- Role keys:
+  - `arch`: Architecture Agent (engineering/control/governance)
+  - `infra`: Infrastructure Agent (host/container/VM operations)
+  - `runner`: Runner Agent (VM CI/CD + test execution)
+- Governance rules:
+  - Owner values are execution semantics:
+    - `<role>:codex` means a Codex runtime is installed/authenticated in
+      that role environment and is being prompted there.
+    - `<role>:agent` means the `arch:codex` control-plane is acting as a
+      temporary proxy executor for that role (typically via SSH
+      transport). This is allowed only for bootstrap/emergency and must
+      be called out in handoff summaries as `executor=ssh_direct`.
+  - `arch` delegates work; SSH may be used as a transport layer, but
+    direct SSH command execution must not be conflated with prompting a
+    remote Codex runtime.
+  - Ownership implies closure accountability:
+    - when `arch:codex` is the owner (or is explicitly asked to "take
+      ownership"), `arch` must drive the workstream to closure:
+      - `done` with acceptance met and evidence recorded, or
+      - `blocked` with concrete blockers, correct owners, operator gate,
+        and explicit next action(s)
+    - "prepared a packet" is not closure; packets are inputs to closure
+  - Commit hygiene (all roles):
+    - each role Codex runtime (`arch`, `infra`, `runner`) is responsible
+      for commit hygiene in its own role repository
+    - make small commits frequently and push so progress is traceable by
+      commit SHA
+    - include commit SHA(s) in handoff summaries for executed work
+    - avoid batching unrelated changes
+  - `arch` is accountable for coordination quality and status reporting.
+  - `arch` should continuously improve agent efficiency and governance
+    quality when requested or when serious inefficiencies are observed.
+  - bootstrap scaffolding by `arch` for a remote role repository does
+    not mean that remote role is active; activation requires explicit
+    owner assignment and first role-context handoff entry.
+  - `infra` must never clone `squeezelite-esp32`.
+  - `infra` does not directly communicate with `runner` except when only
+    local host commands can reach `runner`.
+  - each remote agent role uses a dedicated repository with its own
+    AGENTS/board/handoff artifacts.
+  - evidence paths should use role prefixes for quick origin discovery:
+    `arch_*`, `infra_*`, `runner_*`.
+  - a remote-role workstream must not be set to `in_progress` while
+    owner is `infra:tbd` or `runner:tbd`.
+
+## Role Activation State Machine
+
+- States:
+  - `unassigned`
+  - `assigned`
+  - `first_heartbeat`
+  - `active`
+- Transition rules:
+  - `unassigned` -> `assigned`: concrete owner set (`infra:<id>` or
+    `runner:<id>`)
+  - `assigned` -> `first_heartbeat`: first remote heartbeat evidence
+    captured
+  - `first_heartbeat` -> `active`: first role-context handoff entry
+    logged
+- Enforcement:
+  - remote execution workstreams require role state `>= assigned`
+  - destructive or stateful remote changes require role state
+    `>= first_heartbeat`
+  - continuous delegated execution requires role state `active`
+
+## Change Intake (Prereq + Priority + Intermediate Quest)
+
+When operator/user input indicates plan change (for example: \"we
+missed...\", \"easier way...\", \"we should prioritize...\"), treat it as
+a formal replan event even if it is not a hard prerequisite.
+
+Required board updates:
+
+1. Set impacted workstreams to `blocked` or `pending` as appropriate.
+2. Add new prerequisite/intermediate-quest workstreams when needed.
+3. Update blockers/dependencies and next actions to match new sequence.
+4. Ensure owner + activation state are still valid for the new plan.
+5. Require a matching `action_type=replan` handoff entry.
+
+## Ad-hoc Ticket Reflex
+
+When user/operator gives an ad-hoc request, agents should recommend
+ticket tracking for continuity and let user decide.
+
+Rules:
+1. Ask user: `Track this as a ticket? (yes/no)`.
+2. If `yes`, add/update ticket in:
+   - `documentation/short-term/coordination/ad_hoc_ticket_queue.md`
+3. If `no`, continue and note `ticket_tracking=declined` in handoff.
+4. Default recommendation is `yes` when request spans sessions, roles,
+   or priority changes.
+
+## Role Activation Tracker
+
+| Role | Owner | Activation State | Evidence | Notes |
+|---|---|---|---|---|
+| `infra` | `infra:agent` | `active` | `/workspaces/codex-infra-agent/documentation/evidence/infra_first_heartbeat_20260212_2044_utc.log` | executor=ssh_direct; WS4/WS5 completed with evidence logs under `/workspaces/codex-infra-agent/documentation/evidence/` |
+| `runner` | `runner:codex` | `active` | `/home/runner/workspaces/codex-runner-agent/documentation/evidence/runner_first_heartbeat_20260212_2209_utc.log` | executor=remote_codex; runner repo bootstrap + first handoff entry captured |