docs: plan shell-native message routing

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc

WORK-RECORDS.md

@@ -14,6 +14,7 @@
 | workplan | TAMQ-WP-0003 | active | — | workplans/TAMQ-WP-0003-delivery-reliability.md |
 | workplan | TAMQ-WP-0004 | finished | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md |
 | workplan | TAMQ-WP-0005 | finished | — | workplans/TAMQ-WP-0005-terminal-neutral-manual-messaging.md |
+| workplan | TAMQ-WP-0006 | active | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |
 | task | TAMQ-WP-ADHOC-2026-08-24-T01 | done | — | workplans/ADHOC-2026-08-24.md |
 | task | TAMQ-WP-0001-T01 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md |
 | task | TAMQ-WP-0001-T02 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md |
@@ -34,3 +35,8 @@
 | task | TAMQ-WP-0005-T02 | done | — | workplans/TAMQ-WP-0005-terminal-neutral-manual-messaging.md |
 | task | TAMQ-WP-0005-T03 | done | — | workplans/TAMQ-WP-0005-terminal-neutral-manual-messaging.md |
 | task | TAMQ-WP-0005-T04 | done | — | workplans/TAMQ-WP-0005-terminal-neutral-manual-messaging.md |
+| task | TAMQ-WP-0006-T01 | progress | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |
+| task | TAMQ-WP-0006-T02 | todo | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |
+| task | TAMQ-WP-0006-T03 | todo | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |
+| task | TAMQ-WP-0006-T04 | todo | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |
+| task | TAMQ-WP-0006-T05 | todo | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |

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

@@ -0,0 +1,122 @@
+---
+id: TAMQ-WP-0006
+type: workplan
+title: "Shell-native message routing and explicit inbox filters"
+domain: communication
+repo: tmux-amq
+status: active
+owner: codex
+topic_slug: coulomb-social
+planning_priority: P0
+planning_order: 11
+created: "2026-08-24"
+updated: "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:
+
+```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 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:
+
+```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: 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
+
+```task
+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
+
+```task
+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
+
+```task
+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
+
+```task
+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.