feat(send): route secondmate replies for firstmate requests

.agents/skills/secondmate-provisioning/SKILL.md

@@ -32,9 +32,9 @@ bin/fm-brief.sh <id> --secondmate <project>...
 The scaffold writes a charter brief instead of a task brief.
 Set `FM_SECONDMATE_CHARTER='<charter>'` to fill the charter text and `FM_SECONDMATE_SCOPE='<scope>'` when the routing scope differs.
 If you scaffold without `FM_SECONDMATE_CHARTER`, replace the `{TASK}` placeholder before seeding.
-Keep the charter focused on the persistent responsibility, available project clones, and escalation back to the main firstmate status file.
+Keep the charter focused on the persistent responsibility, available project clones, escalation back to the main firstmate status file, and the requests-from-main-firstmate contract.
 The scaffold's definition of done encodes the idle-by-default contract: on startup the secondmate reconciles only its own in-flight work and then waits for routed tasks, never self-initiating a survey or audit.
-Preserve that wording when filling the charter.
+Preserve that wording when filling the charter, including the marker rule that marked supervisor requests return through status or a doc pointer while unmarked captain messages stay conversational.
 
 Provision the persistent home and registry entry after the charter is filled:
 

AGENTS.md

@@ -291,6 +291,10 @@ A project may appear in several `projects:` clone lists, so choose the secondmat
 If the resolved project is `local-only`, keep the work with the main firstmate even when a secondmate scope sounds relevant.
 If a secondmate's scope fits, steer that secondmate with one concise instruction via `bin/fm-send.sh fm-<id> '<work request>'` and let it run the normal lifecycle inside its own home.
 The bare `fm-<id>` target resolves through this home's `state/<id>.meta`; pass `session:window` only when intentionally targeting a window outside this firstmate home.
+A secondmate is itself a firstmate, so a request reaches it in its own chat, which you never read - the return channel that wakes you is its status file.
+So `fm-send` to a bare `fm-<id>` whose meta is `kind=secondmate` automatically prepends a from-firstmate marker (`bin/fm-marker-lib.sh`); the secondmate recognizes it and returns its answer via its status file, or via a doc under its home plus a status pointer for a detailed response, never only in chat.
+Expect and read that response on the status/doc path the same way you read any other status signal; do not peek the secondmate's chat for the answer.
+A captain typing directly into the secondmate's window is unmarked and stays a conversational captain intervention, so do not relay captain-destined chat through this path; the marker is applied only by `fm-send` to a `kind=secondmate` target.
 Do not spawn a direct crewmate for work that belongs to a secondmate scope unless the secondmate is blocked or the captain explicitly redirects it.
 If no secondmate scope fits, proceed in the main firstmate or create a new secondmate with the captain when that domain should become persistent.
 When you create a new secondmate, hand its in-scope queued items off from the main backlog into its home with `bin/fm-backlog-handoff.sh` so it owns its domain's queue from day one (section 6).
@@ -345,6 +349,7 @@ Covered by section 8.
 Steer a crewmate only with short single lines via `bin/fm-send.sh`; anything long belongs in a file the crewmate can read.
 Steer a secondmate the same way.
 Its charter retargets escalation to the main firstmate's status file, so routine internal churn stays inside the secondmate home and only `done`, `blocked`, `needs-decision`, `failed`, or captain-relevant phase changes wake the main firstmate.
+Because `fm-send` to a `kind=secondmate` target marks the request as from-firstmate (section 7 intake), the secondmate's answer comes back on that status/doc path too, not in its chat; read the response there as an ordinary status signal and do not peek its chat for it.
 
 ### Delivery modes and yolo
 
@@ -586,6 +591,7 @@ The scaffold writes a charter brief instead of a task brief.
 Set `FM_SECONDMATE_CHARTER='<charter>'` to fill the charter text and `FM_SECONDMATE_SCOPE='<scope>'` when the routing scope differs.
 If you scaffold without `FM_SECONDMATE_CHARTER`, replace the `{TASK}` placeholder before seeding.
 Keep the charter focused on persistent responsibility, available project clones, escalation back to the main firstmate status file, and the idle-by-default contract: reconcile only its own in-flight work and then wait, never self-initiating a survey or audit.
