@lark-apaas/fullstack-cli 1.1.65 → 1.1.66-alpha.20260902172318

package/templates/scripts/dev.js

@@ -2,6 +2,8 @@
 'use strict';
 
 const fs = require('fs');
+const http = require('http');
+const net = require('net');
 const path = require('path');
 const { spawn, execSync } = require('child_process');
 const readline = require('readline');
@@ -31,13 +33,39 @@ loadEnv();
 
 // ── Configuration ─────────────────────────────────────────────────────────────
 const LOG_DIR = process.env.LOG_DIR || 'logs';
-const MAX_RESTART_COUNT = process.env.MAX_RESTART_COUNT != null && process.env.MAX_RESTART_COUNT !== ''
-  ? parseInt(process.env.MAX_RESTART_COUNT, 10)
-  : Infinity;
+const MAX_RESTART_COUNT =
+  process.env.MAX_RESTART_COUNT != null && process.env.MAX_RESTART_COUNT !== ''
+    ? parseInt(process.env.MAX_RESTART_COUNT, 10)
+    : Infinity;
 const RESTART_DELAY = parseInt(process.env.RESTART_DELAY, 10) || 2;
 const MAX_DELAY = 8;
-const SERVER_PORT = process.env.SERVER_PORT || '3000';
+const LEGACY_SERVER_PORT = process.env.SERVER_PORT || '3000';
+const PLATFORM_HANDOFF_PUBLIC_PORT = 3000;
+const MAX_HANDOFF_READINESS_RESPONSE_BYTES = 64 * 1024;
 const CLIENT_DEV_PORT = process.env.CLIENT_DEV_PORT || '8080';
+// This is an ownership receipt, not the raw TCC flag.  The sandbox entrypoint
+// sets it only after the handoff runtime has bound the public port and
+// published its owner marker.  If that handshake fails, the legacy path below
+// remains the sole backend owner.
+const BACKEND_OWNED_BY_HANDOFF =
+  process.env.MIAODA_NEST_BACKEND_OWNER === 'handoff';
+const HANDOFF_CONTROL_ROOT = '/tmp/miaoda-cold-start';
+const HANDOFF_DECISION_FILE = path.join(HANDOFF_CONTROL_ROOT, 'decision.json');
+const HANDOFF_OWNER_FILE = path.join(
+  HANDOFF_CONTROL_ROOT,
+  'runtime-owner.json'
+);
+const HANDOFF_PROCESS_REGISTRY_FILE = path.join(
+  HANDOFF_CONTROL_ROOT,
+  'runtime-processes.json'
+);
+const HANDOFF_DECISION = BACKEND_OWNED_BY_HANDOFF
+  ? readStrictColdStartDecision()
+  : null;
+const HANDOFF_BOOT_ID = HANDOFF_DECISION?.bootId || '';
+const HANDOFF_RESTORE_EPOCH_MS = HANDOFF_DECISION?.restoreEpochMs || 0;
+const PUBLIC_SERVER_PORT =
+  HANDOFF_DECISION?.publicPort || Number(LEGACY_SERVER_PORT);
 
 fs.mkdirSync(LOG_DIR, { recursive: true });
 
@@ -50,11 +78,16 @@ const devLogFd = fs.openSync(devLogPath, 'a');
 function timestamp() {
   const now = new Date();
   return (
-    now.getFullYear() + '-' +
-    String(now.getMonth() + 1).padStart(2, '0') + '-' +
-    String(now.getDate()).padStart(2, '0') + ' ' +
-    String(now.getHours()).padStart(2, '0') + ':' +
-    String(now.getMinutes()).padStart(2, '0') + ':' +
+    now.getFullYear() +
+    '-' +
+    String(now.getMonth() + 1).padStart(2, '0') +
+    '-' +
+    String(now.getDate()).padStart(2, '0') +
+    ' ' +
+    String(now.getHours()).padStart(2, '0') +
+    ':' +
+    String(now.getMinutes()).padStart(2, '0') +
+    ':' +
     String(now.getSeconds()).padStart(2, '0')
   );
 }
