@twinsearth/w2m-dsh-plugin 1.1.22 → 1.2.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
               },
     "metadata":  {
                      "description":  "The w2m fleet plugins: one account, many machines, any of Windows, macOS or Linux.",
-                     "version":  "1.1.22"
+                     "version":  "1.2.1"
                  },
     "plugins":  [
                     {
                         "name":  "w2m-fleet",
                         "source":  "./",
                         "description":  "Read fleet state and dispatch commands across the machines registered to one account. Read-only MCP surface: the five exposed tools cannot change anything.",
-                        "version":  "1.1.22",
+                        "version":  "1.2.1",
                         "author":  {
                                        "name":  "TwinsEarth"
                                    },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
     "name":  "w2m-fleet",
     "description":  "Drive the same project on online Windows, macOS and Linux machines from one account: read fleet state, dispatch commands and read results. The MCP surface is deliberately read-only.",
-    "version":  "1.1.22",
+    "version":  "1.2.1",
     "author":  {
                    "name":  "TwinsEarth"
                },

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 All notable changes to this project are documented here.
 
+## [1.2.1] — 2026-10-18
+
+**P1 of fleet collaboration: addressing, correlation, and a turn that can time out.**
+
+### 1. Addressing — a message can name its recipient
+
+`POST /v1/fleet/messages` accepts `to`: `"all"` (the fleet group, the default) or one `machine_id`. The relay stores ONE row
+either way and filters at read time (`for_me=1` is answered from the authenticated device identity, never from a caller
+supplied id), because N copies for N recipients would multiply the byte budget by the size of the fleet for no extra
+meaning. A malformed address is refused `BAD_ADDRESS` by the store and `CHAT_BAD_ADDRESS` by the host route.
+
+### 2. Correlation — threads and replies
+
+Messages carry `thread_id`, `reply_to` and `turn`. `reply_to` must name a message that exists in the SAME session
+(`REPLY_TARGET_MISSING` otherwise): a dangling reply makes a thread unreadable. `turn` is assigned by the relay and counts
+the exchange inside a thread, so a reader can order answers without trusting client clocks.
+
+### 6. Turn semantics — waiting is a state, timeouts are values
+
+`w2m_chat` gained `action: "ask"` (send, return the message id) and `action: "await"` (wait for a reply to that id).
+`await` returns `{state: "answered" | "timeout"}` — a timeout is a result the caller reads, not an exception that loses the
+question, and the question stays in the flow so it can be answered later.
+
+### What this needs from the relay
+
+The fields are new, so the relay on the fleet host must be redeployed with this build. An older relay ignores the fields
+(the message still stores and reads, without addressing/threading) because they are plain body fields rather than a
+protocol version bump.
+
+### Verified
+
+Relay store: `BAD_ADDRESS`, `REPLY_TARGET_MISSING`, turn counting, and the read filters. HTTP: the three existing
+fleet-message tests still pass. Tools: 122 pass. relay suite: 163 pass. Gate GREEN twice, 15 of 15.
+
+### Not verified
+
+Two-machine end-to-end (A asks, B answers, A's await reports answered) — that needs both machines on this build, and the
+relay redeployed.
+## [1.2.0] — 2026-10-18
+
+**Fleet chat is one group per relay.**
+
+The conversation used to be keyed from `process.cwd()`, which is the DSH process's own directory and differs per machine
+(`E:\DS` here, `/root` there). Two machines therefore computed two different keys and each panel saw only its own messages:
+"互相收不到队员聊天信息". The rule is now the simplest one that makes a fleet talk: **the relay is the group**.
+
+- one relay → one conversation, whatever project a machine is working on;
+- a trailing slash on the relay URL is the same relay;
+- the project name and the account key are deliberately NOT part of the basis: including either split the fleet into
+  separate streams, which is exactly the bug;
+- the machine id remains only as a last resort when no relay is configured, so a panel can still answer locally.
+
+### What was removed, and why it is not a loss
+
+Two intermediate designs were built and dropped in this release: keying per project (relay + project name) and a
+"同步编队全部项目" scope button that switched between the project stream and the fleet stream. With the relay as the group
+there is nothing to switch to, so the button and its scope parameter are gone rather than left as a no-op. The panel is
+simpler and the operator gets the fleet-wide conversation by default.
+
+### Verified
+
+`conversationBasis` is pure and tested: same relay unites two machines, a trailing slash does not split them, different
+relays stay apart, and a host without a relay falls back to the machine scope. 4 identity tests, 25 client-bundle tests,
+tools 122. Gate GREEN twice, 15 of 15.
+
+### Not verified
+
+Two-machine end-to-end against a live fleet; that check needs both machines on this build, which is the next step.
 ## [1.1.22] — 2026-10-18
 
 **The fleet-chat panel said "this machine has no fleet-chat identity yet" on a machine that was paired and online.**

package/codex/mcp-servers.toml

@@ -12,6 +12,6 @@
 
 [mcp_servers.w2m-fleet]
 command = "npx"
-args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.1.22", "w2m-mcp"]
+args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.2.1", "w2m-mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 60

package/lib/client.js

@@ -693,7 +693,7 @@ window.__ModuleLoader__.load({
           : null;
         const mine = id === localMachineId;
         const name = known?.name ?? message?.machine_name ?? (mine ? localMachineName : null);
-        const detail = mine ? '本机' : (known?.os ?? null);
+        const detail = mine ? '\u672c\u673a' : (known?.os ?? null);
         // A machine with no name yet is shown by a short id, never by a full UUID, and the detail says which of the
         // two it is -- "unknown" next to a UUID is what made the panel look like it was leaking identifiers.
         const shown = name ?? (id.length > 12 ? `${id.slice(0, 8)}…` : id);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "@twinsearth/w2m-dsh-plugin",
-    "version":  "1.1.22",
+    "version":  "1.2.1",
     "description":  "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
     "type":  "module",
     "main":  "lib/index.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
     "$schema":  "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
     "name":  "twinsearth-w2m-dsh",
-    "version":  "1.1.22",
+    "version":  "1.2.1",
     "description":  "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 12 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
     "license":  "MIT",
     "keywords":  [

package/src/plugin/fleet-chat-route.mjs

@@ -19,7 +19,7 @@ import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import {
-  conversationKey as deriveConversationKey, decodeTranscript, extractUserMessages, sessionDirName,
+  decodeTranscript, extractUserMessages, sessionDirName,
 } from './session-watch.mjs';
 import { createSessionSync } from './session-sync.mjs';
 
@@ -56,7 +56,17 @@ const NO_STORE = { 'cache-control': 'no-store' };
  */
 export function registerChatRoutes(ctx, deps) {
   const status = { mounted: false, reason: 'the host has no Connection service' };
-  const cwd = process.cwd();
+  /**
+   * The project this conversation belongs to.
+   *
+   * NOT `process.cwd()`: that is the DSH host's own directory, which differs per machine (E:\DS on one box, /root on
+   * another), so the derived conversation key differed per machine and every panel saw only its own messages. The
+   * operator's rule is account + project NAME; the name has to come from the project this plugin was configured for.
+   */
+  const projectDirOf = () => {
+    const configured = deps.cfg()?.projectDir;
+    return typeof configured === 'string' && configured !== '' ? configured : process.cwd();
+  };
   const sync = createSessionSync({ conversationKey: 'pending', machineId: 'pending', machineName: null });
 
   /**
@@ -81,15 +91,13 @@ export function registerChatRoutes(ctx, deps) {
       // Nothing can be keyed without a machine, and inventing one would put unrelated hosts in one conversation.
       return { error: 'CHAT_NO_IDENTITY', machineId: null, machineName: null, conversationKey: null, source: null };
     }
-    const material = typeof deps.accountMaterial === 'function' ? deps.accountMaterial() : null;
-    const basis = conversationBasis({ machineId, accountMaterial: material });
-    const fingerprint = createHash('sha256')
-      .update('w2m-conversation-basis-v1').update('\\u0000').update(basis.basis).digest('hex');
+    const basis = conversationBasis({ machineId, relayUrl: deps.cfg()?.rabbitUrl ?? null });
     resolved = {
       error: null,
       machineId,
       machineName: typeof local?.machine_name === 'string' ? local.machine_name : null,
-      conversationKey: deriveConversationKey(fingerprint, cwd),
+      // One group per relay: every machine in this fleet shares this conversation, whatever its project.
+      conversationKey: createHash('sha256').update('w2m-fleet-conversation-v1').update(basis.basis).digest('hex'),
       source: basis.source,
     };
     return resolved;
@@ -118,7 +126,7 @@ export function registerChatRoutes(ctx, deps) {
   const mirrorOnce = async () => {
     const identity = await identityOf();
     if (identity.conversationKey === null) return;
-    const file = newestTranscript(cwd);
+    const file = newestTranscript(projectDirOf());
     if (file === null) return;
     let messages;
     try { messages = extractUserMessages(decodeTranscript(readFileSync(file))); } catch { return; }
@@ -153,7 +161,11 @@ export function registerChatRoutes(ctx, deps) {
 
           const url = new URL(request.url);
           const sessionIdOf = (value) => (typeof value === 'string' ? value.trim() : '');
+          // "All projects in this fleet" is an explicit scope, not the default: the operator presses a button for it.
+          // Its key is the relay alone -- deliberately NOT the project name -- so every machine in the fleet
+          // lands in one stream. It is not a history fetch: the caller sends a floor timestamp (see the panel).
           let sessionId = '';
+          const addressing = {};
           let text = null;
           if (request.method === 'GET') {
             sessionId = sessionIdOf(url.searchParams.get('session_id'));
@@ -166,15 +178,24 @@ export function registerChatRoutes(ctx, deps) {
             }
             sessionId = sessionIdOf(body?.session_id);
             text = typeof body?.text === 'string' ? body.text : null;
+            // Addressing + correlation travel as optional fields; each is validated here so a bad one is refused with a
+            // name instead of being stored and never understood.
+            if (typeof body?.to === 'string' && body.to.trim() !== '') {
+              const to = body.to.trim();
+              if (to !== 'all' && (to.length > 64 || /\s/.test(to))) {
+                return refuse(400, 'CHAT_BAD_ADDRESS', 'to must be "all" or a machine id', 'a recipient is either the whole fleet or one machine');
+              }
+              addressing.to = to;
+            }
+            if (typeof body?.thread_id === 'string' && body.thread_id.trim() !== '') addressing.thread_id = body.thread_id.trim().slice(0, 64);
+            if (typeof body?.reply_to === 'string' && body.reply_to.trim() !== '') addressing.reply_to = body.reply_to.trim();
+          }
+          const identity = await identityOf();
+          if (identity.error !== null) {
+            return refuse(503, identity.error, 'this machine has no fleet-chat identity yet', 'pair the machine and let it derive the fleet key');
           }
-           const identity = await identityOf();
-           if (identity.error !== null) {
-             return refuse(503, identity.error, 'this machine has no fleet-chat identity yet', 'pair the machine and let it derive the fleet key');
-           }
-           // v1.1.20: the browser's session id is per-machine and no other machine can compute it, so the wire key is the
-           // conversation key (account + project directory). The browser's value is accepted and then replaced.
-           sessionId = identity.conversationKey;
-          if (sessionId === '') return refuse(400, 'CHAT_SESSION_ID_REQUIRED', '`session_id` is required', 'chat is scoped to one conversation');
+          // One group per relay: the browser sends its own session id, which is replaced here.
+          sessionId = identity.conversationKey;
           if (sessionId.length > MAX_SESSION_ID_LENGTH) {
             return refuse(400, 'CHAT_SESSION_ID_TOO_LONG', `\`session_id\` must be at most ${MAX_SESSION_ID_LENGTH} characters`, 'send the id the host gave this session');
           }
@@ -194,7 +215,11 @@ export function registerChatRoutes(ctx, deps) {
 
           try {
             if (request.method === 'GET') {
-              const query = { session_id: sessionId };
+              const query = { session_id: sessionId, for_me: '1' };
+              const threadOf = url.searchParams.get('thread_id');
+              const toOf = url.searchParams.get('to');
+              if (threadOf !== null && threadOf !== '') query.thread_id = threadOf;
+              if (toOf !== null && toOf !== '') query.to = toOf;
               const sinceMs = url.searchParams.get('since_ms');
               const limit = url.searchParams.get('limit');
               if (sinceMs !== null && /^\d+$/.test(sinceMs)) query.since_ms = sinceMs;
@@ -207,7 +232,7 @@ export function registerChatRoutes(ctx, deps) {
               }
               return Response.json({ ...listed.json, ok: true, local_machine_id: identity.machineId, local_machine_name: identity.machineName, conversation_key: sessionId, conversation_source: identity.source }, { headers: NO_STORE });
             }
-            const posted = await deps.request({ rabbitUrl, token, method: 'POST', pathname: '/v1/fleet/messages', body: { session_id: sessionId, text: text ?? '', machine_id: identity.machineId, machine_name: identity.machineName, origin: 'chat' }, signal: request.signal });
+            const posted = await deps.request({ rabbitUrl, token, method: 'POST', pathname: '/v1/fleet/messages', body: { session_id: sessionId, text: text ?? '', machine_id: identity.machineId, machine_name: identity.machineName, origin: 'chat', ...addressing }, signal: request.signal });
             if (posted?.ok !== true) {
               const code = posted?.json?.error?.code ?? posted?.error?.code ?? 'CHAT_SEND_REFUSED';
               const message = posted?.json?.error?.message ?? posted?.error?.message ?? `the relay answered HTTP ${posted?.status ?? 0}`;
@@ -232,22 +257,23 @@ export function registerChatRoutes(ctx, deps) {
   });
   return status;
 }
-
-/**
- * The material a conversation is keyed from, and which scope it represents.
- *
- * The account key is the right basis -- two machines on the same account and the same project are one conversation. But
- * the account key is derived asynchronously at stack start, and a panel that cannot answer at all is worse than a panel
- * that answers for one machine until the join lands. So the machine id is the documented fallback, and the answer says
- * which basis it used rather than leaving the caller to guess.
- *
- * @param {{machineId?: string|null, accountMaterial?: string|null}} input
- * @returns {{basis: string, source: 'account'|'machine'}|null} null when there is no machine to key on
- */
-export function conversationBasis({ machineId, accountMaterial } = {}) {
-  const machine = typeof machineId === 'string' && machineId !== '' ? machineId : null;
-  if (machine === null) return null;
-  const account = typeof accountMaterial === 'string' && accountMaterial.trim() !== '' ? accountMaterial.trim() : null;
-  if (account !== null) return { basis: 'account:' + account, source: 'account' };
-  return { basis: 'machine:' + machine, source: 'machine' };
-}
+
+/**
+ * The material a conversation is keyed from.
+ *
+ * The operator's rule, in its simplest form: **one relay is one group**. Every machine talking to the same relay shares
+ * one conversation, whatever project it is working on. Neither the project name nor the account key is part of the basis:
+ * including either split the fleet into separate streams, which is the report this replaces.
+ *
+ * The machine id stays only as a last resort for a host with no relay configured, so the panel can still answer locally.
+ *
+ * @param {{machineId?: string|null, relayUrl?: string|null}} input
+ * @returns {{basis: string, source: 'fleet'|'machine'}|null} null when there is no machine to key on
+ */
+export function conversationBasis({ machineId, relayUrl } = {}) {
+  const machine = typeof machineId === 'string' && machineId !== '' ? machineId : null;
+  if (machine === null) return null;
+  const relay = typeof relayUrl === 'string' && relayUrl.trim() !== '' ? relayUrl.trim().replace(/\/+$/, '') : null;
+  if (relay !== null) return { basis: 'fleet:' + relay, source: 'fleet' };
+  return { basis: 'machine:' + machine, source: 'machine' };
+}

package/src/plugin/tools.mjs

@@ -220,7 +220,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '1.1.22';
+const PLUGIN_VERSION = '1.2.1';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -6335,11 +6335,20 @@ export async function apply(ctx, config = {}) {
       'Fleet chat for one session: send plain text to the machines in this conversation, or read what was said. ' +
       'A refused write comes back with its named reason (quota, size, or non-text) rather than as a bare failure.',
     parameters: {
-      action: { type: 'string', enum: ['send', 'list'], description: 'send posts text; list reads the flow (default).', default: 'list' },
+      action: {
+        type: 'string',
+        enum: ['send', 'list', 'ask', 'await'],
+        description: 'send posts text; ask posts a question and returns its message id; await waits for a reply to it; list reads the flow (default).',
+        default: 'list',
+      },
       session_id: { type: 'string', description: 'Which conversation. Chat is scoped to a session, not a machine.' },
       text: { type: 'string', description: 'The message for send. Plain text, UTF-8, at most 4 KiB.' },
       since_ms: { type: 'number', description: 'For list: only messages newer than this relay timestamp.' },
       limit: { type: 'number', description: 'For list: how many of the newest messages (default 50).' },
+      to: { type: 'string', description: 'For send/ask: "all" (the fleet group, the default) or one machine_id.' },
+      thread_id: { type: 'string', description: 'For send/ask: group this message into a named thread (at most 64 characters).' },
+      reply_to: { type: 'string', description: 'For send/ask: the message_id this message answers. For await: the message_id to wait for a reply to.' },
+      timeout_ms: { type: 'number', description: 'For await: how long to wait before reporting a timeout (default 60000, capped at 300000). A timeout is a value, not an error.' },
     },
     output: jsonOutput,
     presentCall: (args) => ({ card: 'generic', title: 'w2m chat ' + (typeof args?.action === 'string' ? args.action : 'list'), kind: args?.action === 'send' ? 'write' : 'read', rawInput: {} }),
@@ -6356,14 +6365,46 @@ export async function apply(ctx, config = {}) {
       // one reported W2M_NO_TOKEN on a machine that was paired and answering every other call.
       const token = await resolveToken(cfg);
       if (token === null) throw new W2MError('W2M_NO_TOKEN', 'W2M_NO_TOKEN: this machine has no device token, so chat cannot be authenticated', { hint: 'pair this machine first (autoStartAgent or a pairing code), then retry' });
-      if (action === 'send') {
-        const posted = await request({ rabbitUrl, token, signal: exec?.signal, method: 'POST', pathname: '/v1/fleet/messages', body: { session_id: sessionId, text: typeof args?.text === 'string' ? args.text : '' } });
+      // Addressing + correlation travel only when the caller supplied them, so a plain broadcast stays byte-identical.
+      const addressing = {};
+      if (typeof args?.to === 'string' && args.to.trim() !== '') {
+        const to = args.to.trim();
+        if (to !== 'all' && (to.length > 64 || /\s/.test(to))) {
+          throw new W2MError('W2M_CHAT_ADDRESS', 'W2M_CHAT_ADDRESS: to must be "all" or a machine id', { hint: 'a recipient is either the whole fleet or one machine listed by w2m_devices' });
+        }
+        addressing.to = to;
+      }
+      if (typeof args?.thread_id === 'string' && args.thread_id.trim() !== '') addressing.thread_id = args.thread_id.trim().slice(0, 64);
+      if (typeof args?.reply_to === 'string' && args.reply_to.trim() !== '') addressing.reply_to = args.reply_to.trim();
+
+      if (action === 'await') {
+        // Waiting for an ANSWER is a state machine, and a timeout is a value the caller reads rather than an exception
+        // that loses the question. The question stays in the flow, so it can still be answered later.
+        const target = typeof args?.reply_to === 'string' ? args.reply_to.trim() : '';
+        if (target === '') throw new W2MError('W2M_CHAT_AWAIT', 'W2M_CHAT_AWAIT: reply_to is required for await', { hint: 'pass the message_id returned by ask' });
+        const timeoutMs = Number.isFinite(args?.timeout_ms) ? Math.max(1000, Math.min(args.timeout_ms, 300000)) : 60000;
+        const startedAt = Date.now();
+        for (;;) {
+          throwIfAborted(exec?.signal);
+          const reply = await request({ rabbitUrl, token, signal: exec?.signal, method: 'GET', pathname: '/v1/fleet/messages', query: { session_id: sessionId, reply_to: target, limit: '10' } });
+          const found = Array.isArray(reply?.json?.messages) ? reply.json.messages : [];
+          if (found.length > 0) return JSON.stringify({ ok: true, action, state: 'answered', reply_to: target, replies: found });
+          if (Date.now() - startedAt >= timeoutMs) {
+            return JSON.stringify({ ok: true, action, state: 'timeout', reply_to: target, waited_ms: Date.now() - startedAt, hint: 'the question is still in the flow and can be answered later' });
+          }
+          await new Promise((resolve) => { setTimeout(resolve, 1500); });
+        }
+      }
+      if (action === 'send' || action === 'ask') {
+        const posted = await request({ rabbitUrl, token, signal: exec?.signal, method: 'POST', pathname: '/v1/fleet/messages', body: { session_id: sessionId, text: typeof args?.text === 'string' ? args.text : '', ...addressing } });
         if (posted?.ok !== true) {
           const code = posted?.json?.error?.code ?? posted?.error?.code ?? 'W2M_CHAT_SEND';
           throw new W2MError('W2M_CHAT_SEND', code + ': the message was refused', { reason_code: code, hint: 'quota, size and non-text each need a different answer' });
         }
-        return JSON.stringify({ ok: true, action, message: posted.json?.message ?? null });
+        return JSON.stringify({ ok: true, action, message: posted.json?.message ?? null, message_id: posted.json?.message?.message_id ?? null });
       }
+      if (typeof args?.thread_id === 'string' && args.thread_id.trim() !== '') query.thread_id = args.thread_id.trim();
+      if (typeof args?.to === 'string' && args.to.trim() !== '') query.to = args.to.trim();
       const query = { session_id: sessionId };
       if (Number.isFinite(args?.since_ms)) query.since_ms = String(args.since_ms);
       if (Number.isInteger(args?.limit)) query.limit = String(args.limit);

package/src/relay/fleet-messages.mjs

@@ -88,25 +88,46 @@ export function createFleetMessages(options = {}) {
     const text = input.text;
     if (text.trim() === '') return { ok: false, code: 'EMPTY_TEXT' };
     // Reject control characters (except tab/newline): "plain text" is a contract, not a preference.
-    // Control characters are the thing being rejected here, so the rule that forbids them in a pattern
-    // does not apply -- the escape IS the contract.
-    // eslint-disable-next-line no-control-regex
+    // eslint-disable-next-line no-control-regex
     if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.test(text)) return { ok: false, code: 'NOT_TEXT' };
     const bytes = Buffer.byteLength(text, 'utf8');
     if (bytes > maxMessageBytes) return { ok: false, code: 'MESSAGE_TOO_LARGE', detail: { bytes, maxBytes: maxMessageBytes } };
 
+    // Addressing: 'all' is the group, a machine id is one recipient. ONE row either way -- N copies for N recipients
+    // would multiply the byte budget by the fleet size for no extra meaning; visibility is a filter at read time.
+    const to = typeof input?.to === 'string' && input.to.trim() !== '' ? input.to.trim() : 'all';
+    if (to !== 'all' && (to.length > 64 || /\s/.test(to))) return { ok: false, code: 'BAD_ADDRESS' };
+    // Correlation: a thread groups a conversation, reply_to points at the message being answered, turn orders the
+    // exchange inside one thread. Plain fields, validated rather than trusted.
+    const threadId = typeof input?.thread_id === 'string' && input.thread_id.trim() !== ''
+      ? input.thread_id.trim().slice(0, 64)
+      : null;
+    const replyTo = typeof input?.reply_to === 'string' && input.reply_to.trim() !== '' ? input.reply_to.trim() : null;
+
     const before = usage();
     const limit = limitBytes();
     if (before.used_24h_bytes + bytes > limit) {
       return { ok: false, code: 'FLEET_QUOTA_EXCEEDED', detail: { used_24h_bytes: before.used_24h_bytes, limit_bytes: limit, bytes } };
     }
 
+    // A reply must point at something that exists in the SAME session: a dangling reply_to makes a thread unreadable.
+    const existing = sessions.get(sessionId) ?? [];
+    if (replyTo !== null && !existing.some((m) => m.message_id === replyTo)) {
+      return { ok: false, code: 'REPLY_TARGET_MISSING', detail: { reply_to: replyTo } };
+    }
+    const threadOf = threadId ?? (replyTo !== null ? (existing.find((m) => m.message_id === replyTo)?.thread_id ?? null) : null);
+    const turn = existing.filter((m) => (threadOf === null ? m.thread_id === null : m.thread_id === threadOf)).length + 1;
+
     seq += 1;
     const message = {
       message_id: 'msg-' + String(seq).padStart(6, '0'),
       session_id: sessionId,
       fleet_id: typeof input?.fleet_id === 'string' ? input.fleet_id : null,
       machine_id: machineId,
+      to,
+      thread_id: threadOf,
+      reply_to: replyTo,
+      turn,
       text,
       at_ms: now(),
       bytes,
@@ -122,9 +143,16 @@ export function createFleetMessages(options = {}) {
   }
 
   /** Read one session's flow. \`since_ms\` is exclusive; the order is the order it was said. */
-  function list({ session_id: sessionId, since_ms: sinceMs = null, limit = 50 } = {}) {
+  function list({ session_id: sessionId, since_ms: sinceMs = null, limit = 50, for_machine_id: forMachine = null,
+    thread_id: threadId = null, to: toFilter = null } = {}) {
     const rows = sessions.get(sessionId) ?? [];
-    const filtered = Number.isFinite(sinceMs) ? rows.filter((m) => m.at_ms > sinceMs) : rows;
+    let filtered = Number.isFinite(sinceMs) ? rows.filter((m) => m.at_ms > sinceMs) : rows;
+    // A reader sees the group and what was addressed to it, never another machine's private message.
+    if (typeof forMachine === 'string' && forMachine !== '') {
+      filtered = filtered.filter((m) => (m.to ?? 'all') === 'all' || m.to === forMachine || m.machine_id === forMachine);
+    }
+    if (typeof threadId === 'string' && threadId !== '') filtered = filtered.filter((m) => m.thread_id === threadId);
+    if (typeof toFilter === 'string' && toFilter !== '') filtered = filtered.filter((m) => (m.to ?? 'all') === toFilter);
     const capped = filtered.slice(-Math.max(1, Math.min(limit, 200)));
     return { ok: true, messages: capped.map((m) => ({ ...m })), count: capped.length };
   }

package/src/relay/server.mjs

@@ -1052,6 +1052,9 @@ export class RelayServer {
         session_id: body.session_id,
         fleet_id: typeof body.fleet_id === 'string' ? body.fleet_id : null,
         machine_id: device.machine_id,
+        to: body.to,
+        thread_id: body.thread_id,
+        reply_to: body.reply_to,
         text: body.text,
       });
       if (posted.ok !== true) {
@@ -1098,6 +1101,11 @@ export class RelayServer {
         session_id: url.searchParams.get('session_id') ?? '',
         since_ms: sinceRaw === null ? null : Number(sinceRaw),
         limit: limitRaw === null ? 50 : Number(limitRaw),
+        // Addressing/correlation filters. `for_me=1` is answered from the authenticated device identity, never from a
+        // caller-supplied machine id: a reader must not be able to ask for another machine's private messages.
+        for_machine_id: url.searchParams.get('for_me') === '1' ? device.machine_id : null,
+        thread_id: url.searchParams.get('thread_id'),
+        to: url.searchParams.get('to'),
       });
       return sendJson(res, 200, {
         protocol_version: PROTOCOL_VERSION,