ai-or-die 0.1.79 → 0.1.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.79",
+  "version": "0.1.80",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {
@@ -17,7 +17,7 @@
     "test:browser": "npx playwright test --config e2e/playwright.config.js",
     "soak": "node test/longevity/harness/cli.js",
     "test:longevity-smoke": "mocha --exit --timeout 120000 test/longevity/smoke.test.js",
-    "test:longevity:server": "mocha --exit --timeout 120000 --recursive --extension .test.js test/longevity/event-loop test/longevity/disk test/longevity/process test/longevity/browser-sampler.test.js test/longevity/cli.test.js test/longevity/gate-evaluator-directional.test.js test/longevity/gate-evaluator-vacuous.test.js test/longevity/resume.test.js test/longevity/smoke.test.js",
+    "test:longevity:server": "mocha --exit --timeout 120000 --recursive --extension .test.js test/longevity/event-loop test/longevity/disk test/longevity/process test/longevity/browser-sampler.test.js test/longevity/cli.test.js test/longevity/gate-evaluator-directional.test.js test/longevity/gate-evaluator-vacuous.test.js test/longevity/event-loop-tolerance.test.js test/longevity/resume.test.js test/longevity/smoke.test.js",
     "test:longevity:browser": "playwright test --config test/longevity/playwright.config.js",
     "test:longevity": "npm run test:longevity:server && npm run test:longevity:browser",
     "build:bundle": "node scripts/build-sea.js bundle",

package/src/base-bridge.js

@@ -275,6 +275,8 @@ class BaseBridge {
     const {
       workingDir = process.cwd(),
       dangerouslySkipPermissions = false,
+      permissionMode = undefined,
+      agentArgs = undefined,
       onOutput = () => {},
       onExit = () => {},
       onError = () => {},
@@ -292,7 +294,10 @@ class BaseBridge {
         console.log(`WARNING: Using ${this.dangerousFlag} flag`);
       }
 
-      const args = this.buildArgs({ dangerouslySkipPermissions });
+      // F10: forward permissionMode/agentArgs so tool-specific buildArgs (claude)
+      // can emit --permission-mode + caller passthrough flags. Subclasses that
+      // don't override buildArgs (terminal/codex) ignore these.
+      const args = this.buildArgs({ dangerouslySkipPermissions, permissionMode, agentArgs });
 
       const env = {
         ...process.env,

package/src/claude-bridge.js

@@ -1,4 +1,16 @@
 const BaseBridge = require('./base-bridge');
+const { TRUST_PROMPT_REGEX } = require('./control/session-status');
+
+// claude's --permission-mode allowlist (F10). The fleet/control plane forwards one
+// of these; an unknown value is rejected up front rather than passed to claude (a
+// flag silently ignored by a skewed claude is a dishonest "mode set").
+const VALID_PERMISSION_MODES = ['plan', 'acceptEdits', 'default', 'bypassPermissions'];
+
+function invalidArgument(message) {
+  const err = new Error(message);
+  err.code = 'INVALID_ARGUMENT';
+  return err;
+}
 
 // Claude is ALWAYS launched through github-router (never the raw `claude`
 // binary): `npx -y github-router@latest claude --browse [claude flags]`. This
@@ -53,22 +65,79 @@ class ClaudeBridge extends BaseBridge {
     this._trustPromptHandled = new Map();
   }
 
+  /**
+   * F10 — the ONE canonical translation layer from a high-level launch intent
+   * (permissionMode + caller agentArgs) to claude's argv, appended AFTER the
+   * github-router launcher prefix (`npx -y github-router@latest claude --browse`).
+   *
+   * claude is launched through github-router, whose `claude` subcommand emits
+   * `--dangerously-skip-permissions` by default and DROPS it when a non-bypass
+   * `--permission-mode` is present. So here we only need to forward the mode flag;
+   * github-router reconciles the dangerous flag on its side.
+   *
+   * Conflict policy: `agentArgs` may NOT itself carry
+   * `--permission-mode` or `--dangerously-skip-permissions` — that would emit
+   * duplicate/conflicting flags. We throw INVALID_ARGUMENT so the create fails
+   * cleanly instead of launching an ambiguous claude. An unknown `permissionMode`
+   * is likewise rejected.
+   */
+  buildArgs(options = {}) {
+    const prefix = this._prefixArgs || [];
+    const out = [...prefix];
+    const { permissionMode, agentArgs, dangerouslySkipPermissions } = options;
+
+    if (agentArgs != null && !Array.isArray(agentArgs)) {
+      throw invalidArgument('agentArgs must be an array of strings');
+    }
+    const extra = Array.isArray(agentArgs) ? agentArgs.map((a) => String(a)) : [];
+    for (const a of extra) {
+      if (/^--permission-mode(=|$)/.test(a) || a === '--dangerously-skip-permissions') {
+        throw invalidArgument(
+          `agentArgs may not contain '${a}'; use permissionMode for permission control`
+        );
+      }
+    }
+
+    if (permissionMode != null && permissionMode !== '') {
+      const mode = String(permissionMode);
+      if (!VALID_PERMISSION_MODES.includes(mode)) {
+        throw invalidArgument(
+          `Unknown permissionMode '${mode}' (expected one of: ${VALID_PERMISSION_MODES.join(', ')})`
+        );
+      }
+      // permissionMode is the source of truth: emit the canonical flag and let
+      // github-router drop --dangerously-skip-permissions for non-bypass modes.
+      out.push('--permission-mode', mode);
+    } else if (dangerouslySkipPermissions && this.dangerousFlag) {
+      // Back-compat: no explicit mode → honor the legacy skip-permissions toggle.
+      out.push(this.dangerousFlag);
+    }
+
+    out.push(...extra);
+    return out;
+  }
+
   processOutput(sessionId, ptyProcess, dataBuffer) {
     if (this._trustPromptHandled.get(sessionId)) return;
     // Strip ANSI first: claude's Ink TUI interleaves escape codes between words,
-    // so a clean-string `includes` misses the folder-trust modal (and the exact
-    // wording shifts between claude versions). Match a stable substring of the
-    // "Do you trust the files in this folder?" / "1. Yes, I trust this folder"
-    // modal on the de-ANSI'd buffer, then accept the default (Enter = Yes). The
+    // so a clean-string match misses the folder-trust modal (and the exact wording
+    // shifts between claude versions). Match the shared TRUST_PROMPT_REGEX on the
+    // de-ANSI'd buffer — but ONLY act when the modal's numbered "1. / 2." choice
+    // list is ALSO present. That structural guard (mirroring awaitingFromScreen)
+    // prevents a false positive from claude merely PRINTING a trust phrase in prose
+    // / a file / a commit message, which would otherwise inject a spurious keystroke
+    // into the live PTY. Then send the EXPLICIT "1" choice + Enter (not a bare Enter,
+    // which could land on a wrong default) — matching _controlMapResponseKeys. The
     // per-session guard makes this a one-shot. This is what lets HEADLESS /
     // fleet-spawned claude sessions (no human to click) get past trust.
     const plain = String(dataBuffer || '').replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
-    if (/Do you trust the files in this folder|trust this folder/i.test(plain)) {
+    const numbered = /\b1\.\s/.test(plain) && /\b2\.\s/.test(plain);
+    if (numbered && TRUST_PROMPT_REGEX.test(plain)) {
       this._trustPromptHandled.set(sessionId, true);
       console.log(`Auto-accepting trust prompt for session ${sessionId}`);
       setTimeout(() => {
-        try { ptyProcess.write('\r'); } catch (_) { /* pty may have exited */ }
-        console.log(`Sent Enter to accept trust prompt for session ${sessionId}`);
+        try { ptyProcess.write('1\r'); } catch (_) { /* pty may have exited */ }
+        console.log(`Sent "1" + Enter to accept trust prompt for session ${sessionId}`);
       }, 500);
     }
   }
@@ -81,3 +150,4 @@ class ClaudeBridge extends BaseBridge {
 
 module.exports = ClaudeBridge;
 module.exports.resolveClaudeLauncher = resolveClaudeLauncher;
+module.exports.VALID_PERMISSION_MODES = VALID_PERMISSION_MODES;

package/src/control/event-bus.js

@@ -11,16 +11,39 @@
 //   - EPOCH: a per-process id. An instance restart mints a new epoch, so a
 //     client holding a pre-restart cursor is told `gap: restart` instead of
 //     silently resuming a reset sequence (the ABA problem).
-//   - GAP REPORTING: when the ring overflows past a client's cursor, `since()`
-//     returns `gap: overflow` so the client resyncs (via list_sessions) instead
-//     of believing nothing happened.
-//   - The cursor is `{ epoch, seq }`; the model never threads it — the fleet
-//     layer manages it per-client (contract v1).
+//   - GAP REPORTING: when retention rolls past a client's cursor, `since()`
+//     returns `gap: overflow` so the client resyncs (via snapshot) instead of
+//     believing nothing happened.
+//   - The cursor is `{ epoch, seq }`; the model never threads it - the fleet
+//     layer manages it per-client (contract v1). Cursors are PER-WATCHER:
+//     `since()` / `waitFor()` are pure reads parameterised by the caller's
+//     cursor, with NO shared global watcher position, so many concurrent
+//     watchers each resume from their own `{epoch,seq}` without interfering
+//     (F22).
+//
+// RETENTION IS PER SESSION (F15). The naive single global ring let one chatty
+// session roll the buffer and evict another session's last `turn_ended`, forcing
+// an avoidable resync. Instead each session keeps its OWN bounded ring, so a busy
+// session only evicts its own old events - never another session's turn boundary.
+// A global monotonic `seq` still orders events across sessions for the cursor,
+// and `_maxEvictedSeq` (the highest seq ever dropped from ANY ring) drives
+// overflow detection: a cursor older than it has provably missed an event. Whole
+// idle-session rings are evicted (LRU) only past a large session cap, also
+// bumping `_maxEvictedSeq` so the drop is never silent.
 
 const { EventEmitter } = require('events');
 const crypto = require('crypto');
 
-const DEFAULT_MAX_EVENTS = 1000;
+// Per-SESSION ring depth. ~85 turns of busy/idle/turn_ended history per session,
+// so a session's last turn_ended survives any realistic fan-out burst by OTHER
+// sessions. (Back-compat: the old `maxEvents` option maps to this.)
+const DEFAULT_MAX_EVENTS_PER_SESSION = 256;
+// Whole-session bucket cap. Past this many distinct sessions, the least-recently
+// active session's ring is evicted wholesale (its events are old/dead). Sized for
+// the scale bar (100+ live sessions) with generous headroom for exited ones.
+const DEFAULT_MAX_SESSIONS = 1024;
+// Bucket key for session-less events (defensive; current emitters always pass an id).
+const GLOBAL_KEY = '__global__';
 
 // Event kinds the control plane emits (mirrors the contract's await_turn `kind`).
 const EVENT_KINDS = Object.freeze([
@@ -38,18 +61,28 @@ class ControlEventBus extends EventEmitter {
   constructor(options = {}) {
     super();
     this.setMaxListeners(0); // many concurrent long-polls
-    this._maxEvents = options.maxEvents || DEFAULT_MAX_EVENTS;
+    // `maxEvents` is the legacy single-ring cap; it now sizes the PER-SESSION ring
+    // (a chatty session evicts only its own old events, never another's turn_ended).
+    this._maxPerSession = options.maxEventsPerSession || options.maxEvents || DEFAULT_MAX_EVENTS_PER_SESSION;
+    this._maxSessions = options.maxSessions || DEFAULT_MAX_SESSIONS;
     // A fresh, unguessable epoch per process. Math.random/Date are fine here
     // (normal server code), but a crypto id avoids cross-process collisions.
     this._epoch = options.epoch || crypto.randomBytes(8).toString('hex');
     this._seq = 0; // last assigned seq; first event is seq 1
-    this._ring = []; // [{ seq, sessionId, kind, at, detail? }], ascending seq
+    this._buckets = new Map(); // sessionKey -> [{ seq, sessionId, kind, at, detail? }] ascending; Map order = LRU
+    this._maxEvictedSeq = 0; // highest seq dropped from ANY ring (GLOBAL overflow floor, for unfiltered watchers)
+    this._evictedBySession = new Map(); // sessionKey -> highest seq evicted from THAT bucket (filter-aware overflow)
   }
 
   get epoch() {
     return this._epoch;
   }
 
+  /** Per-session ring depth (the retention contract surfaced via /capabilities). */
+  get maxEventsPerSession() {
+    return this._maxPerSession;
+  }
+
   /** Append an event, assign it the next seq, and notify long-poll waiters. */
   append(sessionId, kind, detail) {
     if (!EVENT_KINDS.includes(kind)) {
@@ -57,22 +90,79 @@ class ControlEventBus extends EventEmitter {
     }
     const event = { seq: ++this._seq, sessionId: sessionId || null, kind, at: Date.now() };
     if (detail !== undefined) event.detail = detail;
-    this._ring.push(event);
-    if (this._ring.length > this._maxEvents) {
-      this._ring.splice(0, this._ring.length - this._maxEvents);
+
+    const key = event.sessionId || GLOBAL_KEY;
+    let bucket = this._buckets.get(key);
+    if (bucket) {
+      this._buckets.delete(key); // re-insert to mark this session most-recently-active (LRU order)
+    } else {
+      bucket = [];
+    }
+    bucket.push(event);
+    if (bucket.length > this._maxPerSession) {
+      // Evict THIS session's oldest events only - never another session's.
+      const dropped = bucket.splice(0, bucket.length - this._maxPerSession);
+      this._bumpEvictedFor(key, dropped[dropped.length - 1].seq);
     }
+    this._buckets.set(key, bucket);
+
+    // Whole-session eviction: past the session cap, drop the least-recently-active
+    // session's ring entirely (its events are stale). Bump the floor so a watcher
+    // holding a cursor into that range gets an overflow gap, not a silent loss.
+    while (this._buckets.size > this._maxSessions) {
+      const oldestKey = this._buckets.keys().next().value;
+      const oldest = this._buckets.get(oldestKey);
+      this._buckets.delete(oldestKey);
+      if (oldest && oldest.length) this._bumpEvictedFor(oldestKey, oldest[oldest.length - 1].seq);
+    }
+
     this.emit('event', event);
     return event;
   }
 
+  _bumpEvicted(seq) {
+    if (seq > this._maxEvictedSeq) this._maxEvictedSeq = seq;
+  }
+
+  /** Bump BOTH the global overflow floor and the per-bucket evicted watermark. */
+  _bumpEvictedFor(key, seq) {
+    this._bumpEvicted(seq);
+    const cur = this._evictedBySession.get(key) || 0;
+    if (seq > cur) this._evictedBySession.set(key, seq);
+  }
+
   /** The cursor a fresh consumer should start from (i.e. "only new events"). */
   headCursor() {
     return { epoch: this._epoch, seq: this._seq };
   }
 
   /**
-   * Events strictly after `cursor`, plus any gap markers. Pure read.
-   * @param {?{epoch:string, seq:number}} cursor  omitted/null → start at head (no replay)
+   * Retained events with seq strictly greater than `minSeq`, merged across all
+   * session rings and returned ascending by seq. Each ring is already ascending,
+   * so we walk it from the tail and stop once we pass `minSeq` - only the new tail
+   * of each session is collected, not the whole fleet history.
+   */
+  _collectAfter(minSeq) {
+    const out = [];
+    for (const bucket of this._buckets.values()) {
+      for (let i = bucket.length - 1; i >= 0; i--) {
+        if (bucket[i].seq <= minSeq) break;
+        out.push(bucket[i]);
+      }
+    }
+    out.sort((a, b) => a.seq - b.seq);
+    return out;
+  }
+
+  /** All retained events, ascending by seq (diagnostics / restart resync). */
+  listEvents() {
+    return this._collectAfter(0);
+  }
+
+  /**
+   * Events strictly after `cursor`, plus any gap markers. Pure read - no shared
+   * cursor state, so concurrent watchers are independent (F22).
+   * @param {?{epoch:string, seq:number}} cursor  omitted/null -> start at head (no replay)
    * @param {?{sessionIds?:string[], kinds?:string[]}} [filter]
    */
   since(cursor, filter) {
@@ -86,18 +176,34 @@ class ControlEventBus extends EventEmitter {
       // The instance restarted under this consumer. Surface a gap and hand back
       // everything we currently retain so the consumer can resync.
       gaps.push({ reason: 'restart' });
-      events = this._ring.slice();
+      events = this._collectAfter(0);
     } else {
-      const oldestSeq = this._ring.length ? this._ring[0].seq : this._seq + 1;
-      if (cursor.seq < oldestSeq - 1) {
-        // The ring rolled past the cursor: events were dropped.
-        gaps.push({ reason: 'overflow', fromSeq: cursor.seq, toSeq: oldestSeq - 1 });
+      // Overflow is FILTER-AWARE: a session-filtered watcher must only see overflow
+      // caused by eviction in a session IT watches, not by another chatty session's
+      // eviction. Unfiltered watchers use the global floor.
+      const overflowFloor = (filter && Array.isArray(filter.sessionIds) && filter.sessionIds.length)
+        ? Math.max(0, ...filter.sessionIds.map((id) => this._evictedBySession.get(id || GLOBAL_KEY) || 0))
+        : this._maxEvictedSeq;
+      if (cursor.seq < overflowFloor) {
+        // At least one event the watcher cares about was evicted: it must resync
+        // via the snapshot endpoint.
+        gaps.push({ reason: 'overflow', fromSeq: cursor.seq, toSeq: overflowFloor });
       }
-      events = this._ring.filter((e) => e.seq > cursor.seq);
+      // Collect AFTER the gap boundary so returned events never contradict the gap
+      // (an event with seq inside [cursor.seq, overflowFloor] would overlap the
+      // claimed-lost range). With no overflow this is just cursor.seq - unchanged.
+      events = this._collectAfter(Math.max(cursor.seq, overflowFloor));
     }
 
     const filtered = applyFilter(events, filter);
-    const maxSeq = events.length ? events[events.length - 1].seq : this._seq;
+    // Advance the cursor to the global head (`_seq`) past EVERY event seen, so a
+    // filtered watcher never re-scans and a stale cursor can't re-trigger overflow.
+    // The newest event is always retained (a ring evicts only its own oldest, and
+    // the just-active bucket is never the LRU whole-session victim), so in every
+    // reachable state `events[last].seq === _seq` whenever anything is newer than
+    // the cursor; setting it unconditionally removes that fragile invariant-reasoning
+    // with zero behaviour change.
+    const maxSeq = this._seq;
     return { events: filtered, gaps, cursor: { epoch: this._epoch, seq: maxSeq }, more: false };
   }
 
@@ -108,8 +214,17 @@ class ControlEventBus extends EventEmitter {
    * @returns {Promise<{events:Array, gaps:Array, cursor:object, more:boolean}>}
    */
   waitFor(cursor, timeoutMs, filter) {
-    const immediate = this.since(cursor, filter);
-    if (immediate.events.length || immediate.gaps.length) return Promise.resolve(immediate);
+    // A fresh watcher (no cursor) must still RECEIVE the event that wakes the
+    // long-poll. since(undefined) returns []; without anchoring to the current
+    // head, the woken poll would resolve since(undefined) again and drop the very
+    // event it woke for. Anchor to head: only events AFTER wait-start are returned
+    // (no history replay), and the waking event is delivered.
+    const baseCursor = cursor || this.headCursor();
+    const immediate = this.since(baseCursor, filter);
+    // Return immediately when there's already something to deliver, OR when this is
+    // a non-blocking poll (timeoutMs <= 0): a 0-timeout caller wants "what's there
+    // now", and entering the wait with no armed timer (FIX D) would otherwise hang.
+    if (immediate.events.length || immediate.gaps.length || timeoutMs <= 0) return Promise.resolve(immediate);
 
     return new Promise((resolve) => {
       let done = false;
@@ -117,14 +232,16 @@ class ControlEventBus extends EventEmitter {
         if (done) return;
         done = true;
         this.removeListener('event', onEvent);
-        clearTimeout(timer);
-        resolve(this.since(cursor, filter));
+        if (timer) clearTimeout(timer);
+        resolve(this.since(baseCursor, filter));
       };
       const onEvent = (event) => {
         if (matches(event, filter)) finish();
       };
-      const timer = setTimeout(finish, Math.max(0, timeoutMs || 0));
-      if (timer.unref) timer.unref();
+      // FIX D: only arm the timer when a positive timeout is given; setTimeout(0)
+      // would resolve on the next macrotask and turn the long-poll into a hot loop.
+      const timer = timeoutMs > 0 ? setTimeout(finish, timeoutMs) : null;
+      if (timer && timer.unref) timer.unref();
       this.on('event', onEvent);
     });
   }
@@ -146,4 +263,4 @@ function applyFilter(events, filter) {
   return events.filter((e) => matches(e, filter));
 }
 
-module.exports = { ControlEventBus, EVENT_KINDS, DEFAULT_MAX_EVENTS };
+module.exports = { ControlEventBus, EVENT_KINDS, DEFAULT_MAX_EVENTS_PER_SESSION, DEFAULT_MAX_SESSIONS };

package/src/control/routes.js

@@ -67,16 +67,18 @@ function summaryFromStatus(id, session, status) {
 
 function parseCursor(raw) {
   if (!raw) return undefined;
-  // Accept either "epoch:seq" or a base64url JSON blob.
+  // Accept either "epoch:seq" or a base64url JSON blob. A valid seq is a
+  // non-negative safe integer (FIX C: reject -5, 1.5, NaN so a present-but-invalid
+  // cursor is a client bug surfaced as 400, not a silent fresh tail-follow).
   if (typeof raw === 'string' && raw.includes(':')) {
     const idx = raw.lastIndexOf(':');
     const epoch = raw.slice(0, idx);
     const seq = Number(raw.slice(idx + 1));
-    if (epoch && Number.isFinite(seq)) return { epoch, seq };
+    if (epoch && Number.isSafeInteger(seq) && seq >= 0) return { epoch, seq };
   }
   try {
     const obj = JSON.parse(Buffer.from(String(raw), 'base64').toString('utf8'));
-    if (obj && typeof obj.epoch === 'string' && Number.isFinite(obj.seq)) return obj;
+    if (obj && typeof obj.epoch === 'string' && Number.isSafeInteger(obj.seq) && obj.seq >= 0) return obj;
   } catch {
     /* fall through */
   }
@@ -157,17 +159,52 @@ function createControlRouter(deps) {
     if (isRateLimitExempt(req) || !rateLimit.max || !rateLimit.windowMs) return next();
     const limited = checkRateLimit(rateLimitBuckets, rateLimit, rateLimitIdentity(req));
     if (limited) {
+      // F21: a CLASSIFIABLE 429 so the fleet client can back off precisely rather
+      // than hammer. Stable error.code='RATE_LIMITED' + retryAfterMs in the body,
+      // and the standard Retry-After header (whole seconds, min 1).
+      const retryAfterSec = Math.max(1, Math.ceil(limited.retryAfterMs / 1000));
+      res.set('Retry-After', String(retryAfterSec));
       return res.status(429).json({
         error: {
           code: 'RATE_LIMITED',
           message: 'Too many control requests; retry after the current rate-limit window',
           retryAfterMs: limited.retryAfterMs,
+          retryAfterSec,
         },
       });
     }
     next();
   });
 
+  // GET /capabilities — F19 cross-repo capability negotiation. The fleet client
+  // reads this ONCE per instance and fails closed on a missing capability, so a
+  // newer client never silently assumes an older instance supports a field/event.
+  router.get('/capabilities', (req, res, next) => {
+    try {
+      res.json(deps.capabilities ? deps.capabilities() : { capabilities: [], controlVersion: '0' });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  // GET /snapshot — F15 atomic batch resync. Returns every session's derived
+  // status PLUS the event cursor, captured atomically (cursor first, then
+  // statuses), so after a gap/overflow the controller resyncs in ONE call and
+  // resumes the long-poll from `cursor` with zero lost events (a boundary event
+  // may be redelivered — safe/idempotent — but never dropped).
+  router.get('/snapshot', async (req, res, next) => {
+    try {
+      const snap = deps.snapshot ? await deps.snapshot() : { sessions: [], cursor: null, capturedAt: Date.now() };
+      res.json({
+        sessions: snap.sessions || [],
+        cursor: snap.cursor ? encodeCursor(snap.cursor) : null,
+        capturedAt: snap.capturedAt,
+      });
+    } catch (err) {
+      next(err);
+    }
+  });
+
   // GET /sessions — list with derived status (light).
   router.get('/sessions', async (req, res, next) => {
     try {
@@ -215,6 +252,11 @@ function createControlRouter(deps) {
       if (err && err.code === 'INVALID_WORKDIR') {
         return res.status(403).json({ error: { code: 'CAPABILITY_DENIED', message: err.message } });
       }
+      if (err && err.code) {
+        return res.status(err.statusCode || statusForErrorCode(err.code)).json({
+          error: { code: err.code, message: err.message },
+        });
+      }
       next(err);
     }
   });
@@ -305,6 +347,10 @@ function createControlRouter(deps) {
   router.get('/events', async (req, res, next) => {
     try {
       const cursor = parseCursor(req.query.cursor);
+      // FIX C: ABSENT cursor → fresh watcher (ok); PRESENT-but-INVALID → client bug.
+      if (req.query.cursor && cursor === undefined) {
+        return res.status(400).json({ error: { code: 'INVALID_ARGUMENT', message: 'invalid cursor' } });
+      }
       const timeoutMs = clampInt(req.query.timeoutMs, DEFAULT_EVENTS_TIMEOUT_MS, 0, MAX_EVENTS_TIMEOUT_MS);
       const filter = {};
       if (req.query.sessionIds) filter.sessionIds = String(req.query.sessionIds).split(',').filter(Boolean);