@fitlab-ai/agent-infra 0.8.3 → 0.8.5

package/lib/server/process-control.ts

@@ -1,9 +1,19 @@
 import fs from 'node:fs';
-import path from 'node:path';
 import { spawn, execFileSync } from 'node:child_process';
 import { loadServerConfig } from './config.ts';
 import type { ServerConfig } from './config.ts';
 import { runDaemon } from './daemon.ts';
+import {
+  getProcessStartTime,
+  isProcessAlive,
+  processIdentityMatches,
+  readProcessState,
+  removePidFileIfMatches,
+  writePidRecord
+} from './process-state.ts';
+import type { PidRecord } from './process-state.ts';
+
+export { isProcessAlive } from './process-state.ts';
 
 export type StartOptions = { foreground?: boolean };
 export type LogsOptions = { follow?: boolean };
@@ -20,59 +30,33 @@ export function buildStopCommand(pid: number, platform: NodeJS.Platform): StopCo
   }
   return { kind: 'signal', signal: 'SIGTERM' };
 }
-
-
-// Liveness check that treats an exited-but-unreaped daemon as dead.
-//
-// The daemon is spawned detached and re-parented to init when `ai server start`
-// exits. After it terminates, `process.kill(pid, 0)` still succeeds until init
-// reaps the zombie. On Linux we therefore also check /proc state so status/stop
-// /start don't treat an already-exited daemon as running. macOS reaps orphans
-// via launchd and Windows has no zombies, so the kill(pid, 0) result is enough.
-export function isProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-  } catch (error) {
-    // EPERM means the process exists but we may not signal it → still alive.
-    return (error as NodeJS.ErrnoException).code === 'EPERM';
-  }
-  if (process.platform === 'linux') {
-    try {
-      const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
-      // The process state is the first token after the parenthesised comm.
-      const state = stat.slice(stat.lastIndexOf(')') + 1).trim().charAt(0);
-      if (state === 'Z') return false;
-    } catch {
-      return false; // /proc entry vanished → not alive
-    }
-  }
-  return true;
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
 }
 
-function readPid(pidFile: string): number | null {
-  try {
-    const raw = fs.readFileSync(pidFile, 'utf8').trim();
-    const pid = Number.parseInt(raw, 10);
-    return Number.isInteger(pid) && pid > 0 ? pid : null;
-  } catch {
-    return null;
+async function waitForProcessIdentity(pid: number, timeoutMs = 2000): Promise<PidRecord | null> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const startTime = getProcessStartTime(pid);
+    if (startTime !== null) return { version: 1, pid, startTime };
+    await delay(25);
   }
+  return null;
 }
 
