@lark-apaas/fullstack-cli 1.1.59-alpha.20260720184331 → 1.1.59-alpha.20260721044121

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

@@ -2,6 +2,7 @@
 
 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;
@@ -10,10 +11,186 @@ 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 {
@@ -47,13 +224,46 @@ function assertSafeDirectory(fileSystem, 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));
@@ -70,15 +280,36 @@ function createPreviewPhaseOutbox(options) {
     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');
   }
@@ -100,13 +331,41 @@ function createPreviewPhaseOutbox(options) {
   if (!Number.isSafeInteger(maxRunScanEntries) || maxRunScanEntries <= 0) {
     throw new Error('invalid preview phase max_run_scan_entries');
   }
-  const runDir = path.join(root, options.run_id);
-  const eventsPath = path.join(runDir, 'events.jsonl');
-  const metaPath = path.join(runDir, 'meta.json');
-  const writerLockPath = path.join(runDir, 'writer.lock');
-  const sealPath = path.join(runDir, 'sealed.json');
-  const degradedPath = path.join(runDir, 'degraded.json');
-  const quiesceRequestPath = path.join(runDir, 'quiesce.request.json');
+  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`
@@ -114,6 +373,7 @@ function createPreviewPhaseOutbox(options) {
   let recovered = false;
   let metadata = null;
   let writerLockOwned = false;
+  let writerLockDirectory = null;
   let eventsFD = null;
   let committedBytes = null;
   let degraded = false;
@@ -123,8 +383,49 @@ function createPreviewPhaseOutbox(options) {
   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);
@@ -245,12 +546,12 @@ function createPreviewPhaseOutbox(options) {
     return value;
   }
 
-  function syncRunDirectory() {
+  function syncDirectory(directoryPath) {
     const flags =
       fs.constants.O_RDONLY |
       (fs.constants.O_DIRECTORY || 0) |
       (fs.constants.O_NOFOLLOW || 0);
-    const fd = fileSystem.openSync(runDir, flags);
+    const fd = fileSystem.openSync(directoryPath, flags);
     try {
       fileSystem.fsyncSync(fd);
     } finally {
@@ -258,6 +559,10 @@ function createPreviewPhaseOutbox(options) {
     }
   }
 
+  function syncRunDirectory() {
+    syncDirectory(runDir);
+  }
+
   function syncRootDirectory() {
     const flags =
       fs.constants.O_RDONLY |
@@ -328,7 +633,9 @@ function createPreviewPhaseOutbox(options) {
       if (fd != null) {
         try {
           fileSystem.closeSync(fd);
-        } catch {}
+        } catch {
+          // Best-effort fd cleanup.
+        }
       }
       try {
         fileSystem.rmSync(tempPath, { force: true });
@@ -408,69 +715,21 @@ function createPreviewPhaseOutbox(options) {
 
   function publishActiveProducerMarker() {
     if (producerMarkerActive) return;
-    if (!metadata || !writerLockOwned) {
+    if (
+      !producerRegistrationDurable ||
+      !metadata ||
+      !ownsSelectedWriterLock()
+    ) {
       throw new Error(
-        'preview phase producer marker requires writer ownership'
+        'preview phase producer marker requires authoritative registration'
       );
     }
-    if (fileSystem.existsSync(producerEpochMarkerPath)) {
-      const existing = readAndValidateProducerMarker();
-      if (!markerBelongsToThisWriter(existing) || existing.state !== 'active') {
-        throw producerMarkerConflict();
-      }
-      producerStartedAtMs = existing.started_at_ms;
-      producerMarkerActive = true;
-      return;
-    }
-
-    producerStartedAtMs = producerStartedAtMs ?? now();
-    const marker = buildProducerMarker('active');
-    const tempPath = path.join(
-      root,
-      `.producer-epoch.${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;
-      try {
-        fileSystem.linkSync(tempPath, producerEpochMarkerPath);
-        syncRootDirectory();
-      } catch (error) {
-        if (error?.code !== 'EEXIST') throw error;
-        const existing = readAndValidateProducerMarker();
-        if (
-          !markerBelongsToThisWriter(existing) ||
-          existing.state !== 'active'
-        ) {
-          throw producerMarkerConflict();
-        }
-        producerStartedAtMs = existing.started_at_ms;
-      }
-      producerMarkerActive = true;
-    } finally {
-      if (fd != null) {
-        try {
-          fileSystem.closeSync(fd);
-        } catch {}
-      }
-      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();
+    const existing = readAndValidateProducerMarker();
+    if (!markerBelongsToThisWriter(existing) || existing.state !== 'active') {
+      throw producerMarkerConflict();
     }
+    producerStartedAtMs = existing.started_at_ms;
+    producerMarkerActive = true;
   }
 
   function publishTerminalProducerMarker() {
@@ -513,7 +772,9 @@ function createPreviewPhaseOutbox(options) {
       if (fd != null) {
         try {
           fileSystem.closeSync(fd);
-        } catch {}
+        } catch {
+          // Best-effort fd cleanup.
+        }
       }
       let tempRemoved = false;
       try {
@@ -526,13 +787,16 @@ function createPreviewPhaseOutbox(options) {
     }
   }
 
-  function readAndValidateMetadata() {
-    const stat = fileSystem.lstatSync(metaPath);
+  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: ${metaPath}`);
+      throw new Error(`unsafe preview phase outbox path: ${candidateMetaPath}`);
     }
-    fileSystem.chmodSync(metaPath, 0o600);
-    const metadata = JSON.parse(fileSystem.readFileSync(metaPath, 'utf8'));
+    fileSystem.chmodSync(candidateMetaPath, 0o600);
+    const metadata = JSON.parse(
+      fileSystem.readFileSync(candidateMetaPath, 'utf8')
+    );
     if (
       metadata.protocol !== 'preview-phase-outbox-v1' ||
       metadata.schema_version !== 1 ||
@@ -544,11 +808,17 @@ function createPreviewPhaseOutbox(options) {
       (metadata.quiesce_supported !== undefined &&
         metadata.quiesce_supported !== true)
     ) {
-      throw new Error(`invalid preview phase outbox metadata: ${metaPath}`);
+      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)) {
@@ -580,15 +850,350 @@ function createPreviewPhaseOutbox(options) {
         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) ||
@@ -623,8 +1228,22 @@ function createPreviewPhaseOutbox(options) {
     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 (writerLockOwned) return;
+    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,
@@ -649,6 +1268,8 @@ function createPreviewPhaseOutbox(options) {
       try {
         fileSystem.linkSync(tempPath, writerLockPath);
         writerLockOwned = true;
+        writerLockDirectory = runDir;
+        if (runDir === canonicalRunDir) everOwnedCanonicalWriter = true;
         syncRunDirectory();
       } catch (error) {
         if (error?.code !== 'EEXIST') throw error;
@@ -659,12 +1280,234 @@ function createPreviewPhaseOutbox(options) {
         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) {
@@ -682,7 +1525,7 @@ function createPreviewPhaseOutbox(options) {
 
   function assertGenerationIsOpen() {
     if (!fileSystem.existsSync(sealPath)) return;
-    const seal = readAndValidateSeal();
+    readAndValidateSeal();
     const error = new Error(
       `preview phase sealed generation cannot be reopened: ${options.run_id}`
     );
@@ -727,6 +1570,16 @@ function createPreviewPhaseOutbox(options) {
     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();
@@ -745,6 +1598,7 @@ function createPreviewPhaseOutbox(options) {
     }
     fileSystem.rmSync(writerLockPath);
     writerLockOwned = false;
+    writerLockDirectory = null;
     syncRunDirectory();
   }
 
@@ -800,7 +1654,7 @@ function createPreviewPhaseOutbox(options) {
     fallbackRequired = true;
     if (degraded) return;
     degraded = true;
-    if (!metadata) return;
+    if (!metadata || !ownsSelectedWriterLock()) return;
     const reason =
       typeof cause?.code === 'string' && STATE_ID_PATTERN.test(cause.code)
         ? cause.code
@@ -812,7 +1666,9 @@ function createPreviewPhaseOutbox(options) {
         run_id: options.run_id,
         generation: metadata.generation,
         first_failed_event_id:
-          typeof event?.event_id === 'string' ? event.event_id : '',
+          typeof event?.event_id === 'string'
+            ? event.event_id
+            : `${options.run_id}:transport-fallback`,
         degraded_at_ms: now(),
         reason,
       });
@@ -822,6 +1678,153 @@ function createPreviewPhaseOutbox(options) {
     }
   }
 
+  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();
@@ -834,89 +1837,144 @@ function createPreviewPhaseOutbox(options) {
       throw error;
     }
     const record = Buffer.from(`${payload}\n`, 'utf8');
-    try {
-      assertSafeDirectory(fileSystem, root);
-      assertRootDirectoryQuota();
-      assertSafeDirectory(fileSystem, runDir);
-      ensureMetadata();
-      assertGenerationIsOpen();
-      acquireWriterLock();
-      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}`);
+    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;
         }
-        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');
+        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;
         }
