tmux-amq/workplans/TAMQ-WP-0006-shell-native-message-routing.md

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
TAMQ-WP-0006	workplan	Shell-native message routing and explicit inbox filters	communication	tmux-amq	finished	codex	coulomb-social	P0	11	2026-08-24	2026-08-24	ea96613b-c9db-507e-bfa4-33bd046ef1bc

Shell-native message routing and explicit inbox filters

Make manual messaging usable from the ordinary shells that tamq opens. The shell must recognize a repository address before trying to execute it, while tamq remains neutral about shells, agents, and interactive programs.

Required operator contract

Root help exposes the session shorthand and its explicit initial-command option:

tamq --help
tamq --command codex flex-auth audit-core

Starting a session makes commands for its repository names available on each new managed shell's PATH:

tamq flex-auth audit-core
@audit-core: Some message!
@flex-auth Another message

These are tamq-owned executable command shims, not shell aliases. They are placed in the operator command directory that already exposes tamq, with an explicit command-directory override and isolated fallback. They enqueue messages and do nothing else by default. Reading a manual inbox produces comment-safe text:

#flex-auth: Some message! [m-...]

An operator may explicitly consume pending messages through a command:

tamq inbox --filter 'cat >> msg.log'

The filter receives one comment-safe message on standard input with message metadata in environment variables. A zero exit acknowledges that message; a failure leaves it pending and stops processing. No filter runs in the background, modifies a pane, or becomes a startup default.

Expose the session shorthand in root help

id: TAMQ-WP-0006-T01
status: done
priority: high
state_hub_task_id: "f6228d55-37f0-5be6-a868-f681f09d091b"

Document repository-first invocation and --command COMMAND in tamq --help, including the terminal-neutral default and exact opt-in nature of the command.

Completed with a root-help shorthand section that names --command COMMAND, the ordinary-shell default, and the absence of implicit terminal observation or message injection.

Install shell-native repository address commands

id: TAMQ-WP-0006-T02
status: done
priority: high
state_hub_task_id: "432e737c-b34e-56aa-8003-3f61e8ef4faf"

Populate the operator command directory that exposes tamq with safe @repo and @repo: entry points for every requested repository; support an explicit TAMQ_COMMAND_DIR and isolated state fallback, and also add the selected directory to each newly created window's environment. Invocation must route through tamq's existing validation and durable send path. Reject unsafe repository names and refuse to overwrite commands not owned by tamq.

Completed with executable @repo and @repo: shims beside the installed tamq command, TAMQ_COMMAND_DIR override and state fallback, tmux PATH propagation, safe repository-name checks, tamq ownership markers, and collision refusal.

Make manual inbox output comment-safe

id: TAMQ-WP-0006-T03
status: done
priority: high
state_hub_task_id: "b4ff430d-3b09-56de-9c1a-20afb018964c"

Render human-readable messages as shell comments prefixed with #sender: and retain the message id for acknowledgement. Keep structured JSON stable for automation.

Completed with #sender: rendering on every body line, durable ids on the final line, and escaping of non-printing terminal control characters. JSON output retains the original structured record.

Add explicit pull-time inbox filters

id: TAMQ-WP-0006-T04
status: done
priority: high
state_hub_task_id: "d413ad83-06ff-5de1-97aa-256b4f684007"

Add tamq inbox --filter COMMAND. Invoke the command once per pending message, pass only the comment-safe representation on standard input, expose bounded metadata through environment variables, acknowledge only after a zero exit, and leave failed and subsequent messages pending. Filters are explicit inbox consumers and never background terminal interceptors.

Completed with sequential pull-time filters, bounded metadata environment, comment-only standard input, success acknowledgement, fail-fast pending retention, and rejection of ambiguous --all/--json combinations.

Prove and document the ordinary-shell workflow

id: TAMQ-WP-0006-T05
status: done
priority: high
state_hub_task_id: "da957158-fb75-5232-9610-7684ebca45b5"

Cover root help, both address spellings, spaces and shell metacharacters in message bodies, unknown targets, comment-safe inbox output, successful and failed filters, acknowledgement behavior, path isolation, and installed tmux acceptance. Update the operator quickstart and practical command reference.

Completed with 85 passing tests and 75% statement coverage. The isolated installed-package test proves root help, real ordinary-shell command lookup after shell startup, both neutral panes, durable delivery, comment-safe output, filter acknowledgement, target-pane immutability, restart, recovery, and exact explicit-command startup. A live user-install smoke repeated shell-native routing with no target-pane change and left zero pending messages.