@twinsearth/w2m-dsh-plugin 2.0.3 → 2.0.5

package/src/agent/sse-watchdog.mjs

@@ -0,0 +1,71 @@
+/**
+ * SSE watchdog (P0-f): the stream must not hang forever on a half-open connection.
+ *
+ * Two deadlines are enforced:
+ *   · first frame  — nothing parsed within 5 s means the stream is not really attached;
+ *   · idle         — 45 s without any byte, which is longer than the relay's 15 s keepalive
+ *                    interval by design (three missed keepalives before we give up).
+ *
+ * `noteBytes` sustains the idle deadline (keepalive comments prove the socket is alive) but it does
+ * NOT satisfy the first-frame deadline: a stream that connects and sends keepalives without a
+ * parseable `ready` is exactly the buffered/half-dead case this watchdog exists to catch.
+ */
+export const SSE_FIRST_FRAME_MS = 5000;
+export const SSE_IDLE_MS = 45000;
+export const SSE_FIRST_FRAME_TIMEOUT = 'SSE_FIRST_FRAME_TIMEOUT';
+export const SSE_IDLE_TIMEOUT = 'SSE_IDLE_TIMEOUT';
+
+export function createSseWatchdog(input = {}) {
+  const firstFrameMs = Number.isInteger(input.firstFrameMs) && input.firstFrameMs > 0 ? input.firstFrameMs : SSE_FIRST_FRAME_MS;
+  const idleMs = Number.isInteger(input.idleMs) && input.idleMs > 0 ? input.idleMs : SSE_IDLE_MS;
+  const onTimeout = typeof input.onTimeout === 'function' ? input.onTimeout : () => {};
+  let disposed = false;
+  let firstTimer = null;
+  let idleTimer = null;
+
+  const armIdle = () => {
+    if (disposed) return;
+    if (idleTimer !== null) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      if (disposed) return;
+      disposed = true;
+      clearTimers();
+      onTimeout(SSE_IDLE_TIMEOUT);
+    }, idleMs);
+    if (typeof idleTimer.unref === 'function') idleTimer.unref();
+  };
+  const clearTimers = () => {
+    if (firstTimer !== null) { clearTimeout(firstTimer); firstTimer = null; }
+    if (idleTimer !== null) { clearTimeout(idleTimer); idleTimer = null; }
+  };
+
+  firstTimer = setTimeout(() => {
+    if (disposed) return;
+    disposed = true;
+    clearTimers();
+    onTimeout(SSE_FIRST_FRAME_TIMEOUT);
+  }, firstFrameMs);
+  if (typeof firstTimer.unref === 'function') firstTimer.unref();
+  armIdle();
+
+  return {
+    /** Any byte (headers, keepalive comment, frame) proves the socket is alive: it clears the
+     *  first-frame deadline and re-arms the idle deadline. */
+    noteBytes() {
+      if (disposed) return;
+      armIdle();
+    },
+    /** A parsed frame clears the first-frame deadline. */
+    noteFrame() {
+      if (disposed) return;
+      if (firstTimer !== null) { clearTimeout(firstTimer); firstTimer = null; }
+      armIdle();
+    },
+    get disposed() { return disposed; },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      clearTimers();
+    },
+  };
+}

package/src/plugin/dataplane-sink-route.mjs

