@twinsearth/w2m-dsh-plugin 1.2.0 → 1.2.2

package/src/plugin/dataflow.mjs

@@ -0,0 +1,72 @@
+/**
+ * Data flow across the fleet: map results that are too big to return inline travel as blobs, and the reduce step names
+ * exactly which blob it read.
+ *
+ * ## Why a plan instead of a pipe
+ *
+ * Machines do not send data to each other directly: the relay is the only channel every machine can reach, and it already
+ * stores content-addressed blobs. So the shape is map -> PUT blob -> reduce by sha256. The decisions worth testing are the
+ * boundaries: when an output is inline, when it becomes a blob, and what happens when a blob a reduce depends on is not
+ * there. A pipeline that silently drops a shard is worse than one that fails.
+ */
+
+/** Stage stdout at or below this travels inline in the result envelope. */
+export const MAX_INLINE_BYTES = 64 * 1024;
+
+/** Past this a stage output is not a result any more: it is a data problem the operator has to see. */
+export const HARD_CAP_BYTES = 16 * 1024 * 1024;
+
+/**
+ * Decide how one machine's stage output travels.
+ *
+ * @param {{machineId?: string, stageIndex?: number, stdoutBytes?: number}} input
+ * @returns {{ok: true, mode: 'inline'|'blob', stdoutBytes: number} | {ok: false, code: string, detail: object}}
+ */
+export function planStageOutput(input = {}) {
+  const machineId = typeof input.machineId === 'string' && input.machineId !== '' ? input.machineId : null;
+  if (machineId === null) return { ok: false, code: 'STAGE_MACHINE_MISSING', detail: {} };
+  const stdoutBytes = Number.isFinite(input.stdoutBytes) ? Math.max(0, Math.floor(input.stdoutBytes)) : 0;
+  if (stdoutBytes > HARD_CAP_BYTES) {
+    return { ok: false, code: 'STAGE_OUTPUT_TOO_LARGE', detail: { machineId, stdoutBytes, hardCapBytes: HARD_CAP_BYTES } };
+  }
+  return { ok: true, mode: stdoutBytes <= MAX_INLINE_BYTES ? 'inline' : 'blob', stdoutBytes };
+}
+
+const SHA256 = /^[0-9a-f]{64}$/;
+
+/**
+ * Build the reduce input list from the map results.
+ *
+ * Every map machine must contribute exactly one entry: inline text is carried as-is, a blob result must name a sha256.
+ * A missing or malformed hash is refused by name -- the reduce step must never run on a partial fleet and call the answer
+ * complete.
+ *
+ * @param {{results?: Array<{machine_id?: string, mode?: string, stdout?: string, blob_sha256?: string}>,
+ *          reducerMachineId?: string}} input
+ * @returns {{ok: true, reducerMachineId: string, inputs: Array<{machine_id: string, mode: 'inline'|'blob', stdout?: string, sha256?: string}>} |
+ *           {ok: false, code: string, detail: object}}
+ */
+export function buildReducePlan(input = {}) {
+  const reducer = typeof input.reducerMachineId === 'string' && input.reducerMachineId !== '' ? input.reducerMachineId : null;
+  if (reducer === null) return { ok: false, code: 'REDUCER_MISSING', detail: {} };
+  const results = Array.isArray(input.results) ? input.results : null;
+  if (results === null || results.length === 0) return { ok: false, code: 'NO_MAP_RESULTS', detail: {} };
+
+  const seen = new Set();
+  const inputs = [];
+  for (const result of results) {
+    const machineId = typeof result?.machine_id === 'string' && result.machine_id !== '' ? result.machine_id : null;
+    if (machineId === null) return { ok: false, code: 'MAP_MACHINE_MISSING', detail: {} };
+    if (seen.has(machineId)) return { ok: false, code: 'MAP_MACHINE_DUPLICATE', detail: { machineId } };
+    seen.add(machineId);
+    const mode = result?.mode === 'blob' ? 'blob' : 'inline';
+    if (mode === 'blob') {
+      const sha = typeof result?.blob_sha256 === 'string' ? result.blob_sha256.toLowerCase() : '';
+      if (!SHA256.test(sha)) return { ok: false, code: 'BLOB_MISSING', detail: { machineId, sha256: result?.blob_sha256 ?? null } };
+      inputs.push({ machine_id: machineId, mode, sha256: sha });
+    } else {
+      inputs.push({ machine_id: machineId, mode, stdout: typeof result?.stdout === 'string' ? result.stdout : '' });
+    }
+  }
+  return { ok: true, reducerMachineId: reducer, inputs };
+}

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