@@ -63,26 +96,55 @@ function timestamp() {
 // Each pending fs.write retains ~1.5 KB (msg + libuv/V8 wrappers); 1000 ≈ ~1.5 MB ceiling.
 let _stdoutInFlight = 0;
 const STDOUT_MAX_INFLIGHT = 1000;
+const reportedBestEffortFailures = new Set();
+
+function reportBestEffortFailure(operation, error) {
+  if (reportedBestEffortFailures.has(operation)) return;
+  reportedBestEffortFailures.add(operation);
+  const detail = error instanceof Error ? error.message : String(error);
+  try {
+    fs.write(2, `[dev.js] ${operation}: ${detail}\n`, () => {});
+  } catch {
+    // fd 2 is the last-resort diagnostic sink; there is no safe recursive
+    // fallback if submitting this best-effort write itself fails.
+  }
+}
 
 /** Write to dev.std.log (sync, guaranteed) + mirror to terminal (async, non-blocking) */
 function writeOutput(msg) {
   // File first and synchronously — read-logs reads this file; it must never be gated
   // by the terminal consumer.
-  try { fs.writeSync(devStdLogFd, msg); } catch {}
+  try {
+    fs.writeSync(devStdLogFd, msg);
+  } catch (error) {
+    reportBestEffortFailure('write dev.std.log failed', error);
+  }
   // stdout mirror via async fs.write: if process.stdout is a pty/pipe whose consumer
   // stalls, the block happens on the libuv threadpool, NOT the event loop — so the
   // synchronous log-FILE writes above (and subsequent readline callbacks) keep running.
   // Drop overflow when too many writes are already pending (best-effort mirror).
-  if (_stdoutInFlight >= STDOUT_MAX_INFLIGHT) { return; }
+  if (_stdoutInFlight >= STDOUT_MAX_INFLIGHT) {
+    return;
+  }
   _stdoutInFlight++;
-  try { fs.write(1, msg, () => { _stdoutInFlight--; }); } catch { _stdoutInFlight--; }
+  try {
+    fs.write(1, msg, () => {
+      _stdoutInFlight--;
+    });
+  } catch {
+    _stdoutInFlight--;
+  }
 }
 
 /** Structured event log → terminal + dev.std.log + dev.log */
 function logEvent(level, name, message) {
   const msg = `[${timestamp()}] [${level}] [${name}] ${message}\n`;
   writeOutput(msg);
-  try { fs.writeSync(devLogFd, msg); } catch {}
+  try {
+    fs.writeSync(devLogFd, msg);
+  } catch (error) {
+    reportBestEffortFailure('write dev.log failed', error);
+  }
 }
 
 // ── Process group management ──────────────────────────────────────────────────
@@ -94,11 +156,20 @@ function killProcessGroup(pid, signal) {
 
 function killOrphansByPort(port) {
   try {
-    const pids = execSync(`lsof -ti :${port}`, { encoding: 'utf8', timeout: 5000 }).trim();
+    const pids = execSync(`lsof -ti :${port}`, {
+      encoding: 'utf8',
+      timeout: 5000,
+    }).trim();
     if (pids) {
       const pidList = pids.split('\n').filter(Boolean);
       for (const p of pidList) {
-        try { process.kill(parseInt(p, 10), 'SIGKILL'); } catch {}
+        try {
+          process.kill(parseInt(p, 10), 'SIGKILL');
+        } catch (error) {
+          if (error?.code !== 'ESRCH') {
+            reportBestEffortFailure('kill legacy port owner failed', error);
+          }
+        }
       }
       return pidList;
     }
@@ -111,18 +182,435 @@ let stopping = false;
 const managedProcesses = []; // { name, pid, child }
 
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function hasExactKeys(value, expected) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const actual = Object.keys(value).sort();
+  const sortedExpected = [...expected].sort();
+  return (
+    actual.length === sortedExpected.length &&
+    actual.every((key, index) => key === sortedExpected[index])
+  );
+}
+
+function readLinuxProcessIdentity(pid) {
+  if (process.platform !== 'linux' || !Number.isSafeInteger(pid) || pid <= 0)
+    return null;
+  try {
+    const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const commandEnd = stat.lastIndexOf(')');
+    if (commandEnd < 0) return null;
+    const fields = stat
+      .slice(commandEnd + 1)
+      .trim()
+      .split(/\s+/);
+    if (!/^\d+$/.test(fields[19] || '') || !/^\d+$/.test(fields[2] || ''))
+      return null;
+    return {
+      state: fields[0],
+      processStartTicks: fields[19],
+      processGroupId: Number(fields[2]),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function processIdentityIsLive(pid, expectedStartTicks) {
+  if (process.platform === 'linux') {
+    const identity = readLinuxProcessIdentity(pid);
+    return Boolean(
+      identity &&
+      identity.state !== 'Z' &&
+      identity.processStartTicks === expectedStartTicks
+    );
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readJsonNoFollow(file) {
+  try {
+    const parent = fs.lstatSync(path.dirname(file));
+    if (
+      parent.isSymbolicLink() ||
+      !parent.isDirectory() ||
+      (parent.mode & 0o777) !== 0o700 ||
+      (typeof process.getuid === 'function' && parent.uid !== process.getuid())
+    )
+      return null;
+    const before = fs.lstatSync(file);
+    if (
+      before.isSymbolicLink() ||
+      !before.isFile() ||
+      (before.mode & 0o777) !== 0o600 ||
+      (typeof process.getuid === 'function' && before.uid !== process.getuid())
+    )
+      return null;
+    const fd = fs.openSync(
+      file,
+      fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0)
+    );
+    try {
+      const opened = fs.fstatSync(fd);
+      if (
+        !opened.isFile() ||
+        before.dev !== opened.dev ||
+        before.ino !== opened.ino
+      )
+        return null;
+      return { payload: JSON.parse(fs.readFileSync(fd, 'utf8')), stat: opened };
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+
+function readStrictColdStartDecision() {
+  const decision = readJsonNoFollow(HANDOFF_DECISION_FILE)?.payload;
+  if (
+    !hasExactKeys(decision, [
+      'schemaVersion',
+      'appId',
+      'bootId',
+      'restoreEpochMs',
+      'publicPort',
+      'viteDepsCacheEnabled',
+      'nestBundleHandoffEnabled',
+    ]) ||
+    decision.schemaVersion !== 1 ||
+    typeof decision.appId !== 'string' ||
+    decision.appId.length === 0 ||
+    typeof decision.bootId !== 'string' ||
+    !/^[a-zA-Z0-9._:-]{1,128}$/.test(decision.bootId) ||
+    !Number.isSafeInteger(decision.restoreEpochMs) ||
+    decision.restoreEpochMs <= 0 ||
+    decision.publicPort !== PLATFORM_HANDOFF_PUBLIC_PORT ||
+    typeof decision.viteDepsCacheEnabled !== 'boolean' ||
+    decision.nestBundleHandoffEnabled !== true
+  ) {
+    return null;
+  }
+  return decision;
+}
+
+const OWNER_KEYS = [
+  'schemaVersion',
+  'bootId',
+  'restoreEpochMs',
+  'generationId',
+  'pid',
+  'processStartTicks',
+  'publicPort',
+  'createdAtMs',
+];
+
+function readStrictHandoffOwner() {
+  const opened = readJsonNoFollow(HANDOFF_OWNER_FILE);
+  const owner = opened?.payload;
+  if (
+    !hasExactKeys(owner, OWNER_KEYS) ||
+    owner.schemaVersion !== 1 ||
+    owner.bootId !== HANDOFF_BOOT_ID ||
+    owner.restoreEpochMs !== HANDOFF_RESTORE_EPOCH_MS ||
+    !/^[a-f0-9]{64}$/.test(owner.generationId || '') ||
+    !Number.isSafeInteger(owner.pid) ||
+    owner.pid <= 0 ||
+    !/^\d+$/.test(owner.processStartTicks || '') ||
+    owner.publicPort !== PUBLIC_SERVER_PORT ||
+    !Number.isSafeInteger(owner.createdAtMs) ||
+    owner.createdAtMs < HANDOFF_RESTORE_EPOCH_MS ||
+    !processIdentityIsLive(owner.pid, owner.processStartTicks)
+  )
+    return null;
+  return owner;
+}
+
+function publicServerReachable() {
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = reachable => {
+      if (settled) return;
+      settled = true;
+      resolve(reachable);
+    };
+    const request = http.get(
+      {
+        host: '127.0.0.1',
+        port: PUBLIC_SERVER_PORT,
+        path: '/__innerapi__/capability/list',
+      },
+      response => {
+        if (response.statusCode !== 200) {
+          response.resume();
+          response.once('end', () => finish(false));
+          return;
+        }
+        const chunks = [];
+        let responseBytes = 0;
+        response.on('data', chunk => {
+          if (settled) return;
+          const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          responseBytes += buffer.length;
+          if (responseBytes > MAX_HANDOFF_READINESS_RESPONSE_BYTES) {
+            response.destroy();
+            finish(false);
+            return;
+          }
+          chunks.push(buffer);
+        });
+        response.once('end', () => {
+          if (settled) return;
+          try {
+            const payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            finish(
+              payload?.status_code === '0' &&
+                payload.data &&
+                typeof payload.data === 'object' &&
+                !Array.isArray(payload.data) &&
+                Array.isArray(payload.data.capabilities)
+            );
+          } catch {
+            finish(false);
+          }
+        });
+        response.once('error', () => finish(false));
+      }
+    );
+    request.setTimeout(250, () => {
+      request.destroy();
+      finish(false);
+    });
+    request.once('error', () => finish(false));
+  });
+}
+
+function registryMatchesOwner(registry, owner) {
+  if (
+    !hasExactKeys(registry, [
+      'schemaVersion',
+      'bootId',
+      'restoreEpochMs',
+      'runtimePid',
+      'runtimeProcessStartTicks',
+      'updatedAtMs',
+      'processes',
+    ]) ||
+    registry.schemaVersion !== 1 ||
+    registry.bootId !== HANDOFF_BOOT_ID ||
+    registry.restoreEpochMs !== HANDOFF_RESTORE_EPOCH_MS ||
+    registry.runtimePid !== owner.pid ||
+    registry.runtimeProcessStartTicks !== owner.processStartTicks ||
+    !Number.isSafeInteger(registry.updatedAtMs) ||
+    registry.updatedAtMs < HANDOFF_RESTORE_EPOCH_MS ||
+    !Array.isArray(registry.processes)
+  )
+    return false;
+  const roles = new Set();
+  return registry.processes.every(owned => {
+    const valid =
+      hasExactKeys(owned, ['role', 'pid', 'processStartTicks']) &&
+      ['cache', 'source', 'action-plugin-init'].includes(owned.role) &&
+      !roles.has(owned.role) &&
+      Number.isSafeInteger(owned.pid) &&
+      owned.pid > 0 &&
+      /^\d+$/.test(owned.processStartTicks || '');
+    roles.add(owned.role);
+    return valid;
+  });
+}
+
+function ownedGroupIdentityMatches(owned) {
+  const leaderIdentity = readLinuxProcessIdentity(owned.pid);
+  if (
+    leaderIdentity &&
+    (leaderIdentity.processStartTicks !== owned.processStartTicks ||
+      leaderIdentity.processGroupId !== owned.pid)
+  ) {
+    return false;
+  }
+  // Linux reserves a numeric PGID while any member of that group remains, so
+  // the dead leader's PID cannot be reused until the leaderless owned group is
+  // empty. Re-check both PID identity and group existence immediately before
+  // every signal; if a new leader appeared, fail closed above.
+  if (!leaderIdentity) {
+    try {
+      process.kill(owned.pid, 0);
+      return false;
+    } catch (error) {
+      if (error?.code !== 'ESRCH') return false;
+    }
+  }
+  try {
+    for (const name of fs.readdirSync('/proc')) {
+      if (!/^\d+$/.test(name)) continue;
+      const member = readLinuxProcessIdentity(Number(name));
+      if (member?.processGroupId === owned.pid && member.state !== 'Z') {
+        const currentLeader = readLinuxProcessIdentity(owned.pid);
+        return Boolean(
+          !currentLeader ||
+          (currentLeader.processStartTicks === owned.processStartTicks &&
+            currentLeader.processGroupId === owned.pid)
+        );
+      }
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+function runtimeGroupIdentityMatches(owner) {
+  const identity = readLinuxProcessIdentity(owner.pid);
+  return Boolean(
+    identity &&
+    identity.state !== 'Z' &&
+    identity.processStartTicks === owner.processStartTicks &&
+    identity.processGroupId === owner.pid
+  );
+}
+
+async function terminateStrictRuntimeOwner(owner) {
+  if (process.platform !== 'linux' || !runtimeGroupIdentityMatches(owner))
+    return;
+  // Re-check pid birth identity and PGID immediately before every signal. A
+  // numeric pid from the marker is never sufficient authority after waiting.
+  if (runtimeGroupIdentityMatches(owner)) {
+    try {
+      process.kill(-owner.pid, 'SIGTERM');
+    } catch {}
+  }
+  const deadline = Date.now() + 2000;
+  while (Date.now() < deadline && runtimeGroupIdentityMatches(owner)) {
+    await sleep(25);
+  }
+  if (runtimeGroupIdentityMatches(owner)) {
+    try {
+      process.kill(-owner.pid, 'SIGKILL');
+    } catch {}
+  }
+  const killDeadline = Date.now() + 1000;
+  while (Date.now() < killDeadline && runtimeGroupIdentityMatches(owner)) {
+    await sleep(25);
+  }
+}
+
+async function cleanupDeadRuntimeRegistry(owner) {
+  if (process.platform !== 'linux') return;
+  const opened = readJsonNoFollow(HANDOFF_PROCESS_REGISTRY_FILE);
+  const registry = opened?.payload;
+  if (!opened || !registryMatchesOwner(registry, owner)) return;
+  for (const owned of registry.processes) {
+    if (!ownedGroupIdentityMatches(owned)) continue;
+    try {
+      process.kill(-owned.pid, 'SIGTERM');
+    } catch {}
+  }
+  const deadline = Date.now() + 2000;
+  while (
+    Date.now() < deadline &&
+    registry.processes.some(ownedGroupIdentityMatches)
+  ) {
+    await sleep(25);
+  }
+  for (const owned of registry.processes) {
+    if (!ownedGroupIdentityMatches(owned)) continue;
+    try {
+      process.kill(-owned.pid, 'SIGKILL');
+    } catch {}
+  }
+  const killDeadline = Date.now() + 1000;
+  while (
+    Date.now() < killDeadline &&
+    registry.processes.some(ownedGroupIdentityMatches)
+  ) {
+    await sleep(25);
+  }
+  try {
+    const after = fs.lstatSync(HANDOFF_PROCESS_REGISTRY_FILE);
+    if (
+      after.dev === opened.stat.dev &&
+      after.ino === opened.stat.ino &&
+      !registry.processes.some(ownedGroupIdentityMatches)
+    ) {
+      fs.unlinkSync(HANDOFF_PROCESS_REGISTRY_FILE);
+    }
+  } catch {}
+}
+
+function removeDeadOwnerMarker(owner) {
+  if (processIdentityIsLive(owner.pid, owner.processStartTicks)) return;
+  const opened = readJsonNoFollow(HANDOFF_OWNER_FILE);
+  const payload = opened?.payload;
+  if (
+    !opened ||
+    !hasExactKeys(payload, OWNER_KEYS) ||
+    payload.bootId !== owner.bootId ||
+    payload.restoreEpochMs !== owner.restoreEpochMs ||
+    payload.pid !== owner.pid ||
+    payload.processStartTicks !== owner.processStartTicks
+  )
+    return;
+  try {
+    const after = fs.lstatSync(HANDOFF_OWNER_FILE);
+    if (after.dev === opened.stat.dev && after.ino === opened.stat.ino) {
+      fs.unlinkSync(HANDOFF_OWNER_FILE);
+    }
+  } catch {}
+}
+
+function publicPortBindable() {
+  return new Promise(resolve => {
+    const server = net.createServer();
+    let settled = false;
+    const finish = bindable => {
+      if (settled) return;
+      settled = true;
+      server.close(() => resolve(bindable));
+    };
+    server.once('error', () => resolve(false));
+    server.listen(PUBLIC_SERVER_PORT, '127.0.0.1', () => finish(true));
+  });
+}
+
+async function waitForPublicPortRelease() {
+  while (!stopping) {
+    if (await publicPortBindable()) return true;
+    await sleep(50);
+  }
+  return false;
 }
 
 /**
  * Start and supervise a process with auto-restart and log piping.
  * Returns a promise that resolves when the process loop ends.
  */
-function startProcess({ name, command, args, cleanupPort }) {
+function startProcess({
+  name,
+  command,
+  args,
+  cleanupPort,
+  environment,
+  strictOwnership = false,
+}) {
   const logFilePath = path.join(LOG_DIR, `${name}.std.log`);
   const logFd = fs.openSync(logFilePath, 'a');
 
-  const entry = { name, pid: null, child: null };
+  const entry = {
+    name,
+    pid: null,
+    child: null,
+    processStartTicks: null,
+    strictOwnership,
+  };
   managedProcesses.push(entry);
 
   const run = async () => {
@@ -134,21 +622,41 @@ function startProcess({ name, command, args, cleanupPort }) {
         stdio: ['ignore', 'pipe', 'pipe'],
         shell: true,
         cwd: PROJECT_ROOT,
-        env: { ...process.env },
+        env: { ...process.env, ...environment },
       });
 
       entry.pid = child.pid;
       entry.child = child;
+      entry.processStartTicks = readLinuxProcessIdentity(
+        child.pid
+      )?.processStartTicks;
+      if (
+        strictOwnership &&
+        process.platform === 'linux' &&
+        !entry.processStartTicks
+      ) {
+        child.kill('SIGKILL');
+        throw new Error(`Strict process identity unavailable: ${name}`);
+      }
 
       const startTime = Date.now();
-      logEvent('INFO', name, `Process started (PGID: ${child.pid}): ${command} ${args.join(' ')}`);
+      logEvent(
+        'INFO',
+        name,
+        `Process started (PGID: ${child.pid}): ${command} ${args.join(' ')}`
+      );
 
       // Pipe stdout and stderr through readline for timestamped logging
-      const pipeLines = (stream) => {
-        const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-        rl.on('line', (line) => {
+      const pipeLines = stream => {
+        const rl = readline.createInterface({
+          input: stream,
+          crlfDelay: Infinity,
+        });
+        rl.on('line', line => {
           const msg = `[${timestamp()}] [${name}] ${line}\n`;
-          try { fs.writeSync(logFd, msg); } catch {}
+          try {
+            fs.writeSync(logFd, msg);
+          } catch {}
           writeOutput(msg);
         });
       };
@@ -159,25 +667,30 @@ function startProcess({ name, command, args, cleanupPort }) {
       // NOTE: must use 'exit', not 'close'. With shell:true, grandchild processes
       // (e.g. nest's server) inherit stdout pipes. 'close' won't fire until ALL
       // pipe holders exit, causing dev.js to hang when npm/nest dies but server survives.
-      const exitCode = await new Promise((resolve) => {
-        child.on('exit', (code) => resolve(code ?? 1));
+      const exitCode = await new Promise(resolve => {
+        child.on('exit', code => resolve(code ?? 1));
         child.on('error', () => resolve(1));
       });
 
       // Kill the entire process group
       if (entry.pid) {
-        killProcessGroup(entry.pid, 'SIGTERM');
+        signalManagedProcess(entry, 'SIGTERM');
         await sleep(2000);
-        killProcessGroup(entry.pid, 'SIGKILL');
+        signalManagedProcess(entry, 'SIGKILL');
       }
       entry.pid = null;
       entry.child = null;
+      entry.processStartTicks = null;
 
       // Port cleanup fallback
       if (cleanupPort) {
         const orphans = killOrphansByPort(cleanupPort);
         if (orphans.length > 0) {
-          logEvent('WARN', name, `Killed orphan processes on port ${cleanupPort}: ${orphans.join(' ')}`);
+          logEvent(
+            'WARN',
+            name,
+            `Killed orphan processes on port ${cleanupPort}: ${orphans.join(' ')}`
+          );
           await sleep(500);
         }
       }
@@ -187,26 +700,133 @@ function startProcess({ name, command, args, cleanupPort }) {
       const runDuration = (Date.now() - startTime) / 1000;
       if (runDuration >= 60) {
         restartCount = 0;
-        logEvent('INFO', name, `Ran for ${Math.round(runDuration)}s, resetting restart counter`);
+        logEvent(
+          'INFO',
+          name,
+          `Ran for ${Math.round(runDuration)}s, resetting restart counter`
+        );
       } else {
         restartCount++;
       }
       if (restartCount >= MAX_RESTART_COUNT) {
-        logEvent('ERROR', name, `Max restart count (${MAX_RESTART_COUNT}) reached, giving up`);
+        logEvent(
+          'ERROR',
+          name,
+          `Max restart count (${MAX_RESTART_COUNT}) reached, giving up`
+        );
         break;
       }
 
-      const delay = Math.min(RESTART_DELAY * (1 << Math.max(0, restartCount - 1)), MAX_DELAY);
-      logEvent('WARN', name, `Process exited with code ${exitCode}, restarting (${restartCount}/${MAX_RESTART_COUNT}) in ${delay}s...`);
+      const delay = Math.min(
+        RESTART_DELAY * (1 << Math.max(0, restartCount - 1)),
+        MAX_DELAY
+      );
+      logEvent(
+        'WARN',
+        name,
+        `Process exited with code ${exitCode}, restarting (${restartCount}/${MAX_RESTART_COUNT}) in ${delay}s...`
+      );
       await sleep(delay * 1000);
     }
 
-    try { fs.closeSync(logFd); } catch {}
+    try {
+      fs.closeSync(logFd);
+    } catch {}
   };
 
   return run();
 }
 
+function signalManagedProcess(entry, signal) {
+  if (!entry.pid) return;
+  if (entry.strictOwnership && process.platform === 'linux') {
+    if (
+      !ownedGroupIdentityMatches({
+        pid: entry.pid,
+        processStartTicks: entry.processStartTicks,
+      })
+    ) {
+      return;
+    }
+  }
+  killProcessGroup(entry.pid, signal);
+}
+
+function initializeActionPlugins() {
+  writeOutput('\n🔌 Initializing action plugins...\n');
+  try {
+    execSync('fullstack-cli action-plugin init', {
+      cwd: PROJECT_ROOT,
+      stdio: 'inherit',
+    });
+    writeOutput('✅ Action plugins initialized\n\n');
+  } catch {
+    writeOutput(
+      '⚠️  Action plugin initialization failed, continuing anyway...\n\n'
+    );
+  }
+}
+
+let handoffFailbackStarted = false;
+
+async function startHandoffFailback(owner, reason) {
+  if (handoffFailbackStarted || stopping) return;
+  handoffFailbackStarted = true;
+  logEvent(
+    'ERROR',
+    'handoff-watchdog',
+    `Backend owner lost (${reason}); taking over the public server lifecycle`
+  );
+  await terminateStrictRuntimeOwner(owner);
+  await cleanupDeadRuntimeRegistry(owner);
+  removeDeadOwnerMarker(owner);
+  if (!(await waitForPublicPortRelease())) return;
+  initializeActionPlugins();
+  void startProcess({
+    name: 'server',
+    command: 'npm',
+    args: ['run', 'dev:server'],
+    environment: {
+      SERVER_HOST: '127.0.0.1',
+      SERVER_PORT: String(PUBLIC_SERVER_PORT),
+    },
+    strictOwnership: true,
+    // Never use lsof/pkill in handoff failback. The strict per-boot registry is
+    // the only authority for removing the dead runtime's children.
+  });
+}
+
+async function monitorHandoffOwner(initialOwner) {
+  let expectedOwner = initialOwner;
+  let identityFailures = 0;
+  let portFailures = 0;
+  let stableSuccesses = 0;
+  while (!stopping && !handoffFailbackStarted) {
+    const currentOwner = readStrictHandoffOwner();
+    const reachable = await publicServerReachable();
+    if (currentOwner) {
+      expectedOwner = currentOwner;
+      identityFailures = 0;
+    } else {
+      identityFailures += 1;
+    }
+    portFailures = reachable ? 0 : portFailures + 1;
+    stableSuccesses = currentOwner && reachable ? stableSuccesses + 1 : 0;
+    if (identityFailures >= 2 || portFailures >= 5) {
+      await startHandoffFailback(
+        expectedOwner,
+        identityFailures >= 2
+          ? 'owner-identity-stale'
+          : 'public-port-unreachable'
+      );
+      return;
+    }
+    // Stay responsive while establishing health or after the first failure,
+    // then reduce steady-state readiness traffic from 5 QPS to below 1 QPS.
+    await sleep(stableSuccesses >= 3 ? 1500 : 200);
+  }
+}
+
 // ── Cleanup ───────────────────────────────────────────────────────────────────
 let cleanupDone = false;
 
@@ -221,7 +841,7 @@ async function cleanup() {
   for (const entry of managedProcesses) {
     if (entry.pid) {
       logEvent('INFO', 'main', `Stopping process group (PGID: ${entry.pid})`);
-      killProcessGroup(entry.pid, 'SIGTERM');
+      signalManagedProcess(entry, 'SIGTERM');
     }
   }
 
@@ -231,19 +851,27 @@ async function cleanup() {
   // Force kill any remaining
   for (const entry of managedProcesses) {
     if (entry.pid) {
-      logEvent('WARN', 'main', `Force killing process group (PGID: ${entry.pid})`);
-      killProcessGroup(entry.pid, 'SIGKILL');
+      logEvent(
+        'WARN',
+        'main',
+        `Force killing process group (PGID: ${entry.pid})`
+      );
+      signalManagedProcess(entry, 'SIGKILL');
     }
   }
 
   // Port cleanup fallback
-  killOrphansByPort(SERVER_PORT);
+  if (!BACKEND_OWNED_BY_HANDOFF) killOrphansByPort(LEGACY_SERVER_PORT);
   killOrphansByPort(CLIENT_DEV_PORT);
 
   logEvent('INFO', 'main', 'All processes stopped');
 
-  try { fs.closeSync(devStdLogFd); } catch {}
-  try { fs.closeSync(devLogFd); } catch {}
+  try {
+    fs.closeSync(devStdLogFd);
+  } catch {}
+  try {
+    fs.closeSync(devLogFd);
+  } catch {}
 
   process.exit(0);
 }
@@ -267,22 +895,35 @@ async function main() {
 
   cleanStaleDist();
 
-  // Initialize action plugins
-  writeOutput('\n🔌 Initializing action plugins...\n');
-  try {
-    execSync('fullstack-cli action-plugin init', { cwd: PROJECT_ROOT, stdio: 'inherit' });
-    writeOutput('✅ Action plugins initialized\n\n');
-  } catch {
-    writeOutput('⚠️  Action plugin initialization failed, continuing anyway...\n\n');
+  const initialHandoffOwner = BACKEND_OWNED_BY_HANDOFF
+    ? readStrictHandoffOwner()
+    : null;
+  const handoffOwnsBackend = Boolean(initialHandoffOwner);
+  if (BACKEND_OWNED_BY_HANDOFF && !handoffOwnsBackend) {
+    logEvent(
+      'WARN',
+      'handoff-watchdog',
+      'Static handoff claim has no matching live owner; using legacy backend ownership'
+    );
+  }
+
+  if (!handoffOwnsBackend) {
+    // Initialize action plugins. In handoff mode the backend runtime owns this
+    // predecessor and the source process as one lifecycle.
+    initializeActionPlugins();
   }
 
   // Start server and client
-  const serverPromise = startProcess({
-    name: 'server',
-    command: 'npm',
-    args: ['run', 'dev:server'],
-    cleanupPort: SERVER_PORT,
-  });
+  const serverPromise = handoffOwnsBackend
+    ? Promise.resolve()
+    : startProcess({
+        name: 'server',
+        command: 'npm',
+        args: ['run', 'dev:server'],
+        cleanupPort: BACKEND_OWNED_BY_HANDOFF ? undefined : LEGACY_SERVER_PORT,
+        strictOwnership: BACKEND_OWNED_BY_HANDOFF,
+      });
+  if (handoffOwnsBackend) void monitorHandoffOwner(initialHandoffOwner);
 
   const clientPromise = startProcess({
     name: 'client',
@@ -302,7 +943,7 @@ async function main() {
   }
 }
 
-main().catch((err) => {
+main().catch(err => {
   console.error('Fatal error:', err);
   process.exit(1);
 });