claude-code-session-manager 0.108.0 → 0.110.0

package/src/main/lib/crossProjectFeedback.cjs

@@ -83,6 +83,14 @@ const DEFAULT_FEEDBACK_AGENT = 'architect';
 const MAX_TITLE_CHARS = 200;
 const MAX_BODY_CHARS = 20000;
 const MAX_REFERENCES = 20;
+const MAX_MOTIVATION_CHARS = 2000;
+const MAX_LIST_ITEMS = 20;
+const MAX_LIST_ITEM_CHARS = 500;
+const MAX_SERIES_KEY_CHARS = 60;
+const MAX_SERIES_TITLE_CHARS = 120;
+const MAX_SERIES_TOTAL = 50;
+const MAX_ORIGIN_ASK_CHARS = 300;
+const KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 /** Bound on how many `~/.claude/projects/` folders listFeedbackTargets will
  *  resolve. That directory accumulates one folder per path the CLI was ever
@@ -127,6 +135,29 @@ function isSessionManagerProject(cwd) {
   return isDirectory(path.join(cwd, OPS_ROOT_DIR));
 }
 
+/**
+ * resolveOriginAsk(fromCwd, fromEpicId) → string | null
+ *
+ * The sending Epic's own human goal (single line, ≤ 300 chars), read from the
+ * sender project's active-index.json. Never throws: a missing Epic or an
+ * unreadable file is just "no origin known".
+ */
+function resolveOriginAsk(fromCwd, fromEpicId) {
+  if (!fromCwd || !fromEpicId) return null;
+  try {
+    const sessions = readActiveIndex(fromCwd).sessions;
+    if (!Object.prototype.hasOwnProperty.call(sessions, fromEpicId)) return null;
+    const goal = singleLine(sessions[fromEpicId] && sessions[fromEpicId].goalText);
+    return goal ? goal.slice(0, MAX_ORIGIN_ASK_CHARS) : null;
+  } catch {
+    return null;
+  }
+}
+
+function seriesLine(series) {
+  return series ? `Part ${series.index} of ${series.total} — ${singleLine(series.title)}` : '';
+}
+
 /**
  * composeFeedbackIntake({ fromCwd, fromEpicId, title, body, referencePaths })
  *   → { goalText, openingPrompt, sections }
@@ -160,6 +191,12 @@ function composeFeedbackIntake({
   agentName = DEFAULT_FEEDBACK_AGENT,
   agentDescription = null,
   referencePaths = [],
+  originAsk = null,
+  motivation = '',
+  plan = [],
+  acceptanceCriteria = [],
+  outOfScope = [],
+  series = null,
 } = {}) {
   const trimmedTitle = singleLine(title);
   const trimmedBody = String(body ?? '').trim();
@@ -174,21 +211,36 @@ function composeFeedbackIntake({
     });
   }
 
+  const fromPath = singleLine(fromCwd);
+  const fromName = path.basename(fromPath) || fromPath;
   const origin = fromEpicId
-    ? `${singleLine(fromCwd)} (session ${singleLine(fromEpicId)})`
-    : singleLine(fromCwd);
+    ? `${fromName} (${fromPath}, session ${singleLine(fromEpicId)})`
+    : `${fromName} (${fromPath})`;
+  const askClause = originAsk ? ` It was raised while working on: ${singleLine(originAsk)}.` : '';
   sections.push({
     kind: 'input',
     label: 'Input',
     text:
-      `This session is INBOUND FEEDBACK from another project: ${origin}. `
+      `This session is INBOUND FEEDBACK from another project: ${origin}.${askClause} `
       + 'Nobody in this project wrote the report below — an agent working in that project did, and it '
       + 'may be wrong about this codebase. Verify the claim against the code here before acting on it, '
       + 'and if it does not hold, say so and close the session rather than building against it.',
     source: fromCwd,
   });
 
-  const goalBody = trimmedTitle ? `Goal: ${trimmedTitle}\n\n${trimmedBody}` : trimmedBody;
+  const trimmedMotivation = String(motivation ?? '').trim();
+  const blocks = [];
+  if (series) blocks.push(seriesLine(series));
+  if (trimmedMotivation) blocks.push(`## Why\n${trimmedMotivation}`);
+  if (plan.length) blocks.push(`## Proposed plan\n${plan.map((x, i) => `${i + 1}. ${singleLine(x)}`).join('\n')}`);
+  if (acceptanceCriteria.length) {
+    blocks.push(`## Acceptance criteria\n${acceptanceCriteria.map((x) => `- [ ] ${singleLine(x)}`).join('\n')}`);
+  }
+  if (outOfScope.length) blocks.push(`## Out of scope\n${outOfScope.map((x) => `- ${singleLine(x)}`).join('\n')}`);
+  blocks.push(`## Details\n${trimmedBody}`);
+  const structured = blocks.join('\n\n');
+
+  const goalBody = trimmedTitle ? `Goal: ${trimmedTitle}\n\n${structured}` : structured;
   sections.push({ kind: 'goal', label: 'Goal', text: goalBody });
 
   for (const p of referencePaths) {
@@ -203,7 +255,7 @@ function composeFeedbackIntake({
     return out + sep + s.text;
   }, '');
 
-  const bodyText = trimmedTitle ? `${trimmedTitle}\n\n${trimmedBody}` : trimmedBody;
+  const bodyText = trimmedTitle ? `${trimmedTitle}\n\n${structured}` : structured;
   const refLines = referencePaths.map((p) => `Reference: ${singleLine(p)}`);
   const goalText = refLines.length ? `${bodyText}\n\n${refLines.join('\n')}` : bodyText;
 
@@ -237,6 +289,66 @@ function validateFeedbackInput(input = {}) {
     return bad(400, `tag must be one of ${FEEDBACK_TAGS.join(' | ')} (got ${JSON.stringify(tag)})`);
   }
 
+  const motivation = typeof input.motivation === 'string' ? input.motivation.trim() : '';
+  if (!motivation) {
+    return bad(400, 'motivation is required — WHY this is needed, in the sending human\'s terms, so the receiving human can judge it');
+  }
+  if (motivation.length > MAX_MOTIVATION_CHARS) {
+    return bad(400, `motivation is ${motivation.length} chars; cap is ${MAX_MOTIVATION_CHARS}`);
+  }
+
+  const listPurpose = {
+    plan: 'the ordered steps you propose the receiving project take',
+    acceptanceCriteria: 'the checkable conditions that mean this is done',
+    outOfScope: 'what this proposal deliberately does not cover',
+  };
+  const lists = {};
+  for (const field of ['plan', 'acceptanceCriteria', 'outOfScope']) {
+    const raw = input[field];
+    if (raw === undefined || raw === null) { lists[field] = []; continue; }
+    if (!Array.isArray(raw)) return bad(400, `${field} must be an array of strings (${listPurpose[field]})`);
+    if (raw.length > MAX_LIST_ITEMS) {
+      return bad(400, `${field} has ${raw.length} items; cap is ${MAX_LIST_ITEMS} (${listPurpose[field]})`);
+    }
+    const items = [];
+    for (const item of raw) {
+      const t = typeof item === 'string' ? item.trim() : '';
+      if (!t) return bad(400, `${field} items must be non-blank strings (${listPurpose[field]})`);
+      if (t.length > MAX_LIST_ITEM_CHARS) {
+        return bad(400, `a ${field} item is ${t.length} chars; cap is ${MAX_LIST_ITEM_CHARS}`);
+      }
+      items.push(t);
+    }
+    lists[field] = items;
+  }
+  if (lists.acceptanceCriteria.length === 0) {
+    return bad(400, `acceptanceCriteria is required with at least one item — ${listPurpose.acceptanceCriteria}`);
+  }
+  if (tag === 'feature' && lists.plan.length === 0) {
+    return bad(400, `plan is required with at least one item when tag is 'feature' — ${listPurpose.plan}`);
+  }
+
+  let series = null;
+  if (input.series !== undefined && input.series !== null) {
+    const sr = input.series;
+    const sbad = (why) => bad(400, `series ${why} (series groups one request split across several proposals: { key, title, index, total })`);
+    if (typeof sr !== 'object' || Array.isArray(sr)) return sbad('must be an object');
+    const key = typeof sr.key === 'string' ? sr.key : '';
+    if (!key || key.length > MAX_SERIES_KEY_CHARS || !KEBAB_RE.test(key)) {
+      return sbad(`key must be kebab-case, ≤ ${MAX_SERIES_KEY_CHARS} chars`);
+    }
+    const stitle = typeof sr.title === 'string' ? sr.title.trim() : '';
+    if (!stitle || stitle.length > MAX_SERIES_TITLE_CHARS) {
+      return sbad(`title must be non-blank, ≤ ${MAX_SERIES_TITLE_CHARS} chars`);
+    }
+    if (!Number.isInteger(sr.index) || sr.index < 1) return sbad('index must be an integer ≥ 1');
+    if (!Number.isInteger(sr.total) || sr.total < 2 || sr.total > MAX_SERIES_TOTAL) {
+      return sbad(`total must be an integer 2..${MAX_SERIES_TOTAL}`);
+    }
+    if (sr.index > sr.total) return sbad('index must be ≤ total');
+    series = { key, title: stitle, index: sr.index, total: sr.total };
+  }
+
   const referencePaths = Array.isArray(input.referencePaths) ? input.referencePaths : [];
   if (referencePaths.length > MAX_REFERENCES) {
     return bad(400, `too many referencePaths (${referencePaths.length}); cap is ${MAX_REFERENCES}`);
@@ -293,6 +405,11 @@ function validateFeedbackInput(input = {}) {
       title,
       body,
       tag,
+      motivation,
+      plan: lists.plan,
+      acceptanceCriteria: lists.acceptanceCriteria,
+      outOfScope: lists.outOfScope,
+      series,
       referencePaths: referencePaths.map((p) => String(p)),
       fromEpicId: input.fromEpicId ? String(input.fromEpicId) : null,
       agentType: input.agentType ? String(input.agentType) : DEFAULT_FEEDBACK_AGENT,
@@ -337,6 +454,8 @@ async function openFeedbackSession(input, deps = {}) {
     } catch { /* unresolvable — the proposal still delivers, just without a receipt */ }
   }
 