@@ -102,6 +102,36 @@ export function registerChatRoutes(ctx, deps) {
     };
     return resolved;
   };
+
+  /**
+   * The machine ids this fleet knows, cached for five seconds.
+   *
+   * Only the HOST can check a single recipient: the relay validates the shape of a recipient, not whether a machine
+   * with that id exists. Null means the roster could not be read at all, which is deliberately a different answer from
+   * "no such machine" -- a relay outage must not be reported as a typo in the recipient.
+   */
+  let rosterAtMs = 0;
+  let rosterIds = null;
+  const knownMachineIds = async (signal) => {
+    if (rosterIds !== null && Date.now() - rosterAtMs < 5000) return rosterIds;
+    try {
+      const cfg = deps.cfg();
+      const rabbitUrl = cfg?.rabbitUrl ?? null;
+      if (rabbitUrl === null) return null;
+      const token = await deps.resolveToken();
+      if (typeof token !== 'string' || token === '') return null;
+      const listed = await deps.request({ rabbitUrl, token, method: 'GET', pathname: '/v1/devices', signal });
+      if (listed?.ok !== true) return null;
+      const devices = Array.isArray(listed.json?.devices) ? listed.json.devices : null;
+      if (devices === null) return null;
+      const ids = devices.map((device) => device?.machine_id).filter((id) => typeof id === 'string');
+      rosterIds = ids;
+      rosterAtMs = Date.now();
+      return ids;
+    } catch {
+      return null;
+    }
+  };
 
   /** Post one batch into the relay using the machine's device token, exactly as the browser route does. */
   const postToRelay = async (identity, payload) => {
@@ -165,6 +195,7 @@ export function registerChatRoutes(ctx, deps) {
           // 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'));
@@ -177,6 +208,17 @@ 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) {
@@ -203,7 +245,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;
@@ -216,7 +262,17 @@ 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 });
+            // Addressing (v1.2.2): a single recipient must exist in THIS fleet.
+            if (typeof addressing.to === 'string' && addressing.to !== 'all') {
+              const roster = await knownMachineIds(request.signal);
+              if (roster === null) {
+                return refuse(503, 'CHAT_ROSTER_UNAVAILABLE', 'the machine roster could not be read', 'a recipient cannot be checked without the relay roster');
+              }
+              if (!roster.includes(addressing.to)) {
+                return refuse(400, 'CHAT_UNKNOWN_RECIPIENT', 'no machine with that id is in this fleet', 'send all, or a machine_id listed by w2m_devices');
+              }
+            }
+            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}`;

package/src/plugin/intents.mjs

@@ -0,0 +1,137 @@
+/**
+ * Structured intents: the deterministic half of "natural language becomes an action".
+ *
+ * ## What this is not
+ *
+ * It does not understand free text. A machine in this fleet runs an allow-list of commands; asking an LLM on the remote
+ * side to invent a command would defeat the allow-list and put an unbounded decision on a machine nobody is sitting at.
+ * So the caller (the DSH agent, which IS the model) turns language into one of these intents, and this module decides
+ * whether that intent maps to an allowed command. Anything unrecognised is REFUSED by name, never guessed.
+ *
+ * ## Why a catalog instead of string templates from the caller
+ *
+ * A caller that supplies its own argv is `w2m_run` with extra steps. The value here is the closed set: each action has a
+ * fixed argv shape, typed parameters, and a risk level, so an intent cannot smuggle an argument that the allow-list was
+ * meant to stop (a path, a flag that loads code, a shell metacharacter).
+ */
+
+/** The closed set. `argv(params)` receives validated parameters only. */
+export const INTENTS = {
+  'run-tests': {
+    risk: 'read',
+    description: 'Run the project test suite: node --test',
+    params: {},
+    argv: () => ['node', '--test'],
+  },
+  'node-version': {
+    risk: 'read',
+    description: 'Report the Node version on the machine: node --version',
+    params: {},
+    argv: () => ['node', '--version'],
+  },
+  'git-status': {
+    risk: 'read',
+    description: 'Show the working tree status: git status --porcelain',
+    params: {},
+    argv: () => ['git', 'status', '--porcelain'],
+  },
+  'git-head': {
+    risk: 'read',
+    description: 'Report the commit HEAD points at: git rev-parse HEAD',
+    params: {},
+    argv: () => ['git', 'rev-parse', 'HEAD'],
+  },
+  'fleet-facts': {
+    risk: 'read',
+    description: 'Run the demo fact collector: node src/facts.mjs',
+    params: {},
+    argv: () => ['node', 'src/facts.mjs'],
+  },
+  'shard-probe': {
+    risk: 'read',
+    description: 'Run the demo shard probe with one non-negative integer: node src/shard.mjs <n>',
+    params: { n: 'non-negative integer' },
+    argv: (params) => ['node', 'src/shard.mjs', String(params.n)],
+  },
+};
+
+/** The catalog as data, for a tool/README to list without duplicating it. */
+export function listIntents() {
+  return Object.entries(INTENTS).map(([action, spec]) => ({
+    action,
+    risk: spec.risk,
+    description: spec.description,
+    params: spec.params,
+  }));
+}
+
+/** A single argument must be a plain token: no spaces, no shell metacharacters, no path separators. */
+function tokenIsSafe(value) {
+  return typeof value === 'string' && value !== '' && value.length <= 128 && !/[\s;&|$`<>\\/"']/.test(value);
+}
+
+/** Render an argv the way the allow-list matcher compares it (space separated), for the refusal message. */
+function renderArgv(argv) {
+  return argv.join(' ');
+}
+
+/**
+ * Map one structured intent onto an allow-listed argv.
+ *
+ * @param {{action?: string, params?: object}} intent
+ * @param {{allowedCommands?: string[]}} [options] the machine's allow-list, as the agent sees it
+ * @returns {{ok: true, action: string, argv: string[], risk: string, command: string} |
+ *           {ok: false, code: string, detail?: object, hint: string}}
+ */
+export function resolveIntent(intent, options = {}) {
+  const action = typeof intent?.action === 'string' ? intent.action.trim() : '';
+  if (action === '') {
+    return { ok: false, code: 'INTENT_MISSING', hint: 'pass {"action": "<one of w2m_intent list>", "params": {...}}' };
+  }
+  const spec = INTENTS[action];
+  if (spec === undefined) {
+    return {
+      ok: false,
+      code: 'INTENT_UNKNOWN',
+      detail: { action, known: Object.keys(INTENTS) },
+      hint: 'this fleet does not invent commands: pick one of the catalog actions',
+    };
+  }
+
+  const params = intent?.params ?? {};
+  if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+    return { ok: false, code: 'INTENT_PARAM_INVALID', detail: { action }, hint: 'params must be an object' };
+  }
+  const expected = Object.keys(spec.params);
+  for (const key of Object.keys(params)) {
+    if (!expected.includes(key)) {
+      return { ok: false, code: 'INTENT_PARAM_UNKNOWN', detail: { action, key, expected }, hint: 'unknown parameter for this action' };
+    }
+  }
+  if (action === 'shard-probe') {
+    const n = params.n;
+    if (!Number.isInteger(n) || n < 0) {
+      return { ok: false, code: 'INTENT_PARAM_INVALID', detail: { action, param: 'n', expected: 'non-negative integer' }, hint: 'n must be a non-negative integer' };
+    }
+  }
+  // Only CALLER-SUPPLIED values are shape-checked: the fixed argv comes from this catalog, where a path separator is
+  // normal. A metacharacter in a caller value is how a command becomes something else.
+  for (const key of Object.keys(params)) {
+    const value = params[key];
+    if (typeof value === 'string' && !tokenIsSafe(value)) {
+      return { ok: false, code: 'INTENT_ARG_UNSAFE', detail: { action, parameter: key }, hint: 'a parameter may not contain spaces, quotes or shell metacharacters' };
+    }
+  }
+  const argv = spec.argv(params);
+  const command = renderArgv(argv);
+  const allowed = Array.isArray(options.allowedCommands) ? options.allowedCommands : null;
+  if (allowed !== null && !allowed.includes(command)) {
+    return {
+      ok: false,
+      code: 'INTENT_NOT_ALLOWED',
+      detail: { action, command, allowedCommands: allowed },
+      hint: 'the machine allow-list does not contain this command; ask the operator to add it',
+    };
+  }
+  return { ok: true, action, argv, risk: spec.risk, command };
+}

