@sanqianx/claude-ai-workbench 0.13.2 → 0.13.4

package/packages/server/lib/delegation-store.js

@@ -1,468 +1,474 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-// Immutable reservation ledger for trusted Workbench delegation commands.
-//
-// Phase 1 (W1-28): records only RESERVE identity — delegationId plus a
-// reserved childSessionId — before any child session exists or any model
-// input is sent. There is deliberately no update, dispatch or delete path:
-// a reservation record is written once via exclusive create and never
-// rewritten. The ledger stores the canonical command binding (full TaskScope,
-// requestId, normalized payloadHash, resolved workspace, profile/model
-// selection) but never prompt bodies, credentials, env or private error text.
-//
-// Identity split (W1-DELEGATION-DECISIONS / W1-OWNER-DECISION): delegationId
-// identifies the Workbench server command. It is NOT an SDK run id; the record
-// carries sdkRunIdClaimed=false and inputCausalityClaimed=false because the
-// SDK has not been asked anything at reservation time. SDK ownerRunId keeps
-// its own meaning (sdk-launch facts only) and never appears here.
-//
-// Durability & concurrency: a record becomes visible only through
-// tmp-file + fsync + fs.link (create-if-absent). link() fails with EEXIST
-// when the record already exists, so two processes can never overwrite each
-// other's reservation; the loser re-reads and returns the original IDs. The
-// unique record file per (scope, requestId) is the single source of truth —
-// no secondary on-disk index exists to diverge, and getById rebuilds its
-// lookup by scanning records. Directory-entry fsync is attempted after the
-// link; on platforms whose primitives refuse it (Windows: EPERM) the store
-// records that capability instead of pretending durability it cannot get.
-// That directory fsync is a commit fence on EVERY reserve() success — fresh
-// commit, replay of an existing record, or an EEXIST loss to an identical
-// concurrent winner. A record whose fence never succeeded can never turn
-// into a success later without the fence being re-attempted in that same
-// call; the record itself is never rewritten, so recovery replays the
-// original IDs.
-
-const SCHEMA = 'workbench-delegation/v1';
-const VERSION = 1;
-const SOURCE = 'workbench-delegation-command';
-const BASIS = 'server-command';
-const PHASE = 'reserved';
-const OUTCOME = 'not-started';
-const RECORDS_DIR = 'records';
-const TMP_DIR = 'tmp';
-const NAME_RE = /^[0-9a-f]{64}\.json$/;
-const HASH_RE = /^[0-9a-f]{64}$/;
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-const SESSION_ID_RE = /^sess-[0-9a-f]{12}$/;
-// The set of errnos that mean "this platform does not offer directory fsync
-// through this API" rather than "the committed record is in doubt".
-const DIR_FSYNC_UNSUPPORTED = new Set(['EPERM', 'EINVAL', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EACCES']);
-
-function fail(code, status, message, extra) {
-  const error = new Error(message);
-  error.code = code;
-  error.status = status;
-  if (extra) Object.assign(error, extra);
-  throw error;
-}
-
-function hasControlCharacter(value) {
-  for (let k = 0; k < value.length; k += 1) {
-    const code = value.charCodeAt(k);
-    if (code < 0x20 || code === 0x7f) return true;
-  }
-  return false;
-}
-
-function isCleanString(value, max) {
-  return typeof value === 'string' && value.length > 0 && value.length <= max
-    && !hasControlCharacter(value);
-}
-
-function isPlainObject(value) {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-
-function exactKeys(object, keys) {
-  const actual = Object.keys(object);
-  return actual.length === keys.length && keys.every(key => Object.prototype.hasOwnProperty.call(object, key));
-}
-
-function validateScope(scope) {
-  if (!isPlainObject(scope) || !exactKeys(scope, ['storeScope', 'contextId', 'parentSessionId'])) {
-    fail('DELEGATION_SCOPE_INVALID', 400, 'scope must be an object with exactly storeScope, contextId and parentSessionId');
-  }
-  if (!UUID_RE.test(scope.storeScope)) fail('DELEGATION_SCOPE_INVALID', 400, 'scope.storeScope must be a canonical lowercase UUID v4');
-  if (!isCleanString(scope.contextId, 128)) fail('DELEGATION_SCOPE_INVALID', 400, 'scope.contextId must be a non-empty string');
-  if (!isCleanString(scope.parentSessionId, 128)) fail('DELEGATION_SCOPE_INVALID', 400, 'scope.parentSessionId must be a non-empty string');
-  return { storeScope: scope.storeScope, contextId: scope.contextId, parentSessionId: scope.parentSessionId };
-}
-
-function validateWorkspace(workspace) {
-  if (!isPlainObject(workspace) || !exactKeys(workspace, ['ref', 'rootPath', 'resolvedFrom'])) {
-    fail('DELEGATION_WORKSPACE_INVALID', 400, 'workspace must be an object with exactly ref, rootPath and resolvedFrom');
-  }
-  const { ref, rootPath, resolvedFrom } = workspace;
-  if (!isCleanString(ref, 128) || path.isAbsolute(ref) || /[\\/]/.test(ref)) {
-    fail('DELEGATION_WORKSPACE_INVALID', 400, 'workspace.ref must be an opaque registered reference, not a path');
-  }
-  if (typeof rootPath !== 'string' || !path.isAbsolute(rootPath) || !isCleanString(rootPath.replace(/\s/g, ''), 1024)) {
-    fail('DELEGATION_WORKSPACE_INVALID', 400, 'workspace.rootPath must be an absolute local directory path');
-  }
-  if (resolvedFrom !== 'parent-session-record') {
-    fail('DELEGATION_WORKSPACE_INVALID', 400, "workspace.resolvedFrom must be 'parent-session-record'");
-  }
-  return { ref, rootPath, resolvedFrom };
-}
-
-function validateSelection(selection) {
-  if (!isPlainObject(selection) || !exactKeys(selection, ['profileId', 'model'])) {
-    fail('DELEGATION_SELECTION_REJECTED', 400, 'selection must be an object with exactly profileId and model; credentials and env are never accepted or stored');
-  }
-  for (const key of ['profileId', 'model']) {
-    const value = selection[key];
-    if (value !== null && !isCleanString(value, 128)) {
-      fail('DELEGATION_SELECTION_REJECTED', 400, `selection.${key} must be null or a non-empty string`);
-    }
-  }
-  return { profileId: selection.profileId, model: selection.model };
-}
-
-function requestHashOf(scope, requestId) {
-  const canonical = JSON.stringify([scope.storeScope, scope.contextId, scope.parentSessionId, requestId]);
-  return crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
-}
-
-function newDelegationId() { return crypto.randomUUID(); }
-
-function newChildSessionId() { return `sess-${crypto.randomBytes(6).toString('hex')}`; }
-
-function canonicalBinding(scope, requestId, payloadHash, workspace, selection) {
-  return {
-    scope: { storeScope: scope.storeScope, contextId: scope.contextId, parentSessionId: scope.parentSessionId },
-    requestId,
-    payloadHash,
-    workspace: { ref: workspace.ref, rootPath: workspace.rootPath, resolvedFrom: workspace.resolvedFrom },
-    selection: { profileId: selection.profileId, model: selection.model },
-  };
-}
-
-// Full self-consistency validation of a stored record. Returns a normalized
-// deep copy or throws CORRUPT — the file itself is never touched.
-function validateRecord(parsed, entryName) {
-  const corrupt = detail => fail('DELEGATION_RECORD_CORRUPT', 500, `stored delegation record is invalid: ${detail}`, { entry: entryName });
-  if (!isPlainObject(parsed)) corrupt('not an object');
-  if (parsed.schema !== SCHEMA || parsed.version !== VERSION) corrupt('unknown schema/version');
-  if (!UUID_RE.test(parsed.delegationId || '')) corrupt('delegationId is not a UUID');
-  if (!SESSION_ID_RE.test(parsed.childSessionId || '')) corrupt('childSessionId is not a reserved session id');
-  let scope;
-  try { scope = validateScope(parsed.scope); } catch { corrupt('scope invalid'); }
-  if (!isCleanString(parsed.requestId || '', 256)) corrupt('requestId invalid');
-  if (!HASH_RE.test(parsed.requestHash || '')) corrupt('requestHash invalid');
-  if (!HASH_RE.test(parsed.payloadHash || '')) corrupt('payloadHash invalid');
-  let workspace;
-  let selection;
-  try { workspace = validateWorkspace(parsed.workspace); } catch { corrupt('workspace invalid'); }
-  try { selection = validateSelection(parsed.selection); } catch { corrupt('selection invalid'); }
-  if (requestHashOf(scope, parsed.requestId) !== parsed.requestHash) corrupt('requestHash does not match scope+requestId');
-  if (typeof parsed.issuedAt !== 'string' || !Number.isFinite(Date.parse(parsed.issuedAt))) corrupt('issuedAt invalid');
-  if (parsed.source !== SOURCE || parsed.basis !== BASIS || parsed.phase !== PHASE || parsed.outcome !== OUTCOME) {
-    corrupt('source/basis/phase/outcome literals changed');
-  }
-  if (parsed.sdkRunIdClaimed !== false || parsed.inputCausalityClaimed !== false) {
-    corrupt('sdk claims must stay false at reservation time');
-  }
-  return {
-    schema: SCHEMA, version: VERSION,
-    delegationId: parsed.delegationId, childSessionId: parsed.childSessionId,
-    scope, requestId: parsed.requestId, requestHash: parsed.requestHash, payloadHash: parsed.payloadHash,
-    workspace, selection, issuedAt: parsed.issuedAt,
-    source: SOURCE, basis: BASIS, phase: PHASE, outcome: OUTCOME,
-    sdkRunIdClaimed: false, inputCausalityClaimed: false,
-  };
-}
-
-function sameBinding(record, binding) {
-  return JSON.stringify(canonicalBinding(record.scope, record.requestId, record.payloadHash, record.workspace, record.selection))
-    === JSON.stringify(binding);
-}
-
-function bindingDifference(record, binding) {
-  const fields = ['payloadHash'];
-  if (record.payloadHash !== binding.payloadHash) return 'payloadHash';
-  if (JSON.stringify(record.workspace) !== JSON.stringify(binding.workspace)) return 'workspace';
-  if (JSON.stringify(record.selection) !== JSON.stringify(binding.selection)) return 'selection';
-  return fields[0];
-}
-
-function defaultDirFsync(f, dirPath) {
-  let fd;
-  try {
-    fd = f.openSync(dirPath, 'r');
-    f.fsyncSync(fd);
-    return 'supported';
-  } catch (error) {
-    if (DIR_FSYNC_UNSUPPORTED.has(error && error.code)) return 'unsupported';
-    throw error;
-  } finally {
-    if (fd !== undefined) { try { f.closeSync(fd); } catch { /* closed or unusable */ } }
-  }
-}
-
-function createDelegationStore(options = {}) {
-  const { root, storeScope } = options || {};
-  // fsx is an internal seam for fault-injection tests; production callers
-  // omit it and get the real fs module.
-  const f = options.fsx || fs;
-  const dirFsync = typeof f.dirFsync === 'function' ? f.dirFsync.bind(f) : dirPath => defaultDirFsync(f, dirPath);
-  if (typeof root !== 'string' || !root.trim() || !path.isAbsolute(root)) {
-    fail('DELEGATION_STORE_ROOT_INVALID', 400, 'root must be an absolute server-owned directory');
-  }
-  if (!UUID_RE.test(storeScope || '')) {
-    fail('DELEGATION_STORE_SCOPE_INVALID', 400, 'storeScope must be a canonical lowercase UUID v4');
-  }
-  const rootDir = path.resolve(root);
-  const recordsDir = path.join(rootDir, RECORDS_DIR);
-  const tmpDir = path.join(rootDir, TMP_DIR);
-
-  function ensureRealDir(dirPath, what) {
-    try {
-      f.mkdirSync(dirPath, { recursive: true });
-    } catch (error) {
-      // recursive mkdir reports EEXIST/ENOTDIR when a non-directory already
-      // occupies the path; the lstat classification below gives the honest
-      // answer, and anything else (EACCES, EROFS, ...) is a real failure.
-      if (!(error && (error.code === 'EEXIST' || error.code === 'ENOTDIR'))) throw error;
-    }
-    const st = f.lstatSync(dirPath);
-    if (st.isSymbolicLink()) fail('DELEGATION_STORE_PATH_UNSAFE', 400, `${what} must not be a symbolic link`, { path: what });
-    if (!st.isDirectory()) fail('DELEGATION_STORE_PATH_UNSAFE', 400, `${what} must be a real directory`, { path: what });
-  }
-
-  ensureRealDir(rootDir, 'store root');
-  ensureRealDir(recordsDir, 'records directory');
-  ensureRealDir(tmpDir, 'tmp directory');
-
-  let directoryFsync = 'unknown';
-  let tmpCounter = 0;
-
-  const recordPathOf = requestHash => path.join(recordsDir, `${requestHash}.json`);
-
-  // Reads a record file and validates it against the caller's expectation.
-  // 'missing' | { record } — corrupt/unsafe files throw and are preserved.
-  function readRecord(requestHash, expected) {
-    const file = recordPathOf(requestHash);
-    let st;
-    try { st = f.lstatSync(file); } catch (error) {
-      if (error && error.code === 'ENOENT') return { status: 'missing' };
-      throw error;
-    }
-    const entry = path.basename(file);
-    if (st.isSymbolicLink()) fail('DELEGATION_RECORD_INVALID', 500, 'record entry must not be a symbolic link', { entry });
-    if (!st.isFile()) fail('DELEGATION_RECORD_INVALID', 500, 'record entry must be a regular file', { entry });
-    // A transient read error (AV lock, EBUSY, EIO) must surface as itself:
-    // folding it into "corrupt" would permanently block a healthy request.
-    let parsed;
-    try { parsed = JSON.parse(f.readFileSync(file, 'utf8')); } catch (error) {
-      if (error instanceof SyntaxError) parsed = null;
-      else throw error;
-    }
-    const record = validateRecord(parsed, entry);
-    if (record.requestHash !== requestHash) fail('DELEGATION_RECORD_CORRUPT', 500, 'record does not belong to its request path', { entry });
-    if (expected) {
-      if (JSON.stringify(record.scope) !== JSON.stringify(expected.scope)) {
-        fail('DELEGATION_RECORD_CORRUPT', 500, 'record scope does not match its request path', { entry });
-      }
-      if (record.requestId !== expected.requestId) {
-        fail('DELEGATION_RECORD_CORRUPT', 500, 'record requestId does not match its request path', { entry });
-      }
-    }
-    return { status: 'ok', record };
-  }
-
-  // Every entry in the records directory must be a well-named regular file;
-  // anything else is tampering and fails loudly — never a silent empty list.
-  function scanRecordNames() {
-    const names = f.readdirSync(recordsDir).sort();
-    for (const name of names) {
-      if (!NAME_RE.test(name)) {
-        fail('DELEGATION_STORE_DIR_INVALID', 500, 'records directory contains an unexpected entry', { entry: name });
-      }
-    }
-    return names;
-  }
-
-  function cleanupOwnTmp(tmpPath) {
-    const resolved = path.resolve(tmpPath);
-    if (resolved !== tmpPath || !resolved.startsWith(tmpDir + path.sep) || path.basename(resolved).includes(path.sep)) {
-      return; // not provably this call's own temp file inside the dedicated root: leave it alone
-    }
-    try { f.unlinkSync(resolved); } catch (error) { if (error && error.code !== 'ENOENT') throw error; }
-  }
-
-  function returnCopy(record) {
-    return JSON.parse(JSON.stringify(record));
-  }
-
-  function requireBoundScope(scope) {
-    const valid = validateScope(scope);
-    if (valid.storeScope !== storeScope) {
-      fail('DELEGATION_STORE_SCOPE_MISMATCH', 400, 'this ledger is bound to a different storeScope');
-    }
-    return valid;
-  }
-
-  // Every success a caller could act on (a later dispatch phase starts from
-  // these IDs) must pass the commit fence within the same reserve() call:
-  // fresh commits, replays of existing records, and EEXIST losses to an
-  // identical winner are all fenced. The fence either syncs the directory
-  // entry, discloses that the platform primitive is unavailable, or fails —
-  // a record whose fence never succeeded must not be returned as success
-  // later without the fence being re-attempted. The record is never
-  // rewritten by this path, so a retry after recovery replays the same IDs.
-  function commitFence(after) {
-    try {
-      directoryFsync = dirFsync(recordsDir);
-    } catch (error) {
-      fail('DELEGATION_DIR_FSYNC_FAILED', 500, `reservation ${after}: commit fence (directory fsync) failed; the record stays untouched and a retry after recovery returns the same ids`, { reason: error && error.code });
-    }
-  }
-
-  function reserve(input = {}) {
-    const scope = requireBoundScope(validateScope(input.scope));
-    if (!isCleanString(input.requestId, 256)) fail('DELEGATION_REQUEST_INVALID', 400, 'requestId must be a non-empty string without control characters');
-    const requestId = input.requestId;
-    if (typeof input.payloadHash !== 'string' || !HASH_RE.test(input.payloadHash.toLowerCase())) {
-      fail('DELEGATION_PAYLOAD_HASH_INVALID', 400, 'payloadHash must be the server-computed canonical command sha256 hex');
-    }
-    const payloadHash = input.payloadHash.toLowerCase();
-    const workspace = validateWorkspace(input.workspace);
-    const selection = validateSelection(input.selection);
-    const binding = canonicalBinding(scope, requestId, payloadHash, workspace, selection);
-    const requestHash = requestHashOf(scope, requestId);
-
-    const existing = readRecord(requestHash, { scope, requestId });
-    if (existing.status === 'ok') {
-      if (sameBinding(existing.record, binding)) {
-        commitFence('replay');
-        return returnCopy(existing.record);
-      }
-      fail('DELEGATION_PAYLOAD_CONFLICT', 409, `a reservation already exists for this requestId with a different ${bindingDifference(existing.record, binding)}`);
-    }
-
-    const record = {
-      schema: SCHEMA, version: VERSION,
-      delegationId: newDelegationId(), childSessionId: newChildSessionId(),
-      scope, requestId, requestHash, payloadHash,
-      workspace, selection,
-      issuedAt: new Date().toISOString(),
-      source: SOURCE, basis: BASIS, phase: PHASE, outcome: OUTCOME,
-      sdkRunIdClaimed: false, inputCausalityClaimed: false,
-    };
-    const payload = Buffer.from(`${JSON.stringify(record)}\n`, 'utf8');
-    tmpCounter += 1;
-    const tmpPath = path.join(tmpDir, `${process.pid}-${tmpCounter}-${crypto.randomUUID()}.tmp`);
-    let fd;
-    try {
-      fd = f.openSync(tmpPath, 'wx');
-      let written = 0;
-      while (written < payload.length) {
-        // writeSync returns THIS call's byte count: accumulate it and keep
-        // passing the true offset/length, so a legal short write never
-        // re-writes or skips bytes. A zero return means no progress at all
-        // and would otherwise spin forever — fail on the first one.
-        const bytesWritten = f.writeSync(fd, payload, written, payload.length - written);
-        if (!(bytesWritten > 0)) {
-          const noProgress = new Error('writeSync returned no progress');
-          noProgress.code = 'write-zero-progress';
-          throw noProgress;
-        }
-        written += bytesWritten;
-      }
-      f.fsyncSync(fd);
-    } catch (error) {
-      if (fd !== undefined) { try { f.closeSync(fd); } catch { /* already closed */ } }
-      try { cleanupOwnTmp(tmpPath); } catch { /* failure below is the honest answer */ }
-      fail('DELEGATION_WRITE_FAILED', 500, 'reservation record could not be written durably; nothing was reserved', { reason: error && error.code });
-    }
-    try { f.closeSync(fd); } catch { /* data already fsynced; close failure is not a durability loss */ }
-    try {
-      f.linkSync(tmpPath, recordPathOf(requestHash));
-    } catch (error) {
-      try { cleanupOwnTmp(tmpPath); } catch { /* reported below */ }
-      if (error && error.code === 'EEXIST') {
-        const winner = readRecord(requestHash, { scope, requestId });
-        if (winner.status !== 'ok') {
-          fail('DELEGATION_RECORD_CORRUPT', 500, 'concurrent reservation record exists but cannot be validated', { entry: `${requestHash}.json` });
-        }
-        if (sameBinding(winner.record, binding)) {
-          commitFence('lost-race');
-          return returnCopy(winner.record);
-        }
-        fail('DELEGATION_PAYLOAD_CONFLICT', 409, `a concurrent reservation won this requestId with a different ${bindingDifference(winner.record, binding)}`);
-      }
-      fail('DELEGATION_COMMIT_FAILED', 500, 'atomic reservation commit is unavailable on this platform/path; nothing was reserved', { reason: error && error.code });
-    }
-    // The link is visible and the content was fsynced before it. The commit
-    // fence syncs the directory entry (or discloses the capability gap via
-    // describe()); an unexpected failure surfaces as an error while the
-    // record itself stays intact — a retry re-attempts the fence and then
-    // replays the same IDs.
-    try {
-      commitFence('commit');
-    } catch (error) {
-      try { cleanupOwnTmp(tmpPath); } catch { /* the fence failure is the honest answer */ }
-      throw error;
-    }
-    try { cleanupOwnTmp(tmpPath); } catch (error) {
-      fail('DELEGATION_TMP_CLEANUP_FAILED', 500, 'reservation committed but its temp file could not be removed', { reason: error && error.code });
-    }
-    return returnCopy(record);
-  }
-
-  function getByRequest(scope, requestId) {
-    const valid = requireBoundScope(scope);
-    if (!isCleanString(requestId, 256)) fail('DELEGATION_REQUEST_INVALID', 400, 'requestId must be a non-empty string without control characters');
-    const found = readRecord(requestHashOf(valid, requestId), { scope: valid, requestId });
-    return found.status === 'ok' ? returnCopy(found.record) : null;
-  }
-
-  function getById(scope, delegationId) {
-    const valid = requireBoundScope(scope);
-    if (typeof delegationId !== 'string' || !UUID_RE.test(delegationId)) {
-      fail('DELEGATION_ID_INVALID', 400, 'delegationId must be a UUID issued by this ledger');
-    }
-    for (const name of scanRecordNames()) {
-      const requestHash = name.slice(0, -'.json'.length);
-      const found = readRecord(requestHash, null);
-      if (found.record.delegationId === delegationId) {
-        if (JSON.stringify(found.record.scope) !== JSON.stringify(valid)) {
-          fail('DELEGATION_SCOPE_MISMATCH', 403, 'this delegationId belongs to a different scope', { delegationId });
-        }
-        return returnCopy(found.record);
-      }
-    }
-    return null;
-  }
-
-  function list(scope) {
-    const valid = requireBoundScope(scope);
-    const records = [];
-    for (const name of scanRecordNames()) {
-      const found = readRecord(name.slice(0, -'.json'.length), null);
-      if (JSON.stringify(found.record.scope) === JSON.stringify(valid)) records.push(found.record);
-    }
-    records.sort((a, b) => a.issuedAt.localeCompare(b.issuedAt) || a.delegationId.localeCompare(b.delegationId));
-    return records.map(returnCopy);
-  }
-
-  return {
-    reserve,
-    getByRequest,
-    getById,
-    list,
-    describe() {
-      return { schema: SCHEMA, version: VERSION, root: rootDir, storeScope, directoryFsync };
-    },
-  };
-}
-
-module.exports = {
-  createDelegationStore,
-  DELEGATION_SCHEMA: SCHEMA,
-  DELEGATION_VERSION: VERSION,
-};
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// Immutable reservation ledger for trusted Workbench delegation commands.
+//
+// Phase 1 (W1-28): records only RESERVE identity — delegationId plus a
+// reserved childSessionId — before any child session exists or any model
+// input is sent. There is deliberately no update, dispatch or delete path:
+// a reservation record is written once via exclusive create and never
+// rewritten. The ledger stores the canonical command binding (full TaskScope,
+// requestId, normalized payloadHash, resolved workspace, profile/model
+// selection). Opt-in parent snapshots are private context on that immutable
+// reservation; credentials, env and private error text are never stored here.
+//
+// Identity split (W1-DELEGATION-DECISIONS / W1-OWNER-DECISION): delegationId
+// identifies the Workbench server command. It is NOT an SDK run id; the record
+// carries sdkRunIdClaimed=false and inputCausalityClaimed=false because the
+// SDK has not been asked anything at reservation time. SDK ownerRunId keeps
+// its own meaning (sdk-launch facts only) and never appears here.
+//
+// Durability & concurrency: a record becomes visible only through
+// tmp-file + fsync + fs.link (create-if-absent). link() fails with EEXIST
+// when the record already exists, so two processes can never overwrite each
+// other's reservation; the loser re-reads and returns the original IDs. The
+// unique record file per (scope, requestId) is the single source of truth —
+// no secondary on-disk index exists to diverge, and getById rebuilds its
+// lookup by scanning records. Directory-entry fsync is attempted after the
+// link; on platforms whose primitives refuse it (Windows: EPERM) the store
+// records that capability instead of pretending durability it cannot get.
+// That directory fsync is a commit fence on EVERY reserve() success — fresh
+// commit, replay of an existing record, or an EEXIST loss to an identical
+// concurrent winner. A record whose fence never succeeded can never turn
+// into a success later without the fence being re-attempted in that same
+// call; the record itself is never rewritten, so recovery replays the
+// original IDs.
+
+const SCHEMA = 'workbench-delegation/v1';
+const VERSION = 1;
+const SOURCE = 'workbench-delegation-command';
+const BASIS = 'server-command';
+const PHASE = 'reserved';
+const OUTCOME = 'not-started';
+const RECORDS_DIR = 'records';
+const TMP_DIR = 'tmp';
+const NAME_RE = /^[0-9a-f]{64}\.json$/;
+const HASH_RE = /^[0-9a-f]{64}$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SESSION_ID_RE = /^sess-[0-9a-f]{12}$/;
+// The set of errnos that mean "this platform does not offer directory fsync
+// through this API" rather than "the committed record is in doubt".
+const DIR_FSYNC_UNSUPPORTED = new Set(['EPERM', 'EINVAL', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EACCES']);
+
+function fail(code, status, message, extra) {
+  const error = new Error(message);
+  error.code = code;
+  error.status = status;
+  if (extra) Object.assign(error, extra);
+  throw error;
+}
+
+function hasControlCharacter(value) {
+  for (let k = 0; k < value.length; k += 1) {
+    const code = value.charCodeAt(k);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+function isCleanString(value, max) {
+  return typeof value === 'string' && value.length > 0 && value.length <= max
+    && !hasControlCharacter(value);
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(object, keys) {
+  const actual = Object.keys(object);
+  return actual.length === keys.length && keys.every(key => Object.prototype.hasOwnProperty.call(object, key));
+}
+
+function validateScope(scope) {
+  if (!isPlainObject(scope) || !exactKeys(scope, ['storeScope', 'contextId', 'parentSessionId'])) {
+    fail('DELEGATION_SCOPE_INVALID', 400, 'scope must be an object with exactly storeScope, contextId and parentSessionId');
+  }
+  if (!UUID_RE.test(scope.storeScope)) fail('DELEGATION_SCOPE_INVALID', 400, 'scope.storeScope must be a canonical lowercase UUID v4');
+  if (!isCleanString(scope.contextId, 128)) fail('DELEGATION_SCOPE_INVALID', 400, 'scope.contextId must be a non-empty string');
+  if (!isCleanString(scope.parentSessionId, 128)) fail('DELEGATION_SCOPE_INVALID', 400, 'scope.parentSessionId must be a non-empty string');
+  return { storeScope: scope.storeScope, contextId: scope.contextId, parentSessionId: scope.parentSessionId };
+}
+
+function validateWorkspace(workspace) {
+  if (!isPlainObject(workspace) || !exactKeys(workspace, ['ref', 'rootPath', 'resolvedFrom'])) {
+    fail('DELEGATION_WORKSPACE_INVALID', 400, 'workspace must be an object with exactly ref, rootPath and resolvedFrom');
+  }
+  const { ref, rootPath, resolvedFrom } = workspace;
+  if (!isCleanString(ref, 128) || path.isAbsolute(ref) || /[\\/]/.test(ref)) {
+    fail('DELEGATION_WORKSPACE_INVALID', 400, 'workspace.ref must be an opaque registered reference, not a path');
+  }
+  if (typeof rootPath !== 'string' || !path.isAbsolute(rootPath) || !isCleanString(rootPath.replace(/\s/g, ''), 1024)) {
+    fail('DELEGATION_WORKSPACE_INVALID', 400, 'workspace.rootPath must be an absolute local directory path');
+  }
+  if (resolvedFrom !== 'parent-session-record') {
+    fail('DELEGATION_WORKSPACE_INVALID', 400, "workspace.resolvedFrom must be 'parent-session-record'");
+  }
+  return { ref, rootPath, resolvedFrom };
+}
+
+function validateSelection(selection) {
+  if (!isPlainObject(selection) || !exactKeys(selection, ['profileId', 'model'])) {
+    fail('DELEGATION_SELECTION_REJECTED', 400, 'selection must be an object with exactly profileId and model; credentials and env are never accepted or stored');
+  }
+  for (const key of ['profileId', 'model']) {
+    const value = selection[key];
+    if (value !== null && !isCleanString(value, 128)) {
+      fail('DELEGATION_SELECTION_REJECTED', 400, `selection.${key} must be null or a non-empty string`);
+    }
+  }
+  return { profileId: selection.profileId, model: selection.model };
+}
+
+function requestHashOf(scope, requestId) {
+  const canonical = JSON.stringify([scope.storeScope, scope.contextId, scope.parentSessionId, requestId]);
+  return crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+
+function newDelegationId() { return crypto.randomUUID(); }
+
+function newChildSessionId() { return `sess-${crypto.randomBytes(6).toString('hex')}`; }
+
+function canonicalBinding(scope, requestId, payloadHash, workspace, selection) {
+  return {
+    scope: { storeScope: scope.storeScope, contextId: scope.contextId, parentSessionId: scope.parentSessionId },
+    requestId,
+    payloadHash,
+    workspace: { ref: workspace.ref, rootPath: workspace.rootPath, resolvedFrom: workspace.resolvedFrom },
+    selection: { profileId: selection.profileId, model: selection.model },
+  };
+}
+
+// Full self-consistency validation of a stored record. Returns a normalized
+// deep copy or throws CORRUPT — the file itself is never touched.
+function validateRecord(parsed, entryName) {
+  const corrupt = detail => fail('DELEGATION_RECORD_CORRUPT', 500, `stored delegation record is invalid: ${detail}`, { entry: entryName });
+  if (!isPlainObject(parsed)) corrupt('not an object');
+  let context;
+  if (parsed.context !== undefined) {
+    try { context = require('./parent-context').validateParentContext(parsed.context); } catch { corrupt('context snapshot invalid'); }
+  }
+  if (parsed.schema !== SCHEMA || parsed.version !== VERSION) corrupt('unknown schema/version');
+  if (!UUID_RE.test(parsed.delegationId || '')) corrupt('delegationId is not a UUID');
+  if (!SESSION_ID_RE.test(parsed.childSessionId || '')) corrupt('childSessionId is not a reserved session id');
+  let scope;
+  try { scope = validateScope(parsed.scope); } catch { corrupt('scope invalid'); }
+  if (!isCleanString(parsed.requestId || '', 256)) corrupt('requestId invalid');
+  if (!HASH_RE.test(parsed.requestHash || '')) corrupt('requestHash invalid');
+  if (!HASH_RE.test(parsed.payloadHash || '')) corrupt('payloadHash invalid');
+  let workspace;
+  let selection;
+  try { workspace = validateWorkspace(parsed.workspace); } catch { corrupt('workspace invalid'); }
+  try { selection = validateSelection(parsed.selection); } catch { corrupt('selection invalid'); }
+  if (requestHashOf(scope, parsed.requestId) !== parsed.requestHash) corrupt('requestHash does not match scope+requestId');
+  if (typeof parsed.issuedAt !== 'string' || !Number.isFinite(Date.parse(parsed.issuedAt))) corrupt('issuedAt invalid');
+  if (parsed.source !== SOURCE || parsed.basis !== BASIS || parsed.phase !== PHASE || parsed.outcome !== OUTCOME) {
+    corrupt('source/basis/phase/outcome literals changed');
+  }
+  if (parsed.sdkRunIdClaimed !== false || parsed.inputCausalityClaimed !== false) {
+    corrupt('sdk claims must stay false at reservation time');
+  }
+  return {
+    schema: SCHEMA, version: VERSION,
+    delegationId: parsed.delegationId, childSessionId: parsed.childSessionId,
+    scope, requestId: parsed.requestId, requestHash: parsed.requestHash, payloadHash: parsed.payloadHash,
+    workspace, selection, issuedAt: parsed.issuedAt, ...(context ? { context } : {}),
+    source: SOURCE, basis: BASIS, phase: PHASE, outcome: OUTCOME,
+    sdkRunIdClaimed: false, inputCausalityClaimed: false,
+  };
+}
+
+function sameBinding(record, binding) {
+  return JSON.stringify(canonicalBinding(record.scope, record.requestId, record.payloadHash, record.workspace, record.selection))
+    === JSON.stringify(binding);
+}
+
+function bindingDifference(record, binding) {
+  const fields = ['payloadHash'];
+  if (record.payloadHash !== binding.payloadHash) return 'payloadHash';
+  if (JSON.stringify(record.workspace) !== JSON.stringify(binding.workspace)) return 'workspace';
+  if (JSON.stringify(record.selection) !== JSON.stringify(binding.selection)) return 'selection';
+  return fields[0];
+}
+
+function defaultDirFsync(f, dirPath) {
+  let fd;
+  try {
+    fd = f.openSync(dirPath, 'r');
+    f.fsyncSync(fd);
+    return 'supported';
+  } catch (error) {
+    if (DIR_FSYNC_UNSUPPORTED.has(error && error.code)) return 'unsupported';
+    throw error;
+  } finally {
+    if (fd !== undefined) { try { f.closeSync(fd); } catch { /* closed or unusable */ } }
+  }
+}
+
+function createDelegationStore(options = {}) {
+  const { root, storeScope } = options || {};
+  // fsx is an internal seam for fault-injection tests; production callers
+  // omit it and get the real fs module.
+  const f = options.fsx || fs;
+  const dirFsync = typeof f.dirFsync === 'function' ? f.dirFsync.bind(f) : dirPath => defaultDirFsync(f, dirPath);
+  if (typeof root !== 'string' || !root.trim() || !path.isAbsolute(root)) {
+    fail('DELEGATION_STORE_ROOT_INVALID', 400, 'root must be an absolute server-owned directory');
+  }
+  if (!UUID_RE.test(storeScope || '')) {
+    fail('DELEGATION_STORE_SCOPE_INVALID', 400, 'storeScope must be a canonical lowercase UUID v4');
+  }
+  const rootDir = path.resolve(root);
+  const recordsDir = path.join(rootDir, RECORDS_DIR);
+  const tmpDir = path.join(rootDir, TMP_DIR);
+
+  function ensureRealDir(dirPath, what) {
+    try {
+      f.mkdirSync(dirPath, { recursive: true });
+    } catch (error) {
+      // recursive mkdir reports EEXIST/ENOTDIR when a non-directory already
+      // occupies the path; the lstat classification below gives the honest
+      // answer, and anything else (EACCES, EROFS, ...) is a real failure.
+      if (!(error && (error.code === 'EEXIST' || error.code === 'ENOTDIR'))) throw error;
+    }
+    const st = f.lstatSync(dirPath);
+    if (st.isSymbolicLink()) fail('DELEGATION_STORE_PATH_UNSAFE', 400, `${what} must not be a symbolic link`, { path: what });
+    if (!st.isDirectory()) fail('DELEGATION_STORE_PATH_UNSAFE', 400, `${what} must be a real directory`, { path: what });
+  }
+
+  ensureRealDir(rootDir, 'store root');
+  ensureRealDir(recordsDir, 'records directory');
+  ensureRealDir(tmpDir, 'tmp directory');
+
+  let directoryFsync = 'unknown';
+  let tmpCounter = 0;
+
+  const recordPathOf = requestHash => path.join(recordsDir, `${requestHash}.json`);
+
+  // Reads a record file and validates it against the caller's expectation.
+  // 'missing' | { record } — corrupt/unsafe files throw and are preserved.
+  function readRecord(requestHash, expected) {
+    const file = recordPathOf(requestHash);
+    let st;
+    try { st = f.lstatSync(file); } catch (error) {
+      if (error && error.code === 'ENOENT') return { status: 'missing' };
+      throw error;
+    }
+    const entry = path.basename(file);
+    if (st.isSymbolicLink()) fail('DELEGATION_RECORD_INVALID', 500, 'record entry must not be a symbolic link', { entry });
+    if (!st.isFile()) fail('DELEGATION_RECORD_INVALID', 500, 'record entry must be a regular file', { entry });
+    // A transient read error (AV lock, EBUSY, EIO) must surface as itself:
+    // folding it into "corrupt" would permanently block a healthy request.
+    let parsed;
+    try { parsed = JSON.parse(f.readFileSync(file, 'utf8')); } catch (error) {
+      if (error instanceof SyntaxError) parsed = null;
+      else throw error;
+    }
+    const record = validateRecord(parsed, entry);
+    if (record.requestHash !== requestHash) fail('DELEGATION_RECORD_CORRUPT', 500, 'record does not belong to its request path', { entry });
+    if (expected) {
+      if (JSON.stringify(record.scope) !== JSON.stringify(expected.scope)) {
+        fail('DELEGATION_RECORD_CORRUPT', 500, 'record scope does not match its request path', { entry });
+      }
+      if (record.requestId !== expected.requestId) {
+        fail('DELEGATION_RECORD_CORRUPT', 500, 'record requestId does not match its request path', { entry });
+      }
+    }
+    return { status: 'ok', record };
+  }
+
+  // Every entry in the records directory must be a well-named regular file;
+  // anything else is tampering and fails loudly — never a silent empty list.
+  function scanRecordNames() {
+    const names = f.readdirSync(recordsDir).sort();
+    for (const name of names) {
+      if (!NAME_RE.test(name)) {
+        fail('DELEGATION_STORE_DIR_INVALID', 500, 'records directory contains an unexpected entry', { entry: name });
+      }
+    }
+    return names;
+  }
+
+  function cleanupOwnTmp(tmpPath) {
+    const resolved = path.resolve(tmpPath);
+    if (resolved !== tmpPath || !resolved.startsWith(tmpDir + path.sep) || path.basename(resolved).includes(path.sep)) {
+      return; // not provably this call's own temp file inside the dedicated root: leave it alone
+    }
+    try { f.unlinkSync(resolved); } catch (error) { if (error && error.code !== 'ENOENT') throw error; }
+  }
+
+  function returnCopy(record) {
+    return JSON.parse(JSON.stringify(record));
+  }
+
+  function requireBoundScope(scope) {
+    const valid = validateScope(scope);
+    if (valid.storeScope !== storeScope) {
+      fail('DELEGATION_STORE_SCOPE_MISMATCH', 400, 'this ledger is bound to a different storeScope');
+    }
+    return valid;
+  }
+
+  // Every success a caller could act on (a later dispatch phase starts from
+  // these IDs) must pass the commit fence within the same reserve() call:
+  // fresh commits, replays of existing records, and EEXIST losses to an
+  // identical winner are all fenced. The fence either syncs the directory
+  // entry, discloses that the platform primitive is unavailable, or fails —
+  // a record whose fence never succeeded must not be returned as success
+  // later without the fence being re-attempted. The record is never
+  // rewritten by this path, so a retry after recovery replays the same IDs.
+  function commitFence(after) {
+    try {
+      directoryFsync = dirFsync(recordsDir);
+    } catch (error) {
+      fail('DELEGATION_DIR_FSYNC_FAILED', 500, `reservation ${after}: commit fence (directory fsync) failed; the record stays untouched and a retry after recovery returns the same ids`, { reason: error && error.code });
+    }
+  }
+
+  function reserve(input = {}) {
+    const scope = requireBoundScope(validateScope(input.scope));
+    if (!isCleanString(input.requestId, 256)) fail('DELEGATION_REQUEST_INVALID', 400, 'requestId must be a non-empty string without control characters');
+    const requestId = input.requestId;
+    if (typeof input.payloadHash !== 'string' || !HASH_RE.test(input.payloadHash.toLowerCase())) {
+      fail('DELEGATION_PAYLOAD_HASH_INVALID', 400, 'payloadHash must be the server-computed canonical command sha256 hex');
+    }
+    const payloadHash = input.payloadHash.toLowerCase();
+    const workspace = validateWorkspace(input.workspace);
+    const selection = validateSelection(input.selection);
+    const binding = canonicalBinding(scope, requestId, payloadHash, workspace, selection);
+    const requestHash = requestHashOf(scope, requestId);
+
+    const existing = readRecord(requestHash, { scope, requestId });
+    if (existing.status === 'ok') {
+      if (sameBinding(existing.record, binding)) {
+        commitFence('replay');
+        return returnCopy(existing.record);
+      }
+      fail('DELEGATION_PAYLOAD_CONFLICT', 409, `a reservation already exists for this requestId with a different ${bindingDifference(existing.record, binding)}`);
+    }
+
+    const record = {
+      schema: SCHEMA, version: VERSION,
+      delegationId: newDelegationId(), childSessionId: newChildSessionId(),
+      scope, requestId, requestHash, payloadHash,
+      workspace, selection,
+      ...(input.context ? { context: require('./parent-context').validateParentContext(typeof input.context === 'function' ? input.context() : input.context) } : {}),
+      issuedAt: new Date().toISOString(),
+      source: SOURCE, basis: BASIS, phase: PHASE, outcome: OUTCOME,
+      sdkRunIdClaimed: false, inputCausalityClaimed: false,
+    };
+    const payload = Buffer.from(`${JSON.stringify(record)}\n`, 'utf8');
+    tmpCounter += 1;
+    const tmpPath = path.join(tmpDir, `${process.pid}-${tmpCounter}-${crypto.randomUUID()}.tmp`);
+    let fd;
+    try {
+      fd = f.openSync(tmpPath, 'wx');
+      let written = 0;
+      while (written < payload.length) {
+        // writeSync returns THIS call's byte count: accumulate it and keep
+        // passing the true offset/length, so a legal short write never
+        // re-writes or skips bytes. A zero return means no progress at all
+        // and would otherwise spin forever — fail on the first one.
+        const bytesWritten = f.writeSync(fd, payload, written, payload.length - written);
+        if (!(bytesWritten > 0)) {
+          const noProgress = new Error('writeSync returned no progress');
+          noProgress.code = 'write-zero-progress';
+          throw noProgress;
+        }
+        written += bytesWritten;
+      }
+      f.fsyncSync(fd);
+    } catch (error) {
+      if (fd !== undefined) { try { f.closeSync(fd); } catch { /* already closed */ } }
+      try { cleanupOwnTmp(tmpPath); } catch { /* failure below is the honest answer */ }
+      fail('DELEGATION_WRITE_FAILED', 500, 'reservation record could not be written durably; nothing was reserved', { reason: error && error.code });
+    }
+    try { f.closeSync(fd); } catch { /* data already fsynced; close failure is not a durability loss */ }
+    try {
+      f.linkSync(tmpPath, recordPathOf(requestHash));
+    } catch (error) {
+      try { cleanupOwnTmp(tmpPath); } catch { /* reported below */ }
+      if (error && error.code === 'EEXIST') {
+        const winner = readRecord(requestHash, { scope, requestId });
+        if (winner.status !== 'ok') {
+          fail('DELEGATION_RECORD_CORRUPT', 500, 'concurrent reservation record exists but cannot be validated', { entry: `${requestHash}.json` });
+        }
+        if (sameBinding(winner.record, binding)) {
+          commitFence('lost-race');
+          return returnCopy(winner.record);
+        }
+        fail('DELEGATION_PAYLOAD_CONFLICT', 409, `a concurrent reservation won this requestId with a different ${bindingDifference(winner.record, binding)}`);
+      }
+      fail('DELEGATION_COMMIT_FAILED', 500, 'atomic reservation commit is unavailable on this platform/path; nothing was reserved', { reason: error && error.code });
+    }
+    // The link is visible and the content was fsynced before it. The commit
+    // fence syncs the directory entry (or discloses the capability gap via
+    // describe()); an unexpected failure surfaces as an error while the
+    // record itself stays intact — a retry re-attempts the fence and then
+    // replays the same IDs.
+    try {
+      commitFence('commit');
+    } catch (error) {
+      try { cleanupOwnTmp(tmpPath); } catch { /* the fence failure is the honest answer */ }
+      throw error;
+    }
+    try { cleanupOwnTmp(tmpPath); } catch (error) {
+      fail('DELEGATION_TMP_CLEANUP_FAILED', 500, 'reservation committed but its temp file could not be removed', { reason: error && error.code });
+    }
+    return returnCopy(record);
+  }
+
+  function getByRequest(scope, requestId) {
+    const valid = requireBoundScope(scope);
+    if (!isCleanString(requestId, 256)) fail('DELEGATION_REQUEST_INVALID', 400, 'requestId must be a non-empty string without control characters');
+    const found = readRecord(requestHashOf(valid, requestId), { scope: valid, requestId });
+    return found.status === 'ok' ? returnCopy(found.record) : null;
+  }
+
+  function getById(scope, delegationId) {
+    const valid = requireBoundScope(scope);
+    if (typeof delegationId !== 'string' || !UUID_RE.test(delegationId)) {
+      fail('DELEGATION_ID_INVALID', 400, 'delegationId must be a UUID issued by this ledger');
+    }
+    for (const name of scanRecordNames()) {
+      const requestHash = name.slice(0, -'.json'.length);
+      const found = readRecord(requestHash, null);
+      if (found.record.delegationId === delegationId) {
+        if (JSON.stringify(found.record.scope) !== JSON.stringify(valid)) {
+          fail('DELEGATION_SCOPE_MISMATCH', 403, 'this delegationId belongs to a different scope', { delegationId });
+        }
+        return returnCopy(found.record);
+      }
+    }
+    return null;
+  }
+
+  function list(scope) {
+    const valid = requireBoundScope(scope);
+    const records = [];
+    for (const name of scanRecordNames()) {
+      const found = readRecord(name.slice(0, -'.json'.length), null);
+      if (JSON.stringify(found.record.scope) === JSON.stringify(valid)) records.push(found.record);
+    }
+    records.sort((a, b) => a.issuedAt.localeCompare(b.issuedAt) || a.delegationId.localeCompare(b.delegationId));
+    return records.map(returnCopy);
+  }
+
+  return {
+    reserve,
+    getByRequest,
+    getById,
+    list,
+    describe() {
+      return { schema: SCHEMA, version: VERSION, root: rootDir, storeScope, directoryFsync };
+    },
+  };
+}
+
+module.exports = {
+  createDelegationStore,
+  DELEGATION_SCHEMA: SCHEMA,
+  DELEGATION_VERSION: VERSION,
+};