+  const originAsk = resolveOriginAsk(v.fromCwd, v.fromEpicId);
+
   const { goalText, openingPrompt, sections } = composeFeedbackIntake({
     fromCwd: v.fromCwd,
     fromEpicId: v.fromEpicId,
@@ -345,6 +464,12 @@ async function openFeedbackSession(input, deps = {}) {
     agentName: v.agentType,
     agentDescription: v.agentDescription,
     referencePaths: v.referencePaths,
+    originAsk,
+    motivation: v.motivation,
+    plan: v.plan,
+    acceptanceCriteria: v.acceptanceCriteria,
+    outOfScope: v.outOfScope,
+    series: v.series,
   });
 
   // The Epic's stored identity is the one-line title, not the whole report —
@@ -363,6 +488,14 @@ async function openFeedbackSession(input, deps = {}) {
         producer: 'cross-project-feedback',
         fromCwd: v.fromCwd,
         ...(v.fromEpicId ? { fromEpicId: v.fromEpicId } : {}),
+        proposal: {
+          motivation: v.motivation,
+          originAsk,
+          plan: v.plan,
+          acceptanceCriteria: v.acceptanceCriteria,
+          outOfScope: v.outOfScope,
+          series: v.series,
+        },
       },
       mintAuthority: MINT_AUTHORITY_CROSS_PROJECT_FEEDBACK,
     });