package/src/plugin/memory-view.mjs

@@ -0,0 +1,60 @@
+/**
+ * A readable view over memory records.
+ *
+ * The memory log is JSONL rows of mixed kinds (finished task, conclusion, accepted block). Reading it as a model means
+ * reading what it will answer with; reading it as a person means reading what happened, in order, with the counts that
+ * answer "have we done this before". Both are here, and the view never invents a field a record does not carry: an unknown
+ * row shape is shown as itself rather than dropped, because a memory that silently hides rows is worse than a noisy one.
+ */
+
+/** The fields that make one row readable, in the order a person scans them. */
+const SUMMARY_FIELDS = ['status', 'exit_code', 'command', 'conclusion', 'kind'];
+
+function textOf(value) {
+  if (typeof value === 'string') return value;
+  if (value === null || value === undefined) return '';
+  try { return JSON.stringify(value); } catch { return String(value); }
+}
+
+/** One line per record: time, machine, then the first informative field. */
+function lineOf(record, index) {
+  const at = typeof record?.at === 'string' ? record.at : (Number.isFinite(record?.at_ms) ? new Date(record.at_ms).toISOString() : null);
+  const machine = typeof record?.machine_name === 'string' && record.machine_name !== ''
+    ? record.machine_name
+    : (typeof record?.machine_id === 'string' ? record.machine_id.slice(0, 8) : 'unknown');
+  const field = SUMMARY_FIELDS.find((name) => record?.[name] !== undefined && record[name] !== null) ?? null;
+  const detail = field === null ? '' : ' ' + field + '=' + textOf(record[field]);
+  const command = typeof record?.command === 'string' ? ' ' + record.command : '';
+  const head = at === null ? '(no time)' : at.replace('T', ' ').slice(0, 19);
+  const raw = head + '  ' + machine + detail + command;
+  return { index, text: raw.length > 160 ? raw.slice(0, 157) + '...' : raw, machine, at };
+}
+
+/**
+ * @param {Array<object>} records newest first, as the memory reader returns them
+ * @param {{limit?: number}} [options]
+ * @returns {{count: number, shown: number, truncated: boolean, by_machine: object, by_status: object, lines: object[]}}
+ */
+export function renderMemoryView(records, options = {}) {
+  const list = Array.isArray(records) ? records : [];
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 50;
+  const byMachine = {};
+  const byStatus = {};
+  for (const record of list) {
+    const machine = typeof record?.machine_name === 'string' && record.machine_name !== ''
+      ? record.machine_name
+      : (typeof record?.machine_id === 'string' ? record.machine_id.slice(0, 8) : 'unknown');
+    byMachine[machine] = (byMachine[machine] ?? 0) + 1;
+    const status = typeof record?.status === 'string' ? record.status : (typeof record?.kind === 'string' ? record.kind : 'unknown');
+    byStatus[status] = (byStatus[status] ?? 0) + 1;
+  }
+  const shown = list.slice(0, limit);
+  return {
+    count: list.length,
+    shown: shown.length,
+    truncated: list.length > shown.length,
+    by_machine: byMachine,
+    by_status: byStatus,
+    lines: shown.map(lineOf),
+  };
+}

