claude-code-session-manager 0.106.0 → 0.108.0

package/src/main/ipcSchemas.cjs

@@ -30,6 +30,17 @@ const ptyTabId = z.object({ tabId: z.string().min(1).max(128) });
 // have a live PTY? Bounded so the renderer can't ask about unbounded lists.
 const ptyAlive = z.object({ tabIds: z.array(z.string().min(1).max(128)).max(500) });
 
+// v2 mobile: subscribe to a session's live state + summary. cwd is needed to
+// locate the transcript JSONL (transcriptPath); validated against home-dir boundary
+// in webRemote before any fs access.
+const sessionSubscribe = z.object({
+  // tabId becomes a transcript FILENAME (`<tabId>.jsonl`) — restrict to a
+  // session-id charset (no '/', no '.', so it can't traverse out of the project
+  // transcript dir). sessionId is a UUID, which satisfies this.
+  tabId: z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/),
+  cwd: z.string().min(1).max(4096),
+});
+
 // 64 KiB cap per pty:write — typewriter input is bounded; a renderer firing
 // megabytes per call is either a bug or an attack. Block it at the boundary.
 const PTY_WRITE_MAX_BYTES = 64 * 1024;
@@ -932,6 +943,23 @@ const chatExternalSend = z.object({
   ),
 });
 
+// ──────────────────────────────────────────── Web Remote
+// OTP is 8 uppercase alphanumeric chars (case-insensitive entry, normalised to upper in handler).
+const WEB_REMOTE_OTP_RE = /^[A-Z0-9]{8}$/i;
+const DEVICE_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const webRemotePair = z.object({
+  otp: z.string().regex(WEB_REMOTE_OTP_RE),
+}).strict();
+
+const webRemoteRevokeDevice = z.object({
+  deviceId: z.string().regex(DEVICE_ID_RE),
+}).strict();
+
+const webRemoteAuditTail = z.object({
+  lines: z.number().int().min(1).max(500).optional(),
+}).strict();
+
 // ──────────────────────────────────────────── History
 const DATE_YYYY_MM_DD = /^\d{4}-\d{2}-\d{2}$/;
 
@@ -1093,13 +1121,78 @@ function validated(schema, handler) {
   };
 }
 
