---
id: TAMQ-WP-0005
type: workplan
title: "Terminal-neutral sessions and safe manual messaging"
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: "f2bf3c87-4af7-554d-bc71-ce92ecb29998"
---

# Terminal-neutral sessions and safe manual messaging

Correct the operator-alpha contract so tamq owns repository-aware tmux topology
and durable messages without assuming that a coding agent—or any particular
interactive program—owns a pane.

## Required operator contract

```bash
tamq start flex-auth audit-core
```

The repository-first shorthand is equivalent:

```bash
tamq flex-auth audit-core
```

This opens or reuses ordinary interactive shells in the exact registered
repository paths. It runs no initial command, installs no PTY observer, and
never injects a queued message into an active terminal input line.

```bash
tamq start --command codex flex-auth audit-core
```

`--command` is explicit opt-in and runs exactly the supplied initial command in
newly created windows. It does not imply that the command is an agent or that it
accepts tamq message injection.

Manual exchange uses durable commands from repository shells:

```bash
tamq send '@audit-core: please review the auth boundary'
tamq inbox --repo audit-core
tamq ack <message-id>
```

The sender defaults to the repository identity of the current managed window.

## Make repository sessions terminal-neutral

```task
id: TAMQ-WP-0005-T01
status: done
priority: high
state_hub_task_id: "84d3b151-3a0a-56ca-8c00-9000ecbb4751"
```

Remove the implicit Codex default. Leave tmux's ordinary shell untouched when
`--command` is absent; when present, parse and execute only the requested
command. Set a trustworthy per-window `TAMQ_REPO` identity without changing the
user's shell or terminal behavior. Retain explicit compatibility aliases where
they do not weaken the neutral default.

Completed with repository-first and explicit `start` forms, no default command,
untouched tmux shells, per-window exported `TAMQ_REPO`, and exact opt-in
`--command`/`--cmd` execution only for newly created windows.

## Separate durable messaging from pane input

```task
id: TAMQ-WP-0005-T02
status: done
priority: high
state_hub_task_id: "6c0f04a6-2af1-53b7-9976-325a9483a838"
```

Register neutral endpoints in a manual delivery mode and prohibit the service
from turning their queued messages into `send-keys` input. Make any legacy PTY
observation/injection path explicit opt-in, visible in status, and absent from
the default startup path.

Completed with schema-versioned endpoint `delivery_mode`. New and migrated
endpoints default to `manual`; the broker never injects their pending messages.
Pane observation/injection requires both explicit `--tap` and `--command`, is
reported as `pane` mode, and cannot be combined with `--no-service`. Startup
also restarts a legacy broker that lacks the manual-delivery capability before
registration.

## Add a practical manual inbox

```task
id: TAMQ-WP-0005-T03
status: done
priority: high
state_hub_task_id: "80bb61bb-8182-58d3-9067-3530026a59a4"
```

Add a concise inbox command for pending messages by repository, retain JSON for
automation, use the current window's `TAMQ_REPO` as sender identity, validate
targets, and preserve explicit acknowledgement. Manual exchange must work
without corrupting either terminal's current input.

Completed with `tamq inbox`, repository-context sender identity, local target
validation, human-readable and JSON output, pending-by-default filtering, and
the existing explicit acknowledgement command.

## Prove and document the neutral workflow

```task
id: TAMQ-WP-0005-T04
status: done
priority: high
state_hub_task_id: "08ca9746-97d1-56d8-badd-5a5ac2c8e147"
```

Exercise real tmux shells with no initial keystrokes, exact opt-in commands,
per-window repository identity, durable send/inbox/ack exchange, and proof that
pending manual messages never appear as pane input. Update the install/start
quickstart and practical-usability assessment, then record the local acceptance
evidence. This task follows T01-T03.

Completed with the isolated installed-package acceptance. It proves untouched
shells at exact paths, stable reuse, per-window identities, manual
send/inbox/ack exchange, byte-for-byte unchanged target-pane output, service
restart and endpoint recovery, and exact explicit-command startup. The full
suite passes 77 tests with 74% statement coverage; README, INTENT, SCOPE, agent
workflow, and command rules now state the terminal-neutral boundary.