-function removePidFile(pidFile: string): void {
+function terminateIfMatching(record: PidRecord): void {
+  if (!processIdentityMatches(record)) return;
+  const command = buildStopCommand(record.pid, process.platform);
   try {
-    fs.unlinkSync(pidFile);
+    if (command.kind === 'exec') execFileSync(command.command, command.args);
+    else process.kill(record.pid, command.signal);
   } catch {
-    // Already gone.
+    // Best effort cleanup for a daemon whose PID record could not be published.
   }
 }
 
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
 function enabledAdapterNames(config: ServerConfig): string[] {
   return Object.entries(config.adapters)
     .filter(([, adapter]) => adapter?.enabled === true)
@@ -83,15 +67,13 @@ export async function start({ foreground = false }: StartOptions = {}): Promise<
   const config = loadServerConfig();
   const pidPath = config.pidFile;
 
-  // Zombie PID cleanup: a stale PID file from a crashed daemon must not block a
-  // fresh start.
-  const existing = readPid(pidPath);
-  if (existing !== null && isProcessAlive(existing)) {
-    process.stdout.write(`server already running (pid ${existing})\n`);
+  const existing = readProcessState(pidPath);
+  if (existing.kind === 'running') {
+    process.stdout.write(`server already running (pid ${existing.record.pid})\n`);
     return;
   }
-  if (existing !== null) {
-    removePidFile(pidPath);
+  if (existing.kind !== 'missing') {
+    removePidFileIfMatches(pidPath, existing.snapshot);
   }
 
   if (foreground) {
@@ -116,52 +98,69 @@ export async function start({ foreground = false }: StartOptions = {}): Promise<
   if (typeof child.pid !== 'number') {
     throw new Error('server: failed to spawn daemon process');
   }
-  fs.mkdirSync(path.dirname(pidPath), { recursive: true });
-  fs.writeFileSync(pidPath, `${child.pid}\n`);
-  process.stdout.write(`server started (pid ${child.pid})\n`);
+
+  // The initial check, spawn, and record publication are not a mutually
+  // exclusive transaction. Atomic publication keeps the record complete, but
+  // a separate locking design is required to serialize concurrent starts.
+  const record = await waitForProcessIdentity(child.pid);
+  if (record === null || !processIdentityMatches(record)) {
+    throw new Error('server: unable to verify spawned daemon process identity');
+  }
+  try {
+    writePidRecord(pidPath, record);
+  } catch (error) {
+    terminateIfMatching(record);
+    throw error;
+  }
+  process.stdout.write(`server started (pid ${record.pid})\n`);
 }
 
 export async function stop(): Promise<void> {
   const config = loadServerConfig();
-  const pid = readPid(config.pidFile);
+  const state = readProcessState(config.pidFile);
 
-  if (pid === null) {
+  if (state.kind === 'missing') {
     process.stdout.write('server is not running (no pid file)\n');
     return;
   }
-  if (!isProcessAlive(pid)) {
-    removePidFile(config.pidFile);
+  if (state.kind !== 'running') {
+    removePidFileIfMatches(config.pidFile, state.snapshot);
     process.stdout.write('server is not running (removed stale pid file)\n');
     return;
   }
 
-  const command = buildStopCommand(pid, process.platform);
+  const { record } = state;
+  if (!processIdentityMatches(record)) {
+    removePidFileIfMatches(config.pidFile, state.snapshot);
+    process.stdout.write('server is not running (removed stale pid file)\n');
+    return;
+  }
+
+  const command = buildStopCommand(record.pid, process.platform);
   if (command.kind === 'exec') {
     execFileSync(command.command, command.args);
   } else {
-    process.kill(pid, command.signal);
+    process.kill(record.pid, command.signal);
     const deadline = Date.now() + 5000;
-    while (isProcessAlive(pid) && Date.now() < deadline) {
+    while (isProcessAlive(record.pid) && Date.now() < deadline) {
       await delay(100);
     }
-    if (isProcessAlive(pid)) {
-      process.kill(pid, 'SIGKILL');
+    if (isProcessAlive(record.pid) && processIdentityMatches(record)) {
+      process.kill(record.pid, 'SIGKILL');
     }
   }
 
-  removePidFile(config.pidFile);
-  process.stdout.write(`server stopped (pid ${pid})\n`);
+  removePidFileIfMatches(config.pidFile, state.snapshot);
+  process.stdout.write(`server stopped (pid ${record.pid})\n`);
 }
 
 export function status(): void {
   const config = loadServerConfig();
-  const pid = readPid(config.pidFile);
+  const state = readProcessState(config.pidFile);
 
-  if (pid === null || !isProcessAlive(pid)) {
+  if (state.kind !== 'running') {
+    if (state.kind !== 'missing') removePidFileIfMatches(config.pidFile, state.snapshot);
     process.stdout.write('server: stopped\n');
-    if (pid !== null) {
-      process.stdout.write(`  (stale pid file references pid ${pid})\n`);
-    }
     return;
   }
 
@@ -174,7 +173,7 @@ export function status(): void {
   const adapters = enabledAdapterNames(config);
   process.stdout.write(
     `server: running\n` +
-      `  pid: ${pid}\n` +
+      `  pid: ${state.record.pid}\n` +
       `  started: ${startedAt}\n` +
       `  adapters: ${adapters.length > 0 ? adapters.join(', ') : '(none)'}\n` +
       `  pid file: ${config.pidFile}\n` +

package/lib/server/process-state.ts

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export type PidRecord = {
+  version: 1;
+  pid: number;
+  startTime: string;
+};
+
+export type ProcessStartTimeQuery = { command: string; args: string[] };
+
+export type ProcessState =
+  | { kind: 'missing'; snapshot: null }
+  | { kind: 'invalid'; snapshot: string }
+  | { kind: 'legacy'; snapshot: string; pid: number }
+  | { kind: 'stale'; snapshot: string; record: PidRecord }
+  | { kind: 'running'; snapshot: string; record: PidRecord };
+
+export type LinuxProcessStat = { state: string; startTime: string };
+
+export function parseLinuxProcessStat(raw: string): LinuxProcessStat | null {
+  const closeParen = raw.lastIndexOf(')');
+  if (closeParen < 0) return null;
+  const fields = raw.slice(closeParen + 1).trim().split(/\s+/);
+  const state = fields[0];
+  const startTime = fields[19];
+  if (typeof state !== 'string' || state.length !== 1 || !/^\d+$/.test(startTime ?? '')) {
+    return null;
+  }
+  return { state, startTime: startTime! };
+}
+
+export function buildProcessStartTimeQuery(
+  pid: number,
+  platform: NodeJS.Platform
+): ProcessStartTimeQuery | null {
+  if (platform === 'darwin') {
+    return { command: 'ps', args: ['-p', String(pid), '-o', 'lstart='] };
+  }
+  if (platform === 'win32') {
+    const script =
+      `$process = Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}'; ` +
+      `if ($null -ne $process) { $process.CreationDate.ToUniversalTime().ToString('o') }`;
+    return {
+      command: 'powershell.exe',
+      args: ['-NoProfile', '-NonInteractive', '-Command', script]
+    };
+  }
+  return null;
+}
+
+export function isProcessAlive(pid: number, platform: NodeJS.Platform = process.platform): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (platform === 'linux') {
+    try {
+      const stat = parseLinuxProcessStat(fs.readFileSync(`/proc/${pid}/stat`, 'utf8'));
+      return stat !== null && stat.state !== 'Z';
+    } catch {
+      return false;
+    }
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+export function getProcessStartTime(
+  pid: number,
+  platform: NodeJS.Platform = process.platform
+): string | null {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  if (platform === 'linux') {
+    try {
+      const stat = parseLinuxProcessStat(fs.readFileSync(`/proc/${pid}/stat`, 'utf8'));
+      return stat !== null && stat.state !== 'Z' ? stat.startTime : null;
+    } catch {
+      return null;
+    }
+  }
+  if (!isProcessAlive(pid, platform)) return null;
+  const query = buildProcessStartTimeQuery(pid, platform);
+  if (query === null) return null;
+  try {
+    const output = execFileSync(query.command, query.args, { encoding: 'utf8' }).trim();
+    if (output.length === 0) return null;
+    if (platform === 'win32') {
+      const timestamp = new Date(output);
+      return Number.isNaN(timestamp.getTime()) ? null : timestamp.toISOString();
+    }
+    return output;
+  } catch {
+    return null;
+  }
+}
+
+function parsePidRecord(raw: string): { kind: 'invalid' } | { kind: 'legacy'; pid: number } | { kind: 'record'; record: PidRecord } {
+  const trimmed = raw.trim();
+  if (/^[1-9]\d*$/.test(trimmed)) {
+    const pid = Number(trimmed);
+    return Number.isSafeInteger(pid) ? { kind: 'legacy', pid } : { kind: 'invalid' };
+  }
+  try {
+    const value = JSON.parse(trimmed) as Partial<PidRecord> | null;
+    if (
+      value !== null &&
+      value.version === 1 &&
+      Number.isSafeInteger(value.pid) &&
+      (value.pid ?? 0) > 0 &&
+      typeof value.startTime === 'string' &&
+      value.startTime.length > 0
+    ) {
+      return {
+        kind: 'record',
+        record: { version: 1, pid: value.pid!, startTime: value.startTime }
+      };
+    }
+  } catch {
+    // Invalid JSON is an invalid PID record.
+  }
+  return { kind: 'invalid' };
+}
+
+export function readProcessState(pidFile: string): ProcessState {
+  let snapshot: string;
+  try {
+    snapshot = fs.readFileSync(pidFile, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { kind: 'missing', snapshot: null };
+    return { kind: 'invalid', snapshot: '' };
+  }
+
+  const parsed = parsePidRecord(snapshot);
+  if (parsed.kind === 'invalid') return { kind: 'invalid', snapshot };
+  if (parsed.kind === 'legacy') return { kind: 'legacy', snapshot, pid: parsed.pid };
+
+  const currentStartTime = getProcessStartTime(parsed.record.pid);
+  if (currentStartTime === null || currentStartTime !== parsed.record.startTime) {
+    return { kind: 'stale', snapshot, record: parsed.record };
+  }
+  return { kind: 'running', snapshot, record: parsed.record };
+}
+
+export function writePidRecord(pidFile: string, record: PidRecord): void {
+  fs.mkdirSync(path.dirname(pidFile), { recursive: true });
+  const temporary = `${pidFile}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(record)}\n`);
+    fs.renameSync(temporary, pidFile);
+  } catch (error) {
+    try {
+      fs.unlinkSync(temporary);
+    } catch {
+      // The temporary file was never created or was already renamed.
+    }
+    throw error;
+  }
+}
+
+export function removePidFileIfMatches(pidFile: string, expectedSnapshot: string | null): boolean {
+  if (expectedSnapshot === null) return false;
+  try {
+    if (fs.readFileSync(pidFile, 'utf8') !== expectedSnapshot) return false;
+    fs.unlinkSync(pidFile);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function removePidRecordIfMatches(pidFile: string, expected: PidRecord): boolean {
+  const state = readProcessState(pidFile);
+  if (state.kind !== 'running') return false;
+  if (state.record.pid !== expected.pid || state.record.startTime !== expected.startTime) return false;
+  return removePidFileIfMatches(pidFile, state.snapshot);
+}
+
+export function processIdentityMatches(record: PidRecord): boolean {
+  return getProcessStartTime(record.pid) === record.startTime;
+}

package/lib/update.ts

@@ -194,6 +194,12 @@ async function cmdUpdate(): Promise<void> {
     platformType
   );
   ok('Updated .agents/skills/update-agent-infra/');
+  renderFile(
+    path.join(templateDir, '.agents', 'scripts', 'lib', 'agent-infra-package.js'),
+    path.join('.agents', 'scripts', 'lib', 'agent-infra-package.js'),
+    replacements
+  );
+  ok('Updated .agents/scripts/lib/agent-infra-package.js');
   try {
     fs.unlinkSync(path.join('.agents', 'skills', 'update-agent-infra', 'scripts', 'sync-templates.cjs'));
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,7 @@
     "!dist/**/*.map",
     "bin/cli.ts",
     "lib/",
+    "runtime/",
     "templates/"
   ],
   "engines": {