+// ──────────────────────────────────────────── Web Remote command allowlist
+// Commands are split into three tiers:
+//   READ_COMMANDS      — return data; allowed when remoteEnabled=true.
+//   SAS_GATED_READS    — return sensitive user data (sessions, PRDs, logs,
+//                        transcript summaries); additionally require
+//                        _e2eAuthenticated=true (SAS confirmed by user).
+//                        A compromised relay cannot exfiltrate this data from
+//                        a session that has not been SAS-confirmed.
+//   MUTATE_COMMANDS    — write files, spawn processes, or mutate persisted
+//                        state; gated behind remoteControlEnabled=true AND
+//                        _e2eAuthenticated=true.
+// ALLOWED_COMMANDS is the union, kept for existing import compatibility.
+//
+// Ungated READ_COMMANDS (justify each):
+//   cmd:app:version      — exposes only the app semver string; no user data.
+//   cmd:session:unsubscribe — teardown lifecycle; returns nothing sensitive.
+const READ_COMMANDS = new Set([
+  'cmd:app:version',
+  // v2 mobile: unsubscribe is a teardown lifecycle call with no data payload.
+  'cmd:session:unsubscribe',
+]);
+
+// Sensitive reads — return user data; require SAS confirmation same as MUTATE.
+const SAS_GATED_READS = new Set([
+  'cmd:sessions:load',
+  'cmd:history:aggregate',
+  // subscribe initiates a live stream of session state/summary — sensitive.
+  'cmd:session:subscribe',
+  // NOTE: cmd:exchanges:list is intentionally NOT allowlisted — webRemote.cjs has
+  // no dispatch handler for it, so an allowlist entry would only fail closed with
+  // an opaque reject. Re-add here together with the handler when remote exchanges
+  // are wired, so the allowlist always mirrors an actual capability.
+  //
+  // Scheduler/Epics commands (cmd:schedule:*) were removed here deliberately
+  // (core scheduler/Epics redesign) — Remote no longer reaches into scheduler
+  // internals at all; a future Remote rebuild will talk to Scheduler/Epics
+  // through whatever higher-level surface that redesign lands on, not this
+  // per-command allowlist.
+]);
+
+const MUTATE_COMMANDS = new Set([
+  'cmd:sessions:save',
+  'cmd:pty:spawn',
+  'cmd:pty:write',
+  // pty:kill terminates a live session; pty:resize drives the geometry of the
+  // user's interactive PTY — both write live process state, so they are gated
+  // behind remoteControlEnabled + SAS like every other mutation. A read-only
+  // mobile mirror has no business killing or resizing the desktop's session.
+  'cmd:pty:kill',
+  'cmd:pty:resize',
+  // Pushes a prompt into an open tab's chat queue — a real mutation of that
+  // tab's session, same tier as pty:write.
+  'cmd:chat:send',
+]);
+
+const ALLOWED_COMMANDS = new Set([...READ_COMMANDS, ...SAS_GATED_READS, ...MUTATE_COMMANDS]);
+
 module.exports = {
   // Centralized slug regex — used by scheduler.cjs and queueOps.cjs for
   // direct test()/match() containment checks alongside the zod parses.
   SCHEDULE_SLUG_RE,
   SCHEDULE_RUN_ID_RE,
   PRD_CREATE_SLUG_RE,
+  READ_COMMANDS,
+  SAS_GATED_READS,
+  MUTATE_COMMANDS,
+  ALLOWED_COMMANDS,
   schemas: {
+    webRemotePair,
+    webRemoteRevokeDevice,
+    webRemoteAuditTail,
+    sessionSubscribe,
     ptySpawn,
     ptyTabId,
     ptyAlive,

package/src/main/lib/builtinMacros.cjs

@@ -30,9 +30,9 @@ const BUILTIN_MACROS = Object.freeze([
     tag: 'project-home-builder',
     surface: 'project-home',
     projects: ['*'],
-    builtinVersion: 2,
+    builtinVersion: 3,
     prompt:
-      'Generate a 30-second demo video for this project as one self-contained HTML/JavaScript animation that presents its main goals and key features, grounded only in what you read in the repository, with a matching on-device narration track per the audio policy in the persona. Save it with a single project_demo_video_write call.',
+      'Generate a 30-second demo video for this project as one self-contained HTML/JavaScript animation that presents its main goals and key features, grounded only in what you read in the repository, with a matching on-device narration track: narrate with Kokoro (kokoro-onnx) using a natural female (af_heart) or male (am_michael) voice per the audio policy in the persona. Save it with a single project_demo_video_write call passing htmlPath.',
   }),
 ]);
 

package/src/main/lib/e2eStateMachine.cjs

@@ -0,0 +1,39 @@
+/**
+ * Pure E2E session state machine for the web-remote relay.
+ * No Electron, no I/O — importable in unit tests.
+ *
+ * State transitions:
+ *   idle        → pending_sas   : successful deriveSessionKey + deriveSas
+ *   idle        → failed        : crypto derivation error
+ *   pending_sas → authenticated : user confirms SAS
+ *   pending_sas → failed        : deriveSas threw after sessionKey succeeded
+ *   any         → idle          : disconnect / reset
+ */
+
+/** @returns {{ state: string, sessionKey: Buffer|null, pendingSas: string|null }} */
+function makeState(state = 'idle', sessionKey = null, pendingSas = null) {
+  return { state, sessionKey, pendingSas };
+}
+
+/**
+ * Attempt to confirm the SAS.  Pure — does not mutate; returns the next state.
+ * @param {{ state: string, sessionKey: Buffer|null, pendingSas: string|null }} e2eState
+ * @returns {{ ok: boolean, error?: string, next: { state: string, sessionKey: Buffer|null, pendingSas: string|null } }}
+ */
+function confirmSas(e2eState) {
+  if (e2eState.state !== 'pending_sas') {
+    const errorMap = {
+      idle: 'no_e2e_session',
+      failed: 'e2e_failed',
+      authenticated: 'already_authenticated',
+    };
+    const error = errorMap[e2eState.state] ?? 'unexpected_state';
+    return { ok: false, error, next: e2eState };
+  }
+  return {
+    ok: true,
+    next: makeState('authenticated', e2eState.sessionKey, null),
+  };
+}
+
+module.exports = { makeState, confirmSas };