package/src/plugin/tools.mjs

@@ -183,6 +183,9 @@ import {
 // v1.1.17 chat: the host route behind the composer's fleet-chat panel. The relay side and the
 // `w2m_chat` tool shipped first; this is the browser-facing half that was still missing.
 import { registerChatRoutes } from './fleet-chat-route.mjs';
+import { createFleetCouncil, fleetCouncilThread } from './council-fleet.mjs';
+import { renderMemoryView } from './memory-view.mjs';
+import { listIntents, resolveIntent } from './intents.mjs';
 // v0.7.0: the LAN hint layer. Imported here and used in exactly one place (`w2m_devices`); see the
 // module header for why a discovered device is a candidate to *ask* and never an authorisation.
 import { createDiscoverySource } from './mdns-discover.mjs';
@@ -220,7 +223,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.2.0';
+const PLUGIN_VERSION = '1.2.2';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -3390,6 +3393,10 @@ export async function apply(ctx, config = {}) {
    */
   const councilSessions = createCouncilSessions();
 
+  /** v1.2.2: the machine-wide council. Ballots arrive as chat messages, so this is state + arithmetic; the transport is
+   * the fleet chat itself (thread `council-<id>`), which already carries `to` / `thread_id` / `reply_to` since 1.2.1. */
+  const fleetCouncil = createFleetCouncil({});
+
   // v0.6.1: the two browser routes behind the composer's target control. Additive and optional: a
   // host without `connection.fetch` still gets every tool, and `w2m_status` reports the absence  -   // which is the honest place for it, since a host that has no Connection at all is simply not a web
   // composition and does not need a warning on every headless run.
@@ -5234,7 +5241,7 @@ export async function apply(ctx, config = {}) {
        */
       action: {
         type: 'string',
-        enum: ['read', 'publish', 'pull', 'latest', 'diff', 'merge'],
+        enum: ['read', 'publish', 'pull', 'latest', 'diff', 'merge', 'append'],
         description:
           'read (default) = answer from memory. publish = upload the curated collective memory '
           + '(`fleet-memory.md`) to the relay as a content-addressed blob and return its SHA-256. latest = ask the '
@@ -5252,6 +5259,19 @@ export async function apply(ctx, config = {}) {
           + 'relay but belongs to another fleet is reported as not found, exactly like a hash that was never '
           + 'stored -- a distinguishable refusal would confirm to a prober which hashes this relay holds.',
       },
+      records: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          'For action="append": one append-only record per string. Appending is the unit of change, so two machines ' +
+          'can add records without one overwriting the other document.',
+      },
+      if_revision: {
+        type: 'number',
+        description:
+          'For action="append": the revision you read. A stale value is refused with 409 and the records you have not ' +
+          'read, because applying it on top of something you never saw is a silent overwrite.',
+      },
       scope: {
         type: 'string',
         enum: ['local', 'fleet'],
@@ -5340,6 +5360,64 @@ export async function apply(ctx, config = {}) {
     async execute(args, exec) {
       throwIfAborted(exec?.signal);
 
+      /**
+       * v1.2.2: append records to the shared memory under compare-and-swap.
+       *
+       * A 409 is returned AS-IS, with the revision and what the caller has not read. Retrying here would turn a visible
+       * conflict into a silent overwrite, which is the whole reason the relay keeps a revision instead of merging.
+       */
+      if (typeof args?.action === 'string' && args.action === 'append') {
+        const doc = typeof args?.scope === 'string' && args.scope.trim() !== '' ? args.scope.trim() : 'fleet';
+        const incoming = Array.isArray(args?.records)
+          ? args.records
+          : (typeof args?.records === 'string' ? [args.records] : []);
+        const records = incoming.filter((entry) => typeof entry === 'string' && entry.trim() !== '');
+        if (records.length === 0) {
+          throw new W2MError('W2M_MEMORY_APPEND', 'W2M_MEMORY_APPEND: records is required for append', {
+            hint: 'pass records: ["a fact the fleet should keep", ...]',
+          });
+        }
+        const appendUrl = cfg.rabbitUrl ?? null;
+        if (appendUrl === null) {
+          throw new W2MError('W2M_NO_RELAY', 'W2M_NO_RELAY: no relay is configured, so shared memory cannot be written', {
+            hint: 'set rabbitUrl in the profile patch',
+          });
+        }
+        const appendToken = await resolveToken(cfg);
+        if (appendToken === null) {
+          throw new W2MError('W2M_NO_TOKEN', 'W2M_NO_TOKEN: this machine has no device token, so shared memory cannot be written', {
+            hint: 'pair this machine first, then retry',
+          });
+        }
+        const appendBody = { records };
+        if (Number.isInteger(args?.if_revision)) appendBody.if_revision = args.if_revision;
+        const appended = await request({
+          rabbitUrl: appendUrl,
+          token: appendToken,
+          method: 'PUT',
+          pathname: '/v1/fleet/memory/' + encodeURIComponent(doc),
+          body: appendBody,
+          signal: exec?.signal,
+        });
+        if (appended?.ok !== true) {
+          return JSON.stringify({
+            ok: false,
+            action: 'append',
+            doc,
+            status: appended?.status ?? 0,
+            code: appended?.json?.error?.code ?? appended?.error?.code ?? 'W2M_MEMORY_APPEND',
+            detail: appended?.json?.detail ?? null,
+          });
+        }
+        return JSON.stringify({
+          ok: true,
+          action: 'append',
+          doc,
+          revision: appended.json?.revision ?? null,
+          appended: appended.json?.appended ?? 0,
+        });
+      }
+
       /**
        * v1.0.7 (#1c): publish the collective memory as a content-addressed blob.
        *
@@ -6095,7 +6173,8 @@ export async function apply(ctx, config = {}) {
           skipped_lines: current.skipped,
           truncated: current.truncated,
           status_tally: tally(current.records),
-          records: current.records,
+          records: current.records,
+          view: renderMemoryView(current.records),
           ...(previous === null
             ? {}
             : {
@@ -6335,11 +6414,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 +6444,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);
@@ -6373,6 +6493,40 @@ export async function apply(ctx, config = {}) {
     },
   }));
 
+  /**
+   * v1.2.2: structured intents -- the deterministic half of "say it in words, run it on the machine".
+   *
+   * The caller is the model, and it turns language into one of a CLOSED set of intents; this tool maps that intent to an
+   * allow-listed argv or refuses it by name. Free text is deliberately not interpreted here: a remote machine runs an
+   * allow-list, and a model inventing a command on its behalf is exactly what the list exists to stop.
+   */
+  ctx.tools.register(defineTool({
+    name: 'w2m_intent',
+    description:
+      'Map a structured intent to an allow-listed command. Actions: run-tests, node-version, git-status, git-head, ' +
+      'fleet-facts, shard-probe. Unknown actions and unknown parameters are refused by name rather than guessed, and a ' +
+      'command the machine allow-list does not carry is refused with the list it checked.',
+    parameters: {
+      action: { type: 'string', description: 'The catalog action; call with action:"list" to read the catalog.' },
+      params: { type: 'object', description: 'Action parameters, for example { n: 3 } for shard-probe.' },
+    },
+    output: jsonOutput,
+    presentCall: (args) => ({ card: 'generic', title: 'w2m intent ' + (typeof args?.action === 'string' ? args.action : '?'), kind: 'read', rawInput: {} }),
+    async execute(args, exec) {
+      throwIfAborted(exec?.signal);
+      const action = typeof args?.action === 'string' ? args.action.trim() : '';
+      if (action === '' || action === 'list') {
+        return JSON.stringify({ ok: true, action: 'list', intents: listIntents() });
+      }
+      const resolved = resolveIntent({ action, params: args?.params }, { allowedCommands: cfg.allowedCommands ?? null });
+      if (resolved.ok !== true) {
+        return JSON.stringify({ ok: false, action, code: resolved.code, detail: resolved.detail ?? null, hint: resolved.hint });
+      }
+      return JSON.stringify({ ok: true, action, argv: resolved.argv, command: resolved.command, risk: resolved.risk });
+    },
+  }));
+
+
   /**
    * v0.37.0: the eleventh tool -- a question put to a council, and the outcome read back with its dissent.
    *
@@ -6402,7 +6556,7 @@ export async function apply(ctx, config = {}) {
     parameters: {
       action: {
         type: 'string',
-        enum: ['open', 'advance', 'assign', 'argue', 'vote', 'decide', 'record', 'state', 'decision', 'list'],
+        enum: ['open', 'advance', 'assign', 'argue', 'vote', 'decide', 'record', 'state', 'decision', 'list', 'fleet-open', 'fleet-vote', 'fleet-decide', 'fleet-state', 'fleet-list'],
         description: 'What to do. "open" starts a council, "state" reports one mid-flight, "decision" reads a sealed one back with its dissent.',
         default: 'state',
       },
@@ -6433,6 +6587,37 @@ export async function apply(ctx, config = {}) {
       const action = typeof args?.action === 'string' ? args.action : 'state';
       const id = typeof args?.council_id === 'string' ? args.council_id : null;
 
+      // v1.2.2: the FLEET council. Same decision rule as the single-machine one (reproducible weights, a tie is a
+      // refusal); the difference is transport -- ballots are chat messages on `council-<id>`, so every machine can read
+      // the same ballots and recount to the same outcome.
+      if (typeof action === 'string' && action.startsWith('fleet-')) {
+        const threadId = fleetCouncilThread(id);
+        if (action === 'fleet-open') {
+          const opened = fleetCouncil.open({ councilId: id, question: typeof args?.question === 'string' ? args.question : '', openedByMachineId: 'local' });
+          return JSON.stringify({ ok: opened.ok, action, council_id: id, thread_id: threadId, reason_code: opened.code ?? null, council: opened.council ?? null });
+        }
+        if (action === 'fleet-vote') {
+          const voted = fleetCouncil.vote({
+            councilId: id,
+            machineId: typeof args?.participant === 'string' && args.participant !== '' ? args.participant : 'local',
+            choice: args?.choice,
+            reason: args?.reason ?? null,
+            authority: args?.authority ?? null,
+            reputation: args?.reputation ?? null,
+          });
+          return JSON.stringify({ ok: voted.ok, action, council_id: id, thread_id: threadId, reason_code: voted.code ?? null, council: voted.council ?? null });
+        }
+        if (action === 'fleet-decide') {
+          const decided = fleetCouncil.decide({ councilId: id });
+          return JSON.stringify({ ok: decided.ok, action, council_id: id, thread_id: threadId, reason_code: decided.code ?? null, detail: decided.detail ?? null, council: decided.council ?? null });
+        }
+        if (action === 'fleet-list') {
+          return JSON.stringify({ ok: true, action, ...fleetCouncil.list() });
+        }
+        const read = fleetCouncil.state({ councilId: id });
+        return JSON.stringify({ ok: read.ok, action, council_id: id, thread_id: threadId, reason_code: read.code ?? null, council: read.council ?? null });
+      }
+
       if (action === 'list') {
         return JSON.stringify({ ok: true, action, ...councilSessions.ids(), phases: PHASES, roles: [...ROLES] });
       }