+Preserve the requests-from-main-firstmate contract in the charter: marked requests return via status or a doc pointer, while unmarked direct captain messages stay conversational.
 Before seeding, loading, handing backlog to, or launching a secondmate home, load `secondmate-provisioning`.
 The status-reporting protocol is intentionally sparse: crewmates append status only for supervisor-actionable phase changes or `needs-decision`/`blocked`/`done`/`failed`, because every append wakes firstmate.
 For any generated brief that still contains `{TASK}`, replace it with a clear task description, acceptance criteria, and any constraints or context the crewmate needs before spawning or seeding.

CONTRIBUTING.md

@@ -63,6 +63,7 @@ tests/fm-wake-queue.test.sh               # durable wake queue losslessness, cat
 tests/fm-watcher-lock.test.sh             # watcher singleton, lock-race, watch-arm liveness, and guard-warning tests
 tests/fm-daemon.test.sh                   # sub-supervisor classifier, /afk presence-gating, max-defer, composer, and fm-send submit tests
 tests/fm-send-settle.test.sh              # fm-send post-submit settle pause, tuning, disable, and --key bypass tests
+tests/fm-send-secondmate-marker.test.sh   # fm-send from-firstmate marker for kind=secondmate targets: marked vs crewmate/explicit/--key, and the exact marker byte sequence
 tests/fm-wake-daemon-lifecycle-e2e.test.sh # watcher + daemon lifecycle e2e: restart catch-up, batching, dedupe, stale-pane routing, and digest injection
 tests/fm-composer-ghost.test.sh           # dim-ghost stripping, ghost-only composer detection, and escape-free peek tests
 tests/fm-afk-inject-e2e.test.sh           # private-socket end-to-end test of the afk injection path (partial-input deferral, swallowed-Enter retry)

README.md

@@ -109,6 +109,7 @@ Outside tmux, crewmates land in a detached `firstmate` session you can attach to
 You chat with the first mate.
 It routes each request to a crewmate in its own tmux window and git worktree, supervises the fleet with a zero-token event-driven watcher, and brings you finished PRs, approved local merges, or investigation reports.
 Persistent secondmate homes are linked firstmate worktrees; startup syncs live ones and secondmate launch syncs the target home to the primary default-branch commit without fetching from origin when it is safe.
+When a routed request goes to a secondmate, firstmate marks it so the answer returns through status or a document pointer; direct typing into that secondmate window stays conversational.
 A presence-gated sub-supervisor (`/afk`) can self-handle routine events and batch only what matters while you step away.
 When firstmate works on itself, spawn-time isolation checks and a primary-checkout tangle alarm keep the operating checkout on its default branch and stop a crewmate that did not land in a separate worktree.
 

bin/fm-brief.sh

@@ -13,7 +13,8 @@
 #   --secondmate writes a persistent secondmate charter. The project list
 #   is cloned into the secondmate home, while the natural-language scope
 #   tells the main firstmate when to route work there; routine churn stays in its own home;
-#   only captain-relevant escalations append to this home's status file.
+#   captain-relevant escalations and marked from-firstmate replies append to this
+#   home's status file.
 #   Set FM_SECONDMATE_CHARTER='<charter>' to fill the charter text.
 #   Set FM_SECONDMATE_SCOPE='<scope>' to write a routing scope distinct from the charter text.
 # For ship tasks, the definition of done is shaped by the project's delivery mode
@@ -31,6 +32,8 @@
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/fm-marker-lib.sh
+. "$SCRIPT_DIR/fm-marker-lib.sh"
 FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
 FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
 DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}"