package/src/main/lib/mcpToolCatalog.cjs

@@ -50,11 +50,11 @@ const MCP_TOOL_CATALOG = [
   {
     name: 'scheduler_pause',
     group: 'scheduler',
-    purpose: "Pause the scheduler (user-initiated) via the session-manager app's admin API.",
-    whenToUse: 'Use to stop NEW job dispatch on request (e.g. before a risky change). Running jobs are never killed.',
-    whenNotToUse: 'Do not use to cancel a running job (use scheduler_cancel_job) or as a workaround for a stuck queue.',
-    exampleArgs: {},
-    notes: 'A manual pause survives app restart and is never auto-cleared by the rate-limit timer or network recovery — only scheduler_resume clears it.',
+    purpose: "Pause NEW job dispatch for every project on this machine (machine-wide, not per-repo) via the session-manager app's admin API.",
+    whenToUse: 'Use only when the human asks you to stop dispatch everywhere, or for a machine-wide emergency. Pass a `reason`. Running jobs are never killed.',
+    whenNotToUse: "NEVER use it to protect one repo's git/branch state or a single Epic's work — it freezes every project's scheduler. Do not use it to cancel a running job (use scheduler_cancel_job) or as a workaround for a stuck queue.",
+    exampleArgs: { reason: 'machine-wide emergency: disk full' },
+    notes: 'An agent pause auto-expires after 30 minutes, is cleared on app restart, and is audited with the caller (session id + cwd). A human pause outranks it and is only cleared by scheduler_resume.',
   },
   {
     name: 'scheduler_resume',
@@ -279,7 +279,8 @@ const MCP_TOOL_CATALOG = [
     whenToUse: 'Use when asked to generate or refresh the demo video. Compose the whole document yourself '
       + '(inline <style>/<script>, data: URIs for assets, CSS/JS-driven animation) from what is really true about '
       + 'the project, declare its length with <meta name="sm-demo-duration" content="N"> (5-30 seconds), then '
-      + 'pass the full document as `html`.',
+      + 'pass the document as `html` or — preferred when it embeds a base64 audio/image data URI — write it to a '
+      + 'local .html file and pass its absolute path as `htmlPath`.',
     whenNotToUse: 'Never fabricate content — every claim must trace to something concrete in the project. The '
       + 'document must be self-contained and non-network-capable: the call is rejected for empty input, more than '
       + '2MB, any <script src>, <link href="http…">, @import, or url(http…) (no remote references); any '
@@ -291,6 +292,7 @@ const MCP_TOOL_CATALOG = [
       html: '<!DOCTYPE html><html><head><meta name="sm-demo-duration" content="30"></head><body><h1>Example</h1></body></html>',
     },
     notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted. "
+      + 'Give exactly one of `html` / `htmlPath` (absolute .html/.htm file, <= 2MB); prefer `htmlPath` for base64 data URIs. '
       + 'The document is CSP-stamped after it is written, so the viewer sandbox is the real network fence — these checks are defence in depth.',
   },
   {

package/src/main/lib/shippedPersonaSeeds.cjs

@@ -274,6 +274,17 @@ const SHIPPED_PERSONA_SEEDS = deepFreeze({
         effort: "medium",
       },
     },
+    {
+      commit: "e477754c",
+      bodySha256: "cfb0c7fa8c74dbc731ad352a06cd94717446fe0151bb86e93acc56df45f2c3b1",
+      fm: {
+        description: "30-second self-contained HTML/JS demo video for Project Home, saved via project_demo_video_write.",
+        tools: "Read, Grep, Glob, Bash, Write, Edit",
+        title: "Project Home — Demo Video",
+        model: "sonnet",
+        effort: "medium",
+      },
+    },
   ],
 });
 

