@twinsearth/w2m-dsh-plugin 1.3.1 → 1.4.0

package/src/agent/outbox.mjs

@@ -0,0 +1,138 @@
+/**
+ * Result outbox (M6, v1.3.10-beta.21 slice).
+ *
+ * A machine can finish a task while the network is down. The result must not live only in memory: it goes to disk first, is
+ * re-delivered on reconnect, and is removed only after the relay acknowledged it. The relay deduplicates by
+ * (task_id, attempt), so a re-delivery is safe even when the acknowledgement itself was lost.
+ *
+ * Files are written atomically (temp + rename), so a crash leaves either the old state or the complete new one. Retries use
+ * exponential backoff persisted with the entry, which is what makes "close the laptop for an hour" a resume rather than a
+ * restart.
+ *
+ * Limits: at most 200 entries / 16 MiB. Past that the OLDEST entries are dropped and the caller sees outbox_full:true, because
+ * a full disk is a worse failure than a lost notification about old work.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const OUTBOX_LIMITS = Object.freeze({ maxItems: 200, maxBytes: 16 * 1024 * 1024, maxAttempts: 10, baseDelayMs: 1000, maxDelayMs: 60_000 });
+
+const resultIdOf = (taskId, attempt) => taskId + ':' + String(attempt);
+
+export function createResultOutbox({ dir, now = () => Date.now(), limits = OUTBOX_LIMITS }) {
+  if (typeof dir !== 'string' || dir === '') throw new Error('outbox dir is required');
+  const deadDir = join(dir, 'dead');
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(deadDir, { recursive: true });
+
+  const fileOf = (resultId) => join(dir, resultId.replace(/[^A-Za-z0-9._-]/g, '_') + '.json');
+
+  const serialize = (item) => {
+    const envelopeJson = JSON.stringify(item.envelope ?? null);
+    return { ...item, payload_sha256: createHash('sha256').update(envelopeJson).digest('hex') };
+  };
+
+  const writeAtomic = (item) => {
+    const target = fileOf(item.result_id);
+    const temp = target + '.tmp';
+    writeFileSync(temp, JSON.stringify(item) + '\n', 'utf8');
+    renameSync(temp, target);
+    return target;
+  };
+
+  /** Read every entry on disk; a corrupt file is quarantined instead of breaking the agent on start. */
+  const load = () => {
+    const items = [];
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.json')) continue;
+      const path = join(dir, name);
+      try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof parsed?.result_id !== 'string' || typeof parsed?.task_id !== 'string') throw new Error('not an outbox entry');
+        items.push(parsed);
+      } catch {
+        try { renameSync(path, join(deadDir, name + '.corrupt')); } catch { /* best effort */ }
+      }
+    }
+    items.sort((a, b) => (a.created_at_ms ?? 0) - (b.created_at_ms ?? 0) || a.result_id.localeCompare(b.result_id));
+    return items;
+  };
+
+  const sizeOf = (items) => items.reduce((sum, item) => sum + statSize(item), 0);
+  const statSize = (item) => Buffer.byteLength(JSON.stringify(item), 'utf8');
+
+  /** Drop the oldest entries until the new one fits. Returns how many went. */
+  const makeRoom = (items, incoming) => {
+    let dropped = 0;
+    while (items.length > 0 && (items.length >= limits.maxItems || sizeOf(items) + statSize(incoming) > limits.maxBytes)) {
+      const oldest = items.shift();
+      try { rmSync(fileOf(oldest.result_id), { force: true }); } catch { /* already gone */ }
+      dropped += 1;
+    }
+    return dropped;
+  };
+
+  return {
+    /** Persist a result; the same (task_id, attempt) is one entry, so a retried handler does not duplicate it. */
+    enqueue({ taskId, attempt, dedupeKey = '', envelope }) {
+      if (typeof taskId !== 'string' || taskId === '') throw new Error('task_id is required');
+      if (!Number.isInteger(attempt) || attempt < 1) throw new Error('attempt must be a positive integer');
+      const resultId = resultIdOf(taskId, attempt);
+      const existing = fileOf(resultId);
+      if (existsSync(existing)) {
+        const item = JSON.parse(readFileSync(existing, 'utf8'));
+        return { ok: true, duplicate: true, item };
+      }
+      const at = now();
+      const item = serialize({
+        result_id: resultId,
+        task_id: taskId,
+        attempt,
+        dedupe_key: typeof dedupeKey === 'string' ? dedupeKey : '',
+        envelope: envelope ?? null,
+        attempts: 0,
+        next_retry_ms: at,
+        created_at_ms: at,
+        created_at: new Date(at).toISOString(),
+      });
+      if (statSize(item) > limits.maxBytes) return { ok: false, code: 'OUTBOX_FULL', detail: 'the result alone exceeds the outbox byte limit', bytes: statSize(item) };
+      const items = load();
+      const dropped = makeRoom(items, item);
+      writeAtomic(item);
+      return { ok: true, item, outbox_full: dropped > 0, dropped };
+    },
+    /** Entries whose backoff expired; a caller drains these and calls ack or fail for each. */
+    pending() {
+      const at = now();
+      return load().filter((item) => (item.next_retry_ms ?? 0) <= at);
+    },
+    ack({ resultId }) {
+      const path = fileOf(resultId);
+      if (!existsSync(path)) return { ok: false, code: 'OUTBOX_NOT_FOUND', result_id: resultId };
+      rmSync(path, { force: true });
+      return { ok: true };
+    },
+    /** Count a failed delivery. Backoff doubles per attempt; past maxAttempts the entry moves to dead/ and is reported exhausted. */
+    fail({ resultId, error = null }) {
+      const path = fileOf(resultId);
+      if (!existsSync(path)) return { ok: false, code: 'OUTBOX_NOT_FOUND', result_id: resultId };
+      const item = JSON.parse(readFileSync(path, 'utf8'));
+      item.attempts = (item.attempts ?? 0) + 1;
+      item.last_error = error === null ? null : String(error).slice(0, 500);
+      if (item.attempts >= limits.maxAttempts) {
+        try { renameSync(path, join(deadDir, 'exhausted-' + item.result_id.replace(/[^A-Za-z0-9._-]/g, '_') + '.json')); } catch { rmSync(path, { force: true }); }
+        return { ok: true, exhausted: true, attempts: item.attempts };
+      }
+      const delay = Math.min(limits.baseDelayMs * 2 ** (item.attempts - 1), limits.maxDelayMs);
+      item.next_retry_ms = now() + delay;
+      writeAtomic(item);
+      return { ok: true, exhausted: false, attempts: item.attempts, retry_in_ms: delay };
+    },
+    stats() {
+      const items = load();
+      return { depth: items.length, bytes: sizeOf(items), limits: { maxItems: limits.maxItems, maxBytes: limits.maxBytes } };
+    },
+    list() { return load(); },
+  };
+}

