@twinsearth/w2m-dsh-plugin 1.2.1 → 1.2.3

package/src/plugin/council-fleet.mjs

@@ -0,0 +1,221 @@
+/**
+ * A council whose members are machines, not callers in one process.
+ *
+ * ## What is shared with the single-machine council, and what is not
+ *
+ * The RULE is shared: a vote's weight is a pure function of the numbers on its ballot (authority and reputation), so any
+ * machine that holds the same ballots computes the same outcome; and a tie is a REFUSAL, not a coin toss, because a split
+ * council is exactly the case a person has to look at.
+ *
+ * The TRANSPORT is different. A single-machine council holds its ballots in memory; a fleet council's ballots arrive as
+ * chat messages on a thread (\`council-<id>\`), which is what the 1.2.1 relay already supports. So this module is the state
+ * and the arithmetic, and {@link fleetCouncilRequest} / {@link fleetCouncilBallot} are the two messages it exchanges --
+ * plain JSON in text, because the fleet chat contract is "plain text" and inventing a binary frame would need a relay
+ * change for no benefit.
+ *
+ * ## Why late ballots are refused rather than ignored
+ *
+ * Silently dropping a ballot makes a voter believe their vote counted. Refusing it by name can be told to them.
+ */
+export const FLEET_COUNCIL_REFUSAL = Object.freeze({
+  UNKNOWN: 'FLEET_COUNCIL_UNKNOWN',
+  ALREADY_OPEN: 'FLEET_COUNCIL_ALREADY_OPEN',
+  ALREADY_DECIDED: 'FLEET_COUNCIL_ALREADY_DECIDED',
+  NO_BALLOTS: 'FLEET_COUNCIL_NO_BALLOTS',
+  BAD_BALLOT: 'FLEET_COUNCIL_BAD_BALLOT',
+  DUPLICATE_VOTER: 'FLEET_COUNCIL_DUPLICATE_VOTER',
+  LATE_BALLOT: 'FLEET_COUNCIL_LATE_BALLOT',
+  TIED: 'FLEET_COUNCIL_TIED',
+  BAD_MESSAGE: 'FLEET_COUNCIL_BAD_MESSAGE',
+});
+
+/** The weight of one ballot. Deliberately the same formula as \`agent/council.mjs#weightOf\`, restated here because importing
+ * the single-machine module would drag its phase machine into a fleet decision that does not have phases. */
+export function fleetWeightOf({ authority, reputation } = {}) {
+  const level = Number.isFinite(authority) ? authority : null;
+  if (level === null || level < 0 || level > 100) return null;
+  const rep = Number.isFinite(reputation) ? reputation : 0;
+  return level * (1 + rep / 100);
+}
+
+/**
+ * Count the stored ballots. Pure: same ballots, same outcome, on any machine.
+ *
+ * @param {Array<{choice: string, authority: number, reputation: number, machine_id?: string}>} ballots
+ * @returns {{ok: true, choice: string, weight: number, dissent: object[]} | {ok: false, code: string, detail?: object}}
+ */
+export function tallyFleetBallots(ballots) {
+  const list = Array.isArray(ballots) ? ballots : [];
+  if (list.length === 0) return { ok: false, code: FLEET_COUNCIL_REFUSAL.NO_BALLOTS };
+  const totals = new Map();
+  for (const ballot of list) {
+    const choice = typeof ballot?.choice === 'string' ? ballot.choice.trim() : '';
+    if (choice === '') return { ok: false, code: FLEET_COUNCIL_REFUSAL.BAD_BALLOT, detail: { ballot } };
+    const weight = fleetWeightOf(ballot);
+    if (weight === null) return { ok: false, code: FLEET_COUNCIL_REFUSAL.BAD_BALLOT, detail: { authority: ballot?.authority } };
+    totals.set(choice, (totals.get(choice) ?? 0) + weight);
+  }
+  const ranked = [...totals.entries()].sort((a, b) => b[1] - a[1]);
+  const [topChoice, topWeight] = ranked[0];
+  const tied = ranked.slice(1).filter(([, weight]) => weight === topWeight);
+  if (tied.length > 0) {
+    return {
+      ok: false,
+      code: FLEET_COUNCIL_REFUSAL.TIED,
+      detail: { tied: [topChoice, ...tied.map(([choice]) => choice)], weight: topWeight },
+    };
+  }
+  return {
+    ok: true,
+    choice: topChoice,
+    weight: topWeight,
+    dissent: list.filter((ballot) => ballot.choice !== topChoice).map((ballot) => ({ ...ballot })),
+  };
+}
+
+/**
+ * @param {{now?: () => number}} [options]
+ */
+export function createFleetCouncil(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now();
+  /** councilId -> { id, question, openedBy, atMs, decidedAtMs, ballots, decision } */
+  const councils = new Map();
+
+  function open({ councilId, question, openedByMachineId } = {}) {
+    const id = typeof councilId === 'string' && councilId.trim() !== '' ? councilId.trim() : null;
+    if (id === null) return { ok: false, code: FLEET_COUNCIL_REFUSAL.BAD_BALLOT, detail: { field: 'councilId' } };
+    const questionText = typeof question === 'string' ? question.trim() : '';
+    if (questionText === '') return { ok: false, code: FLEET_COUNCIL_REFUSAL.BAD_BALLOT, detail: { field: 'question' } };
+    const existing = councils.get(id);
+    if (existing !== undefined && existing.decision === null) return { ok: false, code: FLEET_COUNCIL_REFUSAL.ALREADY_OPEN };
+    const council = {
+      id,
+      question: questionText,
+      openedBy: typeof openedByMachineId === 'string' ? openedByMachineId : null,
+      atMs: now(),
+      decidedAtMs: null,
+      ballots: [],
+      decision: null,
+    };
+    councils.set(id, council);
+    return { ok: true, council: snapshot(council) };
+  }
+
+  function vote({ councilId, machineId, choice, reason = null, authority = null, reputation = null } = {}) {
+    const council = councils.get(typeof councilId === 'string' ? councilId.trim() : '');
+    if (council === undefined) return { ok: false, code: FLEET_COUNCIL_REFUSAL.UNKNOWN, detail: { councilId } };
+    if (council.decision !== null) return { ok: false, code: FLEET_COUNCIL_REFUSAL.LATE_BALLOT, detail: { decidedAtMs: council.decidedAtMs } };
+    const voter = typeof machineId === 'string' && machineId !== '' ? machineId : null;
+    if (voter === null) return { ok: false, code: FLEET_COUNCIL_REFUSAL.BAD_BALLOT, detail: { field: 'machineId' } };
+    if (council.ballots.some((ballot) => ballot.machine_id === voter)) {
+      return { ok: false, code: FLEET_COUNCIL_REFUSAL.DUPLICATE_VOTER, detail: { machineId: voter } };
+    }
+    const ballot = {
+      machine_id: voter,
+      choice: typeof choice === 'string' ? choice.trim() : '',
+      reason: typeof reason === 'string' ? reason : null,
+      authority: Number.isInteger(authority) && authority >= 0 && authority <= 100 ? authority : null,
+      reputation: Number.isFinite(reputation) ? reputation : null,
+      at_ms: now(),
+    };
+    if (ballot.choice === '' || ballot.authority === null) {
+      return { ok: false, code: FLEET_COUNCIL_REFUSAL.BAD_BALLOT, detail: { ballot } };
+    }
+    council.ballots.push(ballot);
+    return { ok: true, council: snapshot(council) };
+  }
+
+  function decide({ councilId } = {}) {
+    const council = councils.get(typeof councilId === 'string' ? councilId.trim() : '');
+    if (council === undefined) return { ok: false, code: FLEET_COUNCIL_REFUSAL.UNKNOWN, detail: { councilId } };
+    if (council.decision !== null) return { ok: true, council: snapshot(council), alreadyDecided: true };
+    const counted = tallyFleetBallots(council.ballots);
+    if (counted.ok !== true) return counted;
+    council.decision = {
+      choice: counted.choice,
+      weight: counted.weight,
+      dissent: counted.dissent,
+      ballots: council.ballots.length,
+    };
+    council.decidedAtMs = now();
+    return { ok: true, council: snapshot(council) };
+  }
+
+  function state({ councilId } = {}) {
+    const council = councils.get(typeof councilId === 'string' ? councilId.trim() : '');
+    if (council === undefined) return { ok: false, code: FLEET_COUNCIL_REFUSAL.UNKNOWN, detail: { councilId } };
+    return { ok: true, council: snapshot(council) };
+  }
+
+  function list() {
+    return { ok: true, councils: [...councils.values()].map(snapshot) };
+  }
+
+  function snapshot(council) {
+    return {
+      id: council.id,
+      question: council.question,
+      opened_by: council.openedBy,
+      open: council.decision === null,
+      at_ms: council.atMs,
+      decided_at_ms: council.decidedAtMs,
+      ballots: council.ballots.map((ballot) => ({ ...ballot })),
+      decision: council.decision === null ? null : { ...council.decision, dissent: council.decision.dissent.map((b) => ({ ...b })) },
+    };
+  }
+
+  return { open, vote, decide, state, list, _councils: councils };
+}
+
+/** The thread every message about one council travels on. */
+export function fleetCouncilThread(councilId) {
+  return 'council-' + String(councilId ?? '').trim();
+}
+
+/** The message that opens a vote on the fleet chat. */
+export function fleetCouncilRequest({ councilId, question, openedByMachineId = null } = {}) {
+  return JSON.stringify({
+    v: 1,
+    kind: 'council-request',
+    council_id: String(councilId ?? ''),
+    question: String(question ?? ''),
+    opened_by: openedByMachineId,
+  });
+}
+
+/** The message that carries one ballot. */
+export function fleetCouncilBallot({ councilId, machineId, choice, reason = null, authority = null, reputation = null } = {}) {
+  return JSON.stringify({
+    v: 1,
+    kind: 'council-ballot',
+    council_id: String(councilId ?? ''),
+    machine_id: String(machineId ?? ''),
+    choice: String(choice ?? ''),
+    reason,
+    authority,
+    reputation,
+  });
+}
+
+/**
+ * Read one fleet-chat message: is it a council request, a ballot, or neither?
+ *
+ * @param {string} text
+ * @returns {{kind: 'request'|'ballot', payload: object} | {kind: 'none'} | {kind: 'bad', reason: string}}
+ */
+export function parseFleetCouncilMessage(text) {
+  if (typeof text !== 'string' || text.trim() === '') return { kind: 'none' };
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { return { kind: 'none' }; }
+  if (parsed === null || typeof parsed !== 'object' || parsed.v !== 1) return { kind: 'none' };
+  if (parsed.kind === 'council-request') {
+    if (typeof parsed.council_id !== 'string' || parsed.council_id.trim() === '') return { kind: 'bad', reason: 'council_id' };
+    return { kind: 'request', payload: parsed };
+  }
+  if (parsed.kind === 'council-ballot') {
+    if (typeof parsed.council_id !== 'string' || parsed.council_id.trim() === '') return { kind: 'bad', reason: 'council_id' };
+    if (typeof parsed.machine_id !== 'string' || parsed.machine_id.trim() === '') return { kind: 'bad', reason: 'machine_id' };
+    return { kind: 'ballot', payload: parsed };
+  }
+  return { kind: 'none' };
+}

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