package/src/main/lib/usageCircuit.cjs

@@ -137,6 +137,20 @@ function degradedBudget(lastGoodPayload, executorEvidence = {}) {
   return { utilization, concurrencyCap };
 }
 
+/**
+ * Budget while the METER (not the account) is rate-limited: a 429 from the
+ * usage endpoint says nothing about account usage, so a recent-enough cached
+ * payload is trusted as-is. Returns `{ utilization, degraded: false }` from
+ * the cache, or null (no/old cache) so the caller falls back to degradedBudget().
+ */
+function meterFailureBudget({ cachedPayload, staleSinceMs, now = Date.now(), maxStaleMs = 30 * 60 * 1000 } = {}) {
+  if (!cachedPayload || !Number.isFinite(staleSinceMs)) return null;
+  if (now - staleSinceMs > maxStaleMs) return null;
+  const window = bindingWindow(cachedPayload);
+  if (!Number.isFinite(window.utilization)) return null;
+  return { utilization: window.utilization, degraded: false, name: window.name };
+}
+
 /** Wraps `fn` so concurrent callers awaiting an in-flight call share one promise. */
 function singleFlight(fn) {
   let inFlight = null;
@@ -229,6 +243,7 @@ module.exports = {
   isResetFresh,
   bindingWindow,
   degradedBudget,
+  meterFailureBudget,
   degradedConcurrencyCap,
   singleFlight,
 };

package/src/main/scheduler.cjs

@@ -78,7 +78,7 @@ const { detectRateLimitInLog } = require('./lib/rateLimitDetect.cjs');
 const { stripAppOwnedChurn } = require('./lib/jobDirtFilter.cjs');
 const { GATE_AUTHORITY_VERDICTS, decideGateAuthority } = require('./lib/gateAuthority.cjs');
 const { resolveBindingRateLimitReset } = require('./lib/rateLimitWindow.cjs');
-const { isResetFresh, bindingWindow, degradedBudget } = require('./lib/usageCircuit.cjs');
+const { isResetFresh, bindingWindow, degradedBudget, meterFailureBudget } = require('./lib/usageCircuit.cjs');
 const { computeQueueHealth } = require('./lib/queueHealth.cjs');
 const { createLoadGate, topCpuConsumers } = require('./lib/loadGate.cjs');
 const { openLog, withChildAndLog } = require('./lib/childWithLog.cjs');
@@ -3499,8 +3499,11 @@ function recordObservedReset(resetIso) {
 /** Pure: this poll/executor cycle's conservative budget while the meter is degraded. */
 function computeDegradedBudget() {
   return degradedBudget(lastGoodUsagePayload, {
-    observed429: lastFailureKind === 'meter_rate_limited',
-    resetsAt: cachedNextReset,
+    // Only an executor-observed rate limit (the paused.reason === 'rate_limit'
+    // path) may pin utilization; a 429 from the METER says nothing about the
+    // account. That pause already holds dispatch itself, so no evidence here.
+    observed429: false,
+    resetsAt: null,
     now: Date.now(),
     configuredCap: sessionSlots.snapshot().total,
   });
@@ -4047,8 +4050,11 @@ function nextRapidRateLimitCount(prevCount, { rateLimited, durationMs }) {
  * either, which used to leave an indefinite pause with no resume timer at
  * all (a queue that never comes back on its own) — this covers both.
  */
+const AGENT_PAUSE_TTL_MS = 30 * 60_000;
+
 function computeEffectiveResumeAt(reason, resumeAtIso, nowMs = Date.now()) {
   if (resumeAtIso && isResetFresh(resumeAtIso, nowMs)) return resumeAtIso;
+  if (reason === 'agent') return new Date(nowMs + AGENT_PAUSE_TTL_MS).toISOString();
   if (reason === 'network' || reason === 'rate_limit') {
     return new Date(nowMs + 30 * 60_000).toISOString();
   }
@@ -4067,15 +4073,16 @@ function computeResumeDelay(effectiveResumeAtIso, nowMs = Date.now()) {
 }
 
 async function setPaused(reason, resumeAtIso, opts = {}) {
-  const { observedAt = null, force = false } = opts;
+  const { observedAt = null, force = false, by = null } = opts;
   const isManual = reason === 'manual';
+  const isAgent = reason === 'agent';
   // Honor manual-override cooldown: if the user cleared a pause within the
   // last 5 minutes, suppress auto-pause re-engagement UNLESS this pause is
   // backed by a fresh observation (a run that started after the clear) or is
   // forced (the rapid-repeat hard pause, which the cooldown cannot suppress).
   // A user-initiated 'manual' pause is never an auto-detection, so the cooldown
   // (which exists to ignore STALE auto-detections) does not apply to it.
-  if (!isManual && isCooldownSuppressed({ pauseClearedManuallyAt, now: Date.now(), observedAt, force })) {
+  if (!isManual && !isAgent && isCooldownSuppressed({ pauseClearedManuallyAt, now: Date.now(), observedAt, force })) {
     console.log(`[scheduler] setPaused(${reason}) suppressed by manual override cooldown`);
     return;
   }
@@ -4088,6 +4095,7 @@ async function setPaused(reason, resumeAtIso, opts = {}) {
   // 'manual' never arms a resume timer: only schedule:resume / run-now clears it.
   const effectiveResumeAt = isManual ? null : computeEffectiveResumeAt(reason, resumeAtIso);
 
+  let committed = null;
   const kept = await mutate((s) => {
     // A user pause outranks every auto-pause (rate_limit/auth/network): the
     // auto path must not overwrite it, or its resume timer would auto-clear it.
@@ -4097,12 +4105,15 @@ async function setPaused(reason, resumeAtIso, opts = {}) {
     } else {
       s.paused = { reason, since: new Date().toISOString(), resumeAt: effectiveResumeAt || null };
     }
+    if (by && isAgent) s.paused.by = by;
+    committed = { reason: s.paused.reason, resumeAt: s.paused.resumeAt ?? null, by: s.paused.by ?? null };
     return false;
   });
   if (kept) {
     console.log(`[scheduler] setPaused(${reason}) ignored: a manual pause is in force`);
     return;
   }
+  if (committed) appendAuditEvent('scheduler_pause', committed);
   await broadcast({ flush: true });
   cancelToken.cancelled = true;
   if (resumeTimer) { clearTimeout(resumeTimer); resumeTimer = null; }
@@ -4123,6 +4134,7 @@ async function setPaused(reason, resumeAtIso, opts = {}) {
 async function clearPause(source) {
   if (resumeTimer) { clearTimeout(resumeTimer); resumeTimer = null; }
   const humanOverride = source === 'manual' || source === 'run-now';
+  let clearedReason = null;
   const wasPaused = await mutate((s) => {
     // A human Resume / Run now also re-closes every launch circuit breaker:
     // the operator is asserting the environment is fixed (CLI updated,
@@ -4135,9 +4147,11 @@ async function clearPause(source) {
     }
     if (!s.paused) return false;
     console.log(`[scheduler] clearPause (${source || 'manual'})`);
+    clearedReason = s.paused.reason ?? null;
     s.paused = null;
     return true;
   });
+  if (wasPaused) appendAuditEvent('scheduler_resume', { source: source || 'manual', clearedReason });
   // Un-cancel the tick guard on every recovery path, not just runDueJobs().
   applyPauseCleared(wasPaused, cancelToken);
   if (wasPaused) lastPauseClearedAt = Date.now();
@@ -10377,8 +10391,17 @@ async function pollLoop() {
       // Don't update firstNon429FailureAt — 429s don't count toward the 30-min network-pause threshold.
       backoffMs = nextBackoffMs(backoffMs);
       backoffNextAt = Date.now() + backoffMs;
-      applyDegradedBudget();
-      console.log(`[scheduler] billing meter rate-limited (HTTP 429) — firing on degraded budget (util=${cachedUtilization}%, cap=${degradedConcurrencyCapValue}) (failure #${consecutiveFailures}); retry in ${backoffMs / 1000}s`);
+      const cachedBudget = meterFailureBudget({ cachedPayload: r.cached, staleSinceMs: r.staleSince, now: Date.now() });
+      if (cachedBudget) {
+        // Meter 429 ≠ account limit: trust the recent cached reading, full slot pool.
+        lastGoodUsagePayload = r.cached;
+        cachedUtilization = cachedBudget.utilization;
+        cachedBindingWindowName = cachedBudget.name;
+        degradedConcurrencyCapValue = null;
+      } else {
+        applyDegradedBudget();
+      }
+      console.log(`[scheduler] billing meter rate-limited (HTTP 429) — firing on ${cachedBudget ? 'cached' : 'degraded'} budget (util=${cachedUtilization}%, cap=${degradedConcurrencyCapValue}) (failure #${consecutiveFailures}); retry in ${backoffMs / 1000}s`);
       warnFailureStreakIfNeeded();
       persistSchedulerState();
       const cur = await readQueue();
@@ -12948,7 +12971,10 @@ async function init() {
     // happens when the app was closed across the reset window.
     const boot = await readQueue();
     await clearStaleDrainAtBoot(boot);
-    if (boot.paused && boot.paused.resumeAt && new Date(boot.paused.resumeAt).getTime() <= Date.now()) {
+    if (boot.paused && (boot.paused.reason === 'manual' || boot.paused.reason === 'agent')) {
+      console.log(`[scheduler] boot: clearing persisted '${boot.paused.reason}' pause so dispatch runs`);
+      await clearPause('boot');
+    } else if (boot.paused && boot.paused.resumeAt && new Date(boot.paused.resumeAt).getTime() <= Date.now()) {
       await clearPause('boot-elapsed');
     } else if (boot.paused && boot.paused.resumeAt) {
       // Re-arm the resume timer (lost across restart).
@@ -13293,8 +13319,15 @@ const remote = {
   // User-initiated pause/resume — the admin-route/MCP twins of the
   // schedule:pause / schedule:resume IPC handlers, through the same setPaused /
   // clearPause. Pause stops NEW dispatch only; running jobs are never touched.
-  async pause() {
-    await setPaused('manual', null);
+  async pause(opts = {}) {
+    const str = (v, max = 300) => (typeof v === 'string' && v ? v.slice(0, max) : null);
+    await setPaused('agent', null, {
+      by: {
+        originClaudeSessionId: str(opts.originClaudeSessionId),
+        cwd: str(opts.cwd, 1000),
+        reason: str(opts.reason),
+      },
+    });
     return { ok: true };
   },
 
@@ -13650,7 +13683,20 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 
   adminHttp.registerRoute('POST', '/admin/scheduler/pause', async (req, res) => {
-    sendJson(res, 200, await remoteObj.pause());
+    const raw = await readBody(req);
+    let parsed;
+    try {
+      parsed = raw ? JSON.parse(raw) : {};
+    } catch {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    if (!parsed || typeof parsed !== 'object') parsed = {};
+    sendJson(res, 200, await remoteObj.pause({
+      originClaudeSessionId: parsed.originClaudeSessionId,
+      cwd: parsed.cwd,
+      reason: parsed.reason,
+    }));
   });
 
   adminHttp.registerRoute('POST', '/admin/scheduler/resume', async (req, res) => {

package/src/main/usage.cjs

@@ -302,10 +302,18 @@ async function fetchUsage() {
   }
 
   if (lastRateLimitedResult && retryNotBeforeMs && Date.now() < retryNotBeforeMs) {
-    return { ...lastRateLimitedResult, suppressed: true };
+    return withCachedPayload({ ...lastRateLimitedResult, suppressed: true });
   }
 
-  return singleFlightNetworkFetch();
+  return withCachedPayload(await singleFlightNetworkFetch());
+}
+
+/** Attaches the last good payload (+ its age anchor) to a 429 so callers can keep using it. */
+function withCachedPayload(r) {
+  if (r && r.kind === 'meter_rate_limited' && cache && cache.data) {
+    return { ...r, cached: cache.data, staleSince: cache.fetchedAt };
+  }
+  return r;
 }
 
 function registerBillingHandlers() {