docs: plan operator-installable local alpha

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc

.custodian-brief.md

@@ -2,11 +2,19 @@
 # Custodian Brief — tmux-amq
 
 **Domain:** communication  
-**Last synced:** 2026-08-24 12:43 UTC  
+**Last synced:** 2026-08-24 13:30 UTC  
 **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
 
 ## Active Workstreams
 
+### Coordination-engine adapter boundary
+Progress: 0/3 done  |  workplan_id: `48da5fa7-b7bf-5d13-8edc-b90f266e241c`
+
+**Open tasks:**
+- ! Implement the coordination-engine client adapter  `195db613`
+- ! Prove interoperability and recovery  `23c7f6c7`
+- · Specify the adapter contract  `a222dab7`
+
 ### Delivery reliability and practical integration evidence
 Progress: 0/4 done  |  workplan_id: `7961275b-8f1f-5827-b9fc-46b3ac35fb73`
 
@@ -16,14 +24,6 @@ Progress: 0/4 done  |  workplan_id: `7961275b-8f1f-5827-b9fc-46b3ac35fb73`
 - · Enforce bounded delivery attempts  `52c43745`
 - · Add real tmux and PTY lifecycle coverage  `9a3d84b4`
 
-### Coordination-engine adapter boundary
-Progress: 0/3 done  |  workplan_id: `48da5fa7-b7bf-5d13-8edc-b90f266e241c`
-
-**Open tasks:**
-- ! Implement the coordination-engine client adapter  `195db613`
-- ! Prove interoperability and recovery  `23c7f6c7`
-- · Specify the adapter contract  `a222dab7`
-
 ---
 ## MCP Orientation (when available)
 

WORK-RECORDS.md

@@ -12,6 +12,7 @@
 | workplan | TAMQ-WP-0001 | finished | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md |
 | workplan | TAMQ-WP-0002 | active | — | workplans/TAMQ-WP-0002-coordination-engine-adapter.md |
 | workplan | TAMQ-WP-0003 | active | — | workplans/TAMQ-WP-0003-delivery-reliability.md |
+| workplan | TAMQ-WP-0004 | ready | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md |
 | task | TAMQ-WP-ADHOC-2026-08-24-T01 | done | — | workplans/ADHOC-2026-08-24.md |
 | task | TAMQ-WP-0001-T01 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md |
 | task | TAMQ-WP-0001-T02 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md |
@@ -23,3 +24,8 @@
 | task | TAMQ-WP-0003-T02 | wait | — | workplans/TAMQ-WP-0003-delivery-reliability.md |
 | task | TAMQ-WP-0003-T03 | todo | — | workplans/TAMQ-WP-0003-delivery-reliability.md |
 | task | TAMQ-WP-0003-T04 | wait | — | workplans/TAMQ-WP-0003-delivery-reliability.md |
+| task | TAMQ-WP-0004-T01 | todo | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md |
+| task | TAMQ-WP-0004-T02 | todo | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md |
+| task | TAMQ-WP-0004-T03 | todo | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md |
+| task | TAMQ-WP-0004-T04 | wait | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md |
+| task | TAMQ-WP-0004-T05 | wait | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md |

workplans/TAMQ-WP-0004-operator-installable-local-alpha.md

@@ -0,0 +1,133 @@
+---
+id: TAMQ-WP-0004
+type: workplan
+title: "Operator-installable local alpha session"
+domain: communication
+repo: tmux-amq
+status: ready
+owner: codex
+topic_slug: coulomb-social
+planning_priority: P0
+planning_order: 10
+created: "2026-08-24"
+updated: "2026-08-24"
+---
+
+# Operator-installable local alpha session
+
+Make tmux-amq directly usable by the operator from a normal local shell without
+running it from the source checkout or manually assembling service, tmux, and
+agent commands.
+
+## Alpha user journey
+
+The completed workflow must be:
+
+```bash
+git clone <tmux-amq-remote>
+cd tmux-amq
+make install
+
+tamq --version
+tamq start tmux-amq
+```
+
+`tamq start tmux-amq` starts or reuses the local service and managed `tamq`
+session, opens the `tmux-amq` gita repository in its registered path, launches
+Codex behind `tamq tap`, and attaches the operator to the session. The detached
+workflow must also work:
+
+```bash
+tamq start --detach tmux-amq
+tamq status
+tamq attach
+```
+
+## Acceptance gates
+
+- `make install` is documented, repeatable, and installs an isolated `tamq`
+  command into the invoking user's normal executable path.
+- Installation and upgrade do not require activating the repository `.venv`.
+- Missing `uv`, tmux, gita, Codex, PATH configuration, or repository
+  registration produces a direct actionable error before a partial session is
+  left behind.
+- The first and subsequent windows start in their exact `gita freeze` paths.
+- Default `tamq start` attaches; `--detach` returns to the caller and prints a
+  useful endpoint/session summary; `tamq attach` attaches later.
+- Repeating `tamq start` safely reuses the service/session and does not create
+  duplicate repository windows or agent processes.
+- A real installed-package smoke test proves start, attach/detach, status,
+  message routing, history visibility, stop, and bounded cleanup on this local
+  environment.
+- The README contains a short install/start/stop/uninstall quickstart and states
+  the alpha reliability boundaries from `SCOPE.md`.
+
+## Add the user-level install target
+
+```task
+id: TAMQ-WP-0004-T01
+status: todo
+priority: high
+```
+
+Add a phony `make install` target using uv's isolated tool installation flow,
+with an explicit upgrade/reinstall behavior suitable for repeated development
+installs. Verify `command -v tamq`, `tamq --version`, and invocation from outside
+the checkout. Document the corresponding uninstall command and executable-path
+expectation.
+
+## Make session startup match the CLI contract
+
+```task
+id: TAMQ-WP-0004-T02
+status: todo
+priority: high
+```
+
+Implement the currently unused `--detach` flag. Make non-detached `tamq start`
+attach to the managed session after successful endpoint registration and pending
+delivery. Ensure the first boot window uses the selected repository's registered
+path rather than the caller's current directory, and preserve idempotent reuse of
+existing windows.
+
+## Add installation and startup preflight
+
+```task
+id: TAMQ-WP-0004-T03
+status: todo
+priority: high
+```
+
+Before mutating tmux or service state, check the required commands, exact gita
+targets and paths, writable runtime/state locations, agent command availability,
+and session conflicts. Return concise remediation for every failure and avoid
+leaving boot windows, sockets, pidfiles, or processes behind after a failed
+start.
+
+## Prove the installed local session end to end
+
+```task
+id: TAMQ-WP-0004-T04
+status: wait
+priority: high
+```
+
+Add automated coverage using an isolated uv tool directory, state directory,
+socket, and tmux server. Use a deterministic benign agent fixture in automation,
+then perform the operator acceptance with the installed `tamq` command and Codex.
+Prove attach/detach semantics, correct pane directories, idempotent reuse,
+message injection/history, shutdown, and cleanup. This task follows T01-T03.
+
+## Publish the alpha quickstart and evidence
+
+```task
+id: TAMQ-WP-0004-T05
+status: wait
+priority: medium
+```
+
+Update README and agent workflow documentation with prerequisites, install,
+upgrade, start, attach, status, stop, and uninstall commands. Record the exact
+local acceptance commands and results. Clearly retain the reliability caveats
+owned by `TAMQ-WP-0003` and do not claim coordination-engine integration from
+`TAMQ-WP-0002`. This task follows T04.