package/src/agent/patch-artifact.mjs

@@ -0,0 +1,53 @@
+/**
+ * Patch artifacts (M3, v1.3.10-beta.6 slice).
+ *
+ * A task's code change must be transportable and self-describing: the receiver needs the bytes, the hash that names them,
+ * and the base commit they apply to. This module turns a patch into that contract. It never applies a patch and never decides
+ * whether the patch is acceptable — the merge queue owns that.
+ */
+import { createHash } from 'node:crypto';
+
+export const PATCH_FORMAT = 'git-format-patch';
+
+/**
+ * @param {{patch: string, baseCommit: string, headCommit?: string|null, filesChanged?: string[],
+ *          tests?: object|null, outputMode?: 'inline'|'blob'}} input
+ */
+export function describePatchArtifact(input) {
+  const patch = typeof input?.patch === 'string' ? input.patch : null;
+  if (patch === null) return { ok: false, code: 'PATCH_REQUIRED', message: 'patch text is required' };
+  if (typeof input.baseCommit !== 'string' || !/^[0-9a-f]{7,64}$/.test(input.baseCommit)) {
+    return { ok: false, code: 'BASE_COMMIT_INVALID', message: 'base_commit must be a hex commit id' };
+  }
+  const bytes = Buffer.byteLength(patch, 'utf8');
+  const empty = patch.trim() === '';
+  if (empty && input.allowEmpty !== true) {
+    return { ok: true, empty: true, outcome: 'no_change', format: PATCH_FORMAT, baseCommit: input.baseCommit, bytes: 0, sha256: null };
+  }
+  const sha256 = createHash('sha256').update(patch, 'utf8').digest('hex');
+  return {
+    ok: true,
+    empty: false,
+    outcome: 'changed',
+    format: PATCH_FORMAT,
+    sha256,
+    bytes,
+    outputMode: input.outputMode === 'blob' ? 'blob' : 'inline',
+    baseCommit: input.baseCommit,
+    headCommit: typeof input.headCommit === 'string' && input.headCommit !== '' ? input.headCommit : null,
+    filesChanged: Array.isArray(input.filesChanged) ? [...input.filesChanged].sort() : [],
+    tests: input.tests ?? null,
+  };
+}
+
+/** The fields a task result carries for a worktree task (see docs/COLLAB/TASK-MODEL.md §7). */
+export function workspaceEvidence({ workspace, patchArtifact }) {
+  if (patchArtifact?.ok !== true) return { ok: false, code: 'PATCH_ARTIFACT_REQUIRED' };
+  return {
+    ok: true,
+    workspace: workspace ?? null,
+    artifacts: patchArtifact.empty
+      ? []
+      : [{ kind: 'patch', sha256: patchArtifact.sha256, bytes: patchArtifact.bytes, output_mode: patchArtifact.outputMode }],
+  };
+}