@@ -42,7 +42,10 @@ function newestTranscript(cwd) {
   return best === null ? null : best.file;
 }
 
-export const CHAT_ROUTE_PATH = '/api/w2m/chat';
+export const CHAT_ROUTE_PATH = '/api/w2m/chat';
+
+/** The light task board the panel shows beside the chat. The relay already answers GET /v1/tasks. */
+export const TASKS_ROUTE_PATH = '/api/w2m/tasks';
 export const MAX_SESSION_ID_LENGTH = 200;
 
 const NO_STORE = { 'cache-control': 'no-store' };
@@ -102,6 +105,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) => {
@@ -232,6 +265,16 @@ 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 });
             }
+            // 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';
@@ -244,6 +287,48 @@ export function registerChatRoutes(ctx, deps) {
           }
         },
       });
+      // A light task board. The relay answers GET /v1/tasks; this proxy exists so the panel can read it with the device
+      // token that never leaves the host.
+      registry.register({
+        path: TASKS_ROUTE_PATH,
+        methods: ['GET'],
+        requestBody: 'buffered',
+        fetch: async (request) => {
+          const refuse = (httpStatus, reasonCode, error, detail) =>
+            Response.json({ ok: false, error, reason_code: reasonCode, detail }, { status: httpStatus, headers: NO_STORE });
+          if (request.method !== 'GET') {
+            return refuse(405, 'TASKS_METHOD_NOT_ALLOWED', `${request.method} is not answered here`, 'GET only');
+          }
+          const url = new URL(request.url);
+          const limitRaw = url.searchParams.get('limit');
+          const limit = limitRaw !== null && /^[0-9]+$/.test(limitRaw) ? Math.min(Number(limitRaw), 50) : 20;
+          const cfg = deps.cfg();
+          const rabbitUrl = cfg?.rabbitUrl ?? null;
+          if (rabbitUrl === null) return refuse(503, 'TASKS_NO_RELAY', 'no relay is configured', 'set rabbitUrl in the profile patch');
+          let token;
+          try {
+            token = await deps.resolveToken();
+          } catch (error) {
+            return refuse(503, 'TASKS_UNPAIRED', `this machine has no device token: ${error instanceof Error ? error.message : String(error)}`, 'pair the machine first');
+          }
+          if (typeof token !== 'string' || token === '') {
+            return refuse(503, 'TASKS_UNPAIRED', 'this machine has no device token', 'pair the machine first');
+          }
+          try {
+            const listed = await deps.request({
+              rabbitUrl, token, method: 'GET', pathname: '/v1/tasks', query: { limit: String(limit) }, signal: request.signal,
+            });
+            if (listed?.ok !== true) {
+              const code = listed?.json?.error?.code ?? 'TASKS_LIST_REFUSED';
+              return refuse(502, code, `the relay answered HTTP ${listed?.status ?? 0}`, 'the relay must run a version with /v1/tasks');
+            }
+            return Response.json({ ...listed.json, ok: true }, { headers: NO_STORE });
+          } catch (error) {
+            return refuse(502, 'TASKS_RELAY_ERROR', `the relay call failed: ${error instanceof Error ? error.message : String(error)}`, null);
+          }
+        },
+      });
+
       status.mounted = true;
       status.reason = null;
       const timer = setInterval(() => { mirrorOnce().catch(() => { /* one bad tick must not stop the next */ }); }, 2000);

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/schema-spec.mjs

