---
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.