@@ -0,0 +1,113 @@
+/**
+ * `/api/w2m/dataplane-sink` (A3): the settings-page half of the S4 data-plane authorization.
+ *
+ *   GET  -> { ok, configured, kind, root|host/user/dir, saved_at }
+ *   POST -> { ok, configured: true, kind, ... } and writes <stateDir>/dataplane/sink.json (0600)
+ *
+ * Authorization is a LOCAL USER action through this host route. Model/tool parameters can never
+ * authorize a sink: the tool schemas do not expose this path, and this route does not accept an
+ * operator/device token as the authority (the host's same-origin fence is the boundary).
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export const DATAPLANE_SINK_ROUTE_PATH = '/api/w2m/dataplane-sink';
+const NO_STORE = { 'cache-control': 'no-store' };
+const KINDS = new Set(['dir', 'lan-git', 'ssh']);
+const CREDENTIAL_KEYS = /^(?:password|passphrase|key|private_key|token|secret|credential|identity)$/i;
+
+function configPath(stateDir) {
+  return join(stateDir, 'dataplane', 'sink.json');
+}
+
+function readConfig(stateDir) {
+  const file = configPath(stateDir);
+  if (!existsSync(file)) return null;
+  try { return JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, '')); } catch { return null; }
+}
+
+function insideStateDir(stateDir, target) {
+  const rel = relative(stateDir, target);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/** Strip anything that looks like a secret; the file only holds references, never credentials. */
+function publicView(config) {
+  if (config === null) return { configured: false, kind: null };
+  if (config.kind === 'ssh') return { configured: true, kind: config.kind, host: config.host ?? null, user: config.user ?? null, dir: config.dir ?? null, port: config.port ?? null, saved_at: config.saved_at ?? null };
+  return { configured: true, kind: config.kind, root: config.root ?? null, remote: config.remote ?? null, branch: config.branch ?? null, saved_at: config.saved_at ?? null };
+}
+
+/**
+ * @param {object} ctx Cordis context
+ * @param {{stateDir?: () => string|null}} [deps]
+ */
+export function registerDataplaneSinkRoute(ctx, deps = {}) {
+  const status = { mounted: false, reason: 'the host has no Connection service' };
+  if (typeof ctx?.inject !== 'function') return status;
+  ctx.inject(['connection'], (webCtx) => {
+    const registry = webCtx?.connection?.fetch;
+    if (registry === undefined || typeof registry.register !== 'function') {
+      status.reason = 'the connection service carries no fetch registry';
+      return;
+    }
+    const stateDirOf = () => (typeof deps?.stateDir === 'function' ? deps.stateDir() : null);
+    registry.register({
+      path: DATAPLANE_SINK_ROUTE_PATH,
+      methods: ['GET', 'POST'],
+      requestBody: 'buffered',
+      fetch: async (request) => {
+        const stateDir = stateDirOf();
+        if (typeof stateDir !== 'string' || stateDir === '') {
+          return Response.json({ ok: false, code: 'DATAPLANE_STATE_UNAVAILABLE' }, { status: 503, headers: NO_STORE });
+        }
+        if (request.method === 'GET') {
+          return Response.json({ ok: true, ...publicView(readConfig(stateDir)) }, { headers: NO_STORE });
+        }
+        let body = null;
+        try { body = await request.json(); } catch { /* refused below */ }
+        if (body === null || typeof body !== 'object') return Response.json({ ok: false, code: 'SINK_BODY_REQUIRED' }, { status: 400, headers: NO_STORE });
+        for (const key of Object.keys(body)) {
+          if (CREDENTIAL_KEYS.test(key)) return Response.json({ ok: false, code: 'SINK_CREDENTIALS_NOT_ACCEPTED', detail: key }, { status: 400, headers: NO_STORE });
+        }
+        const kind = typeof body.kind === 'string' ? body.kind : '';
+        if (!KINDS.has(kind)) return Response.json({ ok: false, code: 'SINK_KIND_INVALID' }, { status: 400, headers: NO_STORE });
+        const config = { v: 1, kind, saved_at: new Date().toISOString(), approved_by: 'local-user' };
+        if (kind === 'ssh') {
+          if (typeof body.host !== 'string' || !/^[A-Za-z0-9.-]{1,253}$/.test(body.host)) return Response.json({ ok: false, code: 'SINK_SSH_HOST_INVALID' }, { status: 400, headers: NO_STORE });
+          if (typeof body.user !== 'string' || !/^[A-Za-z0-9._-]{1,64}$/.test(body.user)) return Response.json({ ok: false, code: 'SINK_SSH_USER_INVALID' }, { status: 400, headers: NO_STORE });
+          if (typeof body.dir !== 'string' || !isAbsolute(body.dir)) return Response.json({ ok: false, code: 'SINK_SSH_DIR_INVALID' }, { status: 400, headers: NO_STORE });
+          if (body.port !== undefined && !(Number.isInteger(body.port) && body.port >= 1 && body.port <= 65535)) return Response.json({ ok: false, code: 'SINK_SSH_PORT_INVALID' }, { status: 400, headers: NO_STORE });
+          config.host = body.host;
+          config.user = body.user;
+          config.dir = body.dir;
+          if (body.port !== undefined) config.port = body.port;
+        } else {
+          if (typeof body.root !== 'string' || !isAbsolute(body.root)) return Response.json({ ok: false, code: 'SINK_ROOT_INVALID' }, { status: 400, headers: NO_STORE });
+          const resolved = realpathSync.native ? (() => { try { return realpathSync.native(body.root); } catch { return null; } })() : null;
+          if (resolved === null) return Response.json({ ok: false, code: 'SINK_ROOT_NOT_FOUND' }, { status: 400, headers: NO_STORE });
+          const stat = statSync(resolved);
+          if (!stat.isDirectory()) return Response.json({ ok: false, code: 'SINK_ROOT_NOT_DIRECTORY' }, { status: 400, headers: NO_STORE });
+          if (insideStateDir(stateDir, resolved)) return Response.json({ ok: false, code: 'SINK_ROOT_INSIDE_STATE' }, { status: 400, headers: NO_STORE });
+          if (kind === 'lan-git' && !existsSync(join(resolved, '.git'))) return Response.json({ ok: false, code: 'SINK_GIT_NOT_A_REPO' }, { status: 400, headers: NO_STORE });
+          config.root = resolved;
+          if (kind === 'lan-git') {
+            if (typeof body.remote === 'string' && body.remote !== '') config.remote = body.remote;
+            if (typeof body.branch === 'string' && body.branch !== '') config.branch = body.branch;
+          }
+        }
+        const file = configPath(stateDir);
+        mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+        const tmp = file + '.tmp-' + process.pid + '-' + randomBytes(4).toString('hex');
+        writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+        renameSync(tmp, file);
+        try { chmodSync(file, 0o600); } catch { /* Windows ACL */ }
+        return Response.json({ ok: true, ...publicView(config) }, { headers: NO_STORE });
+      },
+    });
+    status.mounted = true;
+    status.reason = null;
+  });
+  return status;
+}

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

