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
TAMQ-WP-0006	workplan	Shell-native message routing and explicit inbox filters	communication	tmux-amq	active	codex	coulomb-social	P0	11	2026-08-24	2026-08-24

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 per-session executable command shims, not shell aliases. 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: progress
priority: high

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

Install shell-native repository address commands

id: TAMQ-WP-0006-T02
status: todo
priority: high

Create a private command directory for the managed session, populate it with safe @repo and @repo: entry points for every requested repository, and add that directory to each newly created window's environment. Invocation must route through tamq's existing validation and durable send path. Reject unsafe repository names rather than creating ambiguous executable paths.

Make manual inbox output comment-safe

id: TAMQ-WP-0006-T03
status: todo
priority: high

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

Add explicit pull-time inbox filters

id: TAMQ-WP-0006-T04
status: todo
priority: high

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.

Prove and document the ordinary-shell workflow

id: TAMQ-WP-0006-T05
status: todo
priority: high

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.