@twinsearth/w2m-dsh-plugin 2.0.4 → 2.0.6

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 12 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

package/src/agent/agent.mjs

@@ -33,6 +33,11 @@ import { tmpdir } from 'node:os';
 import { randomUUID , sign as signBytes } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
+import { deliverArtifact } from './artifact-delivery.mjs';
+
+import { createSseWatchdog } from './sse-watchdog.mjs';
+import { shouldAdvanceCursor } from './sse-cursor.mjs';
+
 import {
   EMPTY_SHA256,
   classifyExit,
@@ -1921,6 +1926,8 @@ export function createAgent(options) {
   const COMPLETED_CACHE_LIMIT = 64;
   let pumping = false;
   let streamAbort = null;
+/** Set when the current attach attempt parsed the relay's `ready` frame. */
+let attemptAttached = false;
   let runAbort = null;
   /** @type {Heartbeat|null} */
   let heartbeat = null;
@@ -2247,26 +2254,19 @@ export function createAgent(options) {
    * @param {string} body
    * @returns {Promise<{ok: boolean, status: number, sha256?: string, code?: string}>}
    */
-  async function putBlobBytes(sha256, body) {
-    const path = `/v1/fleet/blobs/${sha256}`;
-    // The stage's stdout arrives as a Buffer. Work on BYTES: the name must be the hash of exactly what is sent, and the
-    // signature must cover those same bytes -- decoding and re-encoding would replace invalid UTF-8 and change the hash.
-    const bytes = Buffer.isBuffer(body) ? body : Buffer.from(String(body ?? ''), 'utf8');
-    const headers = { 'content-type': 'application/octet-stream', accept: 'application/json' };
-    if (token()) headers.authorization = `Bearer ${token()}`;
-    Object.assign(headers, signingHeaders('PUT', path, bytes.toString('utf8')));
-    try {
-      const response = await fetchImpl(url(path), { method: 'PUT', headers, body: bytes });
-      if (response.ok) return { ok: true, status: response.status, sha256 };
-      let code = `HTTP_${response.status}`;
-      try {
-        const parsed = JSON.parse(await response.text());
-        if (typeof parsed?.error?.code === 'string') code = parsed.error.code;
-      } catch { /* the code is then the HTTP status, which is still a name */ }
-      return { ok: false, status: response.status, code };
-    } catch (error) {
-      return { ok: false, status: 0, code: error instanceof Error ? 'BLOB_UPLOAD_FAILED' : 'BLOB_UPLOAD_FAILED' };
-    }
+  async function putBlobBytes(sha256, body, kind = 'stdout', taskId = null) {
+    // A3/S4: artifacts leave through the user's sink (dir/git/ssh), never through the relay.
+    // Without a sink the bytes are kept locally and the caller reports ARTIFACT_NOT_DELIVERED;
+    // the relay is not contacted at all.
+    const delivered = await deliverArtifact({
+      stateDir,
+      kind,
+      bytes: body,
+      taskId: typeof taskId === 'string' && taskId !== '' ? taskId : 'unknown-task',
+      machineId: identity.machine_id,
+    });
+    if (delivered.ok === true) return { ok: true, status: 200, sha256: delivered.sha256, ref: delivered.ref };
+    return { ok: false, status: 0, code: delivered.code ?? 'ARTIFACT_NOT_DELIVERED', reason: delivered.reason ?? null, local: delivered.local ?? null };
   }
 
   /** @param {string} path @param {object} body @param {number} [retries] */
@@ -3359,8 +3359,12 @@ export function createAgent(options) {
           // The agent caps what it keeps in memory; if that cap was hit the blob holds the same bytes the hash covers, and
           // the warning says so instead of letting a reader assume the stage printed exactly this much.
           if (ran.truncated_stdout === true && !warnings.includes('PIPELINE_STDOUT_TRUNCATED')) warnings.push('PIPELINE_STDOUT_TRUNCATED');
-          const uploaded = await putBlobBytes(ran.stdout_sha256, ran.stdout);
-          if (uploaded.ok !== true) {
+          const uploaded = await putBlobBytes(ran.stdout_sha256, ran.stdout, 'stdout', offer.task_id);
+          if (uploaded.ok !== true && uploaded.code === 'ARTIFACT_NOT_DELIVERED') {
+            // No sink configured: the stage itself succeeded and its bytes are kept locally.
+            warnings.push('ARTIFACT_NOT_DELIVERED');
+            blobSha256 = null;
+          } else if (uploaded.ok !== true) {
             log("warn", offer.task_id + " stage " + stage.index + ": blob upload failed", { code: uploaded.code });
             stageReports.push({
               index: stage.index,
@@ -3377,9 +3381,10 @@ export function createAgent(options) {
             });
             stoppedAt = stage.index;
             break;
+          } else {
+            blobSha256 = uploaded.sha256;
+            lastBlobSha256 = blobSha256;
           }
-          blobSha256 = uploaded.sha256;
-          lastBlobSha256 = blobSha256;
         }
         stageReports.push({
           index: stage.index,
@@ -3422,12 +3427,12 @@ export function createAgent(options) {
         const plainPlan = planStageOutput({ machineId: identity.machine_id, stageIndex: 0, stdoutBytes: execution.stdout_bytes });
         if (plainPlan.ok === true && plainPlan.mode === 'blob') {
           if (execution.truncated_stdout === true && !warnings.includes('STDOUT_TRUNCATED')) warnings.push('STDOUT_TRUNCATED');
-          const uploaded = await putBlobBytes(execution.stdout_sha256, execution.stdout);
+          const uploaded = await putBlobBytes(execution.stdout_sha256, execution.stdout, 'stdout', offer.task_id);
           if (uploaded.ok === true) {
             lastBlobSha256 = uploaded.sha256;
           } else {
             log('warn', offer.task_id + ': plain stdout blob upload failed', { code: uploaded.code });
-            warnings.push('BLOB_UPLOAD_FAILED');
+            warnings.push(uploaded.code === 'ARTIFACT_NOT_DELIVERED' ? 'ARTIFACT_NOT_DELIVERED' : 'BLOB_UPLOAD_FAILED');
           }
         }
       }
@@ -3451,9 +3456,9 @@ export function createAgent(options) {
         let patchSha = null;
         if (patch.ok === true && typeof patch.patch === 'string' && patch.patch.trim() !== '') {
           const sha = sha256Hex(patch.patch);
-          const uploaded = await putBlobBytes(sha, patch.patch);
+          const uploaded = await putBlobBytes(sha, patch.patch, 'patch', offer.task_id);
           if (uploaded.ok === true) patchSha = sha;
-          else warnings.push('PATCH_UPLOAD_FAILED');
+          else warnings.push(uploaded.code === 'ARTIFACT_NOT_DELIVERED' ? 'ARTIFACT_NOT_DELIVERED' : 'PATCH_UPLOAD_FAILED');
         }
         const removed = await removeWorktree({ repoDir: project, worktreeDir: workspaceState.worktreeDir });
         if (removed.ok !== true) warnings.push('WORKTREE_CLEANUP_FAILED');
@@ -3833,7 +3838,24 @@ export function createAgent(options) {
     // break the "proxy strips the prefix" deployment (see signingHeaders).
     Object.assign(headers, signingHeaders('GET', `/v1/stream?${query.toString()}`));
 
-    const response = await fetchImpl(streamUrl, { headers, signal: streamAbort.signal });
+    // Header deadline: a proxy that accepts the socket but never returns headers must not hang the
+    // agent forever. Node >= 20.19 has AbortSignal.any, and every other HTTP call in the tree already
+    // carries a timeout.
+    const headerTimeoutMs = Number(process.env.W2M_SSE_FIRST_FRAME_MS) > 0 ? Number(process.env.W2M_SSE_FIRST_FRAME_MS) : 5000;
+    const headerSignal = typeof AbortSignal.any === 'function'
+      ? AbortSignal.any([streamAbort.signal, AbortSignal.timeout(headerTimeoutMs)])
+      : streamAbort.signal;
+    let response;
+    try {
+      response = await fetchImpl(streamUrl, { headers, signal: headerSignal });
+    } catch (error) {
+      if (streamAbort.signal.aborted) throw error;
+      const timeout = new Error('SSE_FIRST_FRAME_TIMEOUT');
+      timeout.code = 'SSE_FIRST_FRAME_TIMEOUT';
+      state.lastRelayError = { at: new Date().toISOString(), http_status: null, code: timeout.code, path: '/v1/stream' };
+      publishState();
+      throw timeout;
+    }
     if (!response.ok) {
       const body = await response.text().catch(() => '');
       let code = null;
@@ -3855,19 +3877,51 @@ export function createAgent(options) {
       throw error;    }
     if (!response.body) throw new Error('stream response had no body');
 
+    // P0-f: two deadlines on the stream this attempt. A half-open connection must not look
+    // like a healthy one forever; the relay keepalive is 15 s, so 45 s is three missed beats.
+    const envMs = (name) => (Number(process.env[name]) > 0 ? Number(process.env[name]) : undefined);
+    let timeoutCode = null;
+    let source = null;
+    const watchdog = createSseWatchdog({
+      firstFrameMs: envMs('W2M_SSE_FIRST_FRAME_MS'),
+      idleMs: envMs('W2M_SSE_IDLE_MS'),
+      onTimeout: (code) => {
+        timeoutCode = code;
+        state.lastRelayError = { at: new Date().toISOString(), http_status: null, code, path: '/v1/stream' };
+        publishState();
+        const error = new Error(code);
+        error.code = code;
+        try { source?.destroy(error); } catch { /* already gone */ }
+      },
+    });
+
     // Both assignments mark the same stream attempt as no longer live: one before the read loop, one
     // after it ends. Only one stream runs at a time, so there is nothing to interleave with.
     // eslint-disable-next-line require-atomic-updates -- one stream attempt at a time
     state.connected = false;
     const decoder = new TextDecoder('utf-8');
     const parser = new SseParser();
-    const source = Readable.fromWeb(response.body);
+    source = Readable.fromWeb(response.body);
 
-    for await (const chunk of source) {
-      if (state.stopped) break;
-      for (const frame of parser.push(decoder.decode(chunk, { stream: true }))) {
-        handleFrame(frame);
+    try {
+      for await (const chunk of source) {
+        if (state.stopped) break;
+        watchdog.noteBytes();
+        for (const frame of parser.push(decoder.decode(chunk, { stream: true }))) {
+          watchdog.noteFrame();
+          handleFrame(frame);
+        }
+      }
+    } catch (error) {
+      if (timeoutCode !== null) {
+        const timeout = new Error(timeoutCode);
+        timeout.code = timeoutCode;
+        log('warn', 'event stream watchdog fired; reconnecting', { code: timeoutCode });
+        throw timeout;
       }
+      throw error;
+    } finally {
+      watchdog.dispose();
     }
     state.connected = false;
     publishState();
@@ -3934,7 +3988,9 @@ export function createAgent(options) {
    */
   function dispatchFrame(payload, source) {
     const type = payload?.type ?? source.event;
-    if (source.transport === 'relay') {
+    if (source.transport === 'relay' && shouldAdvanceCursor({ type, event: source.event })) {
+      // P0-f: ready/notice carry sequence numbers that never entered the replay ring; adopting one
+      // would claim events that were never received and a reconnect would skip the real gap.
       if (Number.isInteger(payload?.seq)) state.seq = Math.max(state.seq, payload.seq);
       else if (source.id && /^\d+$/.test(source.id)) state.seq = Math.max(state.seq, Number(source.id));
     }
@@ -3950,6 +4006,7 @@ export function createAgent(options) {
         }
         // §3.1: nothing counts as connected before `ready` arrives.
         state.connected = true;
+        attemptAttached = true;
         const relayId =
           typeof payload.relay_id === 'string' && payload.relay_id !== '' ? payload.relay_id : null;
         const previousRelayId = state.relayId;
@@ -4296,6 +4353,7 @@ export function createAgent(options) {
       const response = await postJson('/v1/heartbeat', {
         diagnostic: true,
         machine_id: identity.machine_id,
+        ...(caps === null || caps === undefined ? {} : { caps }),
         ...heartbeatDiagnostics({
           rttMs: state.rttMs,
           reconnectAttempts: state.reconnectAttempts,
@@ -4416,6 +4474,7 @@ export function createAgent(options) {
         streamAbort = new AbortController();
         state.streamRestartRequested = false;
         const openedAt = Date.now();
+        attemptAttached = false;
         /** @type {Error|null} */
         let failure = null;
         try {
@@ -4449,7 +4508,9 @@ export function createAgent(options) {
           });
         }
 
-        const stable = livedMs >= STABLE_STREAM_MS;
+        // A stream that never delivered `ready` is not stable however long the socket lived: the
+        // watchdog deadlines are seconds, so the old rule reset the backoff to 500 ms forever.
+        const stable = attemptAttached && livedMs >= STABLE_STREAM_MS;
         if (stable) {
           reconnectAttempt = 0;
           restartReconnects = 0;

package/src/agent/artifact-delivery.mjs

@@ -0,0 +1,89 @@
+/**
+ * S4 data-plane delivery (A3): artifacts leave the agent through a USER sink, never through relay.
+ *
+ * Order of events:
+ *   1. no sink configured -> keep the bytes locally (0600) and report
+ *      ARTIFACT_NOT_DELIVERED / DATA_PLANE_SINK_REQUIRED; the relay is not contacted;
+ *   2. sink configured -> write the sealed bytes to the sink (dir/git/ssh), then build an ArtifactRef
+ *      (metadata only, <= 4 KiB) that a reader can resolve against the same sink.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { createArtifactRef } from '../util/artifact-ref.mjs';
+import { createDirSink } from './sinks/dir-sink.mjs';
+import { createGitSink } from './sinks/git-sink.mjs';
+import { createSshSink } from './sinks/ssh-sink.mjs';
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+const SAFE_TASK = /^[A-Za-z0-9._-]{1,80}$/;
+
+/** Read `<stateDir>/dataplane/sink.json` and build the configured sink, or null (fail closed). */
+export function loadArtifactSink(stateDir) {
+  if (typeof stateDir !== 'string' || stateDir === '') return null;
+  const file = join(stateDir, 'dataplane', 'sink.json');
+  if (!existsSync(file)) return null;
+  try {
+    const config = JSON.parse(readFileSync(file, 'utf8'));
+    if (config?.kind === 'dir' && typeof config.root === 'string') return createDirSink({ root: config.root });
+    if (config?.kind === 'lan-git' && typeof config.root === 'string') return createGitSink({ root: config.root, remote: config.remote ?? null, branch: config.branch ?? null });
+    if (config?.kind === 'ssh' && typeof config.host === 'string' && typeof config.user === 'string' && typeof config.dir === 'string') {
+      return createSshSink({ host: config.host, user: config.user, dir: config.dir, port: Number.isInteger(config.port) ? config.port : null, keyPath: typeof config.keyPath === 'string' ? config.keyPath : null });
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deliver one artifact.
+ *
+ * @param {{stateDir: string, kind?: 'stdout'|'stderr'|'patch'|'commit'|'reduce-input', bytes: Buffer|string,
+ *          taskId: string, machineId: string, stepId?: string|null, sink?: object|null}} input
+ * @returns {Promise<{ok: true, ref: object, sha256: string, bytes: number}
+ *                 | {ok: false, code: 'ARTIFACT_NOT_DELIVERED', reason: string, local: object}>}
+ */
+export async function deliverArtifact(input) {
+  const bytes = Buffer.isBuffer(input?.bytes) ? input.bytes : Buffer.from(String(input?.bytes ?? ''), 'utf8');
+  const digest = sha256(bytes);
+  const taskId = typeof input?.taskId === 'string' && input.taskId !== '' ? input.taskId : 'unknown-task';
+  const machineId = typeof input?.machineId === 'string' && input.machineId !== '' ? input.machineId : 'unknown-machine';
+  const taskDir = SAFE_TASK.test(taskId) ? taskId : 'unknown-task';
+  const kind = typeof input?.kind === 'string' ? input.kind : 'stdout';
+  const stateDir = typeof input?.stateDir === 'string' ? input.stateDir : '';
+  const localPath = join(stateDir, 'artifacts', taskDir, kind + '-' + digest + '.bin');
+  const keepLocal = () => {
+    try {
+      mkdirSync(join(stateDir, 'artifacts', taskDir), { recursive: true, mode: 0o700 });
+      writeFileSync(localPath, bytes, { encoding: 'utf8', mode: 0o600 });
+      return { sha256: digest, bytes: bytes.length, path: localPath };
+    } catch {
+      return { sha256: digest, bytes: bytes.length, path: null };
+    }
+  };
+  const sink = input?.sink === undefined ? loadArtifactSink(stateDir) : input.sink;
+  if (sink === null || sink === undefined) {
+    return { ok: false, code: 'ARTIFACT_NOT_DELIVERED', reason: 'DATA_PLANE_SINK_REQUIRED', local: keepLocal() };
+  }
+  const objectId = randomBytes(16).toString('hex');
+  const written = await sink.writeObject({ objectId, body: bytes, expectSha256: digest });
+  if (written.ok !== true) {
+    return { ok: false, code: 'ARTIFACT_NOT_DELIVERED', reason: written.code ?? 'SINK_WRITE_FAILED', local: keepLocal() };
+  }
+  const ref = createArtifactRef({
+    objectId,
+    taskId: taskId,
+    stepId: typeof input?.stepId === 'string' ? input.stepId : null,
+    machineId,
+    kind,
+    sinkKind: sink.kind === 'lan-git' ? 'lan-git' : sink.kind,
+    relPath: written.rel_path ?? objectId + '.json',
+    cipherSha256: digest,
+    cipherBytes: bytes.length,
+    plainBytes: bytes.length,
+  });
+  if (ref.ok !== true) return { ok: false, code: 'ARTIFACT_NOT_DELIVERED', reason: ref.code ?? 'REF_INVALID', local: keepLocal() };
+  return { ok: true, ref: ref.ref, sha256: digest, bytes: bytes.length };
+}

package/src/agent/caps.mjs

@@ -20,7 +20,7 @@
  * leaks into an envelope.
  */
 
-import { chmodSync, mkdtempSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir, release as osRelease } from 'node:os';
 import { basename, extname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -40,7 +40,20 @@ export {
 } from './resolve.mjs';
 
 /** Keys of the contract's `caps` object — nothing else may be added. */
-export const CAPS_KEYS = ['case_sensitive_fs', 'symlinks', 'exec_bit', 'python', 'npm', 'node'];
+export const CAPS_KEYS = ['case_sensitive_fs', 'symlinks', 'exec_bit', 'python', 'npm', 'node', 'plugin_version'];
+
+/** The plugin's own version, read once from the package manifest (the version gate compares it). */
+let pluginVersionCache = null;
+export function pluginVersion() {
+  if (pluginVersionCache !== null) return pluginVersionCache;
+  try {
+    const manifest = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8').replace(/^\uFEFF/, ''));
+    pluginVersionCache = typeof manifest.version === 'string' && manifest.version !== '' ? manifest.version : null;
+  } catch {
+    pluginVersionCache = null;
+  }
+  return pluginVersionCache;
+}
 
 /**
  * Run `<exe> <args>` and return the first regex capture of stdout+stderr.
@@ -403,6 +416,7 @@ export async function probeCapsDetailed(options = {}) {
     python: python.version,
     npm: npm.version,
     node: node.version,
+    plugin_version: pluginVersion(),
   };
 
   return {

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

@@ -0,0 +1,78 @@
+/**
+ * Git sink (S4/D3): artifacts land in a user-run git worktree and are committed there.
+ *
+ * The sink never carries plaintext: callers hand it the sealed object bytes. Writes are
+ * object-id-addressed (`<object_id>.json`), hash-verified on the way in and out, and committed so
+ * the same directory can be synced by the operator's own git remote (no relay data plane).
+ */
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+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');
+
+/**
+ * @param {{root: string, run?: Function, commitPrefix?: string, remote?: string|null, branch?: string|null}} input
+ */
+export function createGitSink({ root, run = null, commitPrefix = 'w2m artifact', remote = null, branch = null }) {
+  if (typeof root !== 'string' || root === '') throw new Error('SINK_ROOT_REQUIRED');
+  if (!existsSync(join(root, '.git'))) throw new Error('GIT_SINK_NOT_A_REPO');
+  mkdirSync(root, { recursive: true });
+  const git = (args) => (run === null ? execFileSync('git', args, { cwd: root, stdio: 'pipe' }) : run(args));
+  const pathOf = (objectId) => join(root, 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);
+    try {
+      git(['add', '--', objectId + '.json']);
+      git(['commit', '-m', commitPrefix + ' ' + objectId, '--', objectId + '.json']);
+      if (remote !== null && branch !== null) git(['push', remote, 'HEAD:' + branch]);
+    } catch (error) {
+      return { ok: false, code: 'GIT_SINK_COMMIT_FAILED', detail: error instanceof Error ? error.message : String(error) };
+    }
+    return { ok: true, objectId, path, rel_path: objectId + '.json', sha256: actual, bytes: bytes.length };
+  }
+
+  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: 'lan-git',
+    writeObject,
+    readObject,
+    async listObjects() {
+      return readdirSync(root).filter((name) => name.endsWith('.json') && OBJECT_ID.test(name.slice(0, -5))).map((name) => name.slice(0, -5));
+    },
+    async removeObject(objectId) {
+      if (typeof objectId !== 'string' || !OBJECT_ID.test(objectId)) return { ok: false, code: 'OBJECT_ID_INVALID' };
+      try {
+        unlinkSync(pathOf(objectId));
+        git(['rm', '--cached', '--ignore-unmatch', '--', objectId + '.json']);
+        git(['commit', '-m', commitPrefix + ' remove ' + objectId, '--', objectId + '.json']);
+        return { ok: true };
+      } catch { return { ok: false, code: 'OBJECT_NOT_FOUND' }; }
+    },
+  };
+}

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

@@ -0,0 +1,83 @@
+/**
+ * SSH sink (S4/D3): artifacts are written to a directory on a user-owned host over SSH.
+ *
+ * No relay data plane: the operator supplies the host and directory; every path component is
+ * validated before it is embedded in the remote command, and the local side verifies the object
+ * hash again after a read. The transport is delegated to the system `ssh` binary (optionally
+ * injected for tests), so key handling stays with the user's existing SSH configuration.
+ */
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+const OBJECT_ID = /^[0-9a-f]{32,64}$/;
+const HOST = /^[A-Za-z0-9._:[\]-]+$/;
+const USER = /^[A-Za-z0-9._-]+$/;
+const DIR = /^\/[A-Za-z0-9._/-]*$/;
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+function defaultRun(args, input) {
+  const result = spawnSync('ssh', args, { input, maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+  if (result.error) return { ok: false, code: 'SSH_SPAWN_FAILED', detail: result.error.message };
+  if (result.status !== 0) return { ok: false, code: 'SSH_COMMAND_FAILED', detail: String(result.stderr ?? '').slice(0, 400) };
+  return { ok: true, stdout: Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout ?? '') };
+}
+
+/**
+ * @param {{host: string, user: string, dir: string, port?: number, keyPath?: string|null, run?: Function}} input
+ */
+export function createSshSink({ host, user, dir, port = null, keyPath = null, run = null }) {
+  if (typeof host !== 'string' || !HOST.test(host)) throw new Error('SSH_SINK_HOST_INVALID');
+  if (typeof user !== 'string' || !USER.test(user)) throw new Error('SSH_SINK_USER_INVALID');
+  if (typeof dir !== 'string' || !DIR.test(dir) || dir.includes('..')) throw new Error('SSH_SINK_DIR_INVALID');
+  if (port !== null && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error('SSH_SINK_PORT_INVALID');
+  if (keyPath !== null && (typeof keyPath !== 'string' || keyPath === '')) throw new Error('SSH_SINK_KEY_INVALID');
+  const exec = run ?? defaultRun;
+  const target = user + '@' + host;
+  const baseArgs = ['-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=accept-new'];
+  if (port !== null) baseArgs.push('-p', String(port));
+  if (keyPath !== null) baseArgs.push('-i', keyPath);
+  const pathOf = (objectId) => dir.replace(/\/$/, '') + '/' + objectId + '.json';
+  const ssh = (remoteCommand, input = undefined) => exec([...baseArgs, '--', target, remoteCommand], input);
+
+  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 final = pathOf(objectId);
+    const tmp = final + '.tmp-' + process.pid + '-' + Date.now().toString(36);
+    const written = ssh('mkdir -p ' + dir + ' && cat > ' + tmp + ' && mv ' + tmp + ' ' + final, bytes);
+    if (written.ok !== true) return written;
+    return { ok: true, objectId, rel_path: objectId + '.json', remote_path: final, sha256: actual, bytes: bytes.length };
+  }
+
+  async function readObject({ objectId, expectSha256 = null }) {
+    if (typeof objectId !== 'string' || !OBJECT_ID.test(objectId)) return { ok: false, code: 'OBJECT_ID_INVALID' };
+    const read = ssh('cat ' + pathOf(objectId));
+    if (read.ok !== true) return read;
+    const bytes = read.stdout;
+    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, sha256: actual, bytes };
+  }
+
+  return {
+    kind: 'ssh',
+    writeObject,
+    readObject,
+    async listObjects() {
+      const listed = ssh('ls -1 ' + dir);
+      if (listed.ok !== true) return [];
+      return listed.stdout.toString('utf8').split('\n').map((name) => name.trim()).filter((name) => name.endsWith('.json') && OBJECT_ID.test(name.slice(0, -5))).map((name) => name.slice(0, -5));
+    },
+    async removeObject(objectId) {
+      if (typeof objectId !== 'string' || !OBJECT_ID.test(objectId)) return { ok: false, code: 'OBJECT_ID_INVALID' };
+      const removed = ssh('rm -f ' + pathOf(objectId));
+      return removed.ok === true ? { ok: true } : removed;
+    },
+  };
+}

package/src/agent/sse-cursor.mjs

@@ -0,0 +1,16 @@
+/**
+ * SSE cursor rule (P0-f): only replayable frames may move the resume cursor.
+ *
+ * The relay's `ready` and `notice` frames are assigned a sequence number with `reserveSeq()` but are
+ * not written into the replay ring, so a client that adopts those numbers claims to have seen events
+ * it never received - and a reconnect then silently skips the gap. The cursor therefore advances
+ * only for frames the ring actually replays (`task.*`, `peer.*`, `result.ack`).
+ */
+export const NON_REPLAYABLE_EVENTS = Object.freeze(['ready', 'notice']);
+
+/** @param {{type?: string|null, event?: string|null}} input */
+export function shouldAdvanceCursor(input) {
+  const type = String(input?.type ?? input?.event ?? '');
+  if (type === '') return false;
+  return !NON_REPLAYABLE_EVENTS.includes(type);
+}

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();
+    },
+  };
+}