@@ -377,6 +510,7 @@ async function openFeedbackSession(input, deps = {}) {
     fromEpicId: v.fromEpicId,
     tag: v.tag,
     title: v.title,
+    series: v.series,
   });
 
   let receiptOnOriginEpic = false;
@@ -385,7 +519,9 @@ async function openFeedbackSession(input, deps = {}) {
       receiptOnOriginEpic = await appendReceipt(
         v.fromCwd,
         v.fromEpicId,
-        `Feedback delivered to ${v.toCwd} as a proposed session (${minted.epicId}): "${v.title}". `
+        `Feedback delivered to ${v.toCwd} as a proposed session (${minted.epicId}): "${v.title}"`
+        + (v.series ? ` [${seriesLine(v.series)}]` : '')
+        + '. '
         + 'It will not run until a human in that project approves it.',
       );
     } catch {
@@ -545,6 +681,7 @@ module.exports = {
   resolveProjectsDir,
   isSessionManagerProject,
   composeFeedbackIntake,
+  resolveOriginAsk,
   validateFeedbackInput,
   openFeedbackSession,
   listFeedbackTargets,

package/src/main/lib/mcpToolCatalog.cjs

@@ -238,15 +238,24 @@ const MCP_TOOL_CATALOG = [
       + 'opening prompt and stamped with where it came from. Session Manager performs the cross-folder '
       + 'write; you never write another project\'s files yourself.',
     whenToUse: 'Use when work in this project surfaces something that is genuinely another project\'s to fix. '
-      + 'Write the report for a reader who has never seen your project: state the symptom, where you '
-      + 'observed it, what you expected, and (if you know) the file in THEIR repo that looks responsible. '
-      + 'Never assume they can see your code.',
+      + 'Write for a human who must approve it and has never seen your project. Lead with WHY: `motivation` '
+      + 'in the originating human\'s terms. Then give the full `plan` (required for tag "feature") and '
+      + '`acceptanceCriteria`; put evidence, symptom and references in `body`. Name the file in THEIR repo '
+      + 'that looks responsible if you know it. When one request is split into several proposals, send '
+      + 'them ALL with one shared `series` {key, title, total} (plus each one\'s `index`) and summarise '
+      + 'the overall plan in each motivation.',
     whenNotToUse: 'WHEN NOT TO USE IT: for work in the project you are ALREADY in, run /develop inside the Epic you '
       + 'are already in — this tool refuses toCwd === fromCwd outright.',
     exampleArgs: {
       toCwd: '/home/bilko/Projects/other-project',
       fromCwd: '/home/bilko/Projects/session-manager',
       title: 'Cross-project contract mismatch in the shared admin API',
+      tag: 'feature',
+      motivation: 'The human wants X to work across both projects; today Y breaks because Z, so the shared admin API needs W.',
+      plan: ['Add field F to the admin API response', 'Update the validator to accept F', 'Cover F with a contract test'],
+      acceptanceCriteria: ['Admin API returns F', 'Contract test for F passes'],
+      outOfScope: ['Migrating existing records'],
+      series: { key: 'shared-admin-api-f', title: 'Shared admin API field F', index: 1, total: 2 },
       body: 'Symptom: X. Observed while doing Y in session-manager. Expected: Z. Suspected file: <path in their repo>.',
     },
     notes: 'WHAT THIS DOES NOT DO: it does not start anything, queue a PRD, or spend a token. The session '

package/src/main/lib/reaperHelpers.cjs

@@ -339,6 +339,14 @@ const ORPHAN_REQUEUE_CAP = 5;
  *    diverted into `recovered` exactly like a `findLiveProcess` hit.
  * Both default to a no-op when omitted, so existing callers/tests are
  * unaffected.
+ *
+ * `finalizeOwned` (optional, `(job) → boolean`) covers the dead-PID shape:
+ * a claude child exits BEFORE its spawnJob() has integrated the worktree
+ * branch and written the terminal row, so for that whole window the row is
+ * 'running' with a dead pid. Reaping it then races the fast-forward merge and
+ * parks landed work as reaped_without_integration (family-frame 137,
+ * 2026-10-10: park + merge in the same second). A true return skips the row
+ * with a warning; the caller bounds how long it may keep answering true.
  */
 /**
  * Pure, never-throws formatter for the dispatch-phase breadcrumb appended to
@@ -400,7 +408,7 @@ function resolvePidlessFailureOverride(job) {
 }
 
 function selectReapableJobs(jobs, now, {
-  pidAlive, grace, findLiveProcess, getLogMtimeMs, getLogPid, logFreshWindowMs,
+  pidAlive, grace, findLiveProcess, getLogMtimeMs, getLogPid, logFreshWindowMs, finalizeOwned,
 } = {}) {
   const reapable = [];
   const warnings = [];
@@ -410,6 +418,10 @@ function selectReapableJobs(jobs, now, {
     const pid = j.runtime?.pid;
     if (pid) {
       if (pidAlive(pid)) continue;
+      if (typeof finalizeOwned === 'function' && finalizeOwned(j)) {
+        warnings.push({ slug: j.slug, reason: `pid ${pid} exited but its spawnJob is still finalizing (integration in flight)` });
+        continue;
+      }
       reapable.push({ slug: j.slug, pid, pidless: false });
       continue;
     }

package/src/main/lib/relayClientAuth.cjs

@@ -0,0 +1,133 @@
+'use strict';
+
+// Desktop credential for acting as a 'browser'-role relay client against
+// bilko.run's sm-relay client endpoints. Pairs with a one-time client code,
+// stores the long-lived client token at 0600, and exchanges it for one-time WS
+// tickets and the owner's device list. No Electron imports.
+
+const fs = require('node:fs');
+const https = require('node:https');
+const path = require('node:path');
+const { claudeHome } = require('./schedulerPaths.cjs');
+const { writeJsonAtomicSync, readJsonOrSync } = require('./atomicFs.cjs');
+
+const RELAY_CLIENT_API_BASE = 'https://bilko.run/api/sm-relay';
+const REQUEST_TIMEOUT_MS = 15_000;
+const CLIENT_NAME_MAX = 64;
+
+/** Default transport: resolves { status, json }; never includes headers in errors. */
+function defaultRequest({ method, url, headers = {}, body }) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try { parsed = new URL(url); } catch { reject(new Error('invalid_url')); return; }
+    if (parsed.protocol !== 'https:') {
+      reject(new Error('Only https:// allowed for relay API calls'));
+      return;
+    }
+    const outHeaders = { ...headers };
+    if (body != null) outHeaders['Content-Length'] = Buffer.byteLength(body);
+    const req = https.request({
+      hostname: parsed.hostname,
+      port: parsed.port || 443,
+      path: parsed.pathname + (parsed.search || ''),
+      method,
+      headers: outHeaders,
+      rejectUnauthorized: true,
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => {
+        let json = null;
+        try { json = JSON.parse(data); } catch { /* non-JSON body */ }
+        resolve({ status: res.statusCode, json });
+      });
+    });
+    req.on('error', (err) => reject(new Error(err.message)));
+    req.setTimeout(REQUEST_TIMEOUT_MS, () => { req.destroy(new Error('timeout')); });
+    if (body != null) req.write(body);
+    req.end();
+  });
+}
+
+function defaultTokenPath() {
+  return path.join(claudeHome(), 'session-manager', 'relay-client.json');
+}
+
+function createRelayClientAuth({ tokenPath, request = defaultRequest } = {}) {
+  const file = tokenPath || defaultTokenPath();
+
+  function readStored() {
+    const data = readJsonOrSync(file, null);
+    return data && typeof data.clientToken === 'string' && data.clientToken ? data : null;
+  }
+  function clearToken() {
+    fs.rmSync(file, { force: true });
+  }
+  function isPaired() { return readStored() !== null; }
+  function getClientId() { return readStored()?.clientId ?? null; }
+
+  async function pair(code, clientName) {
+    const body = { code: String(code ?? '').trim().toUpperCase() };
+    const name = typeof clientName === 'string' ? clientName.slice(0, CLIENT_NAME_MAX) : '';
+    if (name) body.clientName = name;
+    const res = await request({
+      method: 'POST',
+      url: `${RELAY_CLIENT_API_BASE}/client-pair`,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    const json = res.json || {};
+    if (res.status === 404) return { ok: false, error: 'relay_client_auth_unavailable' };
+    if (res.status !== 200) return { ok: false, error: json.error || `HTTP ${res.status}` };
+    if (!json.clientToken) return { ok: false, error: 'relay_auth_failed' };
+    writeJsonAtomicSync(file, {
+      clientToken: json.clientToken,
+      clientId: json.clientId,
+      pairedAt: new Date().toISOString(),
+    }, { mode: 0o600 });
+    return { ok: true, clientId: json.clientId };
+  }
+
+  /** Authenticated call; maps status codes to the module's error vocabulary. */
+  async function authed(method, route, body) {
+    const stored = readStored();
+    if (!stored) throw new Error('relay_client_unpaired');
+    const headers = { Authorization: `Bearer ${stored.clientToken}` };
+    if (body != null) headers['Content-Type'] = 'application/json';
+    const res = await request({ method, url: `${RELAY_CLIENT_API_BASE}${route}`, headers, body });
+    if (res.status === 401) {
+      clearToken();
+      throw new Error('relay_client_unpaired');
+    }
+    if (res.status === 404) throw new Error('relay_client_auth_unavailable');
+    if (res.status < 200 || res.status >= 300) {
+      throw new Error((res.json && res.json.error) || `HTTP ${res.status}`);
+    }
+    return res.json || {};
+  }
+
+  // Optional peer argument is accepted and ignored (remoteClient passes it).
+  async function getBrowserTicket(_peer) {
+    const json = await authed('POST', '/client-ticket', '{}');
+    if (!json.ticket) throw new Error('relay_auth_failed');
+    return json.ticket;
+  }
+
+  async function listDevices() {
+    const json = await authed('GET', '/client/devices');
+    return Array.isArray(json.devices) ? json.devices : [];
+  }
+
+  async function getDevicePubKey(deviceId) {
+    const devices = await listDevices();
+    const hit = devices.find((d) => d && d.deviceId === deviceId);
+    if (!hit) throw new Error('device_not_found');
+    return hit.devicePubKey;
+  }
+
+  return { pair, getBrowserTicket, getDevicePubKey, listDevices, isPaired, getClientId, clearToken };
+}
+
+const relayClientAuth = createRelayClientAuth();
+
+module.exports = { createRelayClientAuth, relayClientAuth, RELAY_CLIENT_API_BASE };

package/src/main/lib/remoteClientSessions.cjs

@@ -0,0 +1,84 @@
+'use strict'
+
+/**
+ * Per-client E2E session registry for the web-remote agent.
+ * Pure — no Electron, no I/O — importable in unit tests.
+ *
+ * One record per connected client, keyed by the relay's `fromConn`. Envelopes
+ * without a usable `fromConn` (relay not yet stamping) key to LEGACY_CLIENT_KEY,
+ * which preserves single-client behaviour.
+ */
+
+const { makeState } = require('./e2eStateMachine.cjs')
+
+const LEGACY_CLIENT_KEY = 'legacy'
+const MAX_KEY_LEN = 64
+
+/**
+ * @param {{ fromConn?: unknown } | null | undefined} envelope
+ * @returns {string}
+ */
+function clientKeyOf(envelope) {
+  const k = envelope && envelope.fromConn
+  if (typeof k === 'string' && k.length > 0 && k.length <= MAX_KEY_LEN) return k
+  return LEGACY_CLIENT_KEY
+}
+
+function makeRecord(key, clientId) {
+  return {
+    key,
+    clientId: typeof clientId === 'string' ? clientId : null,
+    e2e: makeState(),
+    peerPubKey: null,
+    deviceId: null,
+    ptyStreams: new Map(),
+    subscriptions: new Set(),
+    lastSessionListJson: null,
+  }
+}
+
+function createClientSessions() {
+  const records = new Map()
+
+  function teardown(key) {
+    const rec = records.get(key)
+    if (!rec) return null
+    for (const unsub of rec.ptyStreams.values()) {
+      try { if (typeof unsub === 'function') unsub() } catch { /* swallow */ }
+    }
+    rec.ptyStreams.clear()
+    rec.subscriptions.clear()
+    records.delete(key)
+    return rec
+  }
+
+  return {
+    clientKeyOf,
+    get: (key) => records.get(key) || null,
+    getOrCreate(key, { clientId = null } = {}) {
+      let rec = records.get(key)
+      if (!rec) {
+        rec = makeRecord(key, clientId)
+        records.set(key, rec)
+      } else if (rec.clientId === null && typeof clientId === 'string') {
+        rec.clientId = clientId
+      }
+      return rec
+    },
+    delete: (key) => records.delete(key),
+    keys: () => [...records.keys()],
+    values: () => [...records.values()],
+    authenticated: () => [...records.values()].filter((r) => r.e2e.state === 'authenticated'),
+    teardown,
+    teardownAll() {
+      let n = 0
+      for (const key of [...records.keys()]) {
+        if (teardown(key)) n++
+      }
+      return n
+    },
+    size: () => records.size,
+  }
+}
+
+module.exports = { createClientSessions, clientKeyOf, LEGACY_CLIENT_KEY }

package/src/main/lib/remoteE2eCrypto.cjs

@@ -0,0 +1,109 @@
+'use strict';
+
+// E2E encryption helpers (P-256 ECDH + AES-256-GCM, ADR §5.2).
+// Shared by the agent side (webRemote.cjs) and the desktop client role.
+
+const crypto = require('node:crypto');
+
+/**
+ * Generate a P-256 ECDH keypair. Public key is SPKI DER base64url; private key
+ * is PKCS8 DER base64url. Both are stored in web-remote.json at 0600.
+ */
+function generateE2EKeyPair() {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', {
+    namedCurve: 'P-256',
+    publicKeyEncoding: { type: 'spki', format: 'der' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'der' },
+  });
+  return {
+    e2ePrivateKey: privateKey.toString('base64url'),
+    e2ePublicKey: publicKey.toString('base64url'),
+  };
+}
+
+/**
+ * Derive an AES-256-GCM session key from two P-256 public keys via ECDH + HKDF.
+ * @param myPrivateKeyB64  Agent's PKCS8 private key, base64url DER
+ * @param peerPublicKeyB64 Browser's SPKI public key, base64url DER
+ * @param deviceId         Used as HKDF salt for domain separation
+ * @returns 32-byte Buffer (AES-256-GCM key)
+ */
+function deriveSessionKey(myPrivateKeyB64, peerPublicKeyB64, deviceId) {
+  const myPrivKey = crypto.createPrivateKey({
+    key: Buffer.from(myPrivateKeyB64, 'base64url'),
+    format: 'der',
+    type: 'pkcs8',
+  });
+  const peerPubKey = crypto.createPublicKey({
+    key: Buffer.from(peerPublicKeyB64, 'base64url'),
+    format: 'der',
+    type: 'spki',
+  });
+  const sharedSecret = crypto.diffieHellman({ privateKey: myPrivKey, publicKey: peerPubKey });
+  // HKDF: salt = deviceId bytes for domain separation, info = fixed protocol label.
+  const salt = Buffer.from(deviceId, 'utf8');
+  const info = Buffer.from('sm-e2e-v1', 'utf8');
+  return Buffer.from(crypto.hkdfSync('sha256', sharedSecret, salt, info, 32));
+}
+
+/**
+ * Derive a 6-digit Short Authentication String from the ECDH shared secret.
+ * Uses a separate HKDF info label ('sm-sas-v1') so the SAS is independent of
+ * the session key. Both sides compute the same value; user confirms they match.
+ */
+function deriveSas(myPrivateKeyB64, peerPublicKeyB64, deviceId) {
+  const myPrivKey = crypto.createPrivateKey({
+    key: Buffer.from(myPrivateKeyB64, 'base64url'),
+    format: 'der',
+    type: 'pkcs8',
+  });
+  const peerPubKey = crypto.createPublicKey({
+    key: Buffer.from(peerPublicKeyB64, 'base64url'),
+    format: 'der',
+    type: 'spki',
+  });
+  const sharedSecret = crypto.diffieHellman({ privateKey: myPrivKey, publicKey: peerPubKey });
+  const salt = Buffer.from(deviceId, 'utf8');
+  const info = Buffer.from('sm-sas-v1', 'utf8');
+  const sasBytes = Buffer.from(crypto.hkdfSync('sha256', sharedSecret, salt, info, 3));
+  const sasNum = ((sasBytes[0] << 16) | (sasBytes[1] << 8) | sasBytes[2]) % 1_000_000;
+  return sasNum.toString().padStart(6, '0');
+}
+
+/**
+ * Encrypt a plaintext JSON string into an AES-256-GCM box.
+ * @returns { nonce: base64url, ciphertext: base64url } — the nonce is 12 random bytes
+ */
+function encryptBox(plaintext, sessionKey) {
+  const nonce = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', sessionKey, nonce);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag(); // 16-byte GCM authentication tag
+  return {
+    nonce: nonce.toString('base64url'),
+    // Append the GCM tag to the ciphertext so decryptBox can locate it.
+    ciphertext: Buffer.concat([encrypted, tag]).toString('base64url'),
+  };
+}
+
+/**
+ * Decrypt an AES-256-GCM box produced by encryptBox (or the browser's equivalent).
+ * @returns Decrypted UTF-8 string, or null if authentication fails.
+ */
+function decryptBox(nonceB64, ciphertextB64, sessionKey) {
+  try {
+    const nonce = Buffer.from(nonceB64, 'base64url');
+    const data = Buffer.from(ciphertextB64, 'base64url');
+    if (data.length < 16) return null; // too short to contain tag
+    const tag = data.subarray(data.length - 16);
+    const ciphertext = data.subarray(0, data.length - 16);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', sessionKey, nonce);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+    return plain;
+  } catch {
+    return null; // authentication failed — drop the message
+  }
+}
+
+module.exports = { generateE2EKeyPair, deriveSessionKey, deriveSas, encryptBox, decryptBox };