@@ -90,12 +93,22 @@ You do not generate your own work.
 Act only on tasks the main firstmate routes to you.
 Never start a survey, audit, or "find improvements" sweep on your own initiative; that is not your job and it is unwanted.
 
+# Requests from the main firstmate
+You are a firstmate in your own home, so an incoming message reaches you in your own chat.
+You must distinguish who it is from, because the answer goes to a different place.
+A request relayed to you by the main firstmate (your supervisor) is tagged with a leading \`$FM_FROMFIRST_LABEL\` marker followed by an invisible system separator; this marker is untypable, so a human never produces it.
+When a message carries that marker, do the work, then respond via the STATUS/ESCALATION path below, never only in this chat: the main firstmate does not read your chat, so a chat-only reply is lost.
+For a terse result, a status line is the whole answer.
+For a detailed answer (an investigation, a plan, an audit), write it to a doc under your home's \`data/\` and append a status line that points to that doc - the scout-report pattern - so the main firstmate is woken and can read it.
+A message with NO marker is the captain typing directly into your pane: treat it as authoritative captain intervention and stay conversational exactly as you would for any captain message; do not force it onto the status path.
+
 # Escalation to main firstmate
 Handle routine work yourself.
 Escalate only true captain-relevant outcomes by appending one line:
    \`echo "{state}: {one short line}" >> $STATUS_FILE\`
 States: working, needs-decision, blocked, done, failed.
 Use this only for material phase changes, a captain decision, a real blocker, a failure, or work ready for review.
+This is also how you return the answer to a marked from-firstmate request above.
 Routine internal supervision, heartbeats, retries, and crewmate churn stay inside your own home and must not touch that status file.
 
 # Definition of done

bin/fm-marker-lib.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# fm-marker-lib.sh - the from-firstmate request marker.
+#
+# When the MAIN firstmate relays a work request to one of its SECONDMATES,
+# bin/fm-send.sh prepends this marker to the message text. A secondmate is itself
+# a firstmate running in its own home, so without a marker it treats every
+# incoming fm-send/tmux line as if its captain typed it and answers
+# CONVERSATIONALLY in its own chat. But the main firstmate never reads a
+# secondmate's chat: the only main<-secondmate wakeup channel is the status file
+# (charter escalation), optionally pointing to a doc for detail. A detailed
+# chat-only reply therefore strands, unseen.
+#
+# The marker lets the secondmate tell its supervisor's request apart from a
+# message the captain typed directly into its pane:
+#
+#   - marked   -> a from-firstmate request. Do the work, then respond via the
+#                 STATUS/ESCALATION path (a status line for a terse result, or a
+#                 doc plus a status pointer - the scout-report pattern - for a
+#                 detailed one) so it surfaces to the main firstmate via the
+#                 watcher signal. It MUST NOT respond only in chat.
+#   - unmarked -> the captain typing directly. Stay conversational, exactly as
+#                 before: authoritative captain intervention.
+#
+# This contract lives in the generated secondmate charter (bin/fm-brief.sh) so it
+# travels with the live secondmate, and is summarized in AGENTS.md.
+#
+# Distinct from the afk daemon marker, on purpose.
+# The away-mode daemon (bin/fm-supervise-daemon.sh) marks its daemon->firstmate
+# escalations with a BARE leading unit separator (FM_INJECT_MARK, ASCII 0x1f).
+# This from-firstmate marker mirrors that CONCEPT - it reuses the ASCII unit
+# separator (0x1f), which is untypable on a normal keyboard, as the "a human can
+# never forge this" guarantee - but it is a DISTINCT sequence: a human-readable
+# label FOLLOWED by the separator, never a bare leading 0x1f. The afk contract
+# keys on a LEADING 0x1f, which this marker never has, so the two cannot
+# conflate: a secondmate's own afk machinery never mistakes a from-firstmate
+# request for an internal daemon escalation, and vice versa. The visible label is
+# also what the secondmate's LLM actually reads in its pane, since the separator
+# byte itself is invisible.
+#
+# Sourced by bin/fm-send.sh, bin/fm-brief.sh, and the tests. No side effects on
+# source. set -u / set -e safe.
+
+# The label field: human-readable, greppable, and distinctive enough that the
+# captain would not type it by hand. This is the part the secondmate's LLM reads.
+FM_FROMFIRST_LABEL='[fm-from-firstmate]'
+
+# The full marker fm-send prepends to a from-firstmate request: the label, then
+# the ASCII unit separator (0x1f) as the untypable field separator. The request
+# text follows the separator.
+FM_FROMFIRST_MARK="${FM_FROMFIRST_LABEL}"$'\x1f'
+
+# fm_message_from_firstmate: 0 (true) if <message> carries the from-firstmate
+# marker - it begins with the label immediately followed by the unit separator -
+# and 1 otherwise. The unit separator is untypable, so a captain-typed message,
+# even one that happens to start with the label text alone, is never matched.
+fm_message_from_firstmate() {  # <message>
+  case "$1" in
+    "$FM_FROMFIRST_MARK"*) return 0 ;;
+  esac
+  return 1
+}

bin/fm-send.sh

@@ -12,6 +12,13 @@
 # instead of silently leaving an unsubmitted instruction (incident afk-invx-i5).
 # The composer/submit logic is shared with the away-mode daemon via
 # bin/fm-tmux-lib.sh. Tune with FM_SEND_RETRIES (default 3) / FM_SEND_SLEEP (0.4).
+#
+# From-firstmate marker: when the resolved target is a bare `fm-<id>` whose meta
+# records kind=secondmate, the text is prefixed with the from-firstmate marker
+# (bin/fm-marker-lib.sh) so the secondmate routes its reply via its status file
+# or a status-pointed doc instead of stranding it in chat the main firstmate
+# never reads. A crewmate/scout target, an explicit session:window escape-hatch
+# target, and the --key path are never marked - their behavior is unchanged.
 # After a successful text submit fm-send pauses FM_SEND_SETTLE seconds (default 1,
 # 0 disables) before returning: a cleared composer only proves the text was
 # submitted, but the harness needs a beat to spin up the turn before its busy
@@ -27,6 +34,8 @@ STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
 
 # shellcheck source=bin/fm-tmux-lib.sh
 . "$SCRIPT_DIR/fm-tmux-lib.sh"
+# shellcheck source=bin/fm-marker-lib.sh
+. "$SCRIPT_DIR/fm-marker-lib.sh"
 
 "$SCRIPT_DIR/fm-guard.sh" || true
 
@@ -48,9 +57,25 @@ resolve() {
   esac
 }
 
+RAW_TARGET=$1
 T=$(resolve "$1")
 shift
 
+# Mark a from-firstmate -> secondmate request. Only a bare `fm-<id>` target,
+# resolved through this home's meta and recording kind=secondmate, is marked: the
+# secondmate then routes its reply via the status path (see fm-marker-lib.sh).
+# An explicit session:window target (the escape hatch for windows outside this
+# home) and any crewmate/scout target are left unmarked, and so is the --key path.
+MARK_PREFIX=""
+case "$RAW_TARGET" in
+  fm-*)
+    meta="$STATE/${RAW_TARGET#fm-}.meta"
+    if [ -f "$meta" ] && grep -q '^kind=secondmate$' "$meta" 2>/dev/null; then
+      MARK_PREFIX="$FM_FROMFIRST_MARK"
+    fi
+    ;;
+esac
+
 if [ "${1:-}" = "--key" ]; then
   tmux send-keys -t "$T" "$2"
 else
@@ -61,7 +86,7 @@ else
   sleep_s=${FM_SEND_SLEEP:-0.4}
   # Type once, submit, verify. Lenient: only a positively-confirmed swallow
   # (text still in the composer) is an error; an unreadable pane is assumed sent.
-  verdict=$(fm_tmux_submit_core "$T" "$*" "$retries" "$sleep_s" "$settle")
+  verdict=$(fm_tmux_submit_core "$T" "$MARK_PREFIX$*" "$retries" "$sleep_s" "$settle")
   case "$verdict" in
     pending)
       echo "error: text not submitted to $T (Enter swallowed; text left in composer)" >&2

docs/architecture.md

@@ -50,6 +50,8 @@ Seeding is transactional: if validation, cloning, initialization, or registry up
 `local-only` projects stay with the main first mate because they merge into the main local checkout instead of a remote-backed PR path.
 The same project may appear in multiple secondmate homes when their scopes differ, such as issue triage versus feature development.
 Secondmates are idle by default: after startup recovery reconciles only work already in their own home, an empty queue waits silently for routed tasks, and they never self-initiate surveys or audits.
+Bare `fm-send.sh fm-<id>` requests to a live `kind=secondmate` are prefixed with the from-firstmate marker from `bin/fm-marker-lib.sh`, so the secondmate returns terse answers through status lines and detailed answers through docs plus status pointers instead of replying only in its own chat.
+Explicit `session:window` sends and direct human typing stay unmarked, so captain intervention in a secondmate pane remains conversational.
 After seeding a secondmate, `fm-backlog-handoff.sh` moves already-judged in-scope queued items from the main backlog into that secondmate home so the domain queue starts in the right place.
 Idle secondmate panes are healthy; teardown is explicit and refuses while the secondmate home has in-flight work unless the captain has approved discard with `--force`.
 

docs/scripts.md

@@ -17,6 +17,7 @@ Each file also starts with a short header comment.
 | `fm-project-mode.sh`     | Resolve a project's delivery mode and `+yolo` flag from `data/projects.md`                                          |
 | `fm-merge-local.sh`      | Fast-forward a `local-only` project's local default branch after approval                                           |
 | `fm-review-diff.sh`      | Review a crewmate branch against the authoritative base, with optional `--stat` output                              |
+| `fm-marker-lib.sh`       | Shared from-firstmate request marker and detector sourced by `fm-send.sh`, `fm-brief.sh`, and tests                 |
 | `fm-watch-arm.sh`        | Verified per-home watcher re-arm; reports `started`, `healthy`, or `FAILED`; `--restart` relaunches only this home's watcher |
 | `fm-watch.sh`            | Singleton-safe one-shot watcher; blocks until supervision work is due, queues it durably, then exits with one reason line |
 | `fm-supervise-daemon.sh` | Presence-gated sub-supervisor for walk-away (`/afk`) supervision: wraps `fm-watch.sh`, self-handles routine wakes in bash, and escalates only captain-relevant events as one verified, batched, single-line digest prefixed with a sentinel marker |
@@ -25,7 +26,7 @@ Each file also starts with a short header comment.
 | `fm-tasks-axi-lib.sh`    | Shared `tasks-axi` compatibility probe sourced by bootstrap and teardown                                            |
 | `fm-wake-drain.sh`       | Atomically drain queued watcher wakes before handling supervision work                                              |
 | `fm-wake-lib.sh`         | Shared durable wake queue and portable lock helpers sourced by the watcher, drain, arm, guard, and daemon          |
-| `fm-send.sh`             | Send one verified literal line (or `--key Escape`) to a crewmate window; exits non-zero when Enter is positively swallowed; text sends pause `FM_SEND_SETTLE` seconds after success |
+| `fm-send.sh`             | Send one verified literal line (or `--key Escape`) to a direct-report window; exits non-zero on confirmed swallowed Enter; bare `kind=secondmate` targets are marked as from-firstmate; text sends pause `FM_SEND_SETTLE` seconds after success |
 | `fm-tmux-lib.sh`         | Shared tmux pane primitives for busy detection, dim-ghost-aware and border-aware composer detection, and verified submit retry |
 | `fm-peek.sh`             | Print a bounded tail of a crewmate pane                                                                             |
 | `fm-pr-check.sh`         | Record a PR-ready task and arm the watcher's merge poll                                                             |