package/src/agent/worktree.mjs

@@ -0,0 +1,118 @@
+/**
+ * Isolated git worktrees for tasks (M3, v1.3.10-beta.6 slice).
+ *
+ * The old task model ran every command in the machine's own checkout. That cannot support two tasks that change code: they
+ * would see each other's partial edits, and "which base was this change made against" would have no answer. A worktree per
+ * task fixes both: the starting point is a commit the caller named, and everything the task changes is confined to a
+ * directory the task owns.
+ *
+ * All git calls use argv arrays; nothing here goes through a shell, so a branch name or path cannot become a command.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function defaultGit() {
+  return (args, cwd) => new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, timeout: 120_000, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) reject(Object.assign(new Error(String(stderr || error.message).trim()), { stdout, stderr }));
+      else resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
+/**
+ * Create a detached worktree at an exact commit and make it safe to run an agent in.
+ *
+ * @returns {Promise<{ok: true, worktreeDir: string, baseCommit: string} | {ok: false, code: string, message: string}>}
+ */
+export async function createWorktree({ repoDir, baseCommit, worktreeDir, git = defaultGit() }) {
+  if (!existsSync(repoDir)) return { ok: false, code: 'REPO_NOT_FOUND', message: 'repository directory does not exist' };
+  if (typeof baseCommit !== 'string' || !/^[0-9a-f]{7,64}$/.test(baseCommit)) return { ok: false, code: 'BASE_COMMIT_INVALID', message: 'base_commit must be a hex commit id' };
+  if (typeof worktreeDir !== 'string' || worktreeDir === '') return { ok: false, code: 'WORKTREE_PATH_REQUIRED', message: 'worktreeDir is required' };
+  try {
+    await git(['rev-parse', '--verify', baseCommit + '^{commit}'], repoDir);
+  } catch {
+    return { ok: false, code: 'BASE_COMMIT_UNKNOWN', message: 'base_commit does not resolve in this repository' };
+  }
+  try {
+    mkdirSync(join(worktreeDir, '..'), { recursive: true });
+    await git(['worktree', 'add', '--detach', worktreeDir, baseCommit], repoDir);
+  } catch (error) {
+    return { ok: false, code: 'WORKTREE_CREATE_FAILED', message: error?.message ?? 'git worktree add failed' };
+  }
+  // The worktree's configuration is task-local: hooks cannot run a task's code behind its back, and commits must be
+  // reproducible rather than attributed to whoever happens to be logged in.
+  const isolates = [
+    ['config', 'core.hooksPath', join(worktreeDir, '.no-hooks')],
+    ['config', 'user.name', 'w2m-agent'],
+    ['config', 'user.email', 'agent@w2m.invalid'],
+    ['config', 'commit.gpgsign', 'false'],
+  ];
+  for (const argv of isolates) {
+    try { await git(argv, worktreeDir); } catch { /* configuration is defense in depth; git add already succeeded */ }
+  }
+  return { ok: true, worktreeDir, baseCommit };
+}
+
+/** A porcelain snapshot, used before and after a task as evidence of what changed. */
+export async function snapshotStatus({ worktreeDir, git = defaultGit() }) {
+  try {
+    const { stdout } = await git(['status', '--porcelain'], worktreeDir);
+    return { ok: true, dirty: stdout.trim() !== '', status: stdout };
+  } catch (error) {
+    return { ok: false, code: 'STATUS_FAILED', message: error?.message ?? 'git status failed' };
+  }
+}
+
+/**
+ * Commit whatever the task changed, if anything.
+ *
+ * @returns {Promise<{ok: true, changed: boolean, headCommit: string|null, message: string|null} | {ok: false, code: string, message: string}>}
+ */
+export async function commitTaskChanges({ worktreeDir, message = 'task output', git = defaultGit() }) {
+  const before = await snapshotStatus({ worktreeDir, git });
+  if (before.ok !== true) return { ok: false, code: 'STATUS_FAILED', message: before.message };
+  if (before.dirty === false) {
+    const head = await git(['rev-parse', 'HEAD'], worktreeDir).then((r) => r.stdout.trim()).catch(() => null);
+    return { ok: true, changed: false, headCommit: head, message: null };
+  }
+  try {
+    await git(['add', '--all'], worktreeDir);
+    await git(['commit', '-m', message], worktreeDir);
+    const head = (await git(['rev-parse', 'HEAD'], worktreeDir)).stdout.trim();
+    return { ok: true, changed: true, headCommit: head, message };
+  } catch (error) {
+    return { ok: false, code: 'COMMIT_FAILED', message: error?.message ?? 'git commit failed' };
+  }
+}
+
+/** Produce the transportable form of the change: a patch relative to the task's base commit. */
+export async function producePatch({ worktreeDir, baseCommit, git = defaultGit() }) {
+  try {
+    const { stdout } = await git(['format-patch', '--stdout', '--binary', baseCommit], worktreeDir);
+    return { ok: true, patch: stdout, bytes: Buffer.byteLength(stdout, 'utf8'), empty: stdout.trim() === '' };
+  } catch (error) {
+    return { ok: false, code: 'PATCH_FAILED', message: error?.message ?? 'git format-patch failed' };
+  }
+}
+
+/** Remove a worktree. Failure is reported, never hidden: a leaked worktree blocks the next task on that path. */
+export async function listChangedFiles({ worktreeDir, baseCommit, git = defaultGit() }) {
+  try {
+    const result = await git(['diff', '--name-only', baseCommit + '..HEAD'], worktreeDir);
+    return { ok: true, files: String(result.stdout).split(String.fromCharCode(10)).map((line) => line.trim()).filter((line) => line !== '').sort() };
+  } catch (error) {
+    return { ok: false, code: 'DIFF_FAILED', message: error?.message ?? 'git diff failed' };
+  }
+}
+
+export async function removeWorktree({ repoDir, worktreeDir, force = true, git = defaultGit() }) {
+  try {
+    const args = ['worktree', 'remove', ...(force ? ['--force'] : []), worktreeDir];
+    await git(args, repoDir);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, code: 'WORKTREE_REMOVE_FAILED', message: error?.message ?? 'git worktree remove failed' };
+  }
+}

