claude-code-session-manager 0.105.0 → 0.107.0

package/src/main/lib/customerFeedbackInbox.cjs

@@ -0,0 +1,286 @@
+// @ts-check
+/**
+ * customerFeedbackInbox — OWNER side of customer feedback.
+ *
+ * With an owner token configured (env SM_FEEDBACK_OWNER_TOKEN or
+ * ~/.claude/session-manager/customer-feedback-owner.json) this machine incrementally pulls every
+ * submission for the session-manager slug from bilko.run into a local mirror, sets item status on
+ * the host, and records which local Epic an item became. No token = customer machine (ownerMode
+ * false). The token is only ever sent as a bearer header and never appears in errors or the mirror.
+ */
+'use strict';
+
+const path = require('node:path');
+const fsp = require('node:fs/promises');
+const atomicFs = require('./atomicFs.cjs');
+const schedulerPaths = require('./schedulerPaths.cjs');
+const { resolveFeedbackBase, fromWireType, FEEDBACK_SLUG } = require('./customerFeedbackClient.cjs');
+
+const STATUSES = /** @type {const} */ (['open', 'in_progress', 'resolved', 'wontfix']);
+const MAX_NOTE = 500;
+const MAX_ITEMS = 2000;
+const PAGE_LIMIT = 500;
+const MAX_PAGES = 10;
+const TIMEOUT_MS = 15000;
+const SCHEMA_VERSION = 1;
+const NO_TOKEN = 'Feedback owner token not configured';
+const NO_STATUS_SUPPORT = 'Host does not support feedback status yet (or unknown id)';
+const HIDDEN = new Set(['archived', 'deleted']);
+
+/**
+ * @typedef {{ id: string, receivedAt: string|number|null, tag: string, title: string, body: string,
+ *   clientVersion: string|null, clientPlatform: string|null, moderation: string|null, status: string,
+ *   statusNote: string|null, statusAt: string|number|null, epicId: string|null }} InboxItem
+ * @typedef {{ items: InboxItem[], nextSince: string|null, nextModeratedSince: string|null }} Store
+ * @typedef {{ fetchImpl?: typeof fetch, storeFile?: string, ownerFile?: string,
+ *   env?: Record<string, string|undefined>, now?: () => number }} Deps
+ */
+
+/** @param {Deps} [deps] */
+function ctx(deps) {
+  const d = deps || {};
+  return {
+    fetchImpl: d.fetchImpl || globalThis.fetch,
+    storeFile: d.storeFile || path.join(schedulerPaths.schedulerHome(), 'customer-feedback-inbox.json'),
+    ownerFile: d.ownerFile || path.join(schedulerPaths.schedulerHome(), 'customer-feedback-owner.json'),
+    env: d.env || process.env,
+    now: d.now || Date.now,
+  };
+}
+
+/** @param {Deps} [deps] @returns {{ token: string, projectCwd: string|null }|null} */
+function loadOwnerConfig(deps) {
+  const c = ctx(deps);
+  const envToken = (c.env.SM_FEEDBACK_OWNER_TOKEN || '').trim();
+  if (envToken) return { token: envToken, projectCwd: c.env.SM_FEEDBACK_OWNER_PROJECT_CWD || null };
+  try {
+    const j = JSON.parse(require('node:fs').readFileSync(c.ownerFile, 'utf8'));
+    const token = j && typeof j.token === 'string' ? j.token.trim() : '';
+    if (token) return { token, projectCwd: typeof j.projectCwd === 'string' && j.projectCwd ? j.projectCwd : null };
+  } catch { /* missing or corrupt = not an owner */ }
+  return null;
+}
+
+/** Never includes the token. @param {Deps} [deps] */
+function getOwnerInfo(deps) {
+  const cfg = loadOwnerConfig(deps);
+  return { ownerMode: !!cfg, projectCwd: cfg ? cfg.projectCwd : null };
+}
+
+/** @param {string} file @returns {Promise<Store>} */
+async function readStore(file) {
+  try {
+    const j = JSON.parse(await fsp.readFile(file, 'utf8'));
+    if (j && Array.isArray(j.items)) {
+      return {
+        items: j.items.filter((/** @type {unknown} */ i) => i && typeof i === 'object'),
+        nextSince: typeof j.nextSince === 'string' ? j.nextSince : null,
+        nextModeratedSince: typeof j.nextModeratedSince === 'string' ? j.nextModeratedSince : null,
+      };
+    }
+  } catch { /* missing or corrupt reads as empty */ }
+  return { items: [], nextSince: null, nextModeratedSince: null };
+}
+
+let writeQueue = Promise.resolve();
+/**
+ * Serialized read-modify-write over the mirror.
+ * @template T
+ * @param {string} file
+ * @param {(s: Store) => T} mutate mutates the store in place, returns a result
+ * @returns {Promise<T>}
+ */
+function mutateStore(file, mutate) {
+  const run = async () => {
+    const store = await readStore(file);
+    const result = mutate(store);
+    store.items = sortItems(store.items).slice(0, MAX_ITEMS);
+    await atomicFs.writeJsonAtomic(file, { schemaVersion: SCHEMA_VERSION, ...store }, { mode: 0o600 });
+    return result;
+  };
+  const tail = writeQueue.then(run, run);
+  writeQueue = tail.then(() => {}, () => {});
+  return tail;
+}
+
+/** @param {InboxItem[]} items */
+function sortItems(items) {
+  const t = (/** @type {InboxItem} */ i) => (i.receivedAt == null ? 0 : (typeof i.receivedAt === 'number' ? i.receivedAt : Date.parse(i.receivedAt) || 0));
+  return items.slice().sort((a, b) => t(b) - t(a));
+}
+
+/** @param {string} s @param {string} token */
+function redact(s, token) {
+  return token ? s.split(token).join('[redacted]') : s;
+}
+
+/** @param {unknown} e @param {string} token */
+function netError(e, token) {
+  return `Could not reach the feedback service: ${redact(e instanceof Error ? e.message : String(e), token)}`;
+}
+
+/** @param {Response} res @param {string} fallback */
+async function errorText(res, fallback) {
+  try {
+    /** @type {any} */
+    const j = await res.json();
+    if (j && typeof j.error === 'string' && j.error) return j.error;
+  } catch { /* no body */ }
+  return fallback;
+}
+
+/** @param {number} status */
+function httpError(status) {
+  if (status === 401) return 'Feedback owner token was rejected (401).';
+  if (status === 503) return 'Host has no feedback owner token configured (503).';
+  return `Feedback service returned ${status}.`;
+}
+
+/** @param {any} w @param {InboxItem|undefined} prev @returns {InboxItem} */
+function toItem(w, prev) {
+  const client = w.client && typeof w.client === 'object' ? w.client : {};
+  const st = w.status && typeof w.status === 'object' ? w.status : null;
+  return {
+    id: w.id,
+    receivedAt: w.receivedAt ?? null,
+    tag: fromWireType(String(w.type)),
+    title: String(w.title ?? ''),
+    body: String(w.description ?? ''),
+    clientVersion: typeof client.version === 'string' ? client.version : null,
+    clientPlatform: typeof client.platform === 'string' ? client.platform : null,
+    moderation: w.moderation && typeof w.moderation.action === 'string' ? w.moderation.action : null,
+    status: st && typeof st.value === 'string' ? st.value : 'open',
+    statusNote: st && typeof st.note === 'string' ? st.note : null,
+    statusAt: st ? (st.at ?? null) : null,
+    epicId: prev && prev.epicId ? prev.epicId : null,
+  };
+}
+
+/**
+ * @param {Deps} [deps]
+ * @returns {Promise<{ ok: true, fetched: number, pages: number } | { ok: false, error: string }>}
+ */
+async function pull(deps) {
+  const cfg = loadOwnerConfig(deps);
+  if (!cfg) return { ok: false, error: NO_TOKEN };
+  const c = ctx(deps);
+  const base = `${resolveFeedbackBase()}/api/projects/${FEEDBACK_SLUG}/feedback`;
+  const prior = await readStore(c.storeFile);
+  let since = prior.nextSince;
+  let moderatedSince = prior.nextModeratedSince;
+  /** @type {any[]} */
+  const fetched = [];
+  let pages = 0;
+  try {
+    for (; pages < MAX_PAGES;) {
+      const qs = new URLSearchParams();
+      if (since) qs.set('since', since);
+      if (moderatedSince) qs.set('moderatedSince', moderatedSince);
+      qs.set('images', 'none');
+      qs.set('limit', String(PAGE_LIMIT));
+      const res = await c.fetchImpl(`${base}?${qs.toString()}`, {
+        headers: { authorization: `Bearer ${cfg.token}` },
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+      if (!res.ok) return { ok: false, error: await errorText(res, httpError(res.status)) };
+      /** @type {any} */
+      const j = await res.json().catch(() => null);
+      if (!j || !Array.isArray(j.items)) return { ok: false, error: 'Feedback service returned an unexpected response.' };
+      pages++;
+      fetched.push(...j.items.filter((/** @type {any} */ i) => i && typeof i.id === 'string' && i.id));
+      if (typeof j.nextSince === 'string') since = j.nextSince;
+      if (typeof j.nextModeratedSince === 'string') moderatedSince = j.nextModeratedSince;
+      if (j.items.length < PAGE_LIMIT) break;
+    }
+  } catch (e) {
+    return { ok: false, error: netError(e, cfg.token) };
+  }
+  const finalSince = since;
+  const finalModerated = moderatedSince;
+  await mutateStore(c.storeFile, (store) => {
+    const byId = new Map(store.items.map((i) => [i.id, i]));
+    for (const w of fetched) byId.set(w.id, toItem(w, byId.get(w.id)));
+    store.items = [...byId.values()];
+    store.nextSince = finalSince;
+    store.nextModeratedSince = finalModerated;
+  });
+  return { ok: true, fetched: fetched.length, pages };
+}
+
+/**
+ * @param {{ includeHidden?: boolean }} [opts] @param {Deps} [deps]
+ * @returns {Promise<{ ok: true, items: InboxItem[] } | { ok: false, error: string }>}
+ */
+async function list(opts, deps) {
+  if (!loadOwnerConfig(deps)) return { ok: false, error: NO_TOKEN };
+  const store = await readStore(ctx(deps).storeFile);
+  const includeHidden = !!(opts && opts.includeHidden);
+  const items = sortItems(store.items).filter((i) => includeHidden || !(i.moderation && HIDDEN.has(i.moderation)));
+  return { ok: true, items };
+}
+
+/**
+ * @param {string} id @param {string} status @param {string} [note] @param {Deps} [deps]
+ * @returns {Promise<{ ok: true, item: InboxItem|null } | { ok: false, error: string }>}
+ */
+async function setStatus(id, status, note, deps) {
+  const cfg = loadOwnerConfig(deps);
+  if (!cfg) return { ok: false, error: NO_TOKEN };
+  if (typeof id !== 'string' || !id) return { ok: false, error: 'Feedback id is required.' };
+  if (!STATUSES.includes(/** @type {any} */ (status))) return { ok: false, error: `Status must be one of: ${STATUSES.join(', ')}.` };
+  if (note !== undefined && note !== null && (typeof note !== 'string' || note.length > MAX_NOTE)) {
+    return { ok: false, error: `Note must be ${MAX_NOTE} characters or fewer.` };
+  }
+  const c = ctx(deps);
+  try {
+    const res = await c.fetchImpl(`${resolveFeedbackBase()}/api/projects/${FEEDBACK_SLUG}/feedback/${encodeURIComponent(id)}/status`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${cfg.token}` },
+      body: JSON.stringify(note ? { status, note } : { status }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (res.status === 404) return { ok: false, error: NO_STATUS_SUPPORT };
+    if (res.status !== 200) return { ok: false, error: await errorText(res, httpError(res.status)) };
+    /** @type {any} */
+    const j = await res.json().catch(() => null);
+    const statusAt = j && j.statusAt != null ? j.statusAt : c.now();
+    const item = await mutateStore(c.storeFile, (store) => {
+      const it = store.items.find((i) => i.id === id);
+      if (!it) return null;
+      it.status = status;
+      it.statusNote = note || null;
+      it.statusAt = statusAt;
+      return it;
+    });
+    return { ok: true, item };
+  } catch (e) {
+    return { ok: false, error: netError(e, cfg.token) };
+  }
+}
+
+/**
+ * Local-only: record which Epic an item was turned into.
+ * @param {string} id @param {string} epicId @param {Deps} [deps]
+ * @returns {Promise<{ ok: true } | { ok: false, error: string }>}
+ */
+async function linkEpic(id, epicId, deps) {
+  if (!loadOwnerConfig(deps)) return { ok: false, error: NO_TOKEN };
+  if (typeof epicId !== 'string' || !epicId) return { ok: false, error: 'Epic id is required.' };
+  const found = await mutateStore(ctx(deps).storeFile, (store) => {
+    const it = store.items.find((i) => i.id === id);
+    if (!it) return false;
+    it.epicId = epicId;
+    return true;
+  });
+  return found ? { ok: true } : { ok: false, error: 'Unknown feedback id.' };
+}
+
+module.exports = {
+  STATUSES,
+  loadOwnerConfig,
+  getOwnerInfo,
+  pull,
+  list,
+  setStatus,
+  linkEpic,
+};

package/src/main/lib/customerFeedbackIpc.cjs

@@ -0,0 +1,43 @@
+// @ts-check
+'use strict';
+
+const REFRESH_DELAY_MS = 30_000;
+
+/**
+ * Renderer-facing IPC for the customer-feedback client + owner inbox.
+ * Handlers return the libs' `{ ok, ... }` results unchanged.
+ * @param {{ ipcMain?: any, client?: any, inbox?: any, setTimeoutImpl?: typeof setTimeout }} [deps]
+ */
+function registerCustomerFeedbackHandlers(deps = {}) {
+  const ipcMain = deps.ipcMain || require('electron').ipcMain;
+  const { schemas: s, validated: v } = require('../ipcSchemas.cjs');
+  const client = deps.client || require('./customerFeedbackClient.cjs');
+  const inbox = deps.inbox || require('./customerFeedbackInbox.cjs');
+  const timer = deps.setTimeoutImpl || setTimeout;
+
+  ipcMain.handle('customerFeedback:submit', v(s.customerFeedbackSubmit, (p) => client.submit(p)));
+  ipcMain.handle('customerFeedback:list', () => client.list());
+  ipcMain.handle('customerFeedback:refresh-status', () => client.refreshStatuses());
+  ipcMain.handle('customerFeedback:mark-seen', v(s.customerFeedbackMarkSeen, ({ ids }) => client.markSeen(ids)));
+  ipcMain.handle('customerFeedback:owner-info', () => inbox.getOwnerInfo());
+  ipcMain.handle('customerFeedback:inbox-pull', () => inbox.pull());
+  ipcMain.handle('customerFeedback:inbox-list', v(s.customerFeedbackInboxList, ({ includeHidden }) => inbox.list({ includeHidden })));
+  ipcMain.handle('customerFeedback:inbox-set-status', v(s.customerFeedbackInboxSetStatus, ({ id, status, note }) => inbox.setStatus(id, status, note)));
+  ipcMain.handle('customerFeedback:inbox-link-epic', v(s.customerFeedbackInboxLinkEpic, ({ id, epicId }) => inbox.linkEpic(id, epicId)));
+
+  // One-shot deferred refresh so users see resolutions without opening anything.
+  try {
+    const t = timer(() => {
+      Promise.resolve()
+        .then(() => client.refreshStatuses())
+        .catch((/** @type {any} */ e) => {
+          console.warn('[customerFeedback] boot status refresh failed:', e && e.name ? e.name : 'error');
+        });
+    }, REFRESH_DELAY_MS);
+    if (t && typeof t.unref === 'function') t.unref();
+  } catch {
+    /* never throw at boot */
+  }
+}
+
+module.exports = { registerCustomerFeedbackHandlers, REFRESH_DELAY_MS };

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/insideHome.cjs

@@ -64,7 +64,7 @@ function isContainedWin32(target, home) {
 
 function isContained(realPath, home = HOME_REAL, platform = process.platform) {
   if (platform === 'win32') return isContainedWin32(realPath, home);
-  return realPath === home || realPath.startsWith(home + path.sep);
+  return realPath === home || realPath.startsWith(home + path.posix.sep);
 }
 
 function assertInsideHome(p) {

package/src/main/lib/mcpToolCatalog.cjs

@@ -23,7 +23,7 @@ const { z } = require('zod');
 
 const CatalogEntrySchema = z.object({
   name: z.string().min(1),
-  group: z.enum(['scheduler', 'chat', 'feedback', 'help', 'project-home', 'macros']),
+  group: z.enum(['scheduler', 'chat', 'feedback', 'help', 'project-home', 'macros', 'customer-feedback']),
   purpose: z.string().min(1),
   whenToUse: z.string().min(1),
   whenNotToUse: z.string().min(1),
@@ -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',
@@ -293,6 +293,31 @@ const MCP_TOOL_CATALOG = [
     notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted. "
       + 'The document is CSP-stamped after it is written, so the viewer sandbox is the real network fence — these checks are defence in depth.',
   },
+  {
+    name: 'customer_feedback_list',
+    group: 'customer-feedback',
+    purpose: "List the customers' feedback in the owner's local inbox (bug / feature / discussion items submitted "
+      + 'from the {F} feedback panel), optionally pulling new items from the feedback service first.',
+    whenToUse: 'Use to inspect what customers have submitted and each item\'s status. `pull` defaults to true '
+      + '(fetch new items first); pass `includeHidden: true` to include moderated-away items.',
+    whenNotToUse: 'WHEN NOT TO USE IT: this only works on the owner\'s machine (it needs the owner token) and is read-only. '
+      + 'Turning an item into an Epic is done by the human via Open as Epic in the {F} feedback panel — there is no tool '
+      + 'for it. A finding that belongs to another local project uses feedback_open_session instead.',
+    exampleArgs: { pull: true, includeHidden: false },
+    notes: 'Returns { ok, items, pulled? }. Not-configured machines get { ok:false, error } as an error result.',
+  },
+  {
+    name: 'customer_feedback_set_status',
+    group: 'customer-feedback',
+    purpose: 'Set the status of one customer feedback item (open | in_progress | resolved | wontfix) with an optional '
+      + 'note the customer sees, via the session-manager app\'s admin API.',
+    whenToUse: 'Use after inspecting an item with customer_feedback_list, to mark it in progress, resolved, or wontfix.',
+    whenNotToUse: 'WHEN NOT TO USE IT: this changes status only. Turning an item into an Epic is done by the human via '
+      + 'Open as Epic in the {F} feedback panel — there is no tool for it. Cross-project findings use '
+      + 'feedback_open_session. Never mark an item resolved unless the work has actually landed.',
+    exampleArgs: { id: 'fb_123', status: 'resolved', note: 'Fixed in 0.97.0' },
+    notes: 'The note is shown to the customer; keep it short (the inbox enforces a maximum length).',
+  },
   {
     name: 'macro_list',
     group: 'macros',

package/src/main/lib/projectFolder.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * projectFolder.cjs — create a new, empty project folder from a parent
+ * directory + a user-typed name. Electron's `createDirectory` picker property
+ * is macOS-only, so the app creates the folder itself.
+ *
+ * Never throws for validation / exists / io failures; returns a result object.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MAX_NAME_LENGTH = 100;
+// NUL + C0 controls + DEL.
+// eslint-disable-next-line no-control-regex
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+
+/**
+ * @param {unknown} name
+ * @returns {{ ok: true, name: string } | { ok: false, error: string }}
+ */
+function validateProjectName(name) {
+  if (typeof name !== 'string') return { ok: false, error: 'Project name must be text.' };
+  const trimmed = name.trim();
+  if (!trimmed) return { ok: false, error: 'Project name cannot be empty.' };
+  if (trimmed.length > MAX_NAME_LENGTH) {
+    return { ok: false, error: `Project name must be ${MAX_NAME_LENGTH} characters or fewer.` };
+  }
+  if (trimmed === '.' || trimmed === '..') {
+    return { ok: false, error: 'Project name cannot be "." or "..".' };
+  }
+  if (trimmed.startsWith('-')) return { ok: false, error: 'Project name cannot start with "-".' };
+  if (trimmed.includes('/') || trimmed.includes('\\')) {
+    return { ok: false, error: 'Project name cannot contain "/" or "\\".' };
+  }
+  if (CONTROL_RE.test(trimmed)) {
+    return { ok: false, error: 'Project name cannot contain control characters.' };
+  }
+  return { ok: true, name: trimmed };
+}
+
+/**
+ * @param {{ parentDir: string, name: string }} input
+ * @returns {Promise<
+ *   | { ok: true, path: string }
+ *   | { ok: false, code: 'invalid-name' | 'invalid-parent' | 'io', error: string }
+ *   | { ok: false, code: 'exists', path: string, error: string }
+ * >}
+ */
+async function createProjectFolder({ parentDir, name } = /** @type {any} */ ({})) {
+  const v = validateProjectName(name);
+  if (!v.ok) return { ok: false, code: 'invalid-name', error: v.error };
+
+  if (typeof parentDir !== 'string' || !path.isAbsolute(parentDir)) {
+    return { ok: false, code: 'invalid-parent', error: 'Parent folder must be an absolute path.' };
+  }
+  try {
+    const st = await fs.promises.stat(parentDir);
+    if (!st.isDirectory()) {
+      return { ok: false, code: 'invalid-parent', error: `${parentDir} is not a folder.` };
+    }
+  } catch {
+    return { ok: false, code: 'invalid-parent', error: `Parent folder ${parentDir} does not exist.` };
+  }
+
+  const target = path.join(parentDir, v.name);
+  if (path.dirname(target) !== path.resolve(parentDir)) {
+    return { ok: false, code: 'invalid-name', error: 'Project name must be a single folder name.' };
+  }
+
+  try {
+    await fs.promises.mkdir(target); // non-recursive on purpose
+    return { ok: true, path: target };
+  } catch (err) {
+    const e = /** @type {NodeJS.ErrnoException} */ (err);
+    if (e && e.code === 'EEXIST') {
+      return {
+        ok: false,
+        code: 'exists',
+        path: target,
+        error: `A folder named "${v.name}" already exists in ${parentDir}`,
+      };
+    }
+    return { ok: false, code: 'io', error: (e && e.message) || String(err) };
+  }
+}
+
+module.exports = { createProjectFolder, validateProjectName };

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/lib/winUserData.cjs

@@ -0,0 +1,22 @@
+// Chromium resolves 'userData' via Windows known folders; with a stripped profile
+// (no AppData) app.getPath('userData') throws "Failed to get 'userData' path" and the
+// process dies 0x80000003. Fall back to an explicit %APPDATA%-based path.
+const path = require('node:path');
+
+function ensureWinUserDataPath({ app, env, platform, fs, os, log = () => {} }) {
+  if (platform !== 'win32') return false;
+  try {
+    app.getPath('userData');
+    return false;
+  } catch (err) {
+    const appData = (env && env.APPDATA) || path.win32.join(os.homedir(), 'AppData', 'Roaming');
+    const userData = path.win32.join(appData, 'Session Manager');
+    fs.mkdirSync(userData, { recursive: true });
+    app.setPath('appData', appData);
+    app.setPath('userData', userData);
+    log(`[win-userdata] getPath('userData') failed (${err && err.message}); using ${userData}`);
+    return true;
+  }
+}
+
+module.exports = { ensureWinUserDataPath };