@@ -23,6 +23,13 @@ import {
 } from './session-watch.mjs';
 import { createSessionSync } from './session-sync.mjs';
 
+/** Session prompts are mirrored only when the operator opts in; the default is off. */
+export const DEFAULT_MIRROR_MODE = 'off';
+export function mirrorModeOf(cfg) {
+  const mode = cfg?.fleetChatMirror;
+  return mode === 'plaintext' || mode === 'encrypted' ? mode : DEFAULT_MIRROR_MODE;
+}
+
 
 /**
  * The newest transcript for a cwd, or null. Reads directory listings and stat only -- this module never opens a
@@ -158,12 +165,16 @@ export function registerChatRoutes(ctx, deps) {
    * 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 mode = mirrorModeOf(deps.cfg());
+    if (mode === 'off') return;
+    if (mode === 'encrypted') return; // encrypted mirroring lands with the AEAD v2 slice
     const identity = await identityOf();
     if (identity.conversationKey === null) return;
     const file = newestTranscript(projectDirOf());

package/src/plugin/gpw.mjs

@@ -95,7 +95,21 @@ export const GPW_PICK_ROUTE = '/api/w2m/gpw/pick';
 export const GPW_RESET_ROUTE = '/api/w2m/gpw/reset';
 
 const DEFAULT_BUDGET = { maxPerWindow: 10, windowMs: 60_000, minGapMs: 3_000 };
-const DEFAULT_PENDING_TIMEOUT_MS = 100_000;
+const DEFAULT_PENDING_TIMEOUT_MS = 10_000;
+
+/** Two policy strategies; novice is the product default. */
+export const GPW_MODES = Object.freeze(['novice', 'advanced']);
+export const DEFAULT_GPW_MODE = 'novice';
+/** At most one path-naming auto-pass per 3 s in novice mode. */
+export const NOVICE_APPROVE_GAP_MS = 3000;
+/** Always refused in novice mode, even with an empty operator blacklist. */
+export const DEFAULT_PROTECTED_FOLDERS = Object.freeze([
+  'C:\\Windows',
+  'C:\\Program Files',
+  'D:\\Program Files',
+  'C:\\Program Files (x86)',
+  'D:\\Program Files (x86)',
+]);
 const RECENT_LIMIT = 20;
 const NO_STORE = { 'cache-control': 'no-store' };
 /** v1.7.9: lists are MAC-signed (v2) so an external edit is detectable instead of silently trusted. */
@@ -164,29 +178,30 @@ export function readFolders(file, key = null, options = {}) {
     raw = readFileSync(file, 'utf8');
   } catch (error) {
     if (error?.code === 'ENOENT' && key !== null && options.allowMissing !== true) {
-      return { whitelist: [], blacklist: [], tampered: true, reason: 'folder lists file is missing' };
+      return { whitelist: [], blacklist: [], mode: 'novice', tampered: true, reason: 'folder lists file is missing' };
     }
     if (error?.code !== 'ENOENT') {
       return { whitelist: [], blacklist: [], tampered: true, reason: `folder lists unreadable: ${error?.message ?? error}` };
     }
-    return { whitelist: [], blacklist: [], tampered: false, reason: null, legacy: false };
+    return { whitelist: [], blacklist: [], mode: 'novice', tampered: false, reason: null, legacy: false };
   }
   let parsed = null;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    return { whitelist: [], blacklist: [], tampered: true, reason: 'folder lists file is not valid JSON' };
