@lark-apaas/fullstack-cli 1.1.59-alpha.20260719124023 → 1.1.59-alpha.20260720153322

package/dist/index.js

@@ -8660,6 +8660,7 @@ function previewArtifactBuildEnvironment(environment, appBasePath) {
       buildEnvironment[key] = value;
     }
   }
+  buildEnvironment.ASSETS_CDN_PATH = appBasePath;
   buildEnvironment.CLIENT_BASE_PATH = appBasePath;
   buildEnvironment.NODE_ENV = environment?.NODE_ENV ?? "production";
   return buildEnvironment;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-cli",
-  "version": "1.1.59-alpha.20260719124023",
+  "version": "1.1.59-alpha.20260720153322",
   "description": "CLI tool for fullstack template management",
   "type": "module",
   "main": "dist/index.js",

package/templates/scripts/dev.js

@@ -8,7 +8,9 @@ const readline = require('readline');
 const {
   applyPreviewArtifactHostOverrides,
   buildListeningPortLookupArgs,
+  closePreviewPhaseReporterWithRetry,
   createDeferredTypecheckGate,
+  createPreviewPhaseFrameDecoder,
   createPreviewPhaseReporter,
   normalizeTcpPort,
   parseTscWatchSummary,
@@ -199,6 +201,7 @@ function startProcess({
   args,
   cleanupPort,
   phaseDetail = {},
+  phaseChannel = false,
   onReady,
   onOutputLine,
 }) {
@@ -236,12 +239,23 @@ function startProcess({
     }
 
     while (!stopping) {
+      const childEnv = { ...process.env };
+      // The parent is the only outbox writer. Child processes receive a narrow
+      // producer channel, never the filesystem destination.
+      delete childEnv.MIAODA_PREVIEW_PHASE_OUTBOX_ROOT;
+      if (phaseChannel) {
+        childEnv.MIAODA_PREVIEW_PHASE_FD = '3';
+      } else {
+        delete childEnv.MIAODA_PREVIEW_PHASE_FD;
+      }
       const child = spawn(command, args, {
         detached: true,
-        stdio: ['ignore', 'pipe', 'pipe'],
+        stdio: phaseChannel
+          ? ['ignore', 'pipe', 'pipe', 'pipe']
+          : ['ignore', 'pipe', 'pipe'],
         shell: true,
         cwd: PROJECT_ROOT,
-        env: { ...process.env },
+        env: childEnv,
       });
 
       entry.pid = child.pid;
@@ -307,13 +321,24 @@ function startProcess({
 
       // Pipe stdout and stderr through readline for timestamped logging
       let typecheckSummaryReported = false;
-      const pipeLines = stream => {
+      let phaseReported = false;
+      const pipeLines = (stream, allowPhaseFallback = false) => {
         const rl = readline.createInterface({
           input: stream,
           crlfDelay: Infinity,
         });
         rl.on('line', line => {
           if (onOutputLine) onOutputLine(line);
+          const legacyPhaseCandidate =
+            allowPhaseFallback && line.startsWith('[MiaodaPreviewPhase] ');
+          if (legacyPhaseCandidate && !phaseReported) {
+            phaseReported = previewPhaseReporter.ingest(line, {
+              producer: 'vite_plugin',
+              allowed_phases: ['vite_http_listening'],
+              attempt,
+              allow_legacy_stdout: true,
+            });
+          }
           if (name === 'server-typecheck' && !typecheckSummaryReported) {
             const summary = parseTscWatchSummary(line);
             if (summary) {
@@ -334,11 +359,38 @@ function startProcess({
           try {
             fs.writeSync(logFd, msg);
           } catch {}
-          writeOutput(msg);
+          // Phase fallbacks are normalized by the parent reporter before they
+          // enter the shared log. Keep the raw child claim quarantined in the
+          // component log so collectors never observe two representations.
+          if (!legacyPhaseCandidate) writeOutput(msg);
         });
       };
-      if (child.stdout) pipeLines(child.stdout);
+      if (child.stdout) pipeLines(child.stdout, phaseChannel);
       if (child.stderr) pipeLines(child.stderr);
+      if (phaseChannel && child.stdio[3]) {
+        let oversizedPhaseFrameReported = false;
+        const phaseDecoder = createPreviewPhaseFrameDecoder({
+          max_bytes: 16 * 1024,
+          on_oversized_frame: () => {
+            if (oversizedPhaseFrameReported) return;
+            oversizedPhaseFrameReported = true;
+            logEvent(
+              'WARN',
+              name,
+              'Dropped an oversized preview phase producer frame'
+            );
+          },
+          on_frame: line => {
+            if (phaseReported) return;
+            phaseReported = previewPhaseReporter.ingest(line, {
+              producer: 'vite_plugin',
+              allowed_phases: ['vite_http_listening'],
+              attempt,
+            });
+          },
+        });
+        child.stdio[3].on('data', chunk => phaseDecoder.push(chunk));
+      }
 
       // Wait for the direct child to exit.
       // NOTE: must use 'exit', not 'close'. With shell:true, grandchild processes
@@ -468,6 +520,16 @@ async function cleanup() {
 
   logEvent('INFO', 'main', 'All processes stopped');
 
+  const previewPhaseSealed =
+    await closePreviewPhaseReporterWithRetry(previewPhaseReporter);
+  if (!previewPhaseSealed) {
+    logEvent(
+      'ERROR',
+      'main',
+      'Preview phase outbox did not seal after bounded shutdown retries'
+    );
+  }
+
   try {
     fs.closeSync(devStdLogFd);
   } catch {}
@@ -475,7 +537,7 @@ async function cleanup() {
     fs.closeSync(devLogFd);
   } catch {}
 
-  process.exit(0);
+  process.exit(previewPhaseSealed ? 0 : 1);
 }
 
 process.on('SIGTERM', cleanup);
@@ -644,6 +706,7 @@ async function main() {
     command: 'npm',
     args: ['run', 'dev:client'],
     cleanupPort: CLIENT_DEV_PORT,
+    phaseChannel: true,
   });
 
   writeOutput(`📋 Dev processes running. Press Ctrl+C to stop.\n`);
@@ -657,7 +720,14 @@ async function main() {
   }
 }
 
-main().catch(err => {
+main().catch(async err => {
   console.error('Fatal error:', err);
+  const previewPhaseSealed =
+    await closePreviewPhaseReporterWithRetry(previewPhaseReporter);
+  if (!previewPhaseSealed) {
+    console.error(
+      'Preview phase outbox did not seal after bounded fatal-exit retries'
+    );
+  }
   process.exit(1);
 });

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

@@ -0,0 +1,791 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+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 RUN_ID_PATTERN = /^prv_[A-Za-z0-9_-]{1,60}$/;
+const STATE_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+const PROCESS_START_TICKS_PATTERN = /^\d+$/;
+
+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);
+}
+
+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 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;
+  if (!RUN_ID_PATTERN.test(options.run_id || '')) {
+    throw new Error('invalid preview run_id for phase outbox');
+  }
+  if (!STATE_ID_PATTERN.test(writerInstanceID)) {
+    throw new Error('invalid preview phase writer_instance_id');
+  }
+  if (
+    currentProcessStartTicks != null &&
+    !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');
+  }
+  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');
+  let recovered = false;
+  let metadata = null;
+  let writerLockOwned = false;
+  let eventsFD = null;
+  let committedBytes = null;
+  let degraded = false;
+  let fallbackRequired = false;
+  let sealRequested = false;
+  let closed = false;
+  let closeResult = false;
+
+  function rootQuotaError(message) {
+    const error = new Error(message);
+    error.code = 'PREVIEW_PHASE_ROOT_QUOTA_EXCEEDED';
+    return error;
+  }
+
+  function inspectRootUsage() {
+    const entries = fileSystem.readdirSync(root, { withFileTypes: true });
+    if (entries.length > maxRootScanDirectories) {
+      throw rootQuotaError(
+        `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 = fileSystem.readdirSync(entryPath, {
+          withFileTypes: true,
+        });
+      } 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 syncRunDirectory() {
+    const flags =
+      fs.constants.O_RDONLY |
+      (fs.constants.O_DIRECTORY || 0) |
+      (fs.constants.O_NOFOLLOW || 0);
+    const fd = fileSystem.openSync(runDir, 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 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 {}
+      }
+      try {
+        fileSystem.rmSync(tempPath, { force: true });
+      } catch {
+        // A stale temp file is harmless and never consumed by the reader.
+      }
+    }
+  }
+
+  function readAndValidateMetadata() {
+    const stat = fileSystem.lstatSync(metaPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error(`unsafe preview phase outbox path: ${metaPath}`);
+    }
+    fileSystem.chmodSync(metaPath, 0o600);
+    const metadata = JSON.parse(fileSystem.readFileSync(metaPath, 'utf8'));
+    if (
+      metadata.protocol !== 'preview-phase-outbox-v1' ||
+      metadata.schema_version !== 1 ||
+      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: ${metaPath}`);
+    }
+    return metadata;
+  }
+
+  function ensureMetadata() {
+    if (metadata) return;
+    if (fileSystem.existsSync(metaPath)) {
+      metadata = readAndValidateMetadata();
+      return;
+    }
+    const candidate = {
+      protocol: 'preview-phase-outbox-v1',
+      schema_version: 1,
+      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 {
+      fileSystem.writeFileSync(tempPath, `${JSON.stringify(candidate)}\n`, {
+        encoding: 'utf8',
+        flag: 'wx',
+        mode: 0o600,
+      });
+      try {
+        fileSystem.linkSync(tempPath, metaPath);
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error;
+      }
+    } finally {
+      try {
+        fileSystem.rmSync(tempPath, { force: true });
+      } catch {
+        // A stale temp file is harmless and never consumed by the reader.
+      }
+    }
+    metadata = readAndValidateMetadata();
+  }
+
+  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 acquireWriterLock() {
+    if (writerLockOwned) return;
+    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 {
+      fileSystem.writeFileSync(tempPath, `${JSON.stringify(lock)}\n`, {
+        encoding: 'utf8',
+        flag: 'wx',
+        mode: 0o600,
+      });
+      try {
+        fileSystem.linkSync(tempPath, writerLockPath);
+        writerLockOwned = 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 {
+      try {
+        fileSystem.rmSync(tempPath, { force: true });
+      } catch {
+        // A stale temp file is harmless and never consumed by the reader.
+      }
+    }
+  }
+
+  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;
+    const seal = 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 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;
+    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) 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 : '',
+        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 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');
+    try {
+      assertSafeDirectory(fileSystem, root);
+      assertRootDirectoryQuota();
+      assertSafeDirectory(fileSystem, runDir);
+      ensureMetadata();
+      assertGenerationIsOpen();
+      acquireWriterLock();
+      // 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 {}
+        eventsFD = null;
+        committedBytes = null;
+        recovered = false;
+      }
+      latchDegraded(event, error);
+      throw error;
+    }
+  }
+
+  function flush() {
+    if (eventsFD == null) return true;
+    try {
+      fileSystem.fdatasyncSync(eventsFD);
+      return true;
+    } catch (error) {
+      fallbackRequired = true;
+      throw error;
+    }
+  }
+
+  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 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}`
+      );
+    }
+    return close();
+  }
+
+  function close() {
+    if (closed) return closeResult;
+    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 = true;
+        return true;
+      }
+      assertSafeDirectory(fileSystem, root);
+      assertRootDirectoryQuota();
+      assertSafeDirectory(fileSystem, runDir);
+      ensureMetadata();
+
+      if (fileSystem.existsSync(sealPath)) {
+        const seal = readAndValidateSeal();
+        fallbackRequired ||= seal.fallback_required === true;
+        if (writerLockOwned) {
+          removeOwnedWriterLock();
+        } else if (fileSystem.existsSync(writerLockPath)) {
+          closeResult = false;
+          return false;
+        }
+        closed = true;
+        closeResult = true;
+        return true;
+      }
+
+      if (!writerLockOwned) {
+        acquireWriterLock();
+      }
+      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,
+      });
+      removeOwnedWriterLock();
+      closeResult = true;
+      closed = true;
+    } catch {
+      closeResult = false;
+      fallbackRequired = true;
+      if (eventsFD != null) {
+        try {
+          fileSystem.closeSync(eventsFD);
+        } catch {}
+        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.
+    }
+    return closeResult;
+  }
+
+  return {
+    append,
+    flush,
+    close,
+    poll_quiesce: pollQuiesce,
+    events_path: eventsPath,
+    meta_path: metaPath,
+    seal_path: sealPath,
+    degraded_path: degradedPath,
+    quiesce_request_path: quiesceRequestPath,
+  };
+}
+
+module.exports = {
+  DEFAULT_OUTBOX_ROOT,
+  DEFAULT_MAX_RUN_BYTES,
+  DEFAULT_MAX_ROOT_BYTES,
+  DEFAULT_MAX_ROOT_DIRECTORIES,
+  DEFAULT_MAX_ROOT_SCAN_DIRECTORIES,
+  MAX_EVENT_BYTES,
+  createPreviewPhaseOutbox,
+};

package/templates/scripts/preview-startup-timing.cjs

@@ -1,11 +1,13 @@
 'use strict';
 
 const fs = require('fs');
+const crypto = require('crypto');
 const net = require('net');
 const path = require('path');
+const { createPreviewPhaseOutbox } = require('./preview-phase-outbox.cjs');
 
 const PREFIX = '[MiaodaPreviewPhase] ';
-const RUN_ID_PATTERN = /^prv_[A-Za-z0-9_-]{1,128}$/;
+const RUN_ID_PATTERN = /^prv_[A-Za-z0-9_-]{1,60}$/;
 
 function resolveAppId(env) {
   const basePath = env.CLIENT_BASE_PATH || '';
@@ -13,30 +15,340 @@ function resolveAppId(env) {
   return match ? match[1] : env.MIAODA_APP_ID || '';
 }
 
+function createPreviewPhaseFrameDecoder(options = {}) {
+  const maxBytes = options.max_bytes || 16 * 1024;
+  const onFrame = options.on_frame;
+  const onOversizedFrame = options.on_oversized_frame || (() => {});
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new Error('preview phase frame max_bytes must be a positive integer');
+  }
+  if (typeof onFrame !== 'function') {
+    throw new Error('preview phase frame on_frame callback is required');
+  }
+
+  let pending = [];
+  let pendingBytes = 0;
+  let droppingOversizedFrame = false;
+
+  function reset() {
+    pending = [];
+    pendingBytes = 0;
+  }
+
+  function push(chunk) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const newline = buffer.indexOf(0x0a, offset);
+      const end = newline < 0 ? buffer.length : newline;
+      const segment = buffer.subarray(offset, end);
+
+      if (!droppingOversizedFrame) {
+        if (pendingBytes + segment.length > maxBytes) {
+          reset();
+          droppingOversizedFrame = true;
+          onOversizedFrame();
+        } else if (segment.length > 0) {
+          pending.push(segment);
+          pendingBytes += segment.length;
+        }
+      }
+
+      if (newline < 0) return;
+      if (!droppingOversizedFrame) {
+        onFrame(Buffer.concat(pending, pendingBytes).toString('utf8'));
+      }
+      reset();
+      droppingOversizedFrame = false;
+      offset = newline + 1;
+    }
+  }
+
+  return { push };
+}
+
 function createPreviewPhaseReporter(options = {}) {
   const env = options.env || process.env;
   const write = options.write || (line => process.stdout.write(`${line}\n`));
   const now = options.now || Date.now;
+  const randomUUID = options.random_uuid || crypto.randomUUID;
+  const producer = options.producer || 'dev_orchestrator';
+  const onDiagnostic =
+    options.on_diagnostic ||
+    (diagnostic => {
+      try {
+        process.stderr.write(
+          `[MiaodaPreviewOutbox] ${JSON.stringify(diagnostic)}\n`
+        );
+      } catch {
+        // Diagnostics must never block preview startup.
+      }
+    });
+  const producerInstanceID = randomUUID();
+  const runId = env.MIAODA_PREVIEW_RUN_ID || '';
+  const outbox = RUN_ID_PATTERN.test(runId)
+    ? createPreviewPhaseOutbox({
+        root: options.outbox_root || env.MIAODA_PREVIEW_PHASE_OUTBOX_ROOT,
+        run_id: runId,
+        fs: options.fs,
+        random_uuid: randomUUID,
+        now,
+      })
+    : null;
+  const producerSequences = new Map();
+  const startupTerminalPhases = new Set();
+  let reporterSealed = false;
+  let quiescePollTimer = null;
+
+  function reportDiagnostic(diagnostic) {
+    try {
+      onDiagnostic(diagnostic);
+    } catch {
+      // Diagnostics must never become a preview-startup failure mode.
+    }
+  }
 
-  function emit(phase, status, detail = {}) {
-    const runId = env.MIAODA_PREVIEW_RUN_ID || '';
-    if (!RUN_ID_PATTERN.test(runId)) return false;
+  function emitForProducer(eventProducer, phase, status, detail = {}) {
+    if (!RUN_ID_PATTERN.test(runId) || reporterSealed) return false;
     const atMs = detail.at_ms == null ? now() : detail.at_ms;
+    const producerSeq = (producerSequences.get(eventProducer) || 0) + 1;
+    producerSequences.set(eventProducer, producerSeq);
     const event = {
       ...detail,
       schema_version: 1,
+      event_id: `${runId}:${randomUUID()}`,
       run_id: runId,
       app_id: resolveAppId(env),
       sandbox_id: env.SANDBOX_ID || '',
       phase,
       status,
       at_ms: atMs,
+      producer: eventProducer,
+      producer_instance_id:
+        eventProducer === producer
+          ? producerInstanceID
+          : `${producerInstanceID}:${eventProducer}`,
+      producer_seq: producerSeq,
+      recorded_at_ms: now(),
+      transport: 'outbox',
     };
-    write(`${PREFIX}${JSON.stringify(event)}`);
-    return true;
+    let persisted = false;
+    try {
+      persisted = outbox.append(event);
+    } catch (error) {
+      if (error?.code === 'PREVIEW_PHASE_EVENT_TOO_LARGE') {
+        reportDiagnostic({
+          code: 'event_rejected',
+          reason: 'event_too_large',
+          run_id: runId,
+          phase,
+          event_id: event.event_id,
+        });
+        return false;
+      }
+      event.transport = 'stdout_fallback';
+      if (error?.code !== 'PREVIEW_PHASE_OUTBOX_DEGRADED') {
+        reportDiagnostic({
+          code: 'outbox_append_failed',
+          run_id: runId,
+          phase,
+          event_id: event.event_id,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    let mirrored = false;
+    try {
+      write(`${PREFIX}${JSON.stringify(event)}`);
+      mirrored = true;
+    } catch (error) {
+      reportDiagnostic({
+        code: 'stdout_mirror_failed',
+        run_id: runId,
+        phase,
+        event_id: event.event_id,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+    const delivered = persisted || mirrored;
+    if (
+      delivered &&
+      status !== 'start' &&
+      (phase === 'backend_tcp_ready' || phase === 'vite_http_listening')
+    ) {
+      startupTerminalPhases.add(phase);
+      if (startupTerminalPhases.size === 2) {
+        flush();
+        close();
+      }
+    }
+    return delivered;
+  }
+
+  function emit(phase, status, detail = {}) {
+    return emitForProducer(producer, phase, status, detail);
+  }
+
+  function ingest(rawFrame, context = {}) {
+    if (
+      typeof rawFrame !== 'string' ||
+      Buffer.byteLength(rawFrame, 'utf8') > 16 * 1024
+    ) {
+      return false;
+    }
+    const isLegacyStdoutFrame =
+      context.allow_legacy_stdout === true && rawFrame.startsWith(PREFIX);
+    const serializedFrame = isLegacyStdoutFrame
+      ? rawFrame.slice(PREFIX.length).trim()
+      : rawFrame;
+    let frame;
+    try {
+      frame = JSON.parse(serializedFrame);
+    } catch {
+      return false;
+    }
+    const allowedPhases = Array.isArray(context.allowed_phases)
+      ? context.allowed_phases
+      : [];
+    if (
+      (!isLegacyStdoutFrame &&
+        frame?.protocol !== 'preview_phase_producer_v1') ||
+      frame.schema_version !== 1 ||
+      frame.run_id !== runId ||
+      !allowedPhases.includes(frame.phase) ||
+      !/^(?:start|success|error|fallback|skipped|cancelled)$/.test(
+        frame.status || ''
+      ) ||
+      !Number.isFinite(frame.at_ms) ||
+      frame.at_ms <= 0
+    ) {
+      return false;
+    }
+    const detail = {
+      at_ms: frame.at_ms,
+      ...(Number.isFinite(frame.duration_ms) && frame.duration_ms >= 0
+        ? { duration_ms: frame.duration_ms }
+        : {}),
+      ...(Number.isFinite(frame.precision_ms) && frame.precision_ms >= 0
+        ? { precision_ms: frame.precision_ms }
+        : {}),
+      ...(typeof frame.exact === 'boolean' ? { exact: frame.exact } : {}),
+      ...(Number.isSafeInteger(context.attempt) && context.attempt > 0
+        ? { attempt: context.attempt }
+        : {}),
+    };
+    return emitForProducer(
+      context.producer || 'child_process',
+      frame.phase,
+      frame.status,
+      detail
+    );
+  }
+
+  function flush() {
+    if (reporterSealed) return true;
+    if (!outbox) return true;
+    try {
+      return outbox.flush();
+    } catch (error) {
+      reportDiagnostic({
+        code: 'outbox_flush_failed',
+        run_id: runId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return false;
+    }
   }
 
-  return { emit };
+  function stopQuiescePolling() {
+    if (quiescePollTimer == null) return;
+    clearInterval(quiescePollTimer);
+    quiescePollTimer = null;
+  }
+
+  function pollQuiesce() {
+    if (reporterSealed) return true;
+    if (!outbox) return false;
+    try {
+      const sealed = outbox.poll_quiesce();
+      if (sealed) {
+        reporterSealed = true;
+        stopQuiescePolling();
+      }
+      return sealed;
+    } catch (error) {
+      reportDiagnostic({
+        code: 'outbox_quiesce_failed',
+        run_id: runId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return false;
+    }
+  }
+
+  function close() {
+    if (reporterSealed) return true;
+    if (!outbox) return true;
+    try {
+      const sealed = outbox.close();
+      if (sealed) {
+        reporterSealed = true;
+        stopQuiescePolling();
+      }
+      return sealed;
+    } catch (error) {
+      reportDiagnostic({
+        code: 'outbox_close_failed',
+        run_id: runId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return false;
+    }
+  }
+
+  if (outbox) {
+    const intervalMs = options.quiesce_poll_interval_ms ?? 100;
+    if (Number.isSafeInteger(intervalMs) && intervalMs > 0) {
+      quiescePollTimer = setInterval(pollQuiesce, intervalMs);
+      if (typeof quiescePollTimer.unref === 'function') {
+        quiescePollTimer.unref();
+      }
+    }
+  }
+
+  return { emit, ingest, flush, close, pollQuiesce };
+}
+
+async function closePreviewPhaseReporterWithRetry(reporter, options = {}) {
+  const retryDelaysMs = options.retry_delays_ms || [0, 25, 100, 250, 500, 1000];
+  const sleep =
+    options.sleep ||
+    (delayMs => new Promise(resolve => setTimeout(resolve, delayMs)));
+  if (
+    !reporter ||
+    typeof reporter.flush !== 'function' ||
+    typeof reporter.close !== 'function' ||
+    !Array.isArray(retryDelaysMs) ||
+    retryDelaysMs.length === 0 ||
+    retryDelaysMs.some(delayMs => !Number.isSafeInteger(delayMs) || delayMs < 0)
+  ) {
+    throw new Error('invalid preview phase reporter close retry configuration');
+  }
+
+  for (const delayMs of retryDelaysMs) {
+    if (delayMs > 0) await sleep(delayMs);
+    try {
+      reporter.flush();
+    } catch {
+      // close() repeats the durable flush and reports the authoritative result.
+    }
+    try {
+      if (reporter.close()) return true;
+    } catch {
+      // A later bounded attempt may succeed after a transient filesystem fault.
+    }
+  }
+  return false;
 }
 
 function createTscServerCommand(reason, missingModules = []) {
@@ -449,7 +761,9 @@ async function waitForTcpReady(options) {
 module.exports = {
   applyPreviewArtifactHostOverrides,
   buildListeningPortLookupArgs,
+  closePreviewPhaseReporterWithRetry,
   createDeferredTypecheckGate,
+  createPreviewPhaseFrameDecoder,
   createPreviewPhaseReporter,
   normalizeTcpPort,
   parseTscWatchSummary,