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

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
TAMQ-WP-0004	workplan	Operator-installable local alpha session	communication	tmux-amq	finished	codex	coulomb-social	P0	10	2026-08-24	2026-08-24	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:

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:

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:

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

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

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

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

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

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.