+    return { whitelist: [], blacklist: [], mode: 'novice', tampered: true, reason: 'folder lists file is not valid JSON' };
   }
   const whitelist = Array.isArray(parsed?.whitelist) ? parsed.whitelist.filter((v) => typeof v === 'string' && v !== '') : [];
   const blacklist = Array.isArray(parsed?.blacklist) ? parsed.blacklist.filter((v) => typeof v === 'string' && v !== '') : [];
   if (parsed?.version !== FOLDERS_VERSION || typeof parsed?.mac !== 'string') {
-    return { whitelist, blacklist, tampered: false, reason: null, legacy: true };
+    return { whitelist, blacklist, mode: 'novice', tampered: false, reason: null, legacy: true };
   }
-  if (key === null) return { whitelist, blacklist, tampered: false, reason: null, legacy: false };
+  const storedMode = parsed?.mode === 'advanced' ? 'advanced' : 'novice';
+  if (key === null) return { whitelist, blacklist, mode: storedMode, tampered: false, reason: null, legacy: false };
   if (macOfFolders(whitelist, blacklist, key) !== parsed.mac) {
-    return { whitelist, blacklist, tampered: true, reason: 'folder lists were modified outside GPW (MAC mismatch)' };
+    return { whitelist, blacklist, mode: storedMode, tampered: true, reason: 'folder lists were modified outside GPW (MAC mismatch)' };
   }
-  return { whitelist, blacklist, tampered: false, reason: null, legacy: false };
+  return { whitelist, blacklist, mode: storedMode, tampered: false, reason: null, legacy: false };
 }
 
 /**
@@ -200,7 +215,8 @@ export function writeFolders(file, folders, key = null) {
   mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
   const whitelist = [...new Set((folders?.whitelist ?? []).filter((v) => typeof v === 'string' && v.trim() !== ''))];
   const blacklist = [...new Set((folders?.blacklist ?? []).filter((v) => typeof v === 'string' && v.trim() !== ''))];
-  const next = { version: FOLDERS_VERSION, whitelist, blacklist };
+  const mode = folders?.mode === 'advanced' ? 'advanced' : 'novice';
+  const next = { version: FOLDERS_VERSION, whitelist, blacklist, mode };
   if (key !== null) {
     next.algo = FOLDERS_MAC_ALGO;
     next.mac = macOfFolders(whitelist, blacklist, key);
@@ -213,12 +229,12 @@ export function writeFolders(file, folders, key = null) {
   try { chmodSync(tmp, 0o600); } catch { /* best effort */ }
   renameSync(tmp, file);
   try { chmodSync(file, 0o444); } catch { /* read-only is best effort on Windows, MAC still verifies */ }
-  return { whitelist, blacklist };
+  return { whitelist, blacklist, mode };
 }
 
 /** Operator reset: drop every entry and re-sign. Used only after a tamper report. */
 export function resetFolders(file, key) {
-  return writeFolders(file, { whitelist: [], blacklist: [] }, key);
+  return writeFolders(file, { whitelist: [], blacklist: [], mode: 'novice' }, key);
 }
 
 /**
@@ -363,6 +379,7 @@ export function apply(ctx, config = {}) {
   const minGapMs = positiveInt(config.minGapMs, DEFAULT_BUDGET.minGapMs);
   const pendingTimeoutMs = positiveInt(config.pendingTimeoutMs, DEFAULT_PENDING_TIMEOUT_MS);
   const requireFullAccess = config.requireFullAccess !== false;
+  const configuredMode = config.gpwMode === 'advanced' ? 'advanced' : DEFAULT_GPW_MODE;
   const foldersFile = foldersFileOf(config);
   const keyInfo = ensureFoldersKey(foldersFile, config);
   const foldersKey = keyInfo.key;
@@ -384,6 +401,8 @@ export function apply(ctx, config = {}) {
     noteTamper(initialFolders.reason);
   } else {
     // Always leave a signed v2 file behind (first run creates the empty one; later runs re-sign it).
+    // A configured mode is the bootstrap choice when the file carries none yet (tests and first run).
+    if (config.gpwMode !== undefined) initialFolders.mode = configuredMode;
     try {
       writeFolders(foldersFile, initialFolders, foldersKey);
       foldersSeen = true;
@@ -398,6 +417,7 @@ export function apply(ctx, config = {}) {
   let allowedTotal = 0;
   let pendingTotal = 0;
   let deniedTotal = 0;
+  let lastNovicePassAt = 0;
   /** id -> { resolve, createdAt, tool, reason, paths } */
   const pending = new Map();
   /** Newest-first record of calls the gate saw, so the panel can offer "add this folder" in one click. */
