@twinsearth/w2m-dsh-plugin 1.9.17 → 1.9.20

package/src/agent/agent.mjs

@@ -23,7 +23,7 @@
 
 import { Readable } from 'node:stream';
 import { access, constants as fsConstants } from 'node:fs/promises';
-import { existsSync, mkdirSync, mkdtempSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { commitTaskChanges, createWorktree, listChangedFiles, producePatch, removeWorktree } from './worktree.mjs';
 import { describePatchArtifact } from './patch-artifact.mjs';
@@ -31,6 +31,7 @@ import { ferryMaintenance, maintenancePaths } from './maintenance-ferry.mjs';
 import { authorizeWithGrant } from './grant-gate.mjs';
 import { tmpdir } from 'node:os';
 import { randomUUID , sign as signBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
 
 import {
   EMPTY_SHA256,
@@ -2122,6 +2123,10 @@ export function createAgent(options) {
       python: caps.python ?? null,
       npm: caps.npm ?? null,
       git,
+      plugin_version: (() => {
+        try { return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf8')).version ?? null; } catch { return null; }
+      })(),
+      joint_dev: 'v2',
     };
     return toolchainCache;
   }

package/src/agent/sinks/dir-sink.mjs

@@ -1,33 +1,79 @@
 /**
- * 目录 sink（本地/局域网共享盘）：密封对象落盘、按内容哈希取回。
- * 数据面适配器的最小实现；git/ssh 适配器同契约，后续补。
- * 对象已经是 sealObject() 的密文，sink 不接触明文与密钥。
+ * 目录 sink（本地/局域网共享盘）：ArtifactRef v1 的对象落盘与取回。
+ *
+ * 对象已经是调用方封装好的密文字节，sink 不接触明文与密钥。写入是原子的
+ * （tmp → fsync → rename，0600），取回时校验对象 id 形状与期望的 cipher sha256。
  */
 import { createHash } from 'node:crypto';
-import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeSync } from 'node:fs';
 import { join } from 'node:path';
 
+const OBJECT_ID = /^[0-9a-f]{32,64}$/;
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
 export function createDirSink({ root }) {
   if (typeof root !== 'string' || root === '') throw new Error('SINK_ROOT_REQUIRED');
   mkdirSync(root, { recursive: true });
+
+  const pathOf = (objectId) => join(root, objectId + '.json');
+
+  /** Write the sealed object bytes atomically under `<objectId>.json`. */
+  async function writeObject({ objectId, body, expectSha256 = null }) {
+    if (typeof objectId !== 'string' || !OBJECT_ID.test(objectId)) return { ok: false, code: 'OBJECT_ID_INVALID' };
+    const bytes = Buffer.isBuffer(body) ? body : Buffer.from(typeof body === 'string' ? body : JSON.stringify(body), 'utf8');
+    const actual = sha256(bytes);
+    if (typeof expectSha256 === 'string' && expectSha256 !== '' && expectSha256 !== actual) {
+      return { ok: false, code: 'OBJECT_HASH_MISMATCH', detail: { expected: expectSha256, actual } };
+    }
+    const path = pathOf(objectId);
+    const tmp = path + '.tmp-' + process.pid + '-' + Date.now().toString(36);
+    const fd = openSync(tmp, 'w', 0o600);
+    try {
+      writeSync(fd, bytes);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tmp, path);
+    return { ok: true, objectId, path, rel_path: objectId + '.json', sha256: actual, bytes: bytes.length };
+  }
+
+  /** Read the object bytes back and verify the expected cipher sha256. */
+  async function readObject({ objectId, expectSha256 = null }) {
+    if (typeof objectId !== 'string' || !OBJECT_ID.test(objectId)) return { ok: false, code: 'OBJECT_ID_INVALID' };
+    const path = pathOf(objectId);
+    if (!existsSync(path)) return { ok: false, code: 'OBJECT_NOT_FOUND' };
+    let bytes;
+    try { bytes = readFileSync(path); } catch { return { ok: false, code: 'OBJECT_UNREADABLE' }; }
+    const actual = sha256(bytes);
+    if (typeof expectSha256 === 'string' && expectSha256 !== '' && expectSha256 !== actual) {
+      return { ok: false, code: 'OBJECT_HASH_MISMATCH', detail: { expected: expectSha256, actual } };
+    }
+    return { ok: true, objectId, path, sha256: actual, bytes };
+  }
+
   return {
     kind: 'dir',
+    writeObject,
+    readObject,
+    // Backwards-compatible adapters for the pre-v2 callers: the object id is derived from the body.
     async pushObject({ sealed }) {
       if (sealed === null || typeof sealed !== 'object') return { ok: false, code: 'OBJECT_INVALID' };
       const body = JSON.stringify(sealed);
-      const id = createHash('sha256').update(body, 'utf8').digest('hex');
-      const path = join(root, id + '.json');
-      writeFileSync(path, body, { encoding: 'utf8', mode: 0o600 });
-      return { ok: true, objectId: id, path, bytes: Buffer.byteLength(body, 'utf8') };
+      const id = createHash('sha256').update(body, 'utf8').digest('hex').slice(0, 32);
+      const written = await writeObject({ objectId: id, body });
+      return written.ok === true ? { ok: true, objectId: id, path: written.path, bytes: written.bytes } : written;
     },
     async fetchObject({ objectId }) {
-      if (typeof objectId !== 'string' || !/^[0-9a-f]{64}$/.test(objectId)) return { ok: false, code: 'OBJECT_ID_INVALID' };
-      const path = join(root, objectId + '.json');
-      if (!existsSync(path)) return { ok: false, code: 'OBJECT_NOT_FOUND' };
-      return { ok: true, sealed: JSON.parse(readFileSync(path, 'utf8')), path };
+      const read = await readObject({ objectId });
+      if (read.ok !== true) return read;
+      try { return { ok: true, sealed: JSON.parse(read.bytes.toString('utf8')), path: read.path }; } catch { return { ok: false, code: 'OBJECT_UNREADABLE' }; }
     },
     async listObjects() {
-      return readdirSync(root).filter((name) => name.endsWith('.json')).map((name) => name.replace(/\.json$/, ''));
+      return readdirSync(root).filter((name) => name.endsWith('.json') && OBJECT_ID.test(name.slice(0, -5))).map((name) => name.slice(0, -5));
+    },
+    removeObject(objectId) {
+      try { unlinkSync(pathOf(objectId)); return { ok: true }; } catch { return { ok: false, code: 'OBJECT_NOT_FOUND' }; }
     },
   };
 }

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

@@ -156,6 +156,12 @@ export function registerChatRoutes(ctx, deps) {
    * The session files are never written and nothing is injected into DSH: the transcript is read, the user's messages
    * are extracted, and only the new ones are published. A failure here must not disturb the panel or the route.
    */
+  const MIRROR_MAX_BYTES = 3500;
+  const truncateUtf8 = (value, max) => {
+    const bytes = Buffer.from(value, 'utf8');
+    if (bytes.length <= max) return value;
+    return bytes.subarray(0, max).toString('utf8').replace(/\uFFFD+$/, '') + ' …(已截断)';
+  };
   const mirrorOnce = async () => {
     const identity = await identityOf();
     if (identity.conversationKey === null) return;
@@ -165,7 +171,7 @@ export function registerChatRoutes(ctx, deps) {
     try { messages = extractUserMessages(decodeTranscript(readFileSync(file))); } catch { return; }
     for (const payload of sync.pending(messages)) {
       await postToRelay(identity, {
-        text: payload.text,
+        text: truncateUtf8(payload.text, MIRROR_MAX_BYTES),
         machine_id: identity.machineId,
         machine_name: identity.machineName,
         origin: 'session',

package/src/plugin/joint-dev/audit-file.mjs

@@ -2,11 +2,42 @@
  * 红线审计落盘：JSONL + fsync + 哈希链 + 校验。
  * 只接受元数据字段（内容字段直接拒绝），链断裂/篡改可被定位。
  */
-import { closeSync, fsyncSync, openSync, readFileSync, writeSync } from 'node:fs';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 
 export const AUDIT_FORBIDDEN = new Set(['content', 'data', 'file', 'files', 'patch', 'stdout', 'stderr', 'diff', 'blob', 'bytes', 'text', 'base64']);
 
+/** Recursively collect forbidden content keys: a nested payload must not slip past the top level. */
+function contentKeysDeep(value, path = '', hits = []) {
+  if (value === null || typeof value !== 'object') return hits;
+  if (Array.isArray(value)) { value.forEach((entry, index) => contentKeysDeep(entry, path + '[' + index + ']', hits)); return hits; }
+  for (const [key, child] of Object.entries(value)) {
+    const keyPath = path === '' ? key : path + '.' + key;
+    if (AUDIT_FORBIDDEN.has(key.toLowerCase())) hits.push(keyPath);
+    else contentKeysDeep(child, keyPath, hits);
+  }
+  return hits;
+}
+
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+function withLock(file, fn) {
+  const lock = file + '.lock';
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    try {
+      const fd = openSync(lock, 'wx', 0o600);
+      try { writeSync(fd, String(process.pid)); } finally { closeSync(fd); }
+      try { return fn(); } finally { try { unlinkSync(lock); } catch { /* already gone */ } }
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try { if (Date.now() - statSync(lock).mtimeMs > 10_000) { unlinkSync(lock); continue; } } catch { /* raced */ }
+      sleep(20);
+    }
+  }
+  return { ok: false, code: 'AUDIT_BUSY' };
+}
+
+
 function stable(value) {
   if (value === null || typeof value !== 'object') return JSON.stringify(value);
   if (Array.isArray(value)) return '[' + value.map(stable).join(',') + ']';
@@ -20,44 +51,46 @@ export function appendAudit(file, event) {
   if (event === null || typeof event !== 'object' || Array.isArray(event)) {
     return { ok: false, code: 'AUDIT_EVENT_INVALID' };
   }
-  const bad = Object.keys(event).filter((key) => AUDIT_FORBIDDEN.has(key.toLowerCase()));
+  const bad = contentKeysDeep(event);
   if (bad.length > 0) return { ok: false, code: 'AUDIT_CONTENT_FORBIDDEN', detail: { keys: bad } };
-
-  let previous = null;
-  let seq = 1;
-  try {
-    const lines = readFileSync(file, 'utf8').split('\n').filter((line) => line.trim() !== '');
-    if (lines.length > 0) {
-      const last = JSON.parse(lines[lines.length - 1]);
-      previous = last.record_sha256 ?? null;
-      seq = Number(last.seq ?? lines.length) + 1;
+  return withLock(file, () => {
+    let previous = null;
+    let seq = 1;
+    if (existsSync(file)) {
+      const lines = readFileSync(file, 'utf8').split('\n').filter((line) => line.trim() !== '');
+      if (lines.length > 0) {
+        // A corrupt tail is refused, never treated as "a new file": resetting the chain hides tampering.
+        let last;
+        try { last = JSON.parse(lines[lines.length - 1]); } catch { return { ok: false, code: 'AUDIT_TAIL_CORRUPT', detail: { line: lines.length } }; }
+        previous = last.record_sha256 ?? null;
+        seq = Number(last.seq ?? lines.length) + 1;
+      }
     }
-  } catch { /* 新文件 */ }
-
-  const body = {
-    v: 1,
-    seq,
-    at: event.at ?? new Date().toISOString(),
-    event: typeof event.event === 'string' ? event.event : 'joint.event',
-    plan_sha256: event.plan_sha256 ?? null,
-    step_id: event.step_id ?? null,
-    task_id: event.task_id ?? null,
-    machine_id: event.machine_id ?? null,
-    outcome: event.outcome ?? null,
-    reason_code: event.reason_code ?? null,
-    control_bytes: Number.isInteger(event.control_bytes) ? event.control_bytes : null,
-    control_sha256: typeof event.control_sha256 === 'string' ? event.control_sha256 : null,
-    prev_sha256: previous,
-  };
-  const record = { ...body, record_sha256: sha256(stable(body)) };
-  const fd = openSync(file, 'a');
-  try {
-    writeSync(fd, JSON.stringify(record) + '\n');
-    fsyncSync(fd);
-  } finally {
-    closeSync(fd);
-  }
-  return { ok: true, record };
+    const body = {
+      v: 1,
+      seq,
+      at: event.at ?? new Date().toISOString(),
+      event: typeof event.event === 'string' ? event.event : 'joint.event',
+      plan_sha256: event.plan_sha256 ?? null,
+      step_id: event.step_id ?? null,
+      task_id: event.task_id ?? null,
+      machine_id: event.machine_id ?? null,
+      outcome: event.outcome ?? null,
+      reason_code: event.reason_code ?? null,
+      control_bytes: Number.isInteger(event.control_bytes) ? event.control_bytes : null,
+      control_sha256: typeof event.control_sha256 === 'string' ? event.control_sha256 : null,
+      prev_sha256: previous,
+    };
+    const record = { ...body, record_sha256: sha256(stable(body)) };
+    const fd = openSync(file, 'a');
+    try {
+      writeSync(fd, JSON.stringify(record) + '\n');
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    return { ok: true, record };
+  });
 }
 
 /** 校验整条链；返回第一处问题的 seq。 */

package/src/plugin/joint-dev/merge-engine.mjs

@@ -0,0 +1,102 @@
+/**
+ * S5 MergeEngine: apply machine patches in order inside an integration worktree.
+ *
+ * Local git only. The engine never touches the target ref: `advanceTarget` is a separate,
+ * compare-and-swap step the operator runs only after the user approves the merged head. A conflict
+ * is a first-class refusal (`MERGE_CONFLICT`) — patches are not auto-resolved and force is never
+ * passed to git.
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const defaultRunGit = (args, cwd) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+
+function assertBaseCommit(repoDir, baseCommit, runGit) {
+  try { runGit(['cat-file', '-e', `${baseCommit}^{commit}`], repoDir); return true; } catch { return false; }
+}
+
+/** @returns {{ok: true, worktree: string, integration_head: string, applied: object[]} | {ok: false, code: string, detail?: object}} */
+export function mergePatches({ repoDir, baseCommit, patches, runGit = defaultRunGit }) {
+  if (typeof repoDir !== 'string' || repoDir === '') return { ok: false, code: 'MERGE_REPO_REQUIRED' };
+  if (typeof baseCommit !== 'string' || !/^[0-9a-f]{7,40}$/.test(baseCommit)) return { ok: false, code: 'MERGE_BASE_INVALID' };
+  if (!Array.isArray(patches) || patches.length === 0) return { ok: false, code: 'MERGE_PATCHES_REQUIRED' };
+  if (assertBaseCommit(repoDir, baseCommit, runGit) !== true) return { ok: false, code: 'MERGE_BASE_MISMATCH', detail: { base_commit: baseCommit } };
+
+  const worktree = mkdtempSync(join(tmpdir(), 'w2m-merge-'));
+  const cleanup = () => {
+    try { runGit(['worktree', 'remove', '--force', worktree], repoDir); } catch { /* already gone */ }
+    try { rmSync(worktree, { recursive: true, force: true }); } catch { /* best effort */ }
+  };
+  try {
+    runGit(['worktree', 'add', '--detach', worktree, baseCommit], repoDir);
+  } catch (error) {
+    cleanup();
+    return { ok: false, code: 'MERGE_WORKTREE_FAILED', detail: { message: error instanceof Error ? error.message : String(error) } };
+  }
+
+  const applied = [];
+  try {
+    for (const patch of patches) {
+      if (typeof patch?.step_id !== 'string' || typeof patch?.patch !== 'string' || patch.patch === '') {
+        cleanup();
+        return { ok: false, code: 'MERGE_PATCH_INVALID', detail: { step_id: patch?.step_id ?? null } };
+      }
+      const file = join(worktree, '.w2m-patch-' + patch.step_id.replace(/[^A-Za-z0-9_-]/g, '_') + '.diff');
+      writeFileSync(file, patch.patch, 'utf8');
+      try {
+        runGit(['apply', '--3way', '--check', file], worktree);
+      } catch {
+        const files = (() => {
+          try { return runGit(['apply', '--check', '--numstat', file], worktree).split('\n').map((line) => line.split('\t').pop()).filter(Boolean); } catch { return []; }
+        })();
+        cleanup();
+        return { ok: false, code: 'MERGE_CONFLICT', detail: { step_id: patch.step_id, machine_id: patch.machine_id ?? null, files } };
+      }
+      try {
+        runGit(['apply', '--3way', file], worktree);
+      } catch {
+        const applyFailed = { step_id: patch.step_id, machine_id: patch.machine_id ?? null };
+        cleanup();
+        return { ok: false, code: 'MERGE_CONFLICT', detail: applyFailed };
+      }
+      runGit(['add', '-A'], worktree);
+      runGit(['commit', '-m', `w2m: ${patch.step_id} (${patch.machine_id ?? 'unknown'})`, '--no-verify'], worktree);
+      applied.push({ step_id: patch.step_id, machine_id: patch.machine_id ?? null });
+    }
+    const integrationHead = runGit(['rev-parse', 'HEAD'], worktree);
+    return { ok: true, worktree, integration_head: integrationHead, applied };
+  } catch (error) {
+    cleanup();
+    return { ok: false, code: 'MERGE_APPLY_FAILED', detail: { message: error instanceof Error ? error.message : String(error) } };
+  }
+}
+
+/** Compare-and-swap the target ref; force is impossible here because update-ref takes the old value. */
+export function advanceTarget({ repoDir, targetRef, expectedOld, newCommit, rollbackRef, runGit = defaultRunGit }) {
+  if (typeof targetRef !== 'string' || !/^refs\/heads\/[\w./-]+$/.test(targetRef)) return { ok: false, code: 'MERGE_TARGET_INVALID' };
+  if (typeof newCommit !== 'string' || !/^[0-9a-f]{7,40}$/.test(newCommit)) return { ok: false, code: 'MERGE_COMMIT_INVALID' };
+  if (typeof expectedOld !== 'string' || !/^[0-9a-f]{7,40}$/.test(expectedOld)) return { ok: false, code: 'MERGE_OLD_REQUIRED' };
+  const current = (() => { try { return runGit(['rev-parse', targetRef], repoDir); } catch { return null; } })();
+  if (current !== expectedOld) return { ok: false, code: 'MERGE_BASE_MISMATCH', detail: { expected: expectedOld, current } };
+  if (typeof rollbackRef === 'string' && rollbackRef !== '') {
+    if (!/^refs\/w2m\/rollback\/[\w./-]+$/.test(rollbackRef)) return { ok: false, code: 'MERGE_ROLLBACK_REF_INVALID' };
+    runGit(['update-ref', rollbackRef, expectedOld], repoDir);
+  }
+  try {
+    runGit(['update-ref', targetRef, newCommit, expectedOld], repoDir);
+  } catch (error) {
+    return { ok: false, code: 'MERGE_CAS_FAILED', detail: { message: error instanceof Error ? error.message : String(error) } };
+  }
+  return { ok: true, target_ref: targetRef, head: newCommit, rollback_ref: typeof rollbackRef === 'string' && rollbackRef !== '' ? rollbackRef : null };
+}
+
+/** Remove an integration worktree (after a merge, a refusal or an abort). */
+export function abortMerge({ repoDir, worktree, runGit = defaultRunGit }) {
+  if (typeof worktree === 'string' && worktree !== '') {
+    try { runGit(['worktree', 'remove', '--force', worktree], repoDir); } catch { /* already gone */ }
+    try { rmSync(worktree, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+  return { ok: true };
+}

package/src/plugin/joint-dev/relay-dispatch.mjs

@@ -1,20 +1,54 @@
 /**
  * Joint-dev relay dispatch (v2 S2).
  *
- * Turns an approved plan into relay tasks: one step = one broadcast task pinned to the step's
- * machine via `executor_machine_id`. Capabilities are negotiated first (an older relay that cannot
- * honour the pin is refused, never assumed), and the leases the relay returns are checked: a lease
- * on any machine other than the pinned one cancels the task and fails the dispatch.
- *
- * Only the control plane is written here: plan digest, step id, command hash and the argv the
- * executor needs. Nothing is uploaded; artifacts are the separate sink path (S4).
+ * Turns an approved plan into relay tasks:
+ *   · steps are dispatched in dependency order; a step's `depends_on` is mapped to the task ids of
+ *     the steps it waits for, so the relay's own dependency gate keeps them from running together;
+ *   · task ids are deterministic (`jd-<sha256(plan|step)>`), so retrying a dispatch does not create
+ *     a second task — a relay `TASK_EXISTS` answer is reported as "already dispatched";
+ *   · every control envelope is checked by `inspectControlMessage` (16 KiB, field whitelist, no
+ *     data-plane bytes) and the attempt/outcome is written to the local audit file;
+ *   · capabilities are negotiated first (an older relay is refused), and the leases the relay
+ *     returns are checked: a lease on a machine that was not pinned cancels the task and fails.
  */
+import { createHash } from 'node:crypto';
+
+import { appendAudit } from './audit-file.mjs';
+import { inspectControlMessage } from './redline.mjs';
 import { readRelayCapabilities, negotiateFeatures } from '../relay-capabilities.mjs';
 
+const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
 const trimBase = (value) => (typeof value === 'string' ? value.replace(/\/+$/, '') : '');
+const taskIdOf = (planSha, stepId) => 'jd-' + sha256(planSha + '|' + stepId).slice(0, 26);
+
+/** Kahn order over the plan's dependency graph; unknown dependencies are a refusal, not a guess. */
+function orderSteps(steps) {
+  const byId = new Map(steps.map((step) => [step.step_id, step]));
+  for (const step of steps) {
+    for (const dep of step.depends_on ?? []) {
+      if (!byId.has(dep)) return { ok: false, code: 'PLAN_DEPENDENCY_UNKNOWN', detail: { step_id: step.step_id, depends_on: dep } };
+    }
+  }
+  const placed = new Set();
+  const ordered = [];
+  let remaining = steps.slice();
+  while (remaining.length > 0) {
+    const ready = remaining.filter((step) => (step.depends_on ?? []).every((dep) => placed.has(dep)));
+    if (ready.length === 0) return { ok: false, code: 'PLAN_DEPENDENCY_CYCLE' };
+    for (const step of ready) { ordered.push(step); placed.add(step.step_id); }
+    remaining = remaining.filter((step) => !placed.has(step.step_id));
+  }
+  return { ok: true, steps: ordered };
+}
+
+function writeAudit(file, event) {
+  if (typeof file !== 'string' || file === '') return;
+  try { appendAudit(file, event); } catch { /* an audit write must not change the dispatch outcome */ }
+}
 
 /**
- * @param {{rabbitUrl: string, token: string, plan: object, approval: object, fetchImpl?: Function, timeoutMs?: number, includeOffline?: boolean}} input
+ * @param {{rabbitUrl: string, token: string, plan: object, approval: object, fetchImpl?: Function,
+ *          timeoutMs?: number, includeOffline?: boolean, auditFile?: string}} input
  */
 export async function dispatchPlanToRelay(input) {
   const rabbitUrl = trimBase(input?.rabbitUrl);
@@ -24,12 +58,39 @@ export async function dispatchPlanToRelay(input) {
   if (rabbitUrl === '') return { ok: false, code: 'RELAY_URL_REQUIRED' };
   if (token === '') return { ok: false, code: 'OPERATOR_TOKEN_MISSING' };
   if (plan === null || typeof plan.plan_sha256 !== 'string') return { ok: false, code: 'PLAN_INVALID' };
+  if (!Array.isArray(plan.steps) || plan.steps.length === 0) return { ok: false, code: 'PLAN_INVALID' };
   if (approval === null || typeof approval.approval_sha256 !== 'string') return { ok: false, code: 'APPROVAL_REQUIRED' };
+  for (const step of plan.steps) {
+    if (typeof step?.step_id !== 'string' || step.step_id === '' || typeof step?.machine_id !== 'string' || step.machine_id === '' || !Array.isArray(step?.command_argv) || step.command_argv.length === 0) {
+      return { ok: false, code: 'PLAN_STEP_INVALID', detail: { step_id: step?.step_id ?? null } };
+    }
+  }
+  const ordered = orderSteps(plan.steps);
+  if (ordered.ok !== true) return { ok: false, code: ordered.code, detail: ordered.detail ?? null };
 
   const fetchImpl = input?.fetchImpl ?? globalThis.fetch;
   const timeoutMs = Number.isInteger(input?.timeoutMs) ? input.timeoutMs : 60_000;
   const signalOf = () => (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function' ? AbortSignal.timeout(timeoutMs) : undefined);
   const headers = { authorization: `Bearer ${token}`, 'content-type': 'application/json', accept: 'application/json' };
+  const auditFile = typeof input?.auditFile === 'string' ? input.auditFile : '';
+
+  // R3: when a device token is supplied, every target machine must advertise the same plugin version.
+  if (typeof input?.deviceToken === 'string' && input.deviceToken !== '') {
+    const expected = typeof input?.expectedVersion === 'string' ? input.expectedVersion : null;
+    if (expected !== null) {
+      let fleet;
+      try {
+        const response = await fetchImpl(`${rabbitUrl}/v1/devices`, { headers: { authorization: `Bearer ${input.deviceToken}`, accept: 'application/json' }, signal: signalOf() });
+        fleet = response.ok === true ? await response.json() : null;
+      } catch { fleet = null; }
+      if (fleet === null || !Array.isArray(fleet.devices)) return { ok: false, code: 'VERSION_UNVERIFIABLE', detail: { reason: 'the relay device list could not be read' } };
+      const byId = new Map(fleet.devices.map((device) => [device.machine_id, device]));
+      const skew = ordered.steps
+        .map((step) => ({ machine_id: step.machine_id, version: byId.get(step.machine_id)?.caps?.plugin_version ?? null }))
+        .filter((row) => row.version !== expected);
+      if (skew.length > 0) return { ok: false, code: 'VERSION_SKEW', detail: { expected, machines: skew } };
+    }
+  }
 
   const capabilities = await readRelayCapabilities({ rabbitUrl, fetchImpl, timeoutMs });
   const negotiation = negotiateFeatures(capabilities);
@@ -37,9 +98,13 @@ export async function dispatchPlanToRelay(input) {
     return { ok: false, code: negotiation.code ?? 'RELAY_CAPABILITIES_MISSING', detail: { missing: negotiation.missing ?? null, relay: rabbitUrl } };
   }
 
+  const dispatched = new Map(); // step_id -> task_id
   const tasks = [];
-  for (const step of plan.steps) {
+  for (const step of ordered.steps) {
+    const taskId = taskIdOf(plan.plan_sha256, step.step_id);
+    const dependsOn = (step.depends_on ?? []).map((dep) => dispatched.get(dep)).filter((id) => typeof id === 'string');
     const body = {
+      task_id: taskId,
       mode: 'broadcast',
       executor_machine_id: step.machine_id,
       command_argv: step.command_argv,
@@ -48,40 +113,57 @@ export async function dispatchPlanToRelay(input) {
       plan_sha256: plan.plan_sha256,
       approval_sha256: approval.approval_sha256,
       step_id: step.step_id,
+      ...(dependsOn.length > 0 ? { depends_on: dependsOn } : {}),
+      ...(Array.isArray(step.write_scope) && step.write_scope.length > 0 ? { write: true, write_scope: step.write_scope } : {}),
       ...(step.timeout_ms === undefined ? {} : { timeout_ms: step.timeout_ms }),
       ...(input?.includeOffline === false ? {} : { include_offline: true }),
     };
+    const check = inspectControlMessage({ v: 1, type: 'joint.dispatch', body });
+    if (check.ok !== true) {
+      writeAudit(auditFile, { event: 'joint.dispatch.refused', plan_sha256: plan.plan_sha256, step_id: step.step_id, reason_code: check.code ?? 'CONTROL_REFUSED' });
+      return { ok: false, code: check.code ?? 'CONTROL_REFUSED', detail: check.detail ?? null, partial: tasks.length > 0, tasks };
+    }
     let response;
     try {
       response = await fetchImpl(`${rabbitUrl}/v1/task`, { method: 'POST', headers, body: JSON.stringify(body), signal: signalOf() });
     } catch (error) {
-      return { ok: false, code: 'RELAY_UNREACHABLE', detail: error instanceof Error ? error.message : String(error) };
+      writeAudit(auditFile, { event: 'joint.dispatch.failed', plan_sha256: plan.plan_sha256, step_id: step.step_id, task_id: taskId, reason_code: 'RELAY_UNREACHABLE' });
+      return { ok: false, code: 'RELAY_UNREACHABLE', detail: error instanceof Error ? error.message : String(error), partial: tasks.length > 0, tasks };
     }
     const doc = await response.json().catch(() => null);
+    if (response.status === 409 && doc?.error?.code === 'TASK_EXISTS') {
+      writeAudit(auditFile, { event: 'joint.dispatch.already', plan_sha256: plan.plan_sha256, step_id: step.step_id, task_id: taskId });
+      dispatched.set(step.step_id, taskId);
+      tasks.push({ step_id: step.step_id, task_id: taskId, already: true, leases: [] });
+      continue;
+    }
     if (response.ok !== true) {
-      return { ok: false, code: doc?.error?.code ?? 'RELAY_REFUSED', status: response.status, detail: doc?.error ?? doc };
+      writeAudit(auditFile, { event: 'joint.dispatch.refused', plan_sha256: plan.plan_sha256, step_id: step.step_id, task_id: taskId, reason_code: doc?.error?.code ?? 'RELAY_REFUSED' });
+      return { ok: false, code: doc?.error?.code ?? 'RELAY_REFUSED', status: response.status, detail: doc?.error ?? doc, partial: tasks.length > 0, tasks };
     }
-    const taskId = doc?.task_id ?? doc?.task?.task_id ?? null;
+    const returnedTaskId = doc?.task_id ?? doc?.task?.task_id ?? taskId;
     const leases = Array.isArray(doc?.leases) ? doc.leases : [];
     const foreign = leases.filter((lease) => lease?.state !== 'observing' && lease?.machine_id !== step.machine_id);
     if (foreign.length > 0) {
-      if (taskId !== null) {
-        try {
-          await fetchImpl(`${rabbitUrl}/v1/tasks/${encodeURIComponent(taskId)}/cancel`, {
-            method: 'POST', headers, body: JSON.stringify({ reason: 'SELECTION_NOT_HONOURED' }), signal: signalOf(),
-          });
-        } catch { /* the refusal below is still the answer */ }
-      }
+      try {
+        await fetchImpl(`${rabbitUrl}/v1/tasks/${encodeURIComponent(returnedTaskId)}/cancel`, {
+          method: 'POST', headers, body: JSON.stringify({ reason: 'SELECTION_NOT_HONOURED' }), signal: signalOf(),
+        });
+      } catch { /* the refusal below is still the answer */ }
+      writeAudit(auditFile, { event: 'joint.dispatch.not_honoured', plan_sha256: plan.plan_sha256, step_id: step.step_id, task_id: returnedTaskId });
       return {
         ok: false,
         code: 'SELECTION_NOT_HONOURED',
-        detail: { step_id: step.step_id, named: step.machine_id, leased: foreign.map((lease) => lease.machine_id), task_id: taskId },
+        detail: { step_id: step.step_id, named: step.machine_id, leased: foreign.map((lease) => lease.machine_id), task_id: returnedTaskId },
+        partial: tasks.length > 0,
         tasks,
       };
     }
+    writeAudit(auditFile, { event: 'joint.dispatch.sent', plan_sha256: plan.plan_sha256, step_id: step.step_id, task_id: returnedTaskId, machine_id: step.machine_id });
+    dispatched.set(step.step_id, returnedTaskId);
     tasks.push({
       step_id: step.step_id,
-      task_id: taskId,
+      task_id: returnedTaskId,
       leases: leases.map((lease) => ({ machine_id: lease?.machine_id ?? null, state: lease?.state ?? null })),
     });
   }