@fitlab-ai/agent-infra 0.9.6 → 0.9.7

package/lib/sandbox/recovery.ts

@@ -35,7 +35,7 @@ import {
   type SandboxWorkspaceIdentity
 } from './workspace-identity.ts';
 import { inspectWorktree, type WorktreeSnapshot } from './worktree-safety.ts';
-import { runEngine, runOkEngine, runVerboseEngine } from './shell.ts';
+import { commandForEngine, runEngine, runOkEngine, runProbe, runVerboseEngine } from './shell.ts';
 import {
   declaredTmpfsSeedEntries,
   resolveTools,
@@ -52,12 +52,16 @@ import {
 import { getProcessStartTime, processIdentityMatches, removePidFileIfMatches } from '../server/process-state.ts';
 import {
   acquireSandboxControlBrokerStartup,
-  isSandboxControlRootQuiescing
+  garbageCollectSandboxControlRoot,
+  isSandboxControlRootQuiescing,
+  readSandboxControlManifest,
+  type BrokerOwner
 } from './control/lifecycle.ts';
 import {
   appendSandboxControlAudit,
   readSandboxControlStatus
 } from './control/state.ts';
+import { inspectSandboxControlContainer } from './control/container-identity.ts';
 import {
   SANDBOX_CONTROL_FUTURE_SKEW_MS,
   SANDBOX_CONTROL_STATUS_STALE_MS,
@@ -142,8 +146,27 @@ type RecoveryCommandDeps = {
   start?: typeof startSandboxContainer;
   fetchRows?: typeof fetchSandboxRows;
   ensureControlBroker?: () => void | Promise<void>;
+  probe?: typeof runProbe;
 };
 
+export function worktreeProbeForEngine(
+  engine: string,
+  probe: typeof runProbe = runProbe
+): typeof runProbe {
+  return (cmd, args, opts = {}) => {
+    const engineArgs = [...args];
+    if (engine === 'wsl2' && cmd === 'git') {
+      for (let index = 0; index < engineArgs.length - 1; index += 1) {
+        if (engineArgs[index] === '-C') {
+          engineArgs[index + 1] = toEnginePath(engine, engineArgs[index + 1]!);
+        }
+      }
+    }
+    const command = commandForEngine(engine, cmd, engineArgs);
+    return probe(command.cmd, command.args, opts);
+  };
+}
+
 type EnsureSandboxReadyParams = {
   config: SandboxConfig;
   engine: string;
@@ -151,6 +174,7 @@ type EnsureSandboxReadyParams = {
   workspace?: SandboxWorkspaceIdentity;
   row: SandboxRow;
   allowRecreate?: boolean;
+  forceRecreate?: boolean;
   recreate?: (branch: string) => Promise<void>;
   writeWarning?: (message: string) => void;
   deps?: RecoveryCommandDeps;
@@ -168,7 +192,7 @@ async function waitForSandboxControlBrokerStatus(params: {
   statusDir: string;
   generation: string;
   pid: number;
-  startTime?: string;
+  startTime?: number;
 }, timeoutMs = 5_000): Promise<void> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
@@ -191,7 +215,7 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
   const directory = path.dirname(fileURLToPath(import.meta.url));
   const extension = path.extname(fileURLToPath(import.meta.url));
   const internalCli = path.resolve(directory, '..', '..', 'bin', `internal-cli${extension}`);
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as SandboxControlManifest;
+  const manifest = readSandboxControlManifest(manifestPath);
   const root = path.dirname(manifestPath);
   if (isSandboxControlRootQuiescing(root)) throw new Error('SANDBOX_CONTROL_QUIESCING');
   const brokerPath = path.join(root, 'broker.json');
@@ -207,6 +231,7 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
       version?: unknown;
       pid?: unknown;
       startTime?: unknown;
+      brokerId?: unknown;
       token?: unknown;
       generation?: unknown;
     };
@@ -216,15 +241,22 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
     } catch {
       // Malformed owner records are stale and replaced below.
     }
-    const owner = broker !== null && typeof broker.pid === 'number' && typeof broker.startTime === 'string'
-      ? { version: 1 as const, pid: broker.pid, startTime: broker.startTime }
+    const owner = broker !== null && broker.version === 3 && typeof broker.pid === 'number'
+      && Number.isSafeInteger(broker.pid) && broker.pid > 0 && typeof broker.startTime === 'number'
+      && Number.isSafeInteger(broker.startTime) && typeof broker.brokerId === 'string'
+      && broker.brokerId.length > 0 && typeof broker.token === 'string'
+      && typeof broker.generation === 'string'
+      ? broker as BrokerOwner
       : null;
-    const live = owner !== null && processIdentityMatches(owner);
+    if (broker === null || broker.version !== 3 || owner === null) {
+      throw new Error('SANDBOX_CONTROL_BROKER_VERSION_INVALID: rebuild the sandbox container before starting a new broker');
+    }
+    const live = owner !== null && processIdentityMatches({ pid: owner.pid, startTime: owner.startTime });
     if (
       live
       && owner !== null
       && broker !== null
-      && broker.version === 2
+      && broker.version === 3
       && broker.token === manifest.token
       && broker.generation === manifest.generation
     ) {
@@ -237,27 +269,6 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
       });
       return;
     }
-    if (live && owner) {
-      const deadline = Date.now() + 5_000;
-      while (Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, 25));
-        try {
-          if (fs.readFileSync(brokerPath, 'utf8') !== brokerSnapshot) {
-            return startSandboxControlBroker(repoRoot, manifestPath);
-          }
-        } catch (error) {
-          if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-            return startSandboxControlBroker(repoRoot, manifestPath);
-          }
-          throw error;
-        }
-        if (!processIdentityMatches(owner)) {
-          removePidFileIfMatches(brokerPath, brokerSnapshot);
-          return startSandboxControlBroker(repoRoot, manifestPath);
-        }
-      }
-      throw new Error('SANDBOX_CONTROL_BROKER_OWNER_ACTIVE');
-    }
   }
   const startupStartTime = getProcessStartTime(process.pid);
   if (!startupStartTime) throw new Error('SANDBOX_CONTROL_BROKER_IDENTITY_UNAVAILABLE');
