From c6e850056db468bab166519c556b88b7a3e03c03 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 24 Aug 2026 20:27:44 +0200 Subject: [PATCH] docs: plan shell-native message routing Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc --- WORK-RECORDS.md | 6 + ...MQ-WP-0006-shell-native-message-routing.md | 122 ++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 workplans/TAMQ-WP-0006-shell-native-message-routing.md diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index cb1664e..7469d60 100644 --- a/WORK-RECORDS.md +++ b/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 | diff --git a/workplans/TAMQ-WP-0006-shell-native-message-routing.md b/workplans/TAMQ-WP-0006-shell-native-message-routing.md new file mode 100644 index 0000000..11eed48 --- /dev/null +++ b/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.