tmux-amq/workplans/TAMQ-WP-0005-terminal-neutral-manual-messaging.md

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
TAMQ-WP-0005	workplan	Terminal-neutral sessions and safe manual messaging	communication	tmux-amq	finished	codex	coulomb-social	P0	10	2026-08-24	2026-08-24	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

tamq start flex-auth audit-core

The repository-first shorthand is equivalent:

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.

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:

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

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

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

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

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.