@@ -422,9 +442,13 @@ export function apply(ctx, config = {}) {
       foldersSeen = true;
     }
     const merge = (a, b) => [...new Set([...(Array.isArray(a) ? a : []), ...b])];
+    const mode = config.gpwMode !== undefined ? configuredMode : (stored.mode ?? configuredMode);
+    const storedBlacklist = merge(config.blacklist, stored.blacklist);
     return {
+      mode,
       whitelist: merge(config.whitelist, stored.whitelist),
-      blacklist: merge(config.blacklist, stored.blacklist),
+      blacklist: storedBlacklist,
+      effectiveBlacklist: mode === 'novice' ? [...new Set([...DEFAULT_PROTECTED_FOLDERS, ...storedBlacklist])] : storedBlacklist,
       tampered: tamperedReason !== null,
       reason: tamperedReason,
     };
@@ -529,8 +553,8 @@ export function apply(ctx, config = {}) {
       ctx.logger?.warn?.(`dsh-gpw: refused ${String(call.name ?? 'tool')} -- lists locked (${lists.reason})`);
       return `GPW: folder lists failed integrity check (${lists.reason}); reset them in the GPW panel`;
     }
-    if (lists.blacklist.length === 0) return undefined;
-    const result = classifyToolCall({ ...call, blacklist: lists.blacklist });
+    if (lists.effectiveBlacklist.length === 0) return undefined;
+    const result = classifyToolCall({ ...call, blacklist: lists.effectiveBlacklist });
     if (result.decision !== 'deny') return undefined;
     deniedTotal += 1;
     noteRecent({ tool: String(call.name ?? 'tool'), decision: 'deny', reason: result.reason, paths: result.paths });
@@ -575,6 +599,34 @@ export function apply(ctx, config = {}) {
       ctx.logger?.warn?.(`dsh-gpw: refused ${String(call.name ?? 'tool')} -- lists locked (${lists.reason})`);
       return { kind: 'deny', reason: `GPW: folder lists failed integrity check (${lists.reason}); reset them in the GPW panel` };
     }
