---
id: TAMQ-WP-0006
type: workplan
title: "Shell-native message routing and explicit inbox filters"
domain: communication
repo: tmux-amq
status: finished
owner: codex
topic_slug: coulomb-social
planning_priority: P0
planning_order: 11
created: "2026-08-24"
updated: "2026-08-24"
state_hub_workstream_id: "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:

```bash
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`:

```bash
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:

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

An operator may explicitly consume pending messages through a command:

```bash
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

```task
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

```task
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

```task
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

```task
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

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