@sanqianx/claude-ai-workbench 0.13.2 → 0.13.4

package/src/backend/lib/sdk-session-stream.js

@@ -1,143 +1,143 @@
-'use strict';
-
-// One input queue and one reader own a native session. A turn result makes
-// the composer available; it does not terminate the process hosting tasks.
-class SdkSessionStream {
-  constructor({ onMessage = () => {}, idleMs = 30000, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
-    this.onMessage = onMessage;
-    this.idleMs = idleMs;
-    this.setTimer = setTimer;
-    this.clearTimer = clearTimer;
-    this.foregroundRunning = false;
-    this.completedTurns = 0;
-    this.tasks = new Map();
-    this.queue = [];
-    this.waiter = null;
-    this.closed = false;
-    this.closedSignal = new Promise(resolve => { this.resolveClosed = resolve; });
-    const self = this;
-    this.input = {
-      [Symbol.asyncIterator]() { return this; },
-      next() {
-        if (self.queue.length) return Promise.resolve({ value: self.queue.shift(), done: false });
-        if (self.closed) return Promise.resolve({ done: true });
-        return new Promise(resolve => { self.waiter = resolve; });
-      },
-      return() { return Promise.resolve({ done: true }); },
-    };
-  }
-
-  // 'unknown' marks tasks whose only observed status was missing or an
-  // unrecognized literal: still active, never a claimed terminal state.
-  get activeTaskCount() { return [...this.tasks.values()].filter(status => status === 'running' || status === 'pending' || status === UNKNOWN_TASK_STATUS).length; }
-
-  send(message) {
-    if (this.closed) throw Object.assign(new Error('session transport is closed'), { code: 'SESSION_CLOSED' });
-    if (this.foregroundRunning) throw Object.assign(new Error('session already has an active turn'), { code: 'TURN_BUSY', status: 409 });
-    this.cancelIdle();
-    this.foregroundRunning = true;
-    if (this.waiter) { const resolve = this.waiter; this.waiter = null; resolve({ value: message, done: false }); }
-    else this.queue.push(message);
-  }
-
-  cancelIdle() { if (this.idleTimer) { this.clearTimer(this.idleTimer); } this.idleTimer = null; }
-
-  _observeTask(message) {
-    if (!['task_started', 'task_progress', 'task_updated', 'task_notification'].includes(message.subtype)) return;
-    const prior = this.tasks.get(message.task_id);
-    if (prior !== undefined && TERMINAL_TASK_STATUS.has(prior)) return;
-    const raw = message.subtype === 'task_updated' ? message.patch?.status : message.status;
-    const known = normalizeTaskStatus(raw);
-    if (known !== null) { this.tasks.set(message.task_id, known); return; }
-    if (prior !== undefined) return;
-    this.tasks.set(message.task_id, message.subtype === 'task_started' && !raw ? 'running' : UNKNOWN_TASK_STATUS);
-  }
-
-  observe(message) {
-    const nested = Boolean(message.parent_tool_use_id);
-    if (message.type === 'system' && message.task_id) this._observeTask(message);
-    if (!nested && (message.type === 'result' || mainReplyEnded(message))) {
-      this.foregroundRunning = false;
-      if (message.type === 'result') this.completedTurns++;
-    } else if (!nested && message.type === 'stream_event' && message.event?.type === 'message_start') {
-      this.foregroundRunning = true;
-    }
-    this.onMessage(message);
-    this.cancelIdle();
-    if (!this.foregroundRunning && !this.activeTaskCount) {
-      this.idleTimer = this.setTimer(() => this.close('idle'), this.idleMs);
-      this.idleTimer?.unref?.();
-    }
-  }
-
-  async consume(query) {
-    if (this.query) throw new Error('session transport already has a reader');
-    this.query = query;
-    const iterator = query[Symbol.asyncIterator]();
-    try {
-      while (!this.closed) {
-        const item = await Promise.race([iterator.next(), this.closedSignal]);
-        if (this.closed) break;
-        if (item.done) {
-          if (this.foregroundRunning || this.activeTaskCount || !this.completedTurns) {
-            throw Object.assign(new Error('Claude Code stream closed before all active work completed'), { code: 'INCOMPLETE_RESULT' });
-          }
-          break;
-        }
-        this.observe(item.value);
-      }
-    } finally { this.close('stream-ended'); }
-  }
-
-  close(reason = 'closed') {
-    if (this.closed) return;
-    this.closed = true;
-    this.closeReason = reason;
-    this.cancelIdle();
-    this.queue.length = 0;
-    this.waiter?.({ done: true }); this.waiter = null;
-    this.resolveClosed({ done: true });
-    this.query?.close?.();
-  }
-}
-
-const TASK_STATUS = new Set(['pending', 'running', 'completed', 'failed', 'stopped']);
-const TERMINAL_TASK_STATUS = new Set(['completed', 'failed', 'stopped']);
-const UNKNOWN_TASK_STATUS = 'unknown';
-function normalizeTaskStatus(raw) {
-  if (typeof raw !== 'string' || raw === '') return null;
-  if (raw === 'killed') return 'stopped';
-  return TASK_STATUS.has(raw) ? raw : null;
-}
-function mainReplyEnded(message) {
-  if (message?.parent_tool_use_id) return false;
-  const reason = message?.type === 'stream_event' && message.event?.type === 'message_delta'
-    ? message.event.delta?.stop_reason : message?.type === 'assistant' ? message.message?.stop_reason : null;
-  return ['end_turn', 'stop_sequence', 'refusal'].includes(reason);
-}
-function sdkTaskEvent(message, parentSessionId) {
-  if (message?.type !== 'system' || !['task_started', 'task_progress', 'task_updated', 'task_notification'].includes(message.subtype) || !message.task_id) return null;
-  const patch = message.patch || {};
-  const rawStatus = typeof message.status === 'string' && message.status !== '' ? message.status
-    : typeof patch.status === 'string' && patch.status !== '' ? patch.status : null;
-  const known = normalizeTaskStatus(rawStatus);
-  // Only the task_started fact may imply 'running'; every other missing or
-  // unrecognized status is reported as an explicit unknown, never a success.
-  const status = known !== null ? known : message.subtype === 'task_started' && rawStatus === null ? 'running' : null;
-  const usage = message.usage && Object.fromEntries(['total_tokens', 'tool_uses', 'duration_ms'].filter(key => Number.isFinite(message.usage[key])).map(key => [key, Math.max(0, message.usage[key])]));
-  return {
-    type: `claude/${message.subtype.replaceAll('_', '-')}`,
-    taskId: String(message.task_id), parentSessionId,
-    sdkSessionId: typeof message.session_id === 'string' && message.session_id !== '' ? message.session_id : null,
-    taskType: typeof message.task_type === 'string' && message.task_type !== '' ? message.task_type : null,
-    ...(message.tool_use_id ? { toolUseId: String(message.tool_use_id) } : {}),
-    ...(message.description || patch.description ? { description: String(message.description || patch.description).slice(0, 2000) } : {}),
-    status,
-    ...(status === null ? { diagnostic: rawStatus === null ? 'task-status-missing' : 'task-status-unknown', ...(rawStatus !== null ? { rawStatus: rawStatus.slice(0, 40) } : {}) } : {}),
-    ...(message.summary || patch.error ? { summary: String(message.summary || patch.error).slice(0, 8000) } : {}),
-    ...(message.last_tool_name ? { lastToolName: String(message.last_tool_name) } : {}),
-    ...(usage ? { usage } : {}),
-  };
-}
-
-module.exports = { SdkSessionStream, sdkTaskEvent, mainReplyEnded };
+'use strict';
+
+// One input queue and one reader own a native session. A turn result makes
+// the composer available; it does not terminate the process hosting tasks.
+class SdkSessionStream {
+  constructor({ onMessage = () => {}, idleMs = 30000, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+    this.onMessage = onMessage;
+    this.idleMs = idleMs;
+    this.setTimer = setTimer;
+    this.clearTimer = clearTimer;
+    this.foregroundRunning = false;
+    this.completedTurns = 0;
+    this.tasks = new Map();
+    this.queue = [];
+    this.waiter = null;
+    this.closed = false;
+    this.closedSignal = new Promise(resolve => { this.resolveClosed = resolve; });
+    const self = this;
+    this.input = {
+      [Symbol.asyncIterator]() { return this; },
+      next() {
+        if (self.queue.length) return Promise.resolve({ value: self.queue.shift(), done: false });
+        if (self.closed) return Promise.resolve({ done: true });
+        return new Promise(resolve => { self.waiter = resolve; });
+      },
+      return() { return Promise.resolve({ done: true }); },
+    };
+  }
+
+  // 'unknown' marks tasks whose only observed status was missing or an
+  // unrecognized literal: still active, never a claimed terminal state.
+  get activeTaskCount() { return [...this.tasks.values()].filter(status => status === 'running' || status === 'pending' || status === UNKNOWN_TASK_STATUS).length; }
+
+  send(message) {
+    if (this.closed) throw Object.assign(new Error('session transport is closed'), { code: 'SESSION_CLOSED' });
+    if (this.foregroundRunning) throw Object.assign(new Error('session already has an active turn'), { code: 'TURN_BUSY', status: 409 });
+    this.cancelIdle();
+    this.foregroundRunning = true;
+    if (this.waiter) { const resolve = this.waiter; this.waiter = null; resolve({ value: message, done: false }); }
+    else this.queue.push(message);
+  }
+
+  cancelIdle() { if (this.idleTimer) { this.clearTimer(this.idleTimer); } this.idleTimer = null; }
+
+  _observeTask(message) {
+    if (!['task_started', 'task_progress', 'task_updated', 'task_notification'].includes(message.subtype)) return;
+    const prior = this.tasks.get(message.task_id);
+    if (prior !== undefined && TERMINAL_TASK_STATUS.has(prior)) return;
+    const raw = message.subtype === 'task_updated' ? message.patch?.status : message.status;
+    const known = normalizeTaskStatus(raw);
+    if (known !== null) { this.tasks.set(message.task_id, known); return; }
+    if (prior !== undefined) return;
+    this.tasks.set(message.task_id, message.subtype === 'task_started' && !raw ? 'running' : UNKNOWN_TASK_STATUS);
+  }
+
+  observe(message) {
+    const nested = Boolean(message.parent_tool_use_id);
+    if (message.type === 'system' && message.task_id) this._observeTask(message);
+    if (!nested && (message.type === 'result' || mainReplyEnded(message))) {
+      this.foregroundRunning = false;
+      if (message.type === 'result') this.completedTurns++;
+    } else if (!nested && message.type === 'stream_event' && message.event?.type === 'message_start') {
+      this.foregroundRunning = true;
+    }
+    this.onMessage(message);
+    this.cancelIdle();
+    if (!this.foregroundRunning && !this.activeTaskCount) {
+      this.idleTimer = this.setTimer(() => this.close('idle'), this.idleMs);
+      this.idleTimer?.unref?.();
+    }
+  }
+
+  async consume(query) {
+    if (this.query) throw new Error('session transport already has a reader');
+    this.query = query;
+    const iterator = query[Symbol.asyncIterator]();
+    try {
+      while (!this.closed) {
+        const item = await Promise.race([iterator.next(), this.closedSignal]);
+        if (this.closed) break;
+        if (item.done) {
+          if (this.foregroundRunning || this.activeTaskCount || !this.completedTurns) {
+            throw Object.assign(new Error('Claude Code stream closed before all active work completed'), { code: 'INCOMPLETE_RESULT' });
+          }
+          break;
+        }
+        this.observe(item.value);
+      }
+    } finally { this.close('stream-ended'); }
+  }
+
+  close(reason = 'closed') {
+    if (this.closed) return;
+    this.closed = true;
+    this.closeReason = reason;
+    this.cancelIdle();
+    this.queue.length = 0;
+    this.waiter?.({ done: true }); this.waiter = null;
+    this.resolveClosed({ done: true });
+    this.query?.close?.();
+  }
+}
+
+const TASK_STATUS = new Set(['pending', 'running', 'completed', 'failed', 'stopped']);
+const TERMINAL_TASK_STATUS = new Set(['completed', 'failed', 'stopped']);
+const UNKNOWN_TASK_STATUS = 'unknown';
+function normalizeTaskStatus(raw) {
+  if (typeof raw !== 'string' || raw === '') return null;
+  if (raw === 'killed') return 'stopped';
+  return TASK_STATUS.has(raw) ? raw : null;
+}
+function mainReplyEnded(message) {
+  if (message?.parent_tool_use_id) return false;
+  const reason = message?.type === 'stream_event' && message.event?.type === 'message_delta'
+    ? message.event.delta?.stop_reason : message?.type === 'assistant' ? message.message?.stop_reason : null;
+  return ['end_turn', 'stop_sequence', 'refusal'].includes(reason);
+}
+function sdkTaskEvent(message, parentSessionId) {
+  if (message?.type !== 'system' || !['task_started', 'task_progress', 'task_updated', 'task_notification'].includes(message.subtype) || !message.task_id) return null;
+  const patch = message.patch || {};
+  const rawStatus = typeof message.status === 'string' && message.status !== '' ? message.status
+    : typeof patch.status === 'string' && patch.status !== '' ? patch.status : null;
+  const known = normalizeTaskStatus(rawStatus);
+  // Only the task_started fact may imply 'running'; every other missing or
+  // unrecognized status is reported as an explicit unknown, never a success.
+  const status = known !== null ? known : message.subtype === 'task_started' && rawStatus === null ? 'running' : null;
+  const usage = message.usage && Object.fromEntries(['total_tokens', 'tool_uses', 'duration_ms'].filter(key => Number.isFinite(message.usage[key])).map(key => [key, Math.max(0, message.usage[key])]));
+  return {
+    type: `claude/${message.subtype.replaceAll('_', '-')}`,
+    taskId: String(message.task_id), parentSessionId,
+    sdkSessionId: typeof message.session_id === 'string' && message.session_id !== '' ? message.session_id : null,
+    taskType: typeof message.task_type === 'string' && message.task_type !== '' ? message.task_type : null,
+    ...(message.tool_use_id ? { toolUseId: String(message.tool_use_id) } : {}),
+    ...(message.description || patch.description ? { description: String(message.description || patch.description).slice(0, 2000) } : {}),
+    status,
+    ...(status === null ? { diagnostic: rawStatus === null ? 'task-status-missing' : 'task-status-unknown', ...(rawStatus !== null ? { rawStatus: rawStatus.slice(0, 40) } : {}) } : {}),
+    ...(message.summary || patch.error ? { summary: String(message.summary || patch.error).slice(0, 8000) } : {}),
+    ...(message.last_tool_name ? { lastToolName: String(message.last_tool_name) } : {}),
+    ...(usage ? { usage } : {}),
+  };
+}
+
+module.exports = { SdkSessionStream, sdkTaskEvent, mainReplyEnded };

package/src/backend/lib/sdk-turn-stream.js

@@ -1,16 +1,16 @@
-'use strict';
-
-// Each Workbench turn owns a query. A result is its protocol boundary; an
-// SDK transport can remain open for later notifications after that boundary.
-async function consumeSdkTurn(query, onMessage) {
-  const iterator = query[Symbol.asyncIterator]();
-  try {
-    while (true) {
-      const item = await iterator.next();
-      if (item.done) throw Object.assign(new Error('Claude Code stream closed before its final result'), { code: 'INCOMPLETE_RESULT' });
-      onMessage(item.value);
-      if (item.value?.type === 'result') return item.value;
-    }
-  } finally { query.close?.(); }
-}
-module.exports = { consumeSdkTurn };
+'use strict';
+
+// Each Workbench turn owns a query. A result is its protocol boundary; an
+// SDK transport can remain open for later notifications after that boundary.
+async function consumeSdkTurn(query, onMessage) {
+  const iterator = query[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      const item = await iterator.next();
+      if (item.done) throw Object.assign(new Error('Claude Code stream closed before its final result'), { code: 'INCOMPLETE_RESULT' });
+      onMessage(item.value);
+      if (item.value?.type === 'result') return item.value;
+    }
+  } finally { query.close?.(); }
+}
+module.exports = { consumeSdkTurn };

package/src/backend/lib/store-scope.js

@@ -1,131 +1,131 @@
-'use strict';
-
-// Stable store identity for a workbench data directory (W1-05).
-//
-// <dataDir>/store-id.v1.json holds { schema, storeId }; the storeId UUID v4 is
-// the persistent storeScope that survives restarts. Volatile values (PID,
-// port, runtime epoch, path hashing) may never stand in for it, and the
-// dataDir path itself never leaves this module.
-//
-// Publication protocol - a half-written file is never observable as final:
-//   1. read the final file; only a genuine ENOENT may start creation,
-//   2. write the complete document to a unique temp file opened 'wx' (mode
-//      0600), fsync, close,
-//   3. publish atomically and exclusively with a hard link; EEXIST means a
-//      concurrent winner exists - adopt its bytes, never overwrite them,
-//   4. remove our own temp name only; foreign or stale temps stay untouched.
-// Every failure maps to a fixed errorCode (no paths, no raw OS messages) and
-// an existing final file always keeps its exact bytes.
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-const STORE_FILE = 'store-id.v1.json';
-const STORE_SCHEMA = 'workbench-store/v1';
-// Canonical lowercase UUID v4 is the only accepted storeId spelling.
-const STORE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-
-function unavailable(errorCode) {
-  return { available: false, storeScope: null, errorCode };
-}
-
-function parseStoreDocument(text) {
-  let parsed;
-  try { parsed = JSON.parse(text); } catch { return null; }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
-  const keys = Object.keys(parsed);
-  if (keys.length !== 2 || !('schema' in parsed) || !('storeId' in parsed)) return null;
-  if (parsed.schema !== STORE_SCHEMA) return null;
-  return typeof parsed.storeId === 'string' && STORE_ID_PATTERN.test(parsed.storeId) ? parsed.storeId : null;
-}
-
-// Returns { found: false } only for a genuine ENOENT; any other error throws.
-function readFinalFile(fssystem, file) {
-  try {
-    return { found: true, text: fssystem.readFileSync(file, 'utf8') };
-  } catch (error) {
-    if (error && error.code === 'ENOENT') return { found: false };
-    throw error;
-  }
-}
-
-function removeOwnTemp(fssystem, file) {
-  try { fssystem.unlinkSync(file); } catch { /* best effort; must not mask the primary failure */ }
-}
-
-function adoptFinalFile(fssystem, file) {
-  let winner;
-  try {
-    winner = readFinalFile(fssystem, file);
-  } catch {
-    return unavailable('STORE_SCOPE_READ_FAILED');
-  }
-  if (!winner.found) return unavailable('STORE_SCOPE_READ_FAILED');
-  const storeId = parseStoreDocument(winner.text);
-  return storeId ? { available: true, storeScope: storeId, errorCode: null } : unavailable('STORE_SCOPE_INVALID');
-}
-
-/**
- * Resolve (creating on first use) the persistent store scope of dataDir.
- * Returns { available: true, storeScope, errorCode: null } or
- * { available: false, storeScope: null, errorCode } where errorCode is one of
- * the fixed codes STORE_SCOPE_MKDIR_FAILED | STORE_SCOPE_READ_FAILED |
- * STORE_SCOPE_INVALID | STORE_SCOPE_WRITE_FAILED | STORE_SCOPE_LINK_FAILED.
- * Never throws, never leaks the dataDir path or a raw OS error message.
- * options.fs injects the sync fs primitives for deterministic tests.
- */
-function ensureStoreScope(dataDir, options = {}) {
-  const fssystem = options.fs || fs;
-  const finalFile = path.join(dataDir, STORE_FILE);
-  let initial;
-  try {
-    initial = readFinalFile(fssystem, finalFile);
-  } catch {
-    return unavailable('STORE_SCOPE_READ_FAILED');
-  }
-  if (initial.found) {
-    const storeId = parseStoreDocument(initial.text);
-    return storeId ? { available: true, storeScope: storeId, errorCode: null } : unavailable('STORE_SCOPE_INVALID');
-  }
-  try {
-    fssystem.mkdirSync(dataDir, { recursive: true });
-  } catch {
-    return unavailable('STORE_SCOPE_MKDIR_FAILED');
-  }
-  const storeId = crypto.randomUUID();
-  const payload = Buffer.from(JSON.stringify({ schema: STORE_SCHEMA, storeId }) + '\n', 'utf8');
-  const tempFile = path.join(dataDir, STORE_FILE + '.' + crypto.randomUUID() + '.tmp');
-  let fd = null;
-  let created = false;
-  try {
-    fd = fssystem.openSync(tempFile, 'wx', 0o600);
-    created = true;
-    for (let written = 0; written < payload.length; ) {
-      // Same stance as SessionHistory.flush: a write reporting no progress
-      // must fail loudly - looping would hang boot, succeeding would publish
-      // a truncated document.
-      const progress = fssystem.writeSync(fd, payload, written, payload.length - written);
-      if (!progress) throw Object.assign(new Error('store scope write made no progress'), { code: 'EIO' });
-      written += progress;
-    }
-    fssystem.fsyncSync(fd);
-    fssystem.closeSync(fd);
-    fd = null;
-  } catch {
-    if (fd !== null) { try { fssystem.closeSync(fd); } catch { /* primary failure is reported below */ } }
-    if (created) removeOwnTemp(fssystem, tempFile);
-    return unavailable('STORE_SCOPE_WRITE_FAILED');
-  }
-  try {
-    fssystem.linkSync(tempFile, finalFile);
-  } catch (error) {
-    removeOwnTemp(fssystem, tempFile);
-    if (error && error.code === 'EEXIST') return adoptFinalFile(fssystem, finalFile);
-    return unavailable('STORE_SCOPE_LINK_FAILED');
-  }
-  removeOwnTemp(fssystem, tempFile);
-  return { available: true, storeScope: storeId, errorCode: null };
-}
-
-module.exports = { ensureStoreScope };
+'use strict';
+
+// Stable store identity for a workbench data directory (W1-05).
+//
+// <dataDir>/store-id.v1.json holds { schema, storeId }; the storeId UUID v4 is
+// the persistent storeScope that survives restarts. Volatile values (PID,
+// port, runtime epoch, path hashing) may never stand in for it, and the
+// dataDir path itself never leaves this module.
+//
+// Publication protocol - a half-written file is never observable as final:
+//   1. read the final file; only a genuine ENOENT may start creation,
+//   2. write the complete document to a unique temp file opened 'wx' (mode
+//      0600), fsync, close,
+//   3. publish atomically and exclusively with a hard link; EEXIST means a
+//      concurrent winner exists - adopt its bytes, never overwrite them,
+//   4. remove our own temp name only; foreign or stale temps stay untouched.
+// Every failure maps to a fixed errorCode (no paths, no raw OS messages) and
+// an existing final file always keeps its exact bytes.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const STORE_FILE = 'store-id.v1.json';
+const STORE_SCHEMA = 'workbench-store/v1';
+// Canonical lowercase UUID v4 is the only accepted storeId spelling.
+const STORE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+function unavailable(errorCode) {
+  return { available: false, storeScope: null, errorCode };
+}
+
+function parseStoreDocument(text) {
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { return null; }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const keys = Object.keys(parsed);
+  if (keys.length !== 2 || !('schema' in parsed) || !('storeId' in parsed)) return null;
+  if (parsed.schema !== STORE_SCHEMA) return null;
+  return typeof parsed.storeId === 'string' && STORE_ID_PATTERN.test(parsed.storeId) ? parsed.storeId : null;
+}
+
+// Returns { found: false } only for a genuine ENOENT; any other error throws.
+function readFinalFile(fssystem, file) {
+  try {
+    return { found: true, text: fssystem.readFileSync(file, 'utf8') };
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return { found: false };
+    throw error;
+  }
+}
+
+function removeOwnTemp(fssystem, file) {
+  try { fssystem.unlinkSync(file); } catch { /* best effort; must not mask the primary failure */ }
+}
+
+function adoptFinalFile(fssystem, file) {
+  let winner;
+  try {
+    winner = readFinalFile(fssystem, file);
+  } catch {
+    return unavailable('STORE_SCOPE_READ_FAILED');
+  }
+  if (!winner.found) return unavailable('STORE_SCOPE_READ_FAILED');
+  const storeId = parseStoreDocument(winner.text);
+  return storeId ? { available: true, storeScope: storeId, errorCode: null } : unavailable('STORE_SCOPE_INVALID');
+}
+
+/**
+ * Resolve (creating on first use) the persistent store scope of dataDir.
+ * Returns { available: true, storeScope, errorCode: null } or
+ * { available: false, storeScope: null, errorCode } where errorCode is one of
+ * the fixed codes STORE_SCOPE_MKDIR_FAILED | STORE_SCOPE_READ_FAILED |
+ * STORE_SCOPE_INVALID | STORE_SCOPE_WRITE_FAILED | STORE_SCOPE_LINK_FAILED.
+ * Never throws, never leaks the dataDir path or a raw OS error message.
+ * options.fs injects the sync fs primitives for deterministic tests.
+ */
+function ensureStoreScope(dataDir, options = {}) {
+  const fssystem = options.fs || fs;
+  const finalFile = path.join(dataDir, STORE_FILE);
+  let initial;
+  try {
+    initial = readFinalFile(fssystem, finalFile);
+  } catch {
+    return unavailable('STORE_SCOPE_READ_FAILED');
+  }
+  if (initial.found) {
+    const storeId = parseStoreDocument(initial.text);
+    return storeId ? { available: true, storeScope: storeId, errorCode: null } : unavailable('STORE_SCOPE_INVALID');
+  }
+  try {
+    fssystem.mkdirSync(dataDir, { recursive: true });
+  } catch {
+    return unavailable('STORE_SCOPE_MKDIR_FAILED');
+  }
+  const storeId = crypto.randomUUID();
+  const payload = Buffer.from(JSON.stringify({ schema: STORE_SCHEMA, storeId }) + '\n', 'utf8');
+  const tempFile = path.join(dataDir, STORE_FILE + '.' + crypto.randomUUID() + '.tmp');
+  let fd = null;
+  let created = false;
+  try {
+    fd = fssystem.openSync(tempFile, 'wx', 0o600);
+    created = true;
+    for (let written = 0; written < payload.length; ) {
+      // Same stance as SessionHistory.flush: a write reporting no progress
+      // must fail loudly - looping would hang boot, succeeding would publish
+      // a truncated document.
+      const progress = fssystem.writeSync(fd, payload, written, payload.length - written);
+      if (!progress) throw Object.assign(new Error('store scope write made no progress'), { code: 'EIO' });
+      written += progress;
+    }
+    fssystem.fsyncSync(fd);
+    fssystem.closeSync(fd);
+    fd = null;
+  } catch {
+    if (fd !== null) { try { fssystem.closeSync(fd); } catch { /* primary failure is reported below */ } }
+    if (created) removeOwnTemp(fssystem, tempFile);
+    return unavailable('STORE_SCOPE_WRITE_FAILED');
+  }
+  try {
+    fssystem.linkSync(tempFile, finalFile);
+  } catch (error) {
+    removeOwnTemp(fssystem, tempFile);
+    if (error && error.code === 'EEXIST') return adoptFinalFile(fssystem, finalFile);
+    return unavailable('STORE_SCOPE_LINK_FAILED');
+  }
+  removeOwnTemp(fssystem, tempFile);
+  return { available: true, storeScope: storeId, errorCode: null };
+}
+
+module.exports = { ensureStoreScope };