+    if (lists.mode === 'novice') {
+      // 小白模式: only the blacklist restricts anything; every other call passes.
+      // At most one path-naming call per 3 s is auto-passed, so a burst cannot do unbounded damage.
+      let noviceCwd = null;
+      try {
+        noviceCwd = await ctx.workingDirectory?.ensure?.(exec.agent, exec.signal);
+      } catch {
+        noviceCwd = null;
+      }
+      const noviceCall = toolCallOf(exec);
+      const noviceClassification = classifyToolCall({ ...noviceCall, blacklist: lists.effectiveBlacklist, workspace: noviceCwd ?? null, base: noviceCwd ?? undefined });
+      if (noviceClassification.decision === 'deny') {
+        deniedTotal += 1;
+        colorCounts.red += 1;
+        noteRecent({ tool: String(noviceCall.name ?? 'tool'), decision: 'deny', color: 'red', reason: noviceClassification.reason, paths: noviceClassification.paths });
+        ctx.logger?.warn?.('dsh-gpw: novice -- refused ' + String(noviceCall.name ?? 'tool') + ' -- ' + noviceClassification.reason);
+        return { kind: 'deny', reason: 'GPW: ' + noviceClassification.reason + '; the call was not executed' };
+      }
+      if (noviceClassification.paths.length > 0) {
+        const waitMs = NOVICE_APPROVE_GAP_MS - (Date.now() - lastNovicePassAt);
+        if (waitMs > 0) await new Promise((resolveSlot) => { setTimeout(resolveSlot, Math.min(waitMs, NOVICE_APPROVE_GAP_MS)); });
+        lastNovicePassAt = Date.now();
+      }
+      colorCounts.green += 1;
+      const noviceReason = '小白模式：黑名单外全部放行（每 3 秒最多一次路径操作）';
+      noteRecent({ tool: String(noviceCall.name ?? 'tool'), decision: 'allow', color: 'green', reason: noviceReason, paths: noviceClassification.paths });
+      return { kind: 'allow', reason: noviceReason };
+    }
     let cwd = null;
     try {
       cwd = await ctx.workingDirectory?.ensure?.(exec.agent, exec.signal);
@@ -651,6 +703,11 @@ export function apply(ctx, config = {}) {
           enabled: true,
           require_full_access: requireFullAccess,
           folders: { whitelist: lists.whitelist, blacklist: lists.blacklist },
+          mode: lists.mode,
+          modes: [...GPW_MODES],
+          protected_folders: lists.mode === 'novice' ? [...DEFAULT_PROTECTED_FOLDERS, ...lists.blacklist] : [...lists.blacklist],
+          pending_timeout_ms: pendingTimeoutMs,
+          novice_approve_gap_ms: NOVICE_APPROVE_GAP_MS,
           tampered: lists.tampered,
           tampered_reason: lists.reason,
           counters: { allowedTotal, pendingTotal, deniedTotal, budgetWindow: approvals.length, maxPerWindow, colors: { ...colorCounts }, grants: sessionGrants.size },
@@ -690,6 +747,22 @@ export function apply(ctx, config = {}) {
         } catch {
           /* refused below */
         }
+        if (body?.action === 'set-mode') {
+          const current = folderLists();
+          if (current.tampered) {
+            return json({ ok: false, error: 'folder lists are locked after an integrity failure (' + current.reason + '); reset them first' }, 409);
+          }
+          const mode = body?.mode;
+          if (mode !== 'novice' && mode !== 'advanced') return json({ ok: false, error: 'mode must be novice or advanced' }, 400);
+          const stored = readFolders(foldersFile, foldersKey, { allowMissing: true });
+          try {
+            writeFolders(foldersFile, { ...stored, mode }, foldersKey);
+          } catch (error) {
+            return json({ ok: false, error: 'could not write the policy mode: ' + (error?.message ?? error) }, 500);
+          }
+          ctx.logger?.info?.('dsh-gpw: policy mode -> ' + mode);
+          return json({ ok: true, mode, folders: folderLists() });
+        }
         const list = body?.list;
         if (list !== 'whitelist' && list !== 'blacklist') return json({ ok: false, error: 'list must be whitelist or blacklist' }, 400);
         if (body?.action !== 'add' && body?.action !== 'remove') return json({ ok: false, error: 'action must be add or remove' }, 400);
@@ -698,6 +771,17 @@ export function apply(ctx, config = {}) {
           return json({ ok: false, error: `folder lists are locked after an integrity failure (${current.reason}); reset them first` }, 409);
         }
         const stored = readFolders(foldersFile, foldersKey, { allowMissing: true });
+        if (body?.action === 'set-mode') {
+          const mode = body?.mode;
+          if (mode !== 'novice' && mode !== 'advanced') return json({ ok: false, error: 'mode must be novice or advanced' }, 400);
+          try {
+            writeFolders(foldersFile, { ...stored, mode }, foldersKey);
+          } catch (error) {
+            return json({ ok: false, error: 'could not write the policy mode: ' + (error?.message ?? error) }, 500);
+          }
+          ctx.logger?.info?.('dsh-gpw: policy mode -> ' + mode);
+          return json({ ok: true, mode, folders: folderLists() });
+        }
         if (body.action === 'remove') {
           if (typeof body?.path !== 'string' || body.path.trim() === '') return json({ ok: false, error: 'path must be a non-empty string' }, 400);
           const next = { ...stored, [list]: stored[list].filter((entry) => entry !== body.path) };
@@ -734,7 +818,7 @@ export function apply(ctx, config = {}) {
         }
         if (body?.confirm !== 'reset') return json({ ok: false, error: "confirm must be the string 'reset'" }, 400);
         try {
-          resetFolders(foldersFile, foldersKey);
+          resetFolders(foldersFile, foldersKey, folderLists().mode);
         } catch (error) {
           return json({ ok: false, error: `could not reset folder lists: ${error?.message ?? error}` }, 500);
         }

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

@@ -7,6 +7,8 @@
  */
 import { createHash } from 'node:crypto';
 
+import { computeCommandHash, normalizeCwdRel, SHELL_ID_DIRECT } from '../../relay/state.mjs';
+
 import { appendAudit } from './audit-file.mjs';
 import { createAudit, inspectControlMessage } from './redline.mjs';
 
@@ -80,7 +82,8 @@ export function buildPlan(input) {
       step_id: step.step_id,
       machine_id: step.machine_id,
       command_argv: step.command_argv.slice(0, 32),
-      command_hash: sha256(JSON.stringify(step.command_argv)),
+      cwd_rel: normalizeCwdRel(step.cwd_rel),
+      command_hash: computeCommandHash(step.command_argv, SHELL_ID_DIRECT, normalizeCwdRel(step.cwd_rel)),
       write_scope: Array.isArray(step.write_scope) ? step.write_scope.slice(0, 8) : [],
       depends_on: Array.isArray(step.depends_on) ? step.depends_on.slice(0, 8) : [],
       timeout_ms: Number.isInteger(step.timeout_ms) ? step.timeout_ms : null,
@@ -101,6 +104,7 @@ export function buildControlEnvelopes(plan) {
       base_commit: plan.base_commit,
       command_argv: step.command_argv,
       command_hash: step.command_hash,
+      cwd_rel: step.cwd_rel ?? '.',
       write_scope: step.write_scope,
       depends_on: step.depends_on,
       ...(step.timeout_ms === null ? {} : { timeout_ms: step.timeout_ms }),

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

@@ -0,0 +1,115 @@
+/**
+ * Merge approval (A4/D4): the second human signature in the joint-dev SOP.
+ *
+ * A plan approval authorises *sending work*; a merge approval authorises *moving a branch*. It binds
+ * the plan, repository, base commit, target ref, the old value the CAS will replace, and the exact
+ * integration head that was reviewed. Signed with the same operator Ed25519 key, TTL-capped, and
+ * consumed once (O_EXCL) so a replay cannot move a second branch.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ensureOperatorKey, keyIdOf, signApprovalPayload, verifyApprovalPayload } from '../operator-key.mjs';
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const SHA = /^[0-9a-f]{7,40}$/;
+const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
+
+export function bodyOf(input) {
+  const approvedAtIn = typeof input.approvedAt === 'string' ? input.approvedAt : (typeof input.approved_at === 'string' ? input.approved_at : null);
+  const expiresAtIn = typeof input.expiresAt === 'string' ? input.expiresAt : (typeof input.expires_at === 'string' ? input.expires_at : null);
+  const now = Number.isInteger(input.now) ? input.now : (approvedAtIn !== null ? Date.parse(approvedAtIn) : Date.now());
+  const approvedAt = approvedAtIn !== null ? approvedAtIn : new Date(now).toISOString();
+  const expiresAt = expiresAtIn !== null ? expiresAtIn : new Date(now + (Number.isInteger(input.ttlMs) ? input.ttlMs : 600_000)).toISOString();
+  return {
+    v: 1,
+    type: 'joint.merge',
+    plan_sha256: typeof input.planSha === 'string' && input.planSha !== '' ? input.planSha : (typeof input.plan_sha256 === 'string' && input.plan_sha256 !== '' ? input.plan_sha256 : null),
+    repo: String(input.repo ?? ''),
+    base_commit: String(input.baseCommit ?? input.base_commit ?? ''),
+    target_ref: String(input.targetRef ?? input.target_ref ?? ''),
+    expected_old: String(input.expectedOld ?? input.expected_old ?? ''),
+    integration_head: String(input.integrationHead ?? input.integration_head ?? ''),
+    approver: String(input.approver ?? ''),
+    authority: Number.isInteger(input.authority) ? input.authority : 0,
+    approved_at: approvedAt,
+    expires_at: expiresAt,
+  };
+}
+
+/**
+ * @param {{stateDir: string, planSha?: string|null, repo: string, baseCommit: string, targetRef: string,
+ *          expectedOld: string, integrationHead: string, approver: string, authority: number,
+ *          ttlMs?: number, now?: number, key?: {privateKey: string, publicKeyPem: string, key_id: string}}} input
+ */
+export function createMergeApproval(input) {
+  if (!SHA.test(String(input.baseCommit ?? ''))) return { ok: false, code: 'MERGE_APPROVAL_BASE_INVALID' };
+  if (!SHA.test(String(input.expectedOld ?? ''))) return { ok: false, code: 'MERGE_APPROVAL_OLD_INVALID' };
+  if (!SHA.test(String(input.integrationHead ?? ''))) return { ok: false, code: 'MERGE_APPROVAL_HEAD_INVALID' };
+  if (!Number.isInteger(input.authority) || input.authority < 70 || input.authority > 100) return { ok: false, code: 'MERGE_APPROVAL_AUTHORITY_INVALID' };
+  const key = input.key ?? ensureOperatorKey();
+  if (key === null || key === undefined || key.ok !== true || key.privateKey === undefined) return { ok: false, code: key?.code ?? 'OPERATOR_KEY_MISSING' };
+  const body = bodyOf(input);
+  const approvalSha = sha256(JSON.stringify(body));
+  const record = {
+    ...body,
+    approval_sha256: approvalSha,
+    operator_key: { key_id: key.key_id ?? keyIdOf(key.publicKeyPem), public_key_pem: key.publicKeyPem },
+    sig: signApprovalPayload(body, key.privateKey),
+  };
+  const dir = join(input.stateDir, 'joint-dev', 'merge-approvals');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, approvalSha + '.json');
+  const tmp = path + '.tmp-' + process.pid + '-' + randomBytes(4).toString('hex');
+  writeFileSync(tmp, JSON.stringify(record, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+  renameSync(tmp, path);
+  try { chmodSync(path, 0o600); } catch { /* Windows ACL */ }
+  return { ok: true, approval: record, approval_sha256: approvalSha, path };
+}
+
+/**
+ * Verify signature, TTL and the exact binding the caller is about to apply.
+ *
+ * @param {{stateDir: string, approvalSha: string, trustedOperatorKeyIds?: string[], now?: number,
+ *          repo: string, baseCommit: string, targetRef: string, expectedOld: string, integrationHead: string,
+ *          planSha?: string|null}} input
+ */
+export function loadMergeApproval(input) {
+  if (typeof input?.approvalSha !== 'string' || !HEX64.test(input.approvalSha)) return { ok: false, code: 'MERGE_APPROVAL_ID_INVALID' };
+  const path = join(input.stateDir, 'joint-dev', 'merge-approvals', input.approvalSha + '.json');
+  if (!existsSync(path)) return { ok: false, code: 'MERGE_APPROVAL_NOT_FOUND' };
+  let record = null;
+  try { record = JSON.parse(readFileSync(path, 'utf8').replace(/^\uFEFF/, '')); } catch { return { ok: false, code: 'MERGE_APPROVAL_UNREADABLE' }; }
+  if (record?.type !== 'joint.merge') return { ok: false, code: 'MERGE_APPROVAL_TYPE_INVALID' };
+  if (record.approval_sha256 !== sha256(JSON.stringify(bodyOf(record)))) return { ok: false, code: 'MERGE_APPROVAL_TAMPERED' };
+  const pem = record?.operator_key?.public_key_pem;
+  if (typeof pem !== 'string' || record?.operator_key?.key_id !== keyIdOf(pem)) return { ok: false, code: 'MERGE_APPROVAL_KEY_MISMATCH' };
+  const trusted = Array.isArray(input.trustedOperatorKeyIds) ? input.trustedOperatorKeyIds : null;
+  if (trusted !== null && !trusted.includes(record.operator_key.key_id)) return { ok: false, code: 'MERGE_APPROVAL_KEY_UNTRUSTED' };
+  if (verifyApprovalPayload(record, record.sig, pem) !== true) return { ok: false, code: 'MERGE_APPROVAL_SIGNATURE_INVALID' };
+  const now = Number.isInteger(input.now) ? input.now : Date.now();
+  if (Date.parse(record.expires_at) <= now) return { ok: false, code: 'MERGE_APPROVAL_EXPIRED' };
+  for (const [field, expected] of [['repo', input.repo], ['base_commit', input.baseCommit], ['target_ref', input.targetRef], ['expected_old', input.expectedOld], ['integration_head', input.integrationHead]]) {
+    if (record[field] !== expected) return { ok: false, code: 'MERGE_APPROVAL_MISMATCH', detail: { field, expected, actual: record[field] } };
+  }
+  if (input.planSha !== undefined && input.planSha !== null && record.plan_sha256 !== input.planSha) {
+    return { ok: false, code: 'MERGE_APPROVAL_MISMATCH', detail: { field: 'plan_sha256', expected: input.planSha, actual: record.plan_sha256 } };
+  }
+  return { ok: true, approval: record, strength: 'signature' };
+}
+
+/** One-shot consumption: the marker is created with O_EXCL, so a second apply cannot reuse the signature. */
+export function consumeMergeApproval({ stateDir, approvalSha }) {
+  if (typeof approvalSha !== 'string' || !HEX64.test(approvalSha)) return { ok: false, code: 'MERGE_APPROVAL_ID_INVALID' };
+  const dir = join(stateDir, 'joint-dev', 'merge-consumed');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const marker = join(dir, approvalSha);
+  try {
+    writeFileSync(marker, new Date().toISOString() + '\n', { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    return { ok: true };
+  } catch (error) {
+    if (error?.code === 'EEXIST') return { ok: false, code: 'MERGE_APPROVAL_ALREADY_USED' };
+    return { ok: false, code: 'MERGE_APPROVAL_CONSUME_FAILED', detail: error instanceof Error ? error.message : String(error) };
+  }
+}