tegwick
5774fbd548
Some checks failed
tamq-ci / test (push) Failing after 6s
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc
205 lines
8.2 KiB
Markdown
205 lines
8.2 KiB
Markdown
---
|
|
id: TAMQ-WP-0004
|
|
type: workplan
|
|
title: "Operator-installable local alpha session"
|
|
domain: communication
|
|
repo: tmux-amq
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: coulomb-social
|
|
planning_priority: P0
|
|
planning_order: 10
|
|
created: "2026-08-24"
|
|
updated: "2026-08-24"
|
|
state_hub_workstream_id: "d9f3ddd6-cf3a-54f4-a206-d66a76cd9c7e"
|
|
---
|
|
|
|
# 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 --command codex railiance-platform activity-core
|
|
```
|
|
|
|
`tamq start --command codex railiance-platform activity-core` starts or reuses
|
|
the local service and managed `tamq` session, creates windows named
|
|
`railiance-platform` and `activity-core` in that order, roots them at their exact
|
|
`gita freeze` paths, launches `codex` behind `tamq tap` in each window, and
|
|
attaches the operator to the first window. Because Codex is the default agent
|
|
command, this shorthand must be equivalent:
|
|
|
|
```bash
|
|
tamq start railiance-platform activity-core
|
|
```
|
|
|
|
The repository operands are gita slugs, not startup modes. A single operand such
|
|
as `tmux-amq` means "open one window for the tmux-amq repository"; it has no
|
|
special meaning to tamq.
|
|
|
|
The detached workflow must also work:
|
|
|
|
```bash
|
|
tamq start --detach --command codex railiance-platform activity-core
|
|
tamq status
|
|
tamq attach
|
|
```
|
|
|
|
## Supported startup modes
|
|
|
|
- Interactive multi-repo start: create/reuse the requested windows, launch the
|
|
agent command in new windows, then attach.
|
|
- Detached multi-repo start: perform the same setup with `--detach`, print the
|
|
endpoint summary, and return to the shell.
|
|
- Existing-session attach: `tamq attach` attaches without changing repository
|
|
membership or launching another agent process.
|
|
- Advanced service-only operation: `tamq serve` runs the local broker in the
|
|
foreground for diagnostics or supervision.
|
|
- Degraded tmux-only operation: `tamq start --no-service ...` may be retained
|
|
only with explicit, tested semantics; it must not attempt socket registration
|
|
when no service exists or imply that messaging is available.
|
|
|
|
## 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.
|
|
- `--command` is the documented option name; the existing `--cmd` spelling
|
|
remains a compatibility alias. Omitting both selects `codex`.
|
|
- Each distinct repository operand creates exactly one same-named window and
|
|
invokes the selected agent command exactly once when that window is created.
|
|
- The required two-repository acceptance case creates windows
|
|
`railiance-platform` and `activity-core`, rooted at their registered paths,
|
|
with Codex running automatically in both.
|
|
- 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: done
|
|
priority: high
|
|
state_hub_task_id: "017c4c30-3e1c-5939-b700-e73912e4a01e"
|
|
```
|
|
|
|
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.
|
|
|
|
Completed with a cache-refreshing `uv tool install` target and matching
|
|
uninstall target. The installed command resolves from the user tool bin, reports
|
|
version `0.1.0`, and is exercised from an isolated directory by the installed
|
|
package smoke test.
|
|
|
|
## Make session startup match the CLI contract
|
|
|
|
```task
|
|
id: TAMQ-WP-0004-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "8e926f2b-b7b2-53f5-81e1-9bdd3c4b7d3e"
|
|
```
|
|
|
|
Add `--command` as the canonical start option while retaining `--cmd` as an
|
|
alias, with `codex` as the default. Implement the currently unused `--detach`
|
|
flag. Make non-detached `tamq start` attach to the managed session after
|
|
successful endpoint registration and pending delivery. Ensure all boot windows,
|
|
including the first, use their selected repositories' registered paths rather
|
|
than the caller's current directory. Invoke the agent command exactly once per
|
|
new window and preserve idempotent reuse of existing windows. Define and test
|
|
`--no-service` as an explicitly degraded tmux-only mode or remove it from the
|
|
alpha surface.
|
|
|
|
Completed with canonical `--command`, compatible `--cmd`, default Codex,
|
|
attach-by-default, working detached and explicit no-service modes, exact first
|
|
and subsequent window paths, tmux-scoped endpoint identity, and idempotent
|
|
window/process reuse.
|
|
|
|
## Add installation and startup preflight
|
|
|
|
```task
|
|
id: TAMQ-WP-0004-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "479dd94e-e21f-512d-80e7-2453cf163b67"
|
|
```
|
|
|
|
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.
|
|
|
|
Completed with command, gita target/path, runtime-path, agent, and managed-session
|
|
checks before mutation. Registration failures roll back newly created tmux
|
|
resources, and foreign same-named sessions are rejected rather than adopted.
|
|
|
|
## Prove the installed local session end to end
|
|
|
|
```task
|
|
id: TAMQ-WP-0004-T04
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "76990b5d-b0d7-562f-8316-1b9cc452cadf"
|
|
```
|
|
|
|
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 the
|
|
exact `railiance-platform activity-core` Codex invocation above. Prove that two
|
|
same-named windows open in their registered paths with Codex running
|
|
automatically, along with attach/detach semantics, idempotent reuse, message
|
|
injection/history, shutdown, and cleanup. This task follows T01-T03.
|
|
|
|
Completed with both a real isolated-tmux integration test and an isolated uv
|
|
tool installation smoke test. The latter starts the two required repository
|
|
windows through the installed CLI, verifies exact paths and stable pane PIDs on
|
|
repeat, routes a message into `activity-core`, observes `injected` history,
|
|
checks status, stops the service, and bounds tmux cleanup. The local operator
|
|
acceptance used the same repository operands with Codex and left both live panes
|
|
ready for attachment.
|
|
|
|
## Publish the alpha quickstart and evidence
|
|
|
|
```task
|
|
id: TAMQ-WP-0004-T05
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "e98eda1e-6200-5bfb-8873-c0a210484fc1"
|
|
```
|
|
|
|
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.
|
|
|
|
Completed in `README.md`, `AGENTS.md`, the stack command rules, and `SCOPE.md`.
|
|
The quickstart documents install/upgrade, exact Codex start, detached start,
|
|
attach, status, stop, tmux cleanup, and uninstall while retaining the bounded
|
|
retry, acknowledgement, and coordination-adapter caveats.
|