package/src/maintenance/actions.mjs

@@ -0,0 +1,203 @@
+/**
+ * The three fixed maintenance actions (v1.3.2-beta, M1).
+ *
+ * Everything here is executed by the root runner, so the action set is closed by construction: update/restart/diag are
+ * functions with fixed argv, and no value from a request is ever interpolated into a command line. Parameters name
+ * versions, hashes, URLs and unit selections; they do not become shell text.
+ */
+import { execFile as execFileCb } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { dirname, join as joinPath } from 'node:path';
+
+export const UNITS = Object.freeze({
+  rabbit: 'w2m-rabbit.service',
+  agent: 'w2m-localside.service',
+  stun: 'w2m-stun.service',
+});
+
+const MAX_DOWNLOAD_BYTES = 200 * 1024 * 1024;
+const MAX_SECTION_BYTES = 32 * 1024;
+const MAX_TOTAL_DIAG_BYTES = 256 * 1024;
+
+export function defaultDeps(overrides = {}) {
+  return {
+    platform: process.platform,
+    // The staging tree must be on the SAME filesystem as the app directory: swap is a rename, and /tmp is often tmpfs,
+    // so renaming across the boundary fails with EXDEV after the download and extraction already succeeded.
+    appDir: process.platform === 'win32' ? 'C:\\w2m\\app' : '/opt/w2m/app',
+    stagingRoot: process.platform === 'win32' ? 'C:\\w2m\\staging' : joinPath(dirname('/opt/w2m/app'), '.maintenance-staging'),
+    backupDir: process.platform === 'win32' ? 'C:\\w2m\\app.old' : '/opt/w2m/app.old',
+    healthzUrl: 'http://127.0.0.1:8787/healthz',
+    sleep: (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
+    now: () => Date.now(),
+    fetch: (...args) => globalThis.fetch(...args),
+    execFile: (command, argv, options = {}) => new Promise((resolve, reject) => {
+      execFileCb(command, argv, { timeout: 60_000, maxBuffer: 4 * 1024 * 1024, ...options }, (error, stdout, stderr) => {
+        if (error) reject(Object.assign(error, { stdout, stderr }));
+        else resolve({ stdout, stderr });
+      });
+    }),
+    ...overrides,
+  };
+}
+
+async function run(deps, command, argv) {
+  try {
+    const result = await deps.execFile(command, argv);
+    return { ok: true, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+  } catch (error) {
+    return { ok: false, stdout: error?.stdout ?? '', stderr: error?.stderr ?? String(error?.message ?? error) };
+  }
+}
+
+function clip(text) {
+  const value = String(text ?? '');
+  if (Buffer.byteLength(value, 'utf8') <= MAX_SECTION_BYTES) return value;
+  let cut = value;
+  while (Buffer.byteLength(cut, 'utf8') > MAX_SECTION_BYTES) cut = cut.slice(0, -1024);
+  return cut + '\n[truncated]';
+}
+
+async function diag(deps, _params) {
+  const sections = {};
+  const commands = {
+    version: ['sh', ['-c', `cat ${deps.appDir}/package.json`]],
+    disk: ['df', ['-h', '/opt', '/var/lib/w2m']],
+    ports: ['ss', ['-ltn']],
+  };
+  for (const key of Object.keys(commands)) {
+    const result = await run(deps, commands[key][0], commands[key][1]);
+    sections[key] = clip(result.ok ? result.stdout : `ERROR: ${result.stderr}`);
+  }
+  for (const unit of Object.values(UNITS)) {
+    const active = await run(deps, 'systemctl', ['is-active', unit]);
+    sections[`service:${unit}`] = clip(active.ok ? active.stdout : `inactive (${active.stderr.trim()})`);
+    const logs = await run(deps, 'journalctl', ['-u', unit, '-n', '100', '--no-pager']);
+    sections[`journal:${unit}`] = clip(logs.ok ? logs.stdout : `ERROR: ${logs.stderr}`);
+  }
+  let total = 0;
+  for (const key of Object.keys(sections)) total += Buffer.byteLength(sections[key], 'utf8');
+  return { status: 'ok', detail: { sections, bytes: total, truncated: total > MAX_TOTAL_DIAG_BYTES } };
+}
+
+async function waitFor(deps, probe, timeoutMs, intervalMs = 2000) {
+  const deadline = deps.now() + timeoutMs;
+  while (deps.now() < deadline) {
+    if (await probe()) return true;
+    await deps.sleep(intervalMs);
+  }
+  return false;
+}
+
+async function healthy(deps) {
+  try {
+    const response = await deps.fetch(deps.healthzUrl);
+    return response.status === 200;
+  } catch {
+    return false;
+  }
+}
+
+async function restart(deps, params) {
+  const targets = params.targets === 'all' ? ['rabbit', 'stun', 'agent'] : [params.targets];
+  const states = {};
+  for (const target of targets) {
+    const unit = UNITS[target];
+    const result = await run(deps, 'systemctl', ['restart', unit]);
+    if (!result.ok) return { status: 'failed', code: 'RESTART_FAILED', detail: { unit, stderr: result.stderr } };
+    const active = await run(deps, 'systemctl', ['is-active', unit]);
+    states[target] = active.ok ? active.stdout.trim() : 'inactive';
+  }
+  if (params.wait_healthy === false) return { status: 'ok', detail: { states } };
+  if (targets.includes('rabbit')) {
+    const ok = await waitFor(deps, () => healthy(deps), 60_000);
+    if (!ok) return { status: 'failed', code: 'HEALTH_TIMEOUT', detail: { states, probe: deps.healthzUrl } };
+  }
+  return { status: 'ok', detail: { states, waited: true } };
+}
+
+async function sha256Of(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+async function downloadTo(deps, urls, sha256) {
+  const errors = [];
+  for (const url of urls) {
+    try {
+      const response = await deps.fetch(url);
+      if (response.status !== 200) { errors.push(`${url}: HTTP ${response.status}`); continue; }
+      const buffer = Buffer.from(await response.arrayBuffer());
+      if (buffer.byteLength > MAX_DOWNLOAD_BYTES) { errors.push(`${url}: too large (${buffer.byteLength})`); continue; }
+      const digest = await sha256Of(buffer);
+      if (digest !== sha256) { errors.push(`${url}: sha256 ${digest} != expected`); continue; }
+      const file = join(tmpdir(), 'w2m-maintenance-' + Date.now() + '.tgz');
+      writeFileSync(file, buffer);
+      return { ok: true, file, bytes: buffer.byteLength };
+    } catch (error) {
+      errors.push(`${url}: ${error?.message ?? String(error)}`);
+    }
+  }
+  return { ok: false, errors };
+}
+
+async function update(deps, params, request) {
+  const downloaded = await downloadTo(deps, params.artifact_urls, params.artifact_sha256);
+  if (!downloaded.ok) return { status: 'failed', code: 'UPDATE_DOWNLOAD_FAILED', detail: { errors: downloaded.errors } };
+
+  const staging = join(deps.stagingRoot, 'w2m-maintenance-' + request.request_id);
+  try { rmSync(staging, { recursive: true, force: true }); } catch { /* staging may not exist */ }
+  mkdirSync(staging, { recursive: true });
+  const extracted = await run(deps, 'tar', ['-xzf', downloaded.file, '-C', staging]);
+  if (!extracted.ok) return { status: 'failed', code: 'UPDATE_EXTRACT_FAILED', detail: { stderr: extracted.stderr } };
+
+  const stagedPkg = join(staging, 'package', 'package.json');
+  if (!existsSync(stagedPkg)) return { status: 'failed', code: 'UPDATE_BAD_ARTIFACT', detail: { message: 'package/package.json missing' } };
+  const stagedVersion = JSON.parse(readFileSync(stagedPkg, 'utf8')).version;
+  if (stagedVersion !== params.version) return { status: 'failed', code: 'UPDATE_VERSION_MISMATCH', detail: { expected: params.version, artifact: stagedVersion } };
+
+  let rolledBack = false;
+  const hadPrevious = existsSync(deps.appDir);
+  if (hadPrevious) {
+    try { rmSync(deps.backupDir, { recursive: true, force: true }); } catch { /* old backup is replaceable */ }
+    try { renameSync(deps.appDir, deps.backupDir); } catch (error) { return { status: 'failed', code: 'UPDATE_BACKUP_FAILED', detail: { message: error?.message } }; }
+  }
+  try {
+    renameSync(join(staging, 'package'), deps.appDir);
+  } catch (error) {
+    if (hadPrevious) { try { renameSync(deps.backupDir, deps.appDir); } catch { /* rollback attempted */ } }
+    return { status: 'failed', code: 'UPDATE_SWAP_FAILED', detail: { message: error?.message } };
+  }
+
+  const restarted = params.restart_after_update !== false;
+  if (restarted) {
+    const units = params.target === 'relay' ? ['rabbit', 'stun', 'agent'] : ['agent'];
+    for (const target of units) {
+      const result = await run(deps, 'systemctl', ['restart', UNITS[target]]);
+      if (!result.ok) { rolledBack = true; break; }
+    }
+    if (!rolledBack) {
+      const healthOk = units.includes('rabbit') ? await waitFor(deps, () => healthy(deps), 60_000) : true;
+      if (!healthOk) rolledBack = true;
+    }
+  }
+  if (rolledBack) {
+    try {
+      rmSync(deps.appDir, { recursive: true, force: true });
+      renameSync(deps.backupDir, deps.appDir);
+      await run(deps, 'systemctl', ['restart', UNITS.agent]);
+    } catch { /* rollback best effort, reported below */ }
+    return { status: 'failed', code: 'UPDATE_ROLLED_BACK', detail: { version: params.version, rolled_back: true } };
+  }
+  return { status: 'ok', detail: { version: stagedVersion, sha256: params.artifact_sha256, bytes: downloaded.bytes, restarted, backup: hadPrevious ? deps.backupDir : null } };
+}
+
+/** Execute one verified request. Returns a result the runner writes to the done directory. */
+export async function executeAction(action, params, request, deps = defaultDeps()) {
+  if (action === 'diag') return diag(deps, params);
+  if (action === 'restart') return restart(deps, params);
+  if (action === 'update') return update(deps, params, request);
+  return { status: 'failed', code: 'MAINTENANCE_BAD_ACTION', detail: { action } };
+}

package/src/maintenance/grant.mjs

@@ -0,0 +1,139 @@
+/**
+ * Task-level execution grants (v1.3.10-beta.3 / M2 design slice).
+ *
+ * A grant is the operator's explicit, single-use authorisation for one argv on named machines. It is checked by the agent
+ * before the allow-list: an allow-list entry is a standing decision made by the machine owner, while a grant is a decision
+ * made now, for this, with an expiry — and the ledger can tell them apart afterwards.
+ *
+ * This module is the protocol only. Signing lives on the control side; verification runs on the machine that would execute
+ * the command. Nothing here executes anything.
+ */
+import { createHash, createPrivateKey, createPublicKey, sign as signBytes, verify as verifyBytes } from 'node:crypto';
+import { canonicalize } from './protocol.mjs';
+import { keyIdOf } from './operator-key.mjs';
+
+export const GRANT_PROTOCOL = 'w2m-grant/v1';
+export const MAX_GRANT_BYTES = 8 * 1024;
+export const MAX_GRANT_TTL_MS = 10 * 60 * 1000;
+export const CLOCK_SKEW_MS = 60 * 1000;
+
+const OBJ = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const STR = (value) => typeof value === 'string' && value !== '';
+
+export function argvHash(argv) {
+  return createHash('sha256').update(JSON.stringify(argv), 'utf8').digest('hex');
+}
+
+/**
+ * Build the unsigned grant body. The caller supplies the expanded argv (the operator must see what is being authorised).
+ */
+export function buildGrant({ taskId = null, machineIds, argv, mode, cwdRel, write, writeScope, maxUses = 1, ttlMs = 5 * 60 * 1000, nowMs = Date.now(), issuedBy = 'operator', grantId, nonce }) {
+  const grant = {
+    protocol: GRANT_PROTOCOL,
+    grant_id: grantId ?? 'gr-' + nowMs.toString(36) + '-' + createHash('sha256').update(String(Math.random())).digest('hex').slice(0, 10),
+    task_id: taskId,
+    machine_ids: [...machineIds],
+    argv_hash: argvHash(argv),
+    argv_head: argv.slice(0, 8).map((part) => String(part).slice(0, 160)),
+    max_uses: maxUses,
+    issued_at: new Date(nowMs).toISOString(),
+    expires_at: new Date(nowMs + ttlMs).toISOString(),
+    nonce: nonce ?? createHash('sha256').update(String(Math.random()) + String(nowMs)).digest('hex').slice(0, 32),
+    issued_by: issuedBy,
+  };
+  if (mode !== undefined) grant.mode = mode;
+  if (cwdRel !== undefined) grant.cwd_rel = cwdRel;
+  if (write !== undefined) grant.write = write;
+  if (writeScope !== undefined) grant.write_scope = writeScope;
+  return grant;
+}
+
+export function signingPayload(grant) {
+  const { signature: _signature, ...rest } = grant;
+  return canonicalize(rest);
+}
+
+/** Sign on the control side. The private key never leaves the operator's machine. */
+export function signGrant(grant, privateKeyPem) {
+  const privateKey = createPrivateKey(privateKeyPem);
+  const signature = signBytes(null, Buffer.from(signingPayload(grant), 'utf8'), privateKey);
+  const publicKey = createPublicKey(privateKey);
+  return { ...grant, signature: { alg: 'ed25519', key_id: keyIdOf(publicKey), value_base64: signature.toString('base64') } };
+}
+
+function checkConstraints(grant, context) {
+  const policy = context?.policy ?? {};
+  if (grant.mode !== undefined && typeof policy.mode === 'string' && grant.mode !== policy.mode) return { ok: false, code: 'GRANT_CONSTRAINT_VIOLATION', detail: { field: 'mode', grant: grant.mode, task: policy.mode } };
+  if (grant.cwd_rel !== undefined && typeof policy.cwd_rel === 'string' && grant.cwd_rel !== policy.cwd_rel) return { ok: false, code: 'GRANT_CONSTRAINT_VIOLATION', detail: { field: 'cwd_rel', grant: grant.cwd_rel, task: policy.cwd_rel } };
+  if (grant.write === true && policy.write !== true) return { ok: false, code: 'GRANT_CONSTRAINT_VIOLATION', detail: { field: 'write', reason: 'a grant cannot widen a read-only task' } };
+  if (Array.isArray(grant.write_scope) && Array.isArray(policy.write_scope)) {
+    for (const scope of grant.write_scope) if (!policy.write_scope.includes(scope)) return { ok: false, code: 'GRANT_CONSTRAINT_VIOLATION', detail: { field: 'write_scope', scope } };
+  }
+  return { ok: true };
+}
+
+/**
+ * Verify a grant against the concrete action about to run.
+ *
+ * @param {object} grant parsed JSON (untrusted)
+ * @param {{publicKeyPem: string, expectedKeyId?: string, nowMs?: number, machineId: string, taskId?: string|null,
+ *          argv: string[], usedGrantIds?: Set<string>, usedNonces?: Set<string>, usedCount?: number,
+ *          isRevoked?: (keyId: string) => boolean, policy?: object}} context
+ * @returns {{ok: true, grant: object} | {ok: false, code: string, detail: object}}
+ */
+export function verifyGrant(grant, context) {
+  const nowMs = Number.isInteger(context?.nowMs) ? context.nowMs : Date.now();
+  const fail = (code, message, detail = {}) => ({ ok: false, code, detail: { message, ...detail } });
+
+  if (!OBJ(grant)) return fail('GRANT_BAD_SHAPE', 'grant must be a JSON object');
+  if (Buffer.byteLength(JSON.stringify(grant), 'utf8') > MAX_GRANT_BYTES) return fail('GRANT_TOO_LARGE', `grant exceeds ${MAX_GRANT_BYTES} bytes`);
+  if (grant.protocol !== GRANT_PROTOCOL) return fail('GRANT_UNSUPPORTED_VERSION', 'unknown grant protocol', { got: String(grant.protocol) });
+  if (!STR(grant.grant_id) || !STR(grant.nonce)) return fail('GRANT_BAD_SHAPE', 'grant_id and nonce are required');
+  if (!Array.isArray(grant.machine_ids) || grant.machine_ids.length === 0) return fail('GRANT_BAD_SHAPE', 'machine_ids must be a non-empty array');
+  if (!Number.isInteger(grant.max_uses) || grant.max_uses < 1 || grant.max_uses > 100) return fail('GRANT_BAD_SHAPE', 'max_uses must be an integer in 1..100');
+  if (!/^[0-9a-f]{64}$/.test(String(grant.argv_hash ?? ''))) return fail('GRANT_BAD_SHAPE', 'argv_hash must be 64 lowercase hex');
+
+  const signature = grant.signature;
+  if (!OBJ(signature) || signature.alg !== 'ed25519' || !STR(signature.value_base64) || !STR(signature.key_id)) {
+    return fail('GRANT_MISSING_SIGNATURE', 'grant carries no usable ed25519 signature');
+  }
+  if (context?.expectedKeyId !== undefined && signature.key_id !== context.expectedKeyId) {
+    return fail('GRANT_UNKNOWN_KEY', 'grant was signed by a key this machine has not pinned', { key_id: signature.key_id, pinned: context.expectedKeyId });
+  }
+  if (typeof context?.isRevoked === 'function' && context.isRevoked(signature.key_id) === true) {
+    return fail('GRANT_REVOKED', 'signing key has been revoked', { key_id: signature.key_id });
+  }
+
+  let publicKey;
+  try { publicKey = createPublicKey(context?.publicKeyPem ?? ''); } catch { return fail('GRANT_UNKNOWN_KEY', 'no usable operator public key is configured'); }
+  let ok = false;
+  try { ok = verifyBytes(null, Buffer.from(signingPayload(grant), 'utf8'), publicKey, Buffer.from(signature.value_base64, 'base64')); } catch { ok = false; }
+  if (ok !== true) return fail('GRANT_BAD_SIGNATURE', 'signature does not cover this grant');
+
+  if (!STR(context?.machineId)) return fail('GRANT_BAD_SHAPE', 'machine binding is missing');
+  if (!grant.machine_ids.includes(context.machineId)) return fail('GRANT_WRONG_MACHINE', 'grant does not name this machine', { machine_ids: grant.machine_ids, local: context.machineId });
+
+  const issuedAt = Date.parse(String(grant.issued_at ?? ''));
+  const expiresAt = Date.parse(String(grant.expires_at ?? ''));
+  if (!Number.isFinite(issuedAt) || !Number.isFinite(expiresAt) || expiresAt <= issuedAt) return fail('GRANT_BAD_SHAPE', 'issued_at/expires_at are not a usable window');
+  if (expiresAt - issuedAt > MAX_GRANT_TTL_MS) return fail('GRANT_TTL_TOO_LONG', 'grant lives longer than the maximum TTL', { ttl_ms: expiresAt - issuedAt, max_ttl_ms: MAX_GRANT_TTL_MS });
+  if (issuedAt > nowMs + CLOCK_SKEW_MS) return fail('GRANT_FUTURE', 'grant is not valid yet', { issued_at: grant.issued_at });
+  if (nowMs > expiresAt) return fail('GRANT_EXPIRED', 'grant has expired', { expires_at: grant.expires_at });
+
+  if (grant.task_id !== null && grant.task_id !== undefined) {
+    if (typeof context?.taskId !== 'string' || context.taskId !== grant.task_id) return fail('GRANT_WRONG_TASK', 'grant is bound to a different task', { grant_task: grant.task_id, task: context?.taskId ?? null });
+  }
+  if (context?.usedGrantIds instanceof Set && context.usedGrantIds.has(grant.grant_id)) return fail('GRANT_REPLAY', 'grant_id was already used', { grant_id: grant.grant_id });
+  if (context?.usedNonces instanceof Set && context.usedNonces.has(grant.nonce)) return fail('GRANT_REPLAY', 'nonce was already used', { nonce: grant.nonce });
+  const used = Number.isInteger(context?.usedCount) ? context.usedCount : 0;
+  if (used >= grant.max_uses) return fail('GRANT_USES_EXHAUSTED', 'grant has no uses left', { max_uses: grant.max_uses, used });
+
+  if (!Array.isArray(context?.argv)) return fail('GRANT_BAD_SHAPE', 'the concrete argv is required for the hash comparison');
+  const actualHash = argvHash(context.argv);
+  if (actualHash !== grant.argv_hash) return fail('GRANT_ARGV_MISMATCH', 'argv_hash does not match the command about to run', { expected: grant.argv_hash, actual: actualHash });
+
+  const constraints = checkConstraints(grant, context);
+  if (constraints.ok !== true) return { ok: false, code: constraints.code, detail: constraints.detail };
+
+  return { ok: true, grant };
+}