@twinsearth/w2m-dsh-plugin 0.5.9 → 0.6.2

package/src/agent/agent.mjs

@@ -23,8 +23,8 @@
 
 import { Readable } from 'node:stream';
 import { access, constants as fsConstants } from 'node:fs/promises';
-import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 import {
@@ -49,7 +49,7 @@ import {
 } from './git.mjs';
 import { createSpool } from './spool.mjs';
 import { matchAllowedCommand, parseAllowedCommands } from './allowed-commands.mjs';
-import { CRYPTO_REASON, DeviceKey, PeerKeyStore } from './crypto.mjs';
+import { CRYPTO_REASON, DEVICE_KEY_FILE, DeviceKey, PeerKeyStore } from './crypto.mjs';
 import { DEFAULT_P2P_MODE, P2P_DEFAULTS, P2PNode, normalizeP2PMode, normalizeP2PPort } from './p2p-node.mjs';
 import { punchSession, reverseDialSession } from './p2p.mjs';
 import { createSigner } from '../signing.mjs';
@@ -141,6 +141,24 @@ export const AGENT_STATE_SCHEMA_VERSION = 1;
  */
 export const AGENT_STATE_PUBLISH_INTERVAL_MS = 30_000;
 
+/**
+ * How many times `publishState()` tries the final `renameSync` before giving up, and the base of
+ * the synchronous backoff between tries (attempt N waits N * base).
+ *
+ * The publish renames a temp file *over* `agent-state.json` while another process may be reading
+ * it -- the plugin in the DSH host, an editor, a backup agent, or an antivirus scanner. On Windows
+ * that contention comes back as `EPERM`/`EACCES` from the rename even though both paths are fine,
+ * and the condition clears within milliseconds; without a retry the publish is lost, and (before
+ * v0.5.10) its temp file was left behind, which is how one live state directory accumulated 266
+ * `agent-state.json.tmp-*` files.
+ *
+ * Bounded on purpose: 5 attempts, and only a retryable error is retried, so a permanent failure
+ * (the destination is a directory, the volume is gone, the paths are on different devices) costs at
+ * most 30ms of synchronous backoff on a diagnostics-only path.
+ */
+export const STATE_RENAME_ATTEMPTS = 5;
+export const STATE_RENAME_BACKOFF_MS = 3;
+
 /**
  * How many times a relay identity change may trigger an *immediate* cursor-less
  * re-attach before the agent falls back to the normal backoff ladder. A healthy
@@ -857,6 +875,56 @@ export class Heartbeat {
   }
 }
 
+/**
+ * Block the current thread for a few milliseconds.
+ *
+ * Only for {@link renameStateFile}'s backoff, and only on the failing path: `publishState()` is
+ * synchronous by design (an async publish would need a queue to keep two publishes from
+ * interleaving), and `Atomics.wait` on a throwaway shared buffer is the one way to wait without
+ * either a busy loop or an async boundary. There is no `await` here to yield at, and each wait is
+ * a handful of milliseconds.
+ *
+ * @param {number} ms
+ */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Is this rename failure the transient Windows-contention kind, rather than a real one? */
+function isRetryableRenameError(error) {
+  const code = error?.code;
+  return code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+}
+
+/**
+ * `renameSync` over the state file, retried briefly while the failure is transient.
+ *
+ * See {@link STATE_RENAME_ATTEMPTS} for why this exists at all. Only a retryable error is retried
+ * and only a bounded number of times, so the caller's "never throws" contract is preserved: the
+ * last error is rethrown for a permanent failure, exactly as a bare `renameSync` would have.
+ *
+ * @param {string} from The temp file this call created.
+ * @param {string} to The published path.
+ * @returns {number} The 1-based attempt that succeeded (a caller-visible fact for tests).
+ */
+function renameStateFile(from, to) {
+  /** @type {unknown} */
+  let lastError = null;
+  for (let attempt = 1; attempt <= STATE_RENAME_ATTEMPTS; attempt += 1) {
+    try {
+      renameSync(from, to);
+      return attempt;
+    } catch (error) {
+      lastError = error;
+      if (attempt === STATE_RENAME_ATTEMPTS || !isRetryableRenameError(error)) throw error;
+      sleepSync(STATE_RENAME_BACKOFF_MS * attempt);
+    }
+  }
+  // Unreachable: the loop either returns or throws. Kept so a future edit cannot make this
+  // function fall off the end and return `undefined` to a caller that expects a count.
+  throw lastError;
+}
+
 // ---------------------------------------------------------------------------
 // The agent
 // ---------------------------------------------------------------------------
@@ -920,6 +988,7 @@ export function createAgent(options) {
     project,
     stateDir,
     identity,
+    identityPath = null,
     caps,
     platform,
     once = false,
@@ -1025,11 +1094,17 @@ export function createAgent(options) {
   // *dispatcher* publishes in an offer, and "which key will this machine present" must not depend on
   // whether a particular code path happened to have run yet. `loadOrCreate` is the documented rule
   // ("generated the first time a machine pairs"), and a failure is never fatal — see `deviceKeyError`.
-  const deviceKeyOutcome = loadDeviceKey(options.deviceKey ?? null, stateDir, identity.machine_id);
+  const deviceKeyOutcome = loadDeviceKey(options.deviceKey ?? null, stateDir, identity.machine_id, identityPath);
   /** @type {object|null} This machine's static keypair, or null when there is none. */
   const deviceKey = deviceKeyOutcome.key;
   /** @type {string|null} Why there is no key, when there is none. Reported, never thrown. */
   const deviceKeyError = deviceKeyOutcome.error;
+  /**
+   * A key adopted from the pre-v0.6.2 location (`--state/device.key`). Reported once at startup,
+   * because a machine whose key moved is a machine whose public key a peer may have learned under the
+   * old file — silence here would make "my peers stopped talking to me" have no visible cause.
+   */
+  const deviceKeyMigratedFrom = deviceKeyOutcome.migratedFrom ?? null;
   /**
    * Peer static keys, learned from offers.
    *
@@ -1291,6 +1366,15 @@ export function createAgent(options) {
       log(result.ok ? 'info' : 'warn', `p2p ${p2pMode}: ${result.ok ? 'node started' : 'node did not start'}`, {
         error: result.error ?? null,
       });
+      // v0.6.2: a key adopted from the pre-fix location. Said out loud because the public key is what
+      // a peer authenticates this machine by, and a silent move would look like a peer going deaf.
+      if (deviceKeyMigratedFrom !== null) {
+        log('warn', 'p2p: adopting a device key from the old --state location', {
+          from: deviceKeyMigratedFrom,
+          public_key: deviceKey === null ? null : deviceKey.publicKeyBase64,
+          note: 'v0.6.2 moved device.key beside device.json; delete the old file once every peer has seen the new announcement',
+        });
+      }
       refreshP2PStatus();
       return result;
     })();
@@ -1929,19 +2013,47 @@ export function createAgent(options) {
    * the agent (or a running task) down -- the file is a diagnostic, not a
    * delivery guarantee -- so failure is logged once and otherwise ignored.
    *
+   * v0.5.10 adds the two halves of "the temp file is ours to clean up": the rename is retried
+   * briefly (see {@link renameStateFile}), and a publish that fails outright unlinks its own temp
+   * file. Before that, every failed rename left a `agent-state.json.tmp-*` behind, and a live state
+   * directory that could not rename for a few hours had accumulated 266 of them / 187 KB with the
+   * agent still warning once and carrying on.
+   *
    * @returns {object|null} The snapshot written, or null when the write failed.
    */
   function publishState() {
     const snapshot = agentStateSnapshot();
+    /** @type {string|null} The temp file this call created; null once it has been renamed away. */
+    let tmp = null;
     try {
       mkdirSync(stateDir, { recursive: true, mode: 0o700 });
-      const tmp = `${stateFilePath}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
+      tmp = `${stateFilePath}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
       writeFileSync(tmp, `${JSON.stringify(snapshot, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-      renameSync(tmp, stateFilePath);
+      const attempts = renameStateFile(tmp, stateFilePath);
+      // Renamed: the temp name is gone, so the catch below must not be handed it.
+      tmp = null;
+      if (attempts > 1) {
+        // Named, not silent: contention on this path was invisible before v0.5.10, and the only
+        // trace of it was a growing pile of temp files. One line per publish that needed a retry
+        // is the evidence an operator needs to recognise "something is holding the state file".
+        log('info', `published ${AGENT_STATE_FILE} after ${attempts} rename attempts`, {
+          path: stateFilePath,
+        });
+      }
       state.statePublishedAt = snapshot.updated_at;
       statePublishWarned = false;
       return snapshot;
     } catch (error) {
+      // A publish that failed is a publish whose temp file must not survive it. The unlink is
+      // itself best-effort and never rethrows: this function's contract is "never throws", and the
+      // file it is trying to remove is by definition one nobody wants.
+      if (tmp !== null) {
+        try {
+          unlinkSync(tmp);
+        } catch {
+          /* already gone, or the directory is unwritable -- nothing left to do here */
+        }
+      }
       if (!statePublishWarned) {
         statePublishWarned = true;
         log('warn', `could not publish ${AGENT_STATE_FILE} (diagnostics only; continuing)`, {
@@ -2692,9 +2804,14 @@ export function createAgent(options) {
       }
 
       // ---- 5. allow-list (default-deny) -----------------------------------
+      //
+      // `commandArgv` is the offer's own command line, which for a `pipeline` the relay sets to
+      // `stages[0].command_argv` -- so this check covers the first stage and nothing else. Every
+      // stage is checked below, before any of them runs; see the note there for why the second check
+      // has to exist even though the plugin's pre-flight also checks every stage.
       const allowed = matchAllowedCommand(commandArgv, allowedCommands);
       if (!allowed.allowed) {
-        log('warn', `refused ${offer.task_id}: COMMAND_NOT_ALLOWED`, { argv: commandArgv });
+        log('warn', `refused ${offer.task_id}: ${allowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED}`, { argv: commandArgv });
         await finish({
           offer,
           cwdRel,
@@ -2703,7 +2820,11 @@ export function createAgent(options) {
           anchorsAfter: null,
           execution: null,
           status: 'refused',
-          refusalReason: REFUSAL.COMMAND_NOT_ALLOWED,
+          // The matcher's own code, not a second spelling of it: the plugin's dispatch pre-flight
+          // reports the same literal for the same argv, and `COMMAND_REPARSING_ARGUMENT` and the two
+          // executable-identity codes have to travel the same way or the two ends would disagree
+          // about *why* one command was refused.
+          refusalReason: allowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED,
           warnings,
           startedAt,
           endedAt: new Date().toISOString(),
@@ -2744,6 +2865,48 @@ export function createAgent(options) {
         }))
         : [{ index: 0, command_argv: [...offer.command_argv], cwd_rel: offer.cwd_rel ?? '.', continue_on_failure: false }];
 
+      // ---- 6a. allow-list, again, for **every** stage ----------------------
+      //
+      // Step 5 checked the offer's `command_argv`, which the relay sets to `stages[0].command_argv`
+      // (src/relay/state.mjs) -- so on a chain it vouched for the first stage alone. The plugin's
+      // dispatch-time pre-flight does check every stage (src/plugin/tools.mjs), and its comment says
+      // why: "the allow-list is a default-deny control, and a chain is not an exemption from it".
+      // But that pre-flight runs on the *dispatcher*, and a dispatcher that posts straight to
+      // `/v1/task` with the operator token never calls it. Enforcement on the machine that executes
+      // is the only control that survives a hostile dispatcher, so it has to be here as well.
+      //
+      // The whole chain is refused before anything runs, not at the offending stage: running stages
+      // 1..n-1 of a chain that will not finish would leave side effects from work the caller was
+      // never allowed to ask for, and the plugin's pre-flight refuses the dispatch as a whole for the
+      // same reason. The refusal names the stage index, because "this chain is not allowed" is not
+      // actionable without knowing which stage.
+      for (const stage of plannedStages) {
+        const stageAllowed = matchAllowedCommand(stage.command_argv, allowedCommands);
+        if (stageAllowed.allowed) continue;
+        const code = stageAllowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED;
+        log('warn', `refused ${offer.task_id}: ${code} at stage ${stage.index}`, {
+          argv: stage.command_argv,
+        });
+        await finish({
+          offer,
+          cwdRel,
+          commandArgv,
+          anchorsBefore,
+          anchorsAfter: null,
+          execution: null,
+          status: 'refused',
+          refusalReason: code,
+          warnings,
+          startedAt,
+          endedAt: new Date().toISOString(),
+          // `protocol_violations` is the field a reader already finds a refused stage in (see the
+          // cwd refusal below), and the stage index is the fact that makes it actionable. The
+          // top-level `refusal_reason` carries the code the plugin's pre-flight would have reported.
+          protocolViolations: [`stage ${stage.index}: ${code} - ${stageAllowed.detail}`],
+        });
+        return;
+      }
+
       // The task's timeout is a budget for the whole chain, not per stage. Giving each stage the full
       // timeout would let a 16-stage pipeline run 16x longer than the caller asked for, and the relay
       // would have given up long before.
@@ -3920,32 +4083,88 @@ export function createAgent(options) {
  * be read so an operator can fix it. Refusing to start an agent because a *security upgrade* could not
  * complete is exactly the fleet-losing failure `docs/P2P-CRYPTO.md` §4 forbids.
  *
- * The key lives beside the spool and `agent-state.json` (the `--state` directory), which is where
- * `identity.mjs` puts `device.json` when the agent is run with `--state`. A caller that injected a
- * `DeviceKey` gets that one, which is the test seam and the way a caller supplies a key from
- * somewhere else entirely.
+ * WHERE THE KEY LIVES, AND THE BUG THAT CAME FROM GETTING IT WRONG (v0.6.2)
+ *
+ * `DeviceKey.load` documents the rule as "`device.key` **beside `device.json`**", and this function
+ * used to break it: it loaded from the `--state` directory, justified by a comment claiming that
+ * `identity.mjs` puts `device.json` there "when the agent is run with `--state`". That claim is false.
+ * `device.json` is fixed at `<DSH_HOME>/xclient/device.json` by the identity contract and `--state`
+ * does not move it — which is why an agent run as `--state ~/.dsh/xclient/localside-mac` had its
+ * identity one directory *above* its key.
+ *
+ * The measured consequence, on one machine running both halves of W2M: the plugin (which loads the key
+ * correctly, from `dirname(device.json)`) and the agent each generated a *different* pair, and both
+ * announced to the one `/v1/peer/{machine_id}` slot — the relay's record alternated between the two
+ * nodes' ports every few seconds, and the `static_key` a dispatcher read was one node's or the other's.
+ * A dispatcher that learns the wrong key cannot arm a handshake, so every direct channel came back
+ * `P2P_CRYPTO_PLAINTEXT_PEER` — reported as "the peer is an older build" when both ends were the same
+ * build on the same host.
+ *
+ * MIGRATION. `DeviceKey.load` warns that "silently generating a replacement key would make every peer
+ * that knows the old one refuse this machine". So a key already generated in the old location is
+ * adopted rather than abandoned: canonical first, then a copy forward from `--state`, then generate.
  *
- * @param {object|null} injected A `DeviceKey`, or null to load or generate one from the state dir.
- * @param {string} stateDir
+ * @param {object|null} injected A `DeviceKey`, or null to load or generate one.
+ * @param {string} stateDir The `--state` directory; the key's home only when `deviceFile` is absent.
  * @param {string} machineId
- * @returns {{key: object|null, error: string|null}}
+ * @param {string|null} [deviceFile] Absolute path of the `device.json` this agent loaded. The key
+ *   belongs beside it; pass the path the caller resolved rather than re-resolving `DSH_HOME` here.
+ * @returns {{key: object|null, error: string|null, migratedFrom: string|null}}
  */
-function loadDeviceKey(injected, stateDir, machineId) {
+function loadDeviceKey(injected, stateDir, machineId, deviceFile = undefined) {
   if (injected !== null && injected !== undefined) {
     if (typeof injected.sharedSecret !== 'function' || typeof injected.publicKeyBase64 !== 'string') {
-      return { key: null, error: 'P2P_CRYPTO_NO_KEY: the injected deviceKey is not a DeviceKey' };
+      return { key: null, error: 'P2P_CRYPTO_NO_KEY: the injected deviceKey is not a DeviceKey', migratedFrom: null };
     }
-    return { key: injected, error: null };
+    return { key: injected, error: null, migratedFrom: null };
   }
-  try {
-    const loaded = DeviceKey.load({ dir: stateDir, machineId });
-    return { key: loaded.key, error: null };
-  } catch (error) {
+
+  // Beside `device.json` — the documented rule. `identityPath` is the path the caller actually
+  // loaded, never a fresh global resolution: resolving `DSH_HOME` here would make a test (or any
+  // caller with an injected identity) read and *create* a key in the real user's home.
+  let canonicalDir = null;
+  if (typeof deviceFile === 'string' && deviceFile !== '') canonicalDir = dirname(deviceFile);
+
+  const legacyPath = join(stateDir, DEVICE_KEY_FILE);
+
+  /**
+   * Candidates in order. `mayCreate` is the whole subtlety: only a location that is *the* documented
+   * home may mint a key. A legacy directory is consulted to adopt a key that is already there, never
+   * to create one — `DeviceKey.load` warns that generating a replacement "would make every peer that
+   * knows the old one refuse this machine", so an upgrade must not silently change this machine's
+   * public key.
+   *
+   * With no `identityPath` the caller injected its own identity and there is no canonical home, so
+   * `--state` keeps the pre-v0.6.2 behaviour of being able to create. That is what stops a test or an
+   * embedder from reading and writing the real user's `~/.dsh/xclient`.
+   */
+  const candidates =
+    canonicalDir === null
+      ? [{ dir: stateDir, mayCreate: true, from: null }]
+      : [
+        { dir: canonicalDir, mayCreate: true, from: null },
+        ...(existsSync(legacyPath) ? [{ dir: stateDir, mayCreate: false, from: legacyPath }] : []),
+      ];
+
+  let lastError = null;
+  for (const candidate of candidates) {
+    try {
+      const loaded = DeviceKey.load({ dir: candidate.dir, machineId });
+      if (candidate.mayCreate === false && loaded.created) continue;
+      return { key: loaded.key, error: null, migratedFrom: candidate.from };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  if (lastError !== null) {
     return {
       key: null,
-      error: `P2P_CRYPTO_KEY_UNREADABLE: ${error instanceof Error ? error.message : String(error)}`,
+      error: `P2P_CRYPTO_KEY_UNREADABLE: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
+      migratedFrom: null,
     };
   }
+  return { key: null, error: null, migratedFrom: null };
 }
 
 /**