-        offset += written;
-      }
-      committedBytes += record.length;
-      return true;
-    } catch (error) {
-      if (eventsFD != null) {
-        try {
-          fileSystem.closeSync(eventsFD);
-        } catch {}
-        eventsFD = null;
-        committedBytes = null;
-        recovered = false;
+        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;
       }
-      latchDegraded(event, error);
-      throw error;
     }
+    throw new Error('preview phase transient retry loop exhausted');
   }
 
   function flush() {
     if (eventsFD == null) return true;
-    try {
-      fileSystem.fdatasyncSync(eventsFD);
-      return true;
-    } catch (error) {
-      fallbackRequired = true;
-      throw error;
+    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() {
-    if (closed) return closeResult;
-    if (sealRequested) return close();
-    // A reporter that never acquired this generation's writer lock must not
-    // acknowledge or act on a request intended for the actual owner.
-    if (!metadata || !writerLockOwned) return false;
-    if (!fileSystem.existsSync(quiesceRequestPath)) return false;
+    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 (
@@ -930,11 +1988,29 @@ function createPreviewPhaseOutbox(options) {
         `invalid preview phase quiesce request: ${quiesceRequestPath}`
       );
     }
-    return close();
+    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() {
-    if (closed) return closeResult;
+    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 {
@@ -943,18 +2019,17 @@ function createPreviewPhaseOutbox(options) {
       // this initialization when the filesystem becomes available again.
       if (!metadata && !degraded && !fallbackRequired) {
         closed = true;
-        closeResult = true;
-        return true;
+        closeResult = fallbackCloseResult;
+        return closeResult;
       }
       assertSafeDirectory(fileSystem, root);
       assertRootDirectoryQuota();
-      assertSafeDirectory(fileSystem, runDir);
-      ensureMetadata();
+      ensureCanonicalWriter();
 
       if (fileSystem.existsSync(sealPath)) {
         const seal = readAndValidateSeal();
         fallbackRequired ||= seal.fallback_required === true;
-        if (writerLockOwned) {
+        if (ownsSelectedWriterLock()) {
           publishActiveProducerMarker();
           publishTerminalProducerMarker();
           removeOwnedWriterLock();
@@ -976,14 +2051,15 @@ function createPreviewPhaseOutbox(options) {
           producerMarkerTerminal = true;
         }
         closed = true;
-        closeResult = true;
-        return true;
+        closeResult = fallbackCloseResult;
+        return closeResult;
       }
 
-      if (!writerLockOwned) {
+      if (!ownsSelectedWriterLock()) {
         acquireWriterLock();
       }
       publishActiveProducerMarker();
+      observeFallbackIntent();
       observeDegradedMarker();
       if (eventsFD != null) {
         fileSystem.fdatasyncSync(eventsFD);
@@ -1021,36 +2097,44 @@ function createPreviewPhaseOutbox(options) {
       });
       publishTerminalProducerMarker();
       removeOwnedWriterLock();
-      closeResult = true;
+      closeResult = fallbackCloseResult;
       closed = true;
-    } catch {
+    } catch (error) {
       closeResult = false;
-      fallbackRequired = true;
+      if (!isTransientFilesystemError(error)) {
+        latchDegraded(null, error);
+      }
       if (eventsFD != null) {
         try {
           fileSystem.closeSync(eventsFD);
-        } catch {}
+        } catch {
+          // Best-effort fd cleanup after close failure.
+        }
         eventsFD = null;
         committedBytes = null;
       }
-      // Keep the unique writer owner and pending close intent for transient
-      // retries. If the process dies, shell-server is the sole authority that
-      // verifies PID+starttime, repairs the tail, and seals the generation.
+      // 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,
   };
 }
 
@@ -1061,6 +2145,11 @@ module.exports = {
   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,
 };