@@ -0,0 +1,49 @@
+/**
+ * Authoring rules DSH enforces on tool schemas, checked here so the failure happens at build time in this repository
+ * rather than at mount time in someone else's profile.
+ *
+ * The rule this exists for: DSH's `parameterSchemaSpecToJsonSchema` requires an EXPLICIT `additionalProperties` on every
+ * `type: 'object'` node and throws otherwise. Local tests passed while the packed artifact failed in a real profile,
+ * which is exactly the gap a pure checker closes: the same walk runs in the suite and at registration.
+ */
+
+/**
+ * Every `type: 'object'` node in a JSON-schema-shaped value, with its path.
+ *
+ * @param {unknown} schema
+ * @param {string} [path]
+ * @returns {Array<{path: string, node: object}>}
+ */
+export function objectNodes(schema, path = 'schema') {
+  const found = [];
+  if (schema === null || typeof schema !== 'object') return found;
+  const node = schema;
+  if (node.type === 'object') found.push({ path, node });
+  if (node.properties !== null && typeof node.properties === 'object') {
+    for (const [name, child] of Object.entries(node.properties)) {
+      found.push(...objectNodes(child, path + '.properties.' + name));
+    }
+  }
+  if (node.items !== undefined) found.push(...objectNodes(node.items, path + '[]'));
+  for (const key of ['oneOf', 'anyOf', 'allOf']) {
+    if (Array.isArray(node[key])) {
+      node[key].forEach((child, index) => found.push(...objectNodes(child, path + '.' + key + '[' + index + ']')));
+    }
+  }
+  return found;
+}
+
+/**
+ * The problems a schema would be refused for, as `{path, why}` values rather than a thrown error, so a caller can report
+ * all of them at once instead of fixing one per run.
+ *
+ * @param {unknown} schema
+ * @param {string} [name] tool name, used in the path
+ * @returns {Array<{path: string, why: string}>}
+ */
+export function schemaProblems(schema, name = 'tool') {
+  return objectNodes(schema, 'parameters')
+    .filter(({ node }) => typeof node.additionalProperties !== 'boolean')
+    .map(({ path }) => ({ path: path + '.additionalProperties', why: 'an object parameter must state additionalProperties: true or false' }))
+    .map((problem) => ({ ...problem, path: name + '.' + problem.path }));
+}