@lark-apaas/fullstack-cli 1.1.59-alpha.20260722050835 → 1.1.59-alpha.20260722071909

package/templates/scripts/preview-phase-outbox.cjs

@@ -1,2155 +0,0 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync: nodeSpawnSync } = require('child_process');
-
-const DEFAULT_OUTBOX_ROOT = '/tmp/event/miaoda-preview-phase/v1';
-const MAX_EVENT_BYTES = 16 * 1024;
-const DEFAULT_MAX_RUN_BYTES = 2 * 1024 * 1024;
-const DEFAULT_MAX_ROOT_BYTES = 64 * 1024 * 1024;
-const DEFAULT_MAX_ROOT_DIRECTORIES = 128;
-const DEFAULT_MAX_ROOT_SCAN_DIRECTORIES = 256;
-const DEFAULT_MAX_RUN_SCAN_ENTRIES = 64;
-const DEFAULT_MAX_FALLBACK_FILES = 32;
-const DEFAULT_MAX_FALLBACK_BYTES = 2 * 1024 * 1024;
-const DEFAULT_MAX_FALLBACK_EVENTS = 256;
-const MAX_FALLBACK_RECORD_BYTES = MAX_EVENT_BYTES + 4 * 1024;
-const FALLBACK_TERMINAL_RESERVE_BYTES = 1024;
-const RUN_ID_PATTERN = /^prv_[A-Za-z0-9_-]{1,60}$/;
-const STATE_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
-const PRODUCER_INSTANCE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
-const FALLBACK_SESSION_ID_PATTERN = /^pfs_[a-f0-9]{32}$/;
-const PROCESS_START_TICKS_PATTERN = /^\d+$/;
-const PRODUCER_EPOCH_PATTERN = /^ppe_[a-f0-9]{32}$/;
-const INSTANCE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
-const PRODUCER_REGISTER_URL = 'http://127.0.0.1:8091/shell/exec';
-const PRODUCER_REGISTER_ATTEMPTS = 2;
-const PRODUCER_REGISTER_CURL_TIMEOUT_SECONDS = '0.35';
-const PRODUCER_REGISTER_PROCESS_TIMEOUT_MS = 400;
-const PRODUCER_REGISTER_MAX_RESPONSE_BYTES = 64 * 1024;
-const TRANSIENT_ERRNO_CODES = new Set([
-  'EAGAIN',
-  'EINTR',
-  'EBUSY',
-  'EMFILE',
-  'ENFILE',
-  'ENOMEM',
-]);
-const MAX_TRANSIENT_ATTEMPTS = 3;
-
-function producerRegistrationError(code, message, cause) {
-  const error = new Error(message, cause == null ? undefined : { cause });
-  error.code = code;
-  return error;
-}
-
-function validateProducerRegistrationResponse(response, request) {
-  const commonInvalid =
-    response?.protocol !== 'preview-phase-outbox-v1' ||
-    response.capability_status !== 'supported' ||
-    response.generation !== request.generation ||
-    response.producer_epoch !== request.producer_epoch ||
-    response.producer_generation !== request.generation;
-  const rejected = response?.registration_status === 'rejected';
-  const rejectedInvalid =
-    rejected &&
-    (response.registration_reason !== 'stale_epoch' ||
-      response.writer_active === true ||
-      response.sealed !== true ||
-      response.fallback_required !== true ||
-      response.fallback_session_id !== request.fallback_session_id ||
-      response.fallback_final_seq !== 1 ||
-      response.producer_state !== 'rejected' ||
-      request.rejected_event == null);
-  const acceptedInvalid =
-    !rejected &&
-    ((response?.registration_status != null &&
-      response.registration_status !== 'accepted') ||
-      response.writer_active !== true ||
-      response.producer_state !== 'active');
-  if (commonInvalid || rejectedInvalid || acceptedInvalid) {
-    throw producerRegistrationError(
-      'PREVIEW_PHASE_PRODUCER_REGISTRATION_ACK_UNKNOWN',
-      'invalid preview phase producer registration response'
-    );
-  }
-  return response;
-}
-
-function registerPreviewPhaseProducerViaShellServer(
-  request,
-  spawnSync = nodeSpawnSync
-) {
-  const wireRequest = {
-    phase_outbox: {
-      protocol: 'preview-phase-outbox-v1',
-      operation: 'register',
-      run_id: request.run_id,
-      generation: request.generation,
-      expected_instance_id: request.expected_instance_id,
-      producer_epoch: request.producer_epoch,
-      writer_instance_id: request.writer_instance_id,
-      pid: request.pid,
-      process_start_ticks: request.process_start_ticks,
-      ...(request.rejected_event == null
-        ? {}
-        : {
-            producer_instance_id: request.producer_instance_id,
-            fallback_session_id: request.fallback_session_id,
-            rejected_event: request.rejected_event,
-          }),
-    },
-  };
-  const result = spawnSync(
-    'curl',
-    [
-      '--silent',
-      '--show-error',
-      '--connect-timeout',
-      PRODUCER_REGISTER_CURL_TIMEOUT_SECONDS,
-      '--max-time',
-      PRODUCER_REGISTER_CURL_TIMEOUT_SECONDS,
-      '--request',
-      'POST',
-      '--header',
-      'Content-Type: application/json',
-      '--data-binary',
-      '@-',
-      PRODUCER_REGISTER_URL,
-    ],
-    {
-      input: Buffer.from(JSON.stringify(wireRequest), 'utf8'),
-      encoding: 'utf8',
-      timeout: PRODUCER_REGISTER_PROCESS_TIMEOUT_MS,
-      maxBuffer: PRODUCER_REGISTER_MAX_RESPONSE_BYTES,
-      windowsHide: true,
-    }
-  );
-  if (result?.error) {
-    const code =
-      result.error.code === 'ETIMEDOUT'
-        ? 'PREVIEW_PHASE_PRODUCER_REGISTRATION_ACK_UNKNOWN'
-        : 'PREVIEW_PHASE_PRODUCER_REGISTRATION_UNAVAILABLE';
-    throw producerRegistrationError(
-      code,
-      `preview phase producer registration transport failed: ${result.error.message}`,
-      result.error
-    );
-  }
-  if (result?.signal || result?.status === 28) {
-    throw producerRegistrationError(
-      'PREVIEW_PHASE_PRODUCER_REGISTRATION_ACK_UNKNOWN',
-      'preview phase producer registration acknowledgement timed out'
-    );
-  }
-  if (result?.status !== 0) {
-    throw producerRegistrationError(
-      'PREVIEW_PHASE_PRODUCER_REGISTRATION_UNAVAILABLE',
-      `preview phase producer registration transport exited ${String(result?.status)}`
-    );
-  }
-  let envelope;
-  try {
-    envelope = JSON.parse(result.stdout || '');
-  } catch (error) {
-    throw producerRegistrationError(
-      'PREVIEW_PHASE_PRODUCER_REGISTRATION_ACK_UNKNOWN',
-      'preview phase producer registration returned invalid JSON',
-      error
-    );
-  }
-  if (envelope?.success !== true || envelope?.data?.success !== true) {
-    const detail =
-      envelope?.data?.error || envelope?.error || envelope?.message || 'rejected';
-    const detailText = String(detail);
-    let code = 'PREVIEW_PHASE_PRODUCER_REGISTRATION_REJECTED';
-    if (detailText.includes('registration acknowledgement unknown')) {
-      code = 'PREVIEW_PHASE_PRODUCER_REGISTRATION_ACK_UNKNOWN';
-    } else if (detailText.includes('producer epoch already belongs')) {
-      code = 'PREVIEW_PHASE_PRODUCER_EPOCH_CONFLICT';
-    } else if (
-      detailText.includes('publish preview phase canonical registration') ||
-      detailText.includes('conflicts with canonical run')
-    ) {
-      code = 'PREVIEW_PHASE_RUN_CONFLICT';
-    }
-    throw producerRegistrationError(
-      code,
-      `preview phase producer registration rejected: ${detailText}`
-    );
-  }
-  let response;
-  try {
-    response = JSON.parse(envelope.data.output || '');
-  } catch (error) {
-    throw producerRegistrationError(
-      'PREVIEW_PHASE_PRODUCER_REGISTRATION_ACK_UNKNOWN',
-      'preview phase producer registration acknowledgement was invalid',
-      error
-    );
-  }
-  return validateProducerRegistrationResponse(response, request);
-}
-
-function readLinuxProcessStartTicks(fileSystem, pid) {
-  try {
-    const stat = fileSystem.readFileSync(`/proc/${pid}/stat`, 'utf8');
-    // comm (field 2) may contain spaces or parentheses, so split only after
-    // its final closing parenthesis. The remaining first field is state (3),
-    // therefore starttime (22) is at index 19.
-    const commEnd = stat.lastIndexOf(')');
-    if (commEnd < 0) return null;
-    const fields = stat
-      .slice(commEnd + 1)
-      .trim()
-      .split(/\s+/);
-    const startTicks = fields[19];
-    return PROCESS_START_TICKS_PATTERN.test(startTicks || '')
-      ? startTicks
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function assertSafeDirectory(fileSystem, directoryPath) {
-  if (!fileSystem.existsSync(directoryPath)) {
-    fileSystem.mkdirSync(directoryPath, { recursive: true, mode: 0o700 });
-  }
-  const stat = fileSystem.lstatSync(directoryPath);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) {
-    throw new Error(`unsafe preview phase outbox path: ${directoryPath}`);
-  }
-  fileSystem.chmodSync(directoryPath, 0o700);
-}
-
-// Canonical generations are published only by the staging-directory rename.
-// Every later lookup must be existing-only: recreating a path that the
-// controller just quarantined would hide the durable generation and could
-// manufacture a second, unrelated canonical lifecycle.
-function assertExistingSafeDirectory(fileSystem, directoryPath) {
-  const stat = fileSystem.lstatSync(directoryPath);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) {
-    throw new Error(`unsafe preview phase outbox path: ${directoryPath}`);
-  }
-  fileSystem.chmodSync(directoryPath, 0o700);
-}
-
-function createFallbackSessionID(randomUUID = require('crypto').randomUUID) {
-  const sessionID = `pfs_${String(randomUUID())
-    .replaceAll('-', '')
-    .toLowerCase()}`;
-  if (!FALLBACK_SESSION_ID_PATTERN.test(sessionID)) {
-    throw new Error('invalid preview phase fallback session UUID');
-  }
-  return sessionID;
-}
-
-function createPreviewPhaseOutbox(options) {
-  const fileSystem = options.fs || fs;
-  const root = options.root || DEFAULT_OUTBOX_ROOT;
-  const randomUUID = options.random_uuid || require('crypto').randomUUID;
-  const now = options.now || Date.now;
-  const writerInstanceID = options.writer_instance_id || randomUUID();
-  const producerInstanceID = options.producer_instance_id || writerInstanceID;
-  const fallbackSessionID =
-    options.fallback_session_id || createFallbackSessionID();
-  const producerEpoch = options.producer_epoch;
-  const expectedInstanceID = options.expected_instance_id;
-  const registerProducer =
-    options.register_producer ||
-    (request =>
-      registerPreviewPhaseProducerViaShellServer(
-        request,
-        options.spawn_sync || nodeSpawnSync
-      ));
-  const getProcessStartTicks =
-    options.get_process_start_ticks ||
-    (pid => readLinuxProcessStartTicks(fileSystem, pid));
-  const configuredProcessStartTicks = options.process_start_ticks;
-  const currentProcessStartTicks =
-    configuredProcessStartTicks == null
-      ? getProcessStartTicks(process.pid)
-      : configuredProcessStartTicks;
-  const maxRunBytes = options.max_run_bytes ?? DEFAULT_MAX_RUN_BYTES;
-  const maxRootBytes = options.max_root_bytes ?? DEFAULT_MAX_ROOT_BYTES;
-  const maxRootDirectories =
-    options.max_root_directories ?? DEFAULT_MAX_ROOT_DIRECTORIES;
-  const maxRootScanDirectories =
-    options.max_root_scan_directories ?? DEFAULT_MAX_ROOT_SCAN_DIRECTORIES;
-  const maxRunScanEntries =
-    options.max_run_scan_entries ?? DEFAULT_MAX_RUN_SCAN_ENTRIES;
-  const maxFallbackFiles =
-    options.max_fallback_files ??
-    Math.min(DEFAULT_MAX_FALLBACK_FILES, maxRunScanEntries);
-  const maxFallbackBytes =
-    options.max_fallback_bytes ?? DEFAULT_MAX_FALLBACK_BYTES;
-  const maxFallbackEvents =
-    options.max_fallback_events ?? DEFAULT_MAX_FALLBACK_EVENTS;
-  const maxFallbackRecordBytes =
-    options.max_fallback_record_bytes ?? MAX_FALLBACK_RECORD_BYTES;
-  if (!RUN_ID_PATTERN.test(options.run_id || '')) {
-    throw new Error('invalid preview run_id for phase outbox');
-  }
-  if (!PRODUCER_EPOCH_PATTERN.test(producerEpoch || '')) {
-    throw new Error('invalid preview phase producer_epoch');
-  }
-  if (!INSTANCE_ID_PATTERN.test(expectedInstanceID || '')) {
-    throw new Error('invalid preview phase expected_instance_id');
-  }
-  if (typeof registerProducer !== 'function') {
-    throw new Error('invalid preview phase producer registrar');
-  }
-  if (!STATE_ID_PATTERN.test(writerInstanceID)) {
-    throw new Error('invalid preview phase writer_instance_id');
-  }
-  if (!STATE_ID_PATTERN.test(producerInstanceID)) {
-    throw new Error('invalid preview phase producer_instance_id');
-  }
-  if (!FALLBACK_SESSION_ID_PATTERN.test(fallbackSessionID)) {
-    throw new Error('invalid preview phase fallback_session_id');
-  }
-  if (!PROCESS_START_TICKS_PATTERN.test(currentProcessStartTicks || '')) {
-    throw new Error('invalid preview phase process_start_ticks');
-  }
-  if (!Number.isSafeInteger(maxRunBytes) || maxRunBytes <= 0) {
-    throw new Error('invalid preview phase max_run_bytes');
-  }
-  if (!Number.isSafeInteger(maxRootBytes) || maxRootBytes <= 0) {
-    throw new Error('invalid preview phase max_root_bytes');
-  }
-  if (!Number.isSafeInteger(maxRootDirectories) || maxRootDirectories <= 0) {
-    throw new Error('invalid preview phase max_root_directories');
-  }
-  if (
-    !Number.isSafeInteger(maxRootScanDirectories) ||
-    maxRootScanDirectories < maxRootDirectories
-  ) {
-    throw new Error('invalid preview phase max_root_scan_directories');
-  }
-  if (!Number.isSafeInteger(maxRunScanEntries) || maxRunScanEntries <= 0) {
-    throw new Error('invalid preview phase max_run_scan_entries');
-  }
-  if (
-    !Number.isSafeInteger(maxFallbackFiles) ||
-    maxFallbackFiles <= 0 ||
-    maxFallbackFiles > maxRunScanEntries
-  ) {
-    throw new Error('invalid preview phase max_fallback_files');
-  }
-  if (!Number.isSafeInteger(maxFallbackBytes) || maxFallbackBytes <= 0) {
-    throw new Error('invalid preview phase max_fallback_bytes');
-  }
-  if (!Number.isSafeInteger(maxFallbackEvents) || maxFallbackEvents <= 0) {
-    throw new Error('invalid preview phase max_fallback_events');
-  }
-  if (
-    !Number.isSafeInteger(maxFallbackRecordBytes) ||
-    maxFallbackRecordBytes <= 0
-  ) {
-    throw new Error('invalid preview phase max_fallback_record_bytes');
-  }
-  const canonicalRunDir = path.join(root, options.run_id);
-  const stagingName = `.staging-${process.pid}-${writerInstanceID}`;
-  const stagingRunDir = path.join(root, stagingName);
-  let runDir = canonicalRunDir;
-  let eventsPath = path.join(runDir, 'events.jsonl');
-  let metaPath = path.join(runDir, 'meta.json');
-  let writerLockPath = path.join(runDir, 'writer.lock');
-  let sealPath = path.join(runDir, 'sealed.json');
-  let degradedPath = path.join(runDir, 'degraded.json');
-  let fallbackIntentPath = path.join(runDir, 'fallback.intent.json');
-  let quiesceRequestPath = path.join(runDir, 'quiesce.request.json');
-  let unboundFallbackPath = path.join(runDir, 'producer.unbound.json');
-  const fallbackSpoolPath = path.join(
-    canonicalRunDir,
-    `fallback-${fallbackSessionID}.jsonl`
-  );
-  const producerEpochMarkerPath = path.join(
-    root,
-    `producer-epoch-${producerEpoch}.json`
-  );
-  let recovered = false;
-  let metadata = null;
-  let writerLockOwned = false;
-  let writerLockDirectory = null;
-  let eventsFD = null;
-  let committedBytes = null;
-  let degraded = false;
-  let fallbackRequired = false;
-  let sealRequested = false;
-  let closed = false;
-  let closeResult = false;
-  let producerMarkerActive = false;
-  let producerMarkerTerminal = false;
-  let producerRegistrationDurable = false;
-  let producerRegistrationAttemptCount = 0;
-  let producerRegistrationLastError = null;
-  let producerStartedAtMs = null;
-  let producerTerminalAtMs = null;
-  let canonicalPublicationDurable = false;
-  let everOwnedCanonicalWriter = false;
-  let fallbackFD = null;
-  let fallbackBytes = 0;
-  let fallbackSeq = 0;
-  let fallbackStarted = false;
-  let fallbackSealed = false;
-  let fallbackFailed = false;
-  let fallbackCreatedAt = null;
-  function selectRunDirectory(directoryPath) {
-    if (runDir !== directoryPath) {
-      if (eventsFD != null) {
-        throw new Error(
-          'cannot switch preview phase directory with an open events fd'
-        );
-      }
-      metadata = null;
-      recovered = false;
-      committedBytes = null;
-    }
-    runDir = directoryPath;
-    eventsPath = path.join(runDir, 'events.jsonl');
-    metaPath = path.join(runDir, 'meta.json');
-    writerLockPath = path.join(runDir, 'writer.lock');
-    sealPath = path.join(runDir, 'sealed.json');
-    degradedPath = path.join(runDir, 'degraded.json');
-    fallbackIntentPath = path.join(runDir, 'fallback.intent.json');
-    quiesceRequestPath = path.join(runDir, 'quiesce.request.json');
-    unboundFallbackPath = path.join(runDir, 'producer.unbound.json');
-  }
-
-  function ownsSelectedWriterLock() {
-    return writerLockOwned && writerLockDirectory === runDir;
-  }
-
-  function isTransientFilesystemError(error) {
-    return TRANSIENT_ERRNO_CODES.has(error?.code);
-  }
-
-  function rootQuotaError(message) {
-    const error = new Error(message);
-    error.code = 'PREVIEW_PHASE_ROOT_QUOTA_EXCEEDED';
-    return error;
-  }
-
-  function readDirectoryEntriesBounded(directoryPath, limit, quotaMessage) {
-    const entries = [];
-    const directory = fileSystem.opendirSync(directoryPath);
-    try {
-      while (entries.length <= limit) {
-        const entry = directory.readSync();
-        if (!entry) break;
-        entries.push(entry);
-        if (entries.length > limit) {
-          throw rootQuotaError(quotaMessage);
-        }
-      }
-    } finally {
-      directory.closeSync();
-    }
-    return entries;
-  }
-
-  function inspectRootUsage() {
-    const entries = readDirectoryEntriesBounded(
-      root,
-      maxRootScanDirectories,
-      `preview phase root scan exceeds ${maxRootScanDirectories} entries`
-    );
-    let directories = 0;
-    let bytes = 0;
-    const disappearingEntry = error =>
-      error?.code === 'ENOENT' || error?.code === 'ENOTDIR';
-    for (const entry of entries) {
-      const entryPath = path.join(root, entry.name);
-      let stat;
-      try {
-        stat = fileSystem.lstatSync(entryPath);
-      } catch (error) {
-        // The Go consumer atomically renames and removes acknowledged runs.
-        // A root snapshot can therefore contain an entry that is gone by the
-        // following lstat; disappearance is successful GC, not degradation.
-        if (disappearingEntry(error)) continue;
-        throw error;
-      }
-      if (stat.isSymbolicLink()) {
-        throw new Error(`unsafe preview phase outbox path: ${entryPath}`);
-      }
-      if (stat.isFile()) {
-        bytes += stat.size;
-        continue;
-      }
-      if (!stat.isDirectory()) {
-        throw new Error(`unsafe preview phase outbox path: ${entryPath}`);
-      }
-      directories += 1;
-      let runEntries;
-      try {
-        runEntries = readDirectoryEntriesBounded(
-          entryPath,
-          maxRunScanEntries,
-          `preview phase run scan exceeds ${maxRunScanEntries} entries: ${entryPath}`
-        );
-      } catch (error) {
-        if (disappearingEntry(error)) continue;
-        throw error;
-      }
-      for (const runEntry of runEntries) {
-        const statePath = path.join(entryPath, runEntry.name);
-        let stateStat;
-        try {
-          stateStat = fileSystem.lstatSync(statePath);
-        } catch (error) {
-          if (disappearingEntry(error)) continue;
-          throw error;
-        }
-        if (stateStat.isSymbolicLink() || !stateStat.isFile()) {
-          throw new Error(`unsafe preview phase outbox path: ${statePath}`);
-        }
-        bytes += stateStat.size;
-      }
-    }
-    return { bytes, directories };
-  }
-
-  function assertRootDirectoryQuota() {
-    const usage = inspectRootUsage();
-    if (
-      !fileSystem.existsSync(runDir) &&
-      usage.directories >= maxRootDirectories
-    ) {
-      throw rootQuotaError(
-        `preview phase root directory quota reached ${maxRootDirectories}`
-      );
-    }
-  }
-
-  function assertRootByteQuota(recordBytes) {
-    const usage = inspectRootUsage();
-    if (usage.bytes + recordBytes > maxRootBytes) {
-      throw rootQuotaError(
-        `preview phase root quota would exceed ${maxRootBytes} bytes`
-      );
-    }
-  }
-
-  function readRegularJSON(filePath, description) {
-    const stat = fileSystem.lstatSync(filePath);
-    if (!stat.isFile() || stat.isSymbolicLink()) {
-      throw new Error(`unsafe preview phase outbox path: ${filePath}`);
-    }
-    const value = JSON.parse(fileSystem.readFileSync(filePath, 'utf8'));
-    if (!value || typeof value !== 'object') {
-      throw new Error(`invalid preview phase ${description}: ${filePath}`);
-    }
-    return value;
-  }
-
-  function syncDirectory(directoryPath) {
-    const flags =
-      fs.constants.O_RDONLY |
-      (fs.constants.O_DIRECTORY || 0) |
-      (fs.constants.O_NOFOLLOW || 0);
-    const fd = fileSystem.openSync(directoryPath, flags);
-    try {
-      fileSystem.fsyncSync(fd);
-    } finally {
-      fileSystem.closeSync(fd);
-    }
-  }
-
-  function syncRunDirectory() {
-    syncDirectory(runDir);
-  }
-
-  function syncRootDirectory() {
-    const flags =
-      fs.constants.O_RDONLY |
-      (fs.constants.O_DIRECTORY || 0) |
-      (fs.constants.O_NOFOLLOW || 0);
-    const fd = fileSystem.openSync(root, flags);
-    try {
-      fileSystem.fsyncSync(fd);
-    } finally {
-      fileSystem.closeSync(fd);
-    }
-  }
-
-  function writeAll(fd, payload) {
-    let offset = 0;
-    while (offset < payload.length) {
-      const written = fileSystem.writeSync(
-        fd,
-        payload,
-        offset,
-        payload.length - offset
-      );
-      if (!Number.isInteger(written) || written <= 0) {
-        throw new Error('preview phase state write made no progress');
-      }
-      offset += written;
-    }
-  }
-
-  function writeDurableTempFile(tempPath, payload) {
-    let fd = null;
-    try {
-      const flags =
-        fs.constants.O_CREAT |
-        fs.constants.O_EXCL |
-        fs.constants.O_WRONLY |
-        (fs.constants.O_NOFOLLOW || 0);
-      fd = fileSystem.openSync(tempPath, flags, 0o600);
-      writeAll(fd, payload);
-      fileSystem.fsyncSync(fd);
-    } finally {
-      if (fd != null) {
-        fileSystem.closeSync(fd);
-      }
-    }
-  }
-
-  function publishImmutableState(filePath, label, value) {
-    const tempPath = path.join(
-      runDir,
-      `.${label}.${process.pid}.${writerInstanceID}.tmp`
-    );
-    let fd = null;
-    try {
-      const flags =
-        fs.constants.O_CREAT |
-        fs.constants.O_EXCL |
-        fs.constants.O_WRONLY |
-        (fs.constants.O_NOFOLLOW || 0);
-      fd = fileSystem.openSync(tempPath, flags, 0o600);
-      writeAll(fd, Buffer.from(`${JSON.stringify(value)}\n`, 'utf8'));
-      fileSystem.fsyncSync(fd);
-      fileSystem.closeSync(fd);
-      fd = null;
-      fileSystem.linkSync(tempPath, filePath);
-      syncRunDirectory();
-    } finally {
-      if (fd != null) {
-        try {
-          fileSystem.closeSync(fd);
-        } catch {
-          // Best-effort fd cleanup.
-        }
-      }
-      try {
-        fileSystem.rmSync(tempPath, { force: true });
-      } catch {
-        // A stale temp file is harmless and never consumed by the reader.
-      }
-    }
-  }
-
-  function producerMarkerConflict() {
-    const error = new Error(
-      `preview phase producer epoch already belongs to another writer: ${producerEpoch}`
-    );
-    error.code = 'PREVIEW_PHASE_PRODUCER_EPOCH_CONFLICT';
-    return error;
-  }
-
-  function validateProducerMarker(marker) {
-    const terminal = marker?.state === 'terminal';
-    if (
-      marker?.protocol !== 'preview-phase-producer-epoch-v1' ||
-      marker.schema_version !== 1 ||
-      marker.epoch !== producerEpoch ||
-      !RUN_ID_PATTERN.test(marker.run_id || '') ||
-      !STATE_ID_PATTERN.test(marker.generation || '') ||
-      !STATE_ID_PATTERN.test(marker.writer_instance_id || '') ||
-      !Number.isSafeInteger(marker.pid) ||
-      marker.pid <= 0 ||
-      !PROCESS_START_TICKS_PATTERN.test(marker.process_start_ticks || '') ||
-      !Number.isFinite(marker.started_at_ms) ||
-      marker.started_at_ms <= 0 ||
-      (marker.state !== 'active' && !terminal) ||
-      (terminal &&
-        (!Number.isFinite(marker.terminal_at_ms) ||
-          marker.terminal_at_ms < marker.started_at_ms)) ||
-      (!terminal && marker.terminal_at_ms !== undefined)
-    ) {
-      throw new Error(
-        `invalid preview phase producer epoch marker: ${producerEpochMarkerPath}`
-      );
-    }
-    return marker;
-  }
-
-  function markerBelongsToThisWriter(marker) {
-    return (
-      marker.epoch === producerEpoch &&
-      marker.run_id === options.run_id &&
-      marker.generation === metadata.generation &&
-      marker.writer_instance_id === writerInstanceID &&
-      marker.pid === process.pid &&
-      (marker.process_start_ticks || '') === (currentProcessStartTicks || '')
-    );
-  }
-
-  function readAndValidateProducerMarker() {
-    return validateProducerMarker(
-      readRegularJSON(producerEpochMarkerPath, 'producer epoch marker')
-    );
-  }
-
-  function buildProducerMarker(state) {
-    return {
-      protocol: 'preview-phase-producer-epoch-v1',
-      schema_version: 1,
-      epoch: producerEpoch,
-      run_id: options.run_id,
-      generation: metadata.generation,
-      writer_instance_id: writerInstanceID,
-      pid: process.pid,
-      process_start_ticks: currentProcessStartTicks,
-      started_at_ms: producerStartedAtMs,
-      state,
-      ...(state === 'terminal' ? { terminal_at_ms: producerTerminalAtMs } : {}),
-    };
-  }
-
-  function publishActiveProducerMarker() {
-    if (producerMarkerActive) return;
-    if (
-      !producerRegistrationDurable ||
-      !metadata ||
-      !ownsSelectedWriterLock()
-    ) {
-      throw new Error(
-        'preview phase producer marker requires authoritative registration'
-      );
-    }
-    const existing = readAndValidateProducerMarker();
-    if (!markerBelongsToThisWriter(existing) || existing.state !== 'active') {
-      throw producerMarkerConflict();
-    }
-    producerStartedAtMs = existing.started_at_ms;
-    producerMarkerActive = true;
-  }
-
-  function publishTerminalProducerMarker() {
-    if (producerMarkerTerminal) return;
-    const existing = readAndValidateProducerMarker();
-    if (!markerBelongsToThisWriter(existing)) {
-      throw producerMarkerConflict();
-    }
-    producerStartedAtMs = existing.started_at_ms;
-    if (existing.state === 'terminal') {
-      producerTerminalAtMs = existing.terminal_at_ms;
-      producerMarkerActive = true;
-      producerMarkerTerminal = true;
-      return;
-    }
-    producerTerminalAtMs =
-      producerTerminalAtMs ?? Math.max(now(), producerStartedAtMs);
-    const marker = buildProducerMarker('terminal');
-    const tempPath = path.join(
-      root,
-      `.producer-terminal.${producerEpoch}.${process.pid}.${writerInstanceID}.tmp`
-    );
-    let fd = null;
-    try {
-      const flags =
-        fs.constants.O_CREAT |
-        fs.constants.O_EXCL |
-        fs.constants.O_WRONLY |
-        (fs.constants.O_NOFOLLOW || 0);
-      fd = fileSystem.openSync(tempPath, flags, 0o600);
-      writeAll(fd, Buffer.from(`${JSON.stringify(marker)}\n`, 'utf8'));
-      fileSystem.fsyncSync(fd);
-      fileSystem.closeSync(fd);
-      fd = null;
-      fileSystem.renameSync(tempPath, producerEpochMarkerPath);
-      syncRootDirectory();
-      producerMarkerActive = true;
-      producerMarkerTerminal = true;
-    } finally {
-      if (fd != null) {
-        try {
-          fileSystem.closeSync(fd);
-        } catch {
-          // Best-effort fd cleanup.
-        }
-      }
-      let tempRemoved = false;
-      try {
-        fileSystem.rmSync(tempPath, { force: true });
-        tempRemoved = true;
-      } catch {
-        // A stale temp file is never accepted as lifecycle proof.
-      }
-      if (tempRemoved) syncRootDirectory();
-    }
-  }
-
-  function readAndValidateMetadataAt(directoryPath) {
-    const candidateMetaPath = path.join(directoryPath, 'meta.json');
-    const stat = fileSystem.lstatSync(candidateMetaPath);
-    if (!stat.isFile() || stat.isSymbolicLink()) {
-      throw new Error(`unsafe preview phase outbox path: ${candidateMetaPath}`);
-    }
-    fileSystem.chmodSync(candidateMetaPath, 0o600);
-    const metadata = JSON.parse(
-      fileSystem.readFileSync(candidateMetaPath, 'utf8')
-    );
-    if (
-      metadata.protocol !== 'preview-phase-outbox-v1' ||
-      metadata.schema_version !== 1 ||
-      metadata.producer_epoch !== producerEpoch ||
-      metadata.run_id !== options.run_id ||
-      !/^[A-Za-z0-9_-]{1,128}$/.test(metadata.generation || '') ||
-      !Number.isFinite(metadata.created_at_ms) ||
-      metadata.created_at_ms <= 0 ||
-      (metadata.quiesce_supported !== undefined &&
-        metadata.quiesce_supported !== true)
-    ) {
-      throw new Error(
-        `invalid preview phase outbox metadata: ${candidateMetaPath}`
-      );
-    }
-    return metadata;
-  }
-
-  function readAndValidateMetadata() {
-    return readAndValidateMetadataAt(runDir);
-  }
-
-  function ensureMetadata() {
-    if (metadata) return;
-    if (fileSystem.existsSync(metaPath)) {
-      metadata = readAndValidateMetadata();
-      return;
-    }
-    const candidate = {
-      protocol: 'preview-phase-outbox-v1',
-      schema_version: 1,
-      producer_epoch: producerEpoch,
-      generation: randomUUID(),
-      run_id: options.run_id,
-      created_at_ms: now(),
-      quiesce_supported: true,
-    };
-    const tempPath = path.join(
-      runDir,
-      `.meta.${process.pid}.${candidate.generation}.tmp`
-    );
-    try {
-      writeDurableTempFile(
-        tempPath,
-        Buffer.from(`${JSON.stringify(candidate)}\n`, 'utf8')
-      );
-      try {
-        fileSystem.linkSync(tempPath, metaPath);
-        syncRunDirectory();
-      } catch (error) {
-        if (error?.code !== 'EEXIST') throw error;
-      }
-    } finally {
-      let removed = false;
-      try {
-        fileSystem.rmSync(tempPath, { force: true });
-        removed = true;
-      } catch {
-        // A stale temp file is harmless and never consumed by the reader.
-      }
-      if (removed) syncRunDirectory();
-    }
-    metadata = readAndValidateMetadata();
-  }
-
-  function validateFallbackIntent(intent, canonicalMetadata) {
-    if (
-      intent.protocol !== 'preview-phase-fallback-intent-v1' ||
-      intent.schema_version !== 1 ||
-      intent.producer_epoch !== producerEpoch ||
-      intent.run_id !== options.run_id ||
-      intent.generation !== canonicalMetadata.generation ||
-      !Number.isFinite(intent.created_at_ms) ||
-      intent.created_at_ms <= 0 ||
-      !STATE_ID_PATTERN.test(intent.reason || '')
-    ) {
-      throw new Error(
-        `invalid preview phase fallback intent: ${path.join(
-          canonicalRunDir,
-          'fallback.intent.json'
-        )}`
-      );
-    }
-    return intent;
-  }
-
-  function fallbackSpoolError(code, message, cause) {
-    const error = new Error(message, cause == null ? undefined : { cause });
-    error.code = code;
-    return error;
-  }
-
-  function encodeFallbackRecord(record, description) {
-    const payload = JSON.stringify(record);
-    if (typeof payload !== 'string') {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_RECORD_INVALID',
-        `invalid preview phase fallback ${description}`
-      );
-    }
-    const encoded = Buffer.from(`${payload}\n`, 'utf8');
-    if (encoded.length > maxFallbackRecordBytes) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_RECORD_TOO_LARGE',
-        `preview phase fallback ${description} exceeds ${maxFallbackRecordBytes} bytes`
-      );
-    }
-    return encoded;
-  }
-
-  function fallbackTimestamp() {
-    const timestamp = now();
-    if (!Number.isFinite(timestamp) || timestamp <= 0) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_TIMESTAMP_INVALID',
-        'invalid preview phase fallback timestamp'
-      );
-    }
-    return timestamp;
-  }
-
-  function closeFallbackFD() {
-    if (fallbackFD == null) return;
-    try {
-      fileSystem.closeSync(fallbackFD);
-    } catch {
-      // The durable boundary is fdatasync, not close. Never reuse this fd.
-    }
-    fallbackFD = null;
-  }
-
-  function ensureFallbackSpool(initialEventBytes) {
-    if (fallbackFD != null) return;
-    if (fallbackSealed) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_SEALED',
-        'preview phase fallback spool is sealed'
-      );
-    }
-    if (fallbackFailed) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_DEGRADED',
-        'preview phase fallback spool is degraded'
-      );
-    }
-
-    assertSafeDirectory(fileSystem, root);
-    assertExistingSafeDirectory(fileSystem, canonicalRunDir);
-    const parentMetadata = readAndValidateMetadataAt(canonicalRunDir);
-    const entries = readDirectoryEntriesBounded(
-      canonicalRunDir,
-      maxRunScanEntries,
-      `preview phase run scan exceeds ${maxRunScanEntries} entries: ${canonicalRunDir}`
-    );
-    const fallbackFiles = entries.filter(entry =>
-      /^fallback-pfs_[a-f0-9]{32}\.jsonl$/.test(entry.name)
-    );
-    if (fallbackFiles.length >= maxFallbackFiles) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_FILE_LIMIT',
-        `preview phase fallback file limit reached ${maxFallbackFiles}`
-      );
-    }
-    if (fileSystem.existsSync(fallbackSpoolPath)) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_SESSION_CONFLICT',
-        `preview phase fallback session already exists: ${fallbackSessionID}`
-      );
-    }
-
-    const createdAt = fallbackTimestamp();
-    const metaRecord = encodeFallbackRecord(
-      {
-        protocol: 'preview-phase-fallback-spool-v1',
-        schema_version: 1,
-        record_type: 'meta',
-        session_id: fallbackSessionID,
-        producer_epoch: producerEpoch,
-        run_id: options.run_id,
-        parent_generation: parentMetadata.generation,
-        producer_instance_id: producerInstanceID,
-        pid: process.pid,
-        process_start_ticks: currentProcessStartTicks,
-        // Protocol timestamps use Unix epoch milliseconds. The compact field
-        // name is retained because this is a versioned wire contract.
-        created_at: createdAt,
-      },
-      'meta record'
-    );
-    if (
-      metaRecord.length + initialEventBytes + FALLBACK_TERMINAL_RESERVE_BYTES >
-      maxFallbackBytes
-    ) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_FILE_QUOTA_EXCEEDED',
-        `preview phase fallback file quota would exceed ${maxFallbackBytes} bytes`
-      );
-    }
-    assertRootByteQuota(
-      metaRecord.length + initialEventBytes + FALLBACK_TERMINAL_RESERVE_BYTES
-    );
-
-    const tempPath = path.join(
-      canonicalRunDir,
-      `.fallback-${fallbackSessionID}.${process.pid}.${writerInstanceID}.tmp`
-    );
-    const directoryFlags =
-      fs.constants.O_RDONLY |
-      (fs.constants.O_DIRECTORY || 0) |
-      (fs.constants.O_NOFOLLOW || 0);
-    let directoryFD = null;
-    let fd = null;
-    let published = false;
-    try {
-      directoryFD = fileSystem.openSync(canonicalRunDir, directoryFlags);
-      const fileFlags =
-        fs.constants.O_CREAT |
-        fs.constants.O_EXCL |
-        fs.constants.O_WRONLY |
-        fs.constants.O_APPEND |
-        (fs.constants.O_NOFOLLOW || 0);
-      fd = fileSystem.openSync(tempPath, fileFlags, 0o600);
-      fileSystem.fchmodSync(fd, 0o600);
-      writeAll(fd, metaRecord);
-      fileSystem.fsyncSync(fd);
-      try {
-        fileSystem.linkSync(tempPath, fallbackSpoolPath);
-      } catch (error) {
-        if (error?.code === 'EEXIST') {
-          throw fallbackSpoolError(
-            'PREVIEW_PHASE_FALLBACK_SESSION_CONFLICT',
-            `preview phase fallback session already exists: ${fallbackSessionID}`,
-            error
-          );
-        }
-        throw error;
-      }
-      // Sync the already-open directory, so quarantine rename after link does
-      // not invalidate the durability proof for the published file name.
-      fileSystem.fsyncSync(directoryFD);
-      published = true;
-      try {
-        fileSystem.rmSync(tempPath);
-        fileSystem.fsyncSync(directoryFD);
-      } catch {
-        // A quarantine rename can make the old path unreachable. The hidden
-        // hard-link alias is harmless; the published session remains bounded.
-      }
-      fallbackFD = fd;
-      fd = null;
-      fallbackBytes = metaRecord.length;
-      fallbackStarted = true;
-      fallbackCreatedAt = createdAt;
-    } catch (error) {
-      fallbackFailed = true;
-      throw error;
-    } finally {
-      if (fd != null) {
-        try {
-          fileSystem.closeSync(fd);
-        } catch {
-          // Best-effort fd cleanup.
-        }
-      }
-      if (!published) {
-        try {
-          fileSystem.rmSync(tempPath, { force: true });
-          if (directoryFD != null) fileSystem.fsyncSync(directoryFD);
-        } catch {
-          // Best-effort temp cleanup after a failed publication.
-        }
-      }
-      if (directoryFD != null) {
-        try {
-          fileSystem.closeSync(directoryFD);
-        } catch {
-          // Best-effort directory-fd cleanup.
-        }
-      }
-    }
-  }
-
-  function appendFallback(event) {
-    if (fallbackSealed) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_SEALED',
-        'preview phase fallback spool is sealed'
-      );
-    }
-    if (fallbackFailed) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_DEGRADED',
-        'preview phase fallback spool is degraded'
-      );
-    }
-    if (!event || typeof event !== 'object' || Array.isArray(event)) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_RECORD_INVALID',
-        'invalid preview phase fallback event'
-      );
-    }
-    if (fallbackSeq >= maxFallbackEvents) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_EVENT_LIMIT',
-        `preview phase fallback event limit reached ${maxFallbackEvents}`
-      );
-    }
-    const nextSeq = fallbackSeq + 1;
-    const fallbackEvent = {
-      ...event,
-      transport: 'fallback_spool',
-      fallback_session_id: fallbackSessionID,
-      fallback_seq: nextSeq,
-    };
-    const eventPayload = JSON.stringify(fallbackEvent);
-    if (
-      typeof eventPayload !== 'string' ||
-      Buffer.byteLength(eventPayload, 'utf8') > MAX_EVENT_BYTES
-    ) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_EVENT_TOO_LARGE',
-        `preview phase event exceeds ${MAX_EVENT_BYTES} bytes`
-      );
-    }
-    const record = encodeFallbackRecord(
-      {
-        protocol: 'preview-phase-fallback-spool-v1',
-        schema_version: 1,
-        record_type: 'event',
-        session_id: fallbackSessionID,
-        seq: nextSeq,
-        event: fallbackEvent,
-      },
-      'event record'
-    );
-
-    ensureFallbackSpool(record.length);
-    if (
-      fallbackBytes + record.length + FALLBACK_TERMINAL_RESERVE_BYTES >
-      maxFallbackBytes
-    ) {
-      throw fallbackSpoolError(
-        'PREVIEW_PHASE_FALLBACK_FILE_QUOTA_EXCEEDED',
-        `preview phase fallback file quota would exceed ${maxFallbackBytes} bytes`
-      );
-    }
-    try {
-      writeAll(fallbackFD, record);
-      fileSystem.fdatasyncSync(fallbackFD);
-      fallbackBytes += record.length;
-      fallbackSeq = nextSeq;
-      fallbackRequired = true;
-      return true;
-    } catch (error) {
-      fallbackFailed = true;
-      closeFallbackFD();
-      throw error;
-    }
-  }
-
-  function sealFallback() {
-    if (!fallbackStarted) return !fallbackFailed;
-    if (fallbackSealed) return true;
-    if (fallbackFailed || fallbackFD == null) return false;
-    const terminal = encodeFallbackRecord(
-      {
-        protocol: 'preview-phase-fallback-spool-v1',
-        schema_version: 1,
-        record_type: 'terminal',
-        session_id: fallbackSessionID,
-        final_cursor: fallbackBytes,
-        final_seq: fallbackSeq,
-        // Unix epoch milliseconds; never precedes this session's meta record.
-        sealed_at: Math.max(fallbackTimestamp(), fallbackCreatedAt),
-        recovered: false,
-      },
-      'terminal record'
-    );
-    if (fallbackBytes + terminal.length > maxFallbackBytes) {
-      fallbackFailed = true;
-      closeFallbackFD();
-      return false;
-    }
-    try {
-      writeAll(fallbackFD, terminal);
-      fileSystem.fdatasyncSync(fallbackFD);
-      fallbackBytes += terminal.length;
-      fallbackSealed = true;
-      closeFallbackFD();
-      return true;
-    } catch {
-      fallbackFailed = true;
-      closeFallbackFD();
-      return false;
-    }
-  }
-
-  function validateProcessIdentityState(state, description) {
-    if (
-      !Number.isSafeInteger(state.pid) ||
-      state.pid <= 0 ||
-      (state.process_start_ticks !== undefined &&
-        !PROCESS_START_TICKS_PATTERN.test(state.process_start_ticks))
-    ) {
-      throw new Error(`invalid preview phase ${description}`);
-    }
-  }
-
-  function validateWriterLock(lock) {
-    assertStateGeneration(lock, 'writer lock');
-    validateProcessIdentityState(lock, 'writer lock');
-    if (
-      lock.protocol !== 'preview-phase-writer-v1' ||
-      lock.schema_version !== 1 ||
-      !STATE_ID_PATTERN.test(lock.writer_instance_id || '') ||
-      !Number.isFinite(lock.created_at_ms) ||
-      lock.created_at_ms <= 0
-    ) {
-      throw new Error(`invalid preview phase writer lock: ${writerLockPath}`);
-    }
-    return lock;
-  }
-
-  function writerBusyError() {
-    const busy = new Error(
-      `preview phase generation already has an active writer: ${options.run_id}`
-    );
-    busy.code = 'PREVIEW_PHASE_WRITER_BUSY';
-    return busy;
-  }
-
-  function runConflictError(cause) {
-    const conflict = new Error(
-      `preview phase canonical run was published by another writer: ${options.run_id}`,
-      { cause }
-    );
-    conflict.code = 'PREVIEW_PHASE_RUN_CONFLICT';
-    return conflict;
-  }
-
-  function acquireWriterLock() {
-    if (ownsSelectedWriterLock()) return;
-    if (writerLockOwned) {
-      throw new Error(
-        'preview phase writer ownership belongs to another directory'
-      );
-    }
-    const lock = {
-      protocol: 'preview-phase-writer-v1',
-      schema_version: 1,
-      run_id: options.run_id,
-      generation: metadata.generation,
-      writer_instance_id: writerInstanceID,
-      pid: process.pid,
-      ...(currentProcessStartTicks == null
-        ? {}
-        : { process_start_ticks: currentProcessStartTicks }),
-      created_at_ms: now(),
-    };
-    const tempPath = path.join(
-      runDir,
-      `.writer.${process.pid}.${writerInstanceID}.tmp`
-    );
-    try {
-      writeDurableTempFile(
-        tempPath,
-        Buffer.from(`${JSON.stringify(lock)}\n`, 'utf8')
-      );
-      try {
-        fileSystem.linkSync(tempPath, writerLockPath);
-        writerLockOwned = true;
-        writerLockDirectory = runDir;
-        if (runDir === canonicalRunDir) everOwnedCanonicalWriter = true;
-        syncRunDirectory();
-      } catch (error) {
-        if (error?.code !== 'EEXIST') throw error;
-        // Producers never delete or replace a lock they did not publish. Only
-        // the shell-server can prove owner death and finalize the generation;
-        // this removes path-ABA races between concurrent JS successors.
-        validateWriterLock(readRegularJSON(writerLockPath, 'writer lock'));
-        throw writerBusyError();
-      }
-    } finally {
-      let removed = false;
-      try {
-        fileSystem.rmSync(tempPath, { force: true });
-        removed = true;
-      } catch {
-        // A stale temp file is harmless and never consumed by the reader.
-      }
-      if (removed) syncRunDirectory();
-    }
-  }
-
-  function ensureEmptyEventsFile() {
-    if (fileSystem.existsSync(eventsPath)) {
-      const stat = fileSystem.lstatSync(eventsPath);
-      if (!stat.isFile() || stat.isSymbolicLink()) {
-        throw new Error(`unsafe preview phase outbox path: ${eventsPath}`);
-      }
-      return;
-    }
-    const flags =
-      fs.constants.O_CREAT |
-      fs.constants.O_EXCL |
-      fs.constants.O_RDWR |
-      (fs.constants.O_NOFOLLOW || 0);
-    const fd = fileSystem.openSync(eventsPath, flags, 0o600);
-    try {
-      fileSystem.fchmodSync(fd, 0o600);
-      fileSystem.fdatasyncSync(fd);
-    } finally {
-      fileSystem.closeSync(fd);
-    }
-    syncRunDirectory();
-  }
-
-  function validateOwnedWriterLock() {
-    const lock = validateWriterLock(
-      readRegularJSON(writerLockPath, 'writer lock')
-    );
-    if (
-      lock.writer_instance_id !== writerInstanceID ||
-      lock.pid !== process.pid ||
-      (lock.process_start_ticks || '') !== (currentProcessStartTicks || '')
-    ) {
-      throw writerBusyError();
-    }
-    writerLockOwned = true;
-    writerLockDirectory = runDir;
-  }
-
-  let stagingOwned = false;
-
-  function tryAdoptCanonicalWriter() {
-    const previousDirectory = runDir;
-    const previousWriterLockOwned = writerLockOwned;
-    const previousWriterLockDirectory = writerLockDirectory;
-    try {
-      selectRunDirectory(canonicalRunDir);
-      assertExistingSafeDirectory(fileSystem, canonicalRunDir);
-      metadata = readAndValidateMetadata();
-      writerLockOwned = false;
-      writerLockDirectory = null;
-      validateOwnedWriterLock();
-      stagingOwned = false;
-      everOwnedCanonicalWriter = true;
-      return true;
-    } catch {
-      selectRunDirectory(previousDirectory);
-      writerLockOwned = previousWriterLockOwned;
-      writerLockDirectory = previousWriterLockDirectory;
-      return false;
-    }
-  }
-
-  function ensureCanonicalPublicationDurable() {
-    if (canonicalPublicationDurable) return;
-    try {
-      syncRootDirectory();
-    } catch (firstError) {
-      // rename may have committed even when its first parent-directory fsync
-      // failed. Re-prove the exact writer identity, then retry that commit
-      // point before any event or producer marker can be published.
-      if (!tryAdoptCanonicalWriter()) throw firstError;
-      syncRootDirectory();
-    }
-    canonicalPublicationDurable = true;
-  }
-
-  function registerCanonicalWriter(rejectedEvent) {
-    if (producerRegistrationDurable) return;
-    producerStartedAtMs = producerStartedAtMs ?? now();
-    const rejectedEventForRegistration =
-      rejectedEvent?.schema_version === 1 &&
-      typeof rejectedEvent.event_id === 'string' &&
-      rejectedEvent.event_id.startsWith(`${options.run_id}:`) &&
-      rejectedEvent.run_id === options.run_id &&
-      PRODUCER_INSTANCE_ID_PATTERN.test(
-        rejectedEvent.producer_instance_id || ''
-      ) &&
-      rejectedEvent.producer_seq === 1 &&
-      rejectedEvent.transport === 'outbox'
-        ? rejectedEvent
-        : null;
-    const request = {
-      // root/staging_name/started_at_ms are local callback context only. The
-      // default registrar serializes the fixed protocol whitelist below and
-      // never sends a caller-controlled path to shell-server.
-      root,
-      staging_name: stagingName,
-      run_id: options.run_id,
-      generation: metadata.generation,
-      expected_instance_id: expectedInstanceID,
-      producer_epoch: producerEpoch,
-      writer_instance_id: writerInstanceID,
-      pid: process.pid,
-      process_start_ticks: currentProcessStartTicks,
-      started_at_ms: producerStartedAtMs,
-      ...(rejectedEventForRegistration == null
-        ? {}
-        : {
-            producer_instance_id:
-              rejectedEventForRegistration.producer_instance_id,
-            fallback_session_id: fallbackSessionID,
-            rejected_event: rejectedEventForRegistration,
-          }),
-    };
-    if (producerRegistrationAttemptCount >= PRODUCER_REGISTER_ATTEMPTS) {
-      throw producerRegistrationLastError;
-    }
-    while (producerRegistrationAttemptCount < PRODUCER_REGISTER_ATTEMPTS) {
-      producerRegistrationAttemptCount += 1;
-      try {
-        const response = validateProducerRegistrationResponse(
-          registerProducer(request),
-          request
-        );
-        if (response.registration_status === 'rejected') {
-          request.rejected_event.transport = 'fallback_spool';
-          request.rejected_event.fallback_session_id = fallbackSessionID;
-          request.rejected_event.fallback_seq = 1;
-          fallbackRequired = true;
-          fallbackSeq = 1;
-          fallbackSealed = true;
-          sealRequested = true;
-          closed = true;
-          closeResult = true;
-          writerLockOwned = false;
-          writerLockDirectory = null;
-          stagingOwned = false;
-          producerRegistrationDurable = true;
-          selectRunDirectory(canonicalRunDir);
-          return;
-        }
-        if (!tryAdoptCanonicalWriter()) {
-          throw producerRegistrationError(
-            'PREVIEW_PHASE_PRODUCER_REGISTRATION_ACK_UNKNOWN',
-            'authoritative registration did not publish the expected canonical writer'
-          );
-        }
-        // A successful authoritative response is issued only after the
-        // canonical rename and root-directory fsync. Re-fsyncing here would
-        // add latency without strengthening the controller's commit proof.
-        canonicalPublicationDurable = true;
-        const marker = readAndValidateProducerMarker();
-        if (!markerBelongsToThisWriter(marker) || marker.state !== 'active') {
-          throw producerRegistrationError(
-            'PREVIEW_PHASE_PRODUCER_REGISTRATION_ACK_UNKNOWN',
-            'authoritative registration did not publish the expected active marker'
-          );
-        }
-        producerStartedAtMs = marker.started_at_ms;
-        producerMarkerActive = true;
-        producerRegistrationDurable = true;
-        return;
-      } catch (error) {
-        producerRegistrationLastError = error;
-        if (
-          error?.code === 'PREVIEW_PHASE_PRODUCER_EPOCH_CONFLICT' &&
-          tryAdoptCanonicalWriter()
-        ) {
-          canonicalPublicationDurable = true;
-        }
-        if (
-          error?.code === 'PREVIEW_PHASE_PRODUCER_REGISTRATION_ACK_UNKNOWN' &&
-          producerRegistrationAttemptCount < PRODUCER_REGISTER_ATTEMPTS
-        ) {
-          continue;
-        }
-        throw error;
-      }
-    }
-    throw producerRegistrationLastError;
-  }
-
-  function ensureCanonicalWriter(rejectedEvent) {
-    if (producerRegistrationDurable && runDir === canonicalRunDir && metadata) {
-      ensureCanonicalPublicationDurable();
-      return;
-    }
-
-    if (!stagingOwned && fileSystem.existsSync(canonicalRunDir)) {
-      // Existing canonical state is controller-owned. A JS successor may
-      // inspect it to produce a precise fail-closed reason, but it must never
-      // acquire/remove its writer lock or republish it under a captured epoch.
-      selectRunDirectory(canonicalRunDir);
-      assertExistingSafeDirectory(fileSystem, canonicalRunDir);
-      metadata = readAndValidateMetadata();
-      if (fileSystem.existsSync(sealPath)) {
-        assertGenerationIsOpen();
-      }
-      if (fileSystem.existsSync(writerLockPath)) {
-        validateWriterLock(readRegularJSON(writerLockPath, 'writer lock'));
-        throw writerBusyError();
-      }
-      throw runConflictError();
-    }
-
-    selectRunDirectory(stagingRunDir);
-    if (!stagingOwned) {
-      fileSystem.mkdirSync(stagingRunDir, { mode: 0o700 });
-      stagingOwned = true;
-      syncRootDirectory();
-    }
-    assertSafeDirectory(fileSystem, stagingRunDir);
-    ensureMetadata();
-    if (!ownsSelectedWriterLock()) acquireWriterLock();
-    ensureEmptyEventsFile();
-    syncRunDirectory();
-    registerCanonicalWriter(rejectedEvent);
-  }
-
-  function assertStateGeneration(state, description) {
-    if (
-      state.run_id !== options.run_id ||
-      state.generation !== metadata.generation
-    ) {
-      const error = new Error(
-        `preview phase ${description} generation mismatch: ${options.run_id}`
-      );
-      error.code = 'PREVIEW_PHASE_GENERATION_MISMATCH';
-      throw error;
-    }
-  }
-
-  function assertGenerationIsOpen() {
-    if (!fileSystem.existsSync(sealPath)) return;
-    readAndValidateSeal();
-    const error = new Error(
-      `preview phase sealed generation cannot be reopened: ${options.run_id}`
-    );
-    error.code = 'PREVIEW_PHASE_GENERATION_SEALED';
-    throw error;
-  }
-
-  function readAndValidateSeal() {
-    const seal = readRegularJSON(sealPath, 'seal');
-    assertStateGeneration(seal, 'seal');
-    if (
-      seal.protocol !== 'preview-phase-seal-v1' ||
-      seal.schema_version !== 1 ||
-      !Number.isSafeInteger(seal.final_size_bytes) ||
-      seal.final_size_bytes < 0 ||
-      !Number.isFinite(seal.sealed_at_ms) ||
-      seal.sealed_at_ms <= 0 ||
-      (seal.fallback_required !== undefined &&
-        typeof seal.fallback_required !== 'boolean')
-    ) {
-      throw new Error(`invalid preview phase seal: ${sealPath}`);
-    }
-    return seal;
-  }
-
-  function observeDegradedMarker() {
-    if (!fileSystem.existsSync(degradedPath)) return false;
-    const marker = readRegularJSON(degradedPath, 'degraded marker');
-    assertStateGeneration(marker, 'degraded marker');
-    if (
-      marker.protocol !== 'preview-phase-degraded-v1' ||
-      marker.schema_version !== 1 ||
-      typeof marker.first_failed_event_id !== 'string' ||
-      !Number.isFinite(marker.degraded_at_ms) ||
-      marker.degraded_at_ms <= 0 ||
-      !STATE_ID_PATTERN.test(marker.reason || '')
-    ) {
-      throw new Error(`invalid preview phase degraded marker: ${degradedPath}`);
-    }
-    degraded = true;
-    fallbackRequired = true;
-    return true;
-  }
-
-  function observeFallbackIntent() {
-    if (!fileSystem.existsSync(fallbackIntentPath)) return false;
-    validateFallbackIntent(
-      readRegularJSON(fallbackIntentPath, 'fallback intent'),
-      metadata
-    );
-    fallbackRequired = true;
-    return true;
-  }
-
-  function assertGenerationIsNotDegraded() {
-    if (!observeDegradedMarker()) return;
-    throw degradedError();
-  }
-
-  function removeOwnedWriterLock() {
-    const lock = readRegularJSON(writerLockPath, 'writer lock');
-    if (
-      lock.protocol !== 'preview-phase-writer-v1' ||
-      lock.schema_version !== 1 ||
-      lock.run_id !== options.run_id ||
-      lock.generation !== metadata.generation ||
-      lock.writer_instance_id !== writerInstanceID
-    ) {
-      throw new Error('preview phase writer lock ownership changed');
-    }
-    fileSystem.rmSync(writerLockPath);
-    writerLockOwned = false;
-    writerLockDirectory = null;
-    syncRunDirectory();
-  }
-
-  function recoverTornTail() {
-    if (recovered) return;
-    if (!fileSystem.existsSync(eventsPath)) {
-      recovered = true;
-      return;
-    }
-    const readFlags = fs.constants.O_RDWR | (fs.constants.O_NOFOLLOW || 0);
-    const fd = fileSystem.openSync(eventsPath, readFlags);
-    try {
-      const size = fileSystem.fstatSync(fd).size;
-      if (size === 0) {
-        recovered = true;
-        return;
-      }
-      const tailByte = Buffer.allocUnsafe(1);
-      fileSystem.readSync(fd, tailByte, 0, 1, size - 1);
-      if (tailByte[0] === 0x0a) {
-        recovered = true;
-        return;
-      }
-
-      const chunk = Buffer.allocUnsafe(64 * 1024);
-      let scanEnd = size;
-      while (scanEnd > 0) {
-        const scanStart = Math.max(0, scanEnd - chunk.length);
-        const length = scanEnd - scanStart;
-        const bytesRead = fileSystem.readSync(fd, chunk, 0, length, scanStart);
-        const lastNewline = chunk.lastIndexOf(0x0a, bytesRead - 1);
-        if (lastNewline >= 0) {
-          fileSystem.ftruncateSync(fd, scanStart + lastNewline + 1);
-          recovered = true;
-          return;
-        }
-        scanEnd = scanStart;
-      }
-      fileSystem.ftruncateSync(fd, 0);
-      recovered = true;
-    } finally {
-      fileSystem.closeSync(fd);
-    }
-  }
-
-  function degradedError() {
-    const error = new Error('preview phase outbox is degraded');
-    error.code = 'PREVIEW_PHASE_OUTBOX_DEGRADED';
-    return error;
-  }
-
-  function latchDegraded(event, cause) {
-    fallbackRequired = true;
-    if (degraded) return;
-    degraded = true;
-    if (!metadata || !ownsSelectedWriterLock()) return;
-    const reason =
-      typeof cause?.code === 'string' && STATE_ID_PATTERN.test(cause.code)
-        ? cause.code
-        : 'append_failed';
-    try {
-      publishImmutableState(degradedPath, 'degraded', {
-        protocol: 'preview-phase-degraded-v1',
-        schema_version: 1,
-        run_id: options.run_id,
-        generation: metadata.generation,
-        first_failed_event_id:
-          typeof event?.event_id === 'string'
-            ? event.event_id
-            : `${options.run_id}:transport-fallback`,
-        degraded_at_ms: now(),
-        reason,
-      });
-    } catch {
-      // A total filesystem failure cannot be made durable. The in-memory latch
-      // still prevents this writer from creating holes in the JSONL prefix.
-    }
-  }
-
-  function finalizeUnboundFallback(event, conflict) {
-    fallbackRequired = true;
-    latchDegraded(event, conflict);
-    recoverTornTail();
-    ensureEmptyEventsFile();
-    const fd = fileSystem.openSync(
-      eventsPath,
-      fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0)
-    );
-    let finalSize;
-    try {
-      finalSize = fileSystem.fstatSync(fd).size;
-    } finally {
-      fileSystem.closeSync(fd);
-    }
-    const ownedWriter = validateWriterLock(
-      readRegularJSON(writerLockPath, 'writer lock')
-    );
-    if (
-      ownedWriter.writer_instance_id !== writerInstanceID ||
-      ownedWriter.pid !== process.pid ||
-      (ownedWriter.process_start_ticks || '') !==
-        (currentProcessStartTicks || '')
-    ) {
-      throw writerBusyError();
-    }
-    const terminalAt = Math.max(now(), ownedWriter.created_at_ms);
-    if (!fileSystem.existsSync(sealPath)) {
-      publishImmutableState(sealPath, 'sealed', {
-        protocol: 'preview-phase-seal-v1',
-        schema_version: 1,
-        run_id: options.run_id,
-        generation: metadata.generation,
-        final_size_bytes: finalSize,
-        sealed_at_ms: terminalAt,
-        fallback_required: true,
-      });
-    }
-    const observedOwner = readAndValidateProducerMarker();
-    if (!fileSystem.existsSync(unboundFallbackPath)) {
-      publishImmutableState(unboundFallbackPath, 'producer-unbound', {
-        protocol: 'preview-phase-unbound-fallback-v1',
-        schema_version: 1,
-        epoch: producerEpoch,
-        run_id: options.run_id,
-        generation: metadata.generation,
-        writer_instance_id: writerInstanceID,
-        pid: process.pid,
-        process_start_ticks: currentProcessStartTicks,
-        started_at_ms: ownedWriter.created_at_ms,
-        state: 'terminal',
-        terminal_at_ms: terminalAt,
-        observed_owner_run_id: observedOwner.run_id,
-        observed_owner_generation: observedOwner.generation,
-      });
-    }
-    if (ownsSelectedWriterLock()) removeOwnedWriterLock();
-    closed = true;
-    closeResult = true;
-  }
-
-  function finalizeUnpublishedStagingFallback(event, conflict) {
-    if (
-      runDir !== stagingRunDir ||
-      !stagingOwned ||
-      !ownsSelectedWriterLock()
-    ) {
-      return false;
-    }
-    ensureMetadata();
-    fallbackRequired = true;
-    latchDegraded(event, conflict);
-    recoverTornTail();
-    ensureEmptyEventsFile();
-    const fd = fileSystem.openSync(
-      eventsPath,
-      fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0)
-    );
-    let finalSize;
-    try {
-      finalSize = fileSystem.fstatSync(fd).size;
-    } finally {
-      fileSystem.closeSync(fd);
-    }
-    const ownedWriter = validateWriterLock(
-      readRegularJSON(writerLockPath, 'writer lock')
-    );
-    if (
-      ownedWriter.writer_instance_id !== writerInstanceID ||
-      ownedWriter.pid !== process.pid ||
-      (ownedWriter.process_start_ticks || '') !==
-        (currentProcessStartTicks || '')
-    ) {
-      throw writerBusyError();
-    }
-    if (!fileSystem.existsSync(sealPath)) {
-      publishImmutableState(sealPath, 'sealed', {
-        protocol: 'preview-phase-seal-v1',
-        schema_version: 1,
-        run_id: options.run_id,
-        generation: metadata.generation,
-        final_size_bytes: finalSize,
-        sealed_at_ms: Math.max(now(), ownedWriter.created_at_ms),
-        fallback_required: true,
-      });
-    }
-    removeOwnedWriterLock();
-    closed = true;
-    closeResult = true;
-    try {
-      const allowed = new Set([
-        'meta.json',
-        'events.jsonl',
-        'degraded.json',
-        'sealed.json',
-      ]);
-      const entries = readDirectoryEntriesBounded(
-        stagingRunDir,
-        allowed.size,
-        'preview phase unpublished staging exceeds cleanup entry limit'
-      );
-      for (const entry of entries) {
-        if (!allowed.has(entry.name)) {
-          throw new Error(
-            'preview phase unpublished staging contains unknown state'
-          );
-        }
-        const entryPath = path.join(stagingRunDir, entry.name);
-        const stat = fileSystem.lstatSync(entryPath);
-        if (!stat.isFile() || stat.isSymbolicLink()) {
-          throw new Error(
-            'preview phase unpublished staging contains unsafe state'
-          );
-        }
-        fileSystem.rmSync(entryPath);
-      }
-      syncRunDirectory();
-      fileSystem.rmdirSync(stagingRunDir);
-      syncRootDirectory();
-      stagingOwned = false;
-    } catch {
-      // The writer lock is already durably absent. Trusted controller GC can
-      // finish an unexpected cleanup remainder without touching canonical.
-    }
-    return true;
-  }
-
-  function append(event) {
-    if (closed) throw new Error('preview phase outbox is closed');
-    if (degraded) throw degradedError();
-    const payload = JSON.stringify(event);
-    if (Buffer.byteLength(payload, 'utf8') > MAX_EVENT_BYTES) {
-      const error = new Error(
-        `preview phase event exceeds ${MAX_EVENT_BYTES} bytes`
-      );
-      error.code = 'PREVIEW_PHASE_EVENT_TOO_LARGE';
-      throw error;
-    }
-    const record = Buffer.from(`${payload}\n`, 'utf8');
-    for (let attempt = 1; attempt <= MAX_TRANSIENT_ATTEMPTS; attempt += 1) {
-      try {
-        assertSafeDirectory(fileSystem, root);
-        assertRootDirectoryQuota();
-        ensureCanonicalWriter(event);
-        if (
-          closed &&
-          producerRegistrationDurable &&
-          !everOwnedCanonicalWriter
-        ) {
-          return true;
-        }
-        // The authoritative registrar proves the initial writer identity, but
-        // every append must still fail closed if a controller or an unexpected
-        // same-UID actor replaces auxiliary state after registration.
-        validateOwnedWriterLock();
-        assertGenerationIsOpen();
-        publishActiveProducerMarker();
-        // Any existing writer identity is authoritative to JS. Dead-owner
-        // recovery and torn-tail finalization belong exclusively to shell-server.
-        assertGenerationIsNotDegraded();
-        assertRootByteQuota(record.length);
-        if (eventsFD == null) {
-          if (fileSystem.existsSync(eventsPath)) {
-            const stat = fileSystem.lstatSync(eventsPath);
-            if (!stat.isFile() || stat.isSymbolicLink()) {
-              throw new Error(
-                `unsafe preview phase outbox path: ${eventsPath}`
-              );
-            }
-          }
-          recoverTornTail();
-          const flags =
-            fs.constants.O_CREAT |
-            fs.constants.O_WRONLY |
-            fs.constants.O_APPEND |
-            (fs.constants.O_NOFOLLOW || 0);
-          eventsFD = fileSystem.openSync(eventsPath, flags, 0o600);
-          fileSystem.fchmodSync(eventsFD, 0o600);
-          committedBytes = fileSystem.fstatSync(eventsFD).size;
-        }
-        if (committedBytes + record.length > maxRunBytes) {
-          const error = new Error(
-            `preview phase run quota would exceed ${maxRunBytes} bytes`
-          );
-          error.code = 'PREVIEW_PHASE_RUN_QUOTA_EXCEEDED';
-          throw error;
-        }
-        let offset = 0;
-        while (offset < record.length) {
-          const written = fileSystem.writeSync(
-            eventsFD,
-            record,
-            offset,
-            record.length - offset
-          );
-          if (!Number.isInteger(written) || written <= 0) {
-            throw new Error('preview phase outbox write made no progress');
-          }
-          offset += written;
-        }
-        committedBytes += record.length;
-        return true;
-      } catch (error) {
-        if (eventsFD != null) {
-          try {
-            fileSystem.closeSync(eventsFD);
-          } catch {
-            // Best-effort fd cleanup after append failure.
-          }
-          eventsFD = null;
-          committedBytes = null;
-          recovered = false;
-        }
-        if (error?.code === 'PREVIEW_PHASE_PRODUCER_EPOCH_CONFLICT') {
-          try {
-            finalizeUnboundFallback(event, error);
-          } catch {
-            // The controller can finish a dead CAS loser from its immutable
-            // writer identity. Preserve the original conflict for fallback.
-          }
-          throw error;
-        }
-        if (error?.code === 'PREVIEW_PHASE_RUN_CONFLICT') {
-          try {
-            finalizeUnpublishedStagingFallback(event, error);
-          } catch {
-            // Preserve the staging writer for controller-owned dead-owner GC.
-          }
-          throw error;
-        }
-        if (
-          isTransientFilesystemError(error) &&
-          attempt < MAX_TRANSIENT_ATTEMPTS
-        ) {
-          continue;
-        }
-        latchDegraded(event, error);
-        throw error;
-      }
-    }
-    throw new Error('preview phase transient retry loop exhausted');
-  }
-
-  function flush() {
-    if (eventsFD == null) return true;
-    for (let attempt = 1; attempt <= MAX_TRANSIENT_ATTEMPTS; attempt += 1) {
-      try {
-        fileSystem.fdatasyncSync(eventsFD);
-        return true;
-      } catch (error) {
-        if (
-          isTransientFilesystemError(error) &&
-          attempt < MAX_TRANSIENT_ATTEMPTS
-        ) {
-          continue;
-        }
-        latchDegraded(null, error);
-        throw error;
-      }
-    }
-    throw new Error('preview phase flush retry loop exhausted');
-  }
-
-  function pollQuiesce() {
-    const state = (localSealed, canonicalAcknowledged) => ({
-      local_sealed: localSealed,
-      canonical_acknowledged: canonicalAcknowledged,
-    });
-    if (closed) {
-      return state(closeResult, everOwnedCanonicalWriter && closeResult);
-    }
-    if (sealRequested) {
-      const localSealed = close();
-      return state(localSealed, everOwnedCanonicalWriter && localSealed);
-    }
-    if (!metadata) return state(false, false);
-    if (!fileSystem.existsSync(quiesceRequestPath)) return state(false, false);
-    const request = readRegularJSON(quiesceRequestPath, 'quiesce request');
-    assertStateGeneration(request, 'quiesce request');
-    if (
-      request.protocol !== 'preview-phase-quiesce-v1' ||
-      request.schema_version !== 1 ||
-      !STATE_ID_PATTERN.test(request.request_id || '') ||
-      !Number.isFinite(request.requested_at_ms) ||
-      request.requested_at_ms <= 0
-    ) {
-      throw new Error(
-        `invalid preview phase quiesce request: ${quiesceRequestPath}`
-      );
-    }
-    if (!ownsSelectedWriterLock()) {
-      // Do not acknowledge or mutate the canonical owner lifecycle. The
-      // quiesce boundary still terminalizes this producer's own fallback file.
-      sealRequested = true;
-      closeResult = sealFallback();
-      closed = true;
-      return state(closeResult, false);
-    }
-    const localSealed = close();
-    return state(localSealed, localSealed);
-  }
-
-  function close() {
-    const fallbackCloseResult = sealFallback();
-    // A fallback-only producer never owns the canonical writer lifecycle.
-    // Its open spool fd is sufficient to terminalize after controller rename;
-    // attempting canonical close here could recreate or mutate another owner.
-    if (fallbackStarted && !everOwnedCanonicalWriter) {
-      closed = true;
-      closeResult = fallbackCloseResult;
-      return closeResult;
-    }
-    if (closed) return closeResult && fallbackCloseResult;
-    sealRequested = true;
-    let finalSize = null;
-    try {
-      // A reporter that never attempted persistence has no generation to
-      // close. Persistence failures set degraded/fallbackRequired and retry
-      // this initialization when the filesystem becomes available again.
-      if (!metadata && !degraded && !fallbackRequired) {
-        closed = true;
-        closeResult = fallbackCloseResult;
-        return closeResult;
-      }
-      assertSafeDirectory(fileSystem, root);
-      assertRootDirectoryQuota();
-      ensureCanonicalWriter();
-
-      if (fileSystem.existsSync(sealPath)) {
-        const seal = readAndValidateSeal();
-        fallbackRequired ||= seal.fallback_required === true;
-        if (ownsSelectedWriterLock()) {
-          publishActiveProducerMarker();
-          publishTerminalProducerMarker();
-          removeOwnedWriterLock();
-        } else if (fileSystem.existsSync(writerLockPath)) {
-          closeResult = false;
-          return false;
-        } else {
-          const marker = readAndValidateProducerMarker();
-          if (
-            !markerBelongsToThisWriter(marker) ||
-            marker.state !== 'terminal'
-          ) {
-            closeResult = false;
-            return false;
-          }
-          producerStartedAtMs = marker.started_at_ms;
-          producerTerminalAtMs = marker.terminal_at_ms;
-          producerMarkerActive = true;
-          producerMarkerTerminal = true;
-        }
-        closed = true;
-        closeResult = fallbackCloseResult;
-        return closeResult;
-      }
-
-      if (!ownsSelectedWriterLock()) {
-        acquireWriterLock();
-      }
-      publishActiveProducerMarker();
-      observeFallbackIntent();
-      observeDegradedMarker();
-      if (eventsFD != null) {
-        fileSystem.fdatasyncSync(eventsFD);
-        finalSize = fileSystem.fstatSync(eventsFD).size;
-        fileSystem.closeSync(eventsFD);
-        eventsFD = null;
-        committedBytes = null;
-      } else {
-        recoverTornTail();
-        // The first append can fail after the writer lock is acquired but
-        // before events.jsonl is created (for example, aggregate quota). Such
-        // a degraded generation still needs an empty, sealed prefix so the
-        // lock is releasable and the reader can merge stdout_fallback safely.
-        const flags =
-          fs.constants.O_CREAT |
-          fs.constants.O_RDWR |
-          (fs.constants.O_NOFOLLOW || 0);
-        const fd = fileSystem.openSync(eventsPath, flags, 0o600);
-        try {
-          fileSystem.fchmodSync(fd, 0o600);
-          fileSystem.fdatasyncSync(fd);
-          finalSize = fileSystem.fstatSync(fd).size;
-        } finally {
-          fileSystem.closeSync(fd);
-        }
-      }
-      publishImmutableState(sealPath, 'sealed', {
-        protocol: 'preview-phase-seal-v1',
-        schema_version: 1,
-        run_id: options.run_id,
-        generation: metadata.generation,
-        final_size_bytes: finalSize,
-        sealed_at_ms: now(),
-        fallback_required: fallbackRequired,
-      });
-      publishTerminalProducerMarker();
-      removeOwnedWriterLock();
-      closeResult = fallbackCloseResult;
-      closed = true;
-    } catch (error) {
-      closeResult = false;
-      if (!isTransientFilesystemError(error)) {
-        latchDegraded(null, error);
-      }
-      if (eventsFD != null) {
-        try {
-          fileSystem.closeSync(eventsFD);
-        } catch {
-          // Best-effort fd cleanup after close failure.
-        }
-        eventsFD = null;
-        committedBytes = null;
-      }
-      // Keep the unique writer owner and pending close intent for retries. If
-      // the process dies, shell-server is the sole authority that verifies
-      // PID+starttime, repairs the tail, and seals the generation.
-    }
-    return closeResult;
-  }
-
-  return {
-    append,
-    append_fallback: appendFallback,
-    seal_fallback: sealFallback,
-    flush,
-    close,
-    poll_quiesce: pollQuiesce,
-    is_local_sealed: () => closed && closeResult,
-    events_path: eventsPath,
-    meta_path: metaPath,
-    seal_path: sealPath,
-    degraded_path: degradedPath,
-    quiesce_request_path: quiesceRequestPath,
-    producer_epoch_marker_path: producerEpochMarkerPath,
-    fallback_spool_path: fallbackSpoolPath,
-  };
-}
-
-module.exports = {
-  DEFAULT_OUTBOX_ROOT,
-  DEFAULT_MAX_RUN_BYTES,
-  DEFAULT_MAX_ROOT_BYTES,
-  DEFAULT_MAX_ROOT_DIRECTORIES,
-  DEFAULT_MAX_ROOT_SCAN_DIRECTORIES,
-  DEFAULT_MAX_RUN_SCAN_ENTRIES,
-  DEFAULT_MAX_FALLBACK_FILES,
-  DEFAULT_MAX_FALLBACK_BYTES,
-  DEFAULT_MAX_FALLBACK_EVENTS,
-  MAX_FALLBACK_RECORD_BYTES,
-  MAX_EVENT_BYTES,
-  createFallbackSessionID,
-  createPreviewPhaseOutbox,
-};