@@ -317,9 +328,16 @@ async function ensureSandboxControlBroker(params: {
     identity: params.workspace
   });
   if (!fs.existsSync(control.manifestPath)) return;
-  const manifest = JSON.parse(fs.readFileSync(control.manifestPath, 'utf8')) as SandboxControlManifest;
-  if (manifest.version !== 3) {
-    throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 3; container-only recreation is required');
+  const validatedManifest = readSandboxControlManifest(control.manifestPath);
+  const containerObservation = await inspectSandboxControlContainer(validatedManifest);
+  if (containerObservation.state === 'unknown') {
+    throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${containerObservation.reason}`);
+  }
+  if (containerObservation.state === 'absent') {
+    await garbageCollectSandboxControlRoot(control.root, {
+      inspectContainer: (timeoutMs) => inspectSandboxControlContainer(validatedManifest, { timeoutMs })
+    });
+    throw new Error('SANDBOX_CONTROL_CONTAINER_ABSENT: recreate the sandbox container before broker recovery');
   }
   const brokerPath = path.join(control.root, 'broker.json');
   try {
@@ -327,20 +345,25 @@ async function ensureSandboxControlBroker(params: {
       version?: unknown;
       pid?: unknown;
       startTime?: unknown;
+      brokerId?: unknown;
       token?: unknown;
       generation?: unknown;
     };
     if (
-      broker.version === 2
+      broker.version === 3
       && typeof broker.pid === 'number'
-      && typeof broker.startTime === 'string'
-      && broker.token === manifest.token
-      && broker.generation === manifest.generation
-      && processIdentityMatches({ version: 1, pid: broker.pid, startTime: broker.startTime })
+      && Number.isSafeInteger(broker.pid)
+      && typeof broker.startTime === 'number'
+      && Number.isSafeInteger(broker.startTime)
+      && typeof broker.brokerId === 'string'
+      && broker.brokerId.length > 0
+      && broker.token === validatedManifest.token
+      && broker.generation === validatedManifest.generation
+      && processIdentityMatches({ pid: broker.pid, startTime: broker.startTime })
     ) {
       try {
         const status = readSandboxControlStatus(control.statusDir);
-        if (status.generation === manifest.generation && status.broker.pid === broker.pid
+        if (status.generation === validatedManifest.generation && status.broker.pid === broker.pid
           && status.broker.startTime === broker.startTime
           && Date.now() - status.updatedAt <= SANDBOX_CONTROL_STATUS_STALE_MS
           && status.updatedAt <= Date.now() + SANDBOX_CONTROL_FUTURE_SKEW_MS) return;
@@ -350,7 +373,7 @@ async function ensureSandboxControlBroker(params: {
       await waitForSandboxControlBrokerStatus({
         root: control.root,
         statusDir: control.statusDir,
-        generation: manifest.generation,
+        generation: validatedManifest.generation,
         pid: broker.pid,
         startTime: broker.startTime
       });
@@ -1048,6 +1071,9 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
         workspace: params.workspace ?? { mode: 'branch-only' }
       });
     }
+    if (params.forceRecreate) {
+      throw new Error('Explicit container recreation requested.');
+    }
     if (!params.row.running) {
       startFn(params.engine, params.row.name);
       const initial = assess({
@@ -1192,7 +1218,8 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
       `SANDBOX_RECOVERY_WORKTREE_SNAPSHOT_INVALID: expected exactly one existing worktree for '${params.branch}', found ${existingWorktrees.length}. ${remediation}`
     );
   }
-  const beforeInspection = inspectWorktree(existingWorktrees[0]!);
+  const worktreeProbe = worktreeProbeForEngine(params.engine, deps?.probe);
+  const beforeInspection = inspectWorktree(existingWorktrees[0]!, { probe: worktreeProbe });
   if (beforeInspection.status === 'failed') {
     throw new Error(`SANDBOX_RECOVERY_WORKTREE_SNAPSHOT_INVALID: ${beforeInspection.message}`);
   }
@@ -1204,7 +1231,9 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
     );
   }
 
-  const warning = `Sandbox recovery failed in place. Replacing only the container. ${dataBoundary}`;
+  const warning = params.forceRecreate
+    ? `Explicit sandbox recreation requested. Replacing only the container. ${dataBoundary}`
+    : `Sandbox recovery failed in place. Replacing only the container. ${dataBoundary}`;
   warnings.push(warning);
   (params.writeWarning ?? ((message) => process.stderr.write(`${message}\n`)))(warning);
   const runVerboseFn = deps?.runVerbose ?? runVerboseEngine;
@@ -1245,7 +1274,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
     replacementFailure = error;
   }
 
-  const afterInspection = inspectWorktree(before.worktree);
+  const afterInspection = inspectWorktree(before.worktree, { probe: worktreeProbe });
   if (afterInspection.status === 'failed' || afterInspection.snapshot.identity !== before.identity) {
     const detail = afterInspection.status === 'failed'
       ? afterInspection.message

package/lib/sandbox/workspace-view.ts

@@ -47,6 +47,7 @@ export function sandboxWorkspaceViewPaths(params: Readonly<{
 }
 
 export type SandboxControlSetup = Readonly<{
+  root: string;
   channelDir: string;
   statusDir: string;
   manifestPath: string;
@@ -84,44 +85,6 @@ function assertSafeDirectory(directory: string, expectedBase: string): void {
   }
 }
 
-function assertSafeMountTargetPath(target: string, worktreeRoot: string, canonicalWorktreeRoot: string): void {
-  const relative = path.relative(worktreeRoot, target);
-  if (relative.startsWith('..') || path.isAbsolute(relative)) {
-    throw new Error(`Sandbox workspace mount target escapes its worktree: ${target}`);
-  }
-  let current = worktreeRoot;
-  for (const segment of ['', ...relative.split(path.sep).filter(Boolean)]) {
-    current = segment ? path.join(current, segment) : current;
-    try {
-      if (fs.lstatSync(current).isSymbolicLink()) {
-        throw new Error(`Sandbox workspace mount target must not contain a symbolic link: ${current}`);
-      }
-      const canonicalRelative = path.relative(canonicalWorktreeRoot, fs.realpathSync.native(current));
-      if (canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative)) {
-        throw new Error(`Sandbox workspace mount target escapes its real worktree: ${current}`);
-      }
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
-    }
-  }
-}
-
-export function prepareSandboxWorkspaceMountTargets(worktreeRoot: string): void {
-  const resolvedWorktreeRoot = path.resolve(worktreeRoot);
-  const canonicalWorktreeRoot = fs.realpathSync.native(resolvedWorktreeRoot);
-  const workspaceRoot = path.resolve(resolvedWorktreeRoot, '.agents', 'workspace');
-  const statePaths = sandboxWorkspaceViewStatePaths(workspaceRoot);
-  const registryTarget = path.join(workspaceRoot, 'active', '.short-ids.json');
-  for (const target of [workspaceRoot, ...statePaths.map(({ hostPath }) => hostPath), registryTarget]) {
-    assertSafeMountTargetPath(target, resolvedWorktreeRoot, canonicalWorktreeRoot);
-  }
-  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 });
-  for (const { hostPath } of statePaths) {
-    fs.mkdirSync(hostPath, { recursive: true, mode: 0o700 });
-  }
-  fs.closeSync(fs.openSync(registryTarget, 'a', 0o600));
-}
-
 export function assertSandboxTaskSource(repoRoot: string, taskId: string): string {
   if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
   const activeRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace', 'active'));
@@ -137,6 +100,43 @@ export function assertSandboxTaskSource(repoRoot: string, taskId: string): strin
   return canonical;
 }
 
+export function prepareSandboxWorkspaceMountTarget(worktreeRoot: string): string {
+  const worktree = path.resolve(worktreeRoot);
+  const canonicalWorktree = fs.realpathSync.native(worktree);
+  const agentsRoot = path.join(worktree, '.agents');
+  if (fs.existsSync(agentsRoot)) {
+    const agentsStat = fs.lstatSync(agentsRoot);
+    if (!agentsStat.isDirectory() || agentsStat.isSymbolicLink()) {
+      throw new Error(`Sandbox workspace mount ancestor must be a real directory: ${agentsRoot}`);
+    }
+  } else {
+    fs.mkdirSync(agentsRoot, { mode: 0o700 });
+  }
+  const canonicalAgents = fs.realpathSync.native(agentsRoot);
+  if (path.dirname(canonicalAgents) !== canonicalWorktree) {
+    throw new Error(`Sandbox workspace mount ancestor escapes the worktree: ${agentsRoot}`);
+  }
+
+  const target = path.join(agentsRoot, 'workspace');
+  if (fs.existsSync(target)) {
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Sandbox workspace mount target must not be a symbolic link: ${target}`);
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`Sandbox workspace mount target must be a directory: ${target}`);
+    }
+    if (path.dirname(fs.realpathSync.native(target)) !== canonicalAgents) {
+      throw new Error(`Sandbox workspace mount target escapes the worktree: ${target}`);
+    }
+  } else {
+    fs.mkdirSync(target, { mode: 0o700 });
+  }
+  fs.chmodSync(target, 0o700);
+  fs.accessSync(target, fs.constants.W_OK);
+  return target;
+}
+
 export function materializeSandboxWorkspaceView(params: Readonly<{
   base: string;
   project: string;
@@ -180,6 +180,7 @@ export function materializeSandboxControl(params: Readonly<{
   container: string;
   branch: string;
   identity: SandboxWorkspaceIdentity;
+  engine?: string;
 }>): SandboxControlSetup {
   const { root, channelDir, statusDir, processingDir, manifestPath } = sandboxControlPaths(params);
   assertSafeDirectory(root, path.resolve(params.base));
@@ -201,11 +202,13 @@ export function materializeSandboxControl(params: Readonly<{
   const generation = randomBytes(16).toString('hex');
   const repoRoot = fs.realpathSync.native(params.repoRoot);
   const manifest: SandboxControlManifest = {
-    version: 3,
+    version: 4,
+    engine: params.engine ?? 'docker',
     repoRoot,
     worktreeRoot: fs.realpathSync.native(params.worktreeRoot),
     project: params.project,
     container: params.container,
+    containerIdentity: { id: '', labels: {} },
     branch: params.branch,
     mode: params.identity.mode,
     taskId: params.identity.mode === 'task-bound' ? params.identity.taskId : null,
@@ -216,5 +219,23 @@ export function materializeSandboxControl(params: Readonly<{
     processingDir
   };
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
-  return { channelDir, statusDir, manifestPath, token, generation };
+  return { root, channelDir, statusDir, manifestPath, token, generation };
+}
+
+export function finalizeSandboxControlManifest(
+  setup: SandboxControlSetup,
+  identity: Readonly<{ engine: string; id: string; labels: Readonly<Record<string, string>> }>
+): void {
+  if (!identity.engine || !identity.id) throw new Error('SANDBOX_CONTROL_CONTAINER_ID_INVALID');
+  const manifest = JSON.parse(fs.readFileSync(setup.manifestPath, 'utf8')) as Record<string, unknown>;
+  manifest.version = 4;
+  manifest.engine = identity.engine;
+  manifest.containerIdentity = { id: identity.id, labels: { ...identity.labels } };
+  const temporary = `${setup.manifestPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(manifest)}\n`, { mode: 0o600, flag: 'wx' });
+    fs.renameSync(temporary, setup.manifestPath);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
 }

package/lib/server/daemon.ts

@@ -139,7 +139,7 @@ export async function runDaemon(): Promise<void> {
       logger.close();
       if (ownStartTime !== null) {
         removePidRecordIfMatches(config.pidFile, {
-          version: 1,
+          version: 2,
           pid: process.pid,
           startTime: ownStartTime
         });

package/lib/server/process-control.ts

@@ -11,7 +11,7 @@ import {
   removePidFileIfMatches,
   writePidRecord
 } from './process-state.ts';
-import type { PidRecord } from './process-state.ts';
+import type { PidRecord, ProcessIdentity, ProcessState } from './process-state.ts';
 
 export { isProcessAlive } from './process-state.ts';
 
@@ -51,13 +51,13 @@ async function waitForProcessIdentity(pid: number, timeoutMs = 2000): Promise<Pi
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     const startTime = getProcessStartTime(pid);
-    if (startTime !== null) return { version: 1, pid, startTime };
+    if (startTime !== null) return { version: 2, pid, startTime };
     await delay(25);
   }
   return null;
 }
 
-function terminateIfMatching(record: PidRecord): void {
+function terminateIfMatching(record: ProcessIdentity): void {
   if (!processIdentityMatches(record)) return;
   const command = buildStopCommand(record.pid, process.platform);
   try {
@@ -83,6 +83,9 @@ export async function start({ foreground = false }: StartOptions = {}): Promise<
     process.stdout.write(`server already running (pid ${existing.record.pid})\n`);
     return;
   }
+  if (existing.kind === 'legacy-json' || existing.kind === 'legacy-pid-only' || existing.kind === 'legacy-unknown') {
+    throw new Error('server: legacy pid record requires the matching previous version to stop it before starting');
+  }
   if (existing.kind !== 'missing') {
     removePidFileIfMatches(pidPath, existing.snapshot);
   }
@@ -135,6 +138,9 @@ export async function stop(): Promise<void> {
     return;
   }
   if (state.kind !== 'running') {
+    if (state.kind === 'legacy-json' || state.kind === 'legacy-pid-only' || state.kind === 'legacy-unknown') {
+      throw new Error('server: legacy pid record requires the matching previous version to stop it');
+    }
     removePidFileIfMatches(config.pidFile, state.snapshot);
     process.stdout.write('server is not running (removed stale pid file)\n');
     return;
@@ -170,6 +176,10 @@ export function status(): void {
   const state = readProcessState(config.pidFile);
 
   if (state.kind !== 'running') {
+    if (state.kind === 'legacy-json' || state.kind === 'legacy-pid-only' || state.kind === 'legacy-unknown') {
+      process.stdout.write('server: legacy pid record requires the matching previous version to stop it\n');
+      return;
+    }
     if (state.kind !== 'missing') removePidFileIfMatches(config.pidFile, state.snapshot);
     process.stdout.write('server: stopped\n');
     return;

package/lib/server/process-state.ts

@@ -2,22 +2,34 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 
-export type PidRecord = {
-  version: 1;
+export type ProcessStartTime = number;
+
+export type ProcessIdentity = Readonly<{
   pid: number;
-  startTime: string;
+  startTime: ProcessStartTime;
+}>;
+
+export type PidRecord = ProcessIdentity & {
+  version: 2;
 };
 
 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: 'legacy-json'; snapshot: string; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-pid-only'; snapshot: string; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-unknown'; snapshot: string; legacy: LegacyProcessSnapshot; reason: string }
   | { kind: 'stale'; snapshot: string; record: PidRecord }
   | { kind: 'running'; snapshot: string; record: PidRecord };
 
-export type LinuxProcessStat = { state: string; startTime: string };
+export type LegacyProcessSnapshot = Readonly<{
+  pid?: number;
+  raw: string;
+  format: 'json-v1' | 'pid-only' | 'malformed';
+}>;
+
+export type LinuxProcessStat = { state: string; startTime: number };
 
 export function parseLinuxProcessStat(raw: string): LinuxProcessStat | null {
   const closeParen = raw.lastIndexOf(')');
@@ -28,7 +40,9 @@ export function parseLinuxProcessStat(raw: string): LinuxProcessStat | null {
   if (typeof state !== 'string' || state.length !== 1 || !/^\d+$/.test(startTime ?? '')) {
     return null;
   }
-  return { state, startTime: startTime! };
+  const numericStartTime = Number(startTime);
+  if (!Number.isSafeInteger(numericStartTime)) return null;
+  return { state, startTime: numericStartTime };
 }
 
 export function buildProcessStartTimeQuery(
@@ -68,10 +82,22 @@ export function isProcessAlive(pid: number, platform: NodeJS.Platform = process.
   }
 }
 
+function parseDarwinStartTime(output: string): number | null {
+  const match = output.trim().match(/^(?:Sun|Mon|Tue|Wed|Thu|Fri|Sat) ([A-Z][a-z]{2}) (\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/);
+  if (!match) return null;
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const month = months.indexOf(match[1]!);
+  if (month < 0) return null;
+  const timestamp = Date.UTC(
+    Number(match[6]), month, Number(match[2]), Number(match[3]), Number(match[4]), Number(match[5])
+  );
+  return Number.isNaN(timestamp) ? null : timestamp;
+}
+
 export function getProcessStartTime(
   pid: number,
   platform: NodeJS.Platform = process.platform
-): string | null {
+): ProcessStartTime | null {
   if (!Number.isInteger(pid) || pid <= 0) return null;
   if (platform === 'linux') {
     try {
@@ -85,43 +111,71 @@ export function getProcessStartTime(
   const query = buildProcessStartTimeQuery(pid, platform);
   if (query === null) return null;
   try {
-    const output = execFileSync(query.command, query.args, { encoding: 'utf8' }).trim();
+    const output = execFileSync(query.command, query.args, {
+      encoding: 'utf8',
+      env: platform === 'darwin' ? { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } : process.env
+    }).trim();
     if (output.length === 0) return null;
     if (platform === 'win32') {
       const timestamp = new Date(output);
-      return Number.isNaN(timestamp.getTime()) ? null : timestamp.toISOString();
+      return Number.isNaN(timestamp.getTime()) ? null : timestamp.getTime();
     }
-    return output;
+    if (platform === 'darwin') return parseDarwinStartTime(output);
+    return null;
   } catch {
     return null;
   }
 }
 
-function parsePidRecord(raw: string): { kind: 'invalid' } | { kind: 'legacy'; pid: number } | { kind: 'record'; record: PidRecord } {
+function parsePidRecord(
+  raw: string
+):
+  | { kind: 'legacy-json'; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-pid-only'; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-unknown'; legacy: LegacyProcessSnapshot; reason: string }
+  | { 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' };
+    return Number.isSafeInteger(pid)
+      ? { kind: 'legacy-pid-only', legacy: { pid, raw, format: 'pid-only' } }
+      : { kind: 'legacy-unknown', legacy: { raw, format: 'malformed' }, reason: 'pid is not a safe integer' };
   }
   try {
-    const value = JSON.parse(trimmed) as Partial<PidRecord> | null;
+    const value = JSON.parse(trimmed) as { version?: unknown; pid?: unknown; startTime?: unknown } | null;
+    const pidValue: unknown = value?.pid;
+    const startTimeValue: unknown = value?.startTime;
     if (
       value !== null &&
-      value.version === 1 &&
-      Number.isSafeInteger(value.pid) &&
-      (value.pid ?? 0) > 0 &&
-      typeof value.startTime === 'string' &&
-      value.startTime.length > 0
+      value.version === 2 &&
+      typeof pidValue === 'number' &&
+      Number.isSafeInteger(pidValue) &&
+      pidValue > 0 &&
+      typeof startTimeValue === 'number' &&
+      Number.isSafeInteger(startTimeValue) &&
+      startTimeValue >= 0
     ) {
+      const startTime = startTimeValue as number;
       return {
         kind: 'record',
-        record: { version: 1, pid: value.pid!, startTime: value.startTime }
+        record: { version: 2, pid: pidValue, startTime }
       };
     }
+    if (
+      value !== null &&
+      value.version === 1 &&
+      typeof pidValue === 'number' &&
+      Number.isSafeInteger(pidValue) &&
+      pidValue > 0 &&
+      typeof value.startTime === 'string' &&
+      value.startTime.length > 0
+    ) {
+      return { kind: 'legacy-json', legacy: { pid: pidValue, raw, format: 'json-v1' } };
+    }
+    return { kind: 'legacy-unknown', legacy: { raw, format: 'malformed' }, reason: 'unsupported PID record schema' };
   } catch {
-    // Invalid JSON is an invalid PID record.
+    return { kind: 'legacy-unknown', legacy: { raw, format: 'malformed' }, reason: 'invalid PID record JSON' };
   }
-  return { kind: 'invalid' };
 }
 
 export function readProcessState(pidFile: string): ProcessState {
@@ -130,12 +184,13 @@ export function readProcessState(pidFile: string): ProcessState {
     snapshot = fs.readFileSync(pidFile, 'utf8');
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { kind: 'missing', snapshot: null };
-    return { kind: 'invalid', snapshot: '' };
+    return { kind: 'legacy-unknown', snapshot: '', legacy: { raw: '', format: 'malformed' }, reason: 'PID record cannot be read' };
   }
 
   const parsed = parsePidRecord(snapshot);
-  if (parsed.kind === 'invalid') return { kind: 'invalid', snapshot };
-  if (parsed.kind === 'legacy') return { kind: 'legacy', snapshot, pid: parsed.pid };
+  if (parsed.kind === 'legacy-json') return { kind: parsed.kind, snapshot, legacy: parsed.legacy };
+  if (parsed.kind === 'legacy-pid-only') return { kind: parsed.kind, snapshot, legacy: parsed.legacy };
+  if (parsed.kind === 'legacy-unknown') return { kind: parsed.kind, snapshot, legacy: parsed.legacy, reason: parsed.reason };
 
   const currentStartTime = getProcessStartTime(parsed.record.pid);
   if (currentStartTime === null || currentStartTime !== parsed.record.startTime) {
@@ -178,6 +233,6 @@ export function removePidRecordIfMatches(pidFile: string, expected: PidRecord):
   return removePidFileIfMatches(pidFile, state.snapshot);
 }
 
-export function processIdentityMatches(record: PidRecord): boolean {
-  return getProcessStartTime(record.pid) === record.startTime;
+export function processIdentityMatches(identity: ProcessIdentity): boolean {
+  return getProcessStartTime(identity.pid) === identity.startTime;
 }