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
TAMQ-WP-0004	workplan	Operator-installable local alpha session	communication	tmux-amq	ready	codex	coulomb-social	P0	10	2026-08-24	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:

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:

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

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

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

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

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

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.