tokenmaxxing 0.19.1 → 1.0.0

package/src/lib/keychain.ts

@@ -11,8 +11,15 @@ const KeychainTargetSchema = z.object({ service: z.string(), account: z.string()
 export type KeychainTarget = z.infer<typeof KeychainTargetSchema>;
 
 const SECURITY = "/usr/bin/security";
-// security(1) interactive mode has a ~4KB line buffer; above this we must use argv.
-const INTERACTIVE_MAX = 3800;
+// security(1) interactive mode has a 4096-byte line buffer. The gate below
+// measures the ASSEMBLED line against this (with margin), never the raw
+// secret: quoteDouble expansion (one byte per `"`/`\` when the blob contains
+// an apostrophe) once pushed a raw-length-passing line over the buffer, which
+// SPLITS the line - the write exits 1 ("unknown command" for the spilled
+// remainder) AND the item is left holding a TRUNCATED secret (empirically
+// verified 2026-07-20: a 3667-byte secret assembling to a 5574-byte line
+// corrupted the item to its first 2682 bytes before the error surfaced).
+const INTERACTIVE_MAX_LINE = 4000;
 
 /** Double-quote + backslash-escape for security(1)'s interactive tokenizer. */
 function quoteDouble(s: string): string {
@@ -24,26 +31,40 @@ function quoteValue(s: string): string {
   return s.includes("'") ? quoteDouble(s) : `'${s}'`;
 }
 
-/** Read an item's password blob. Returns null if the item does not exist. */
+/** Read an item's password blob. Returns null ONLY when the item verifiably
+ *  does not exist (exit 44, errSecItemNotFound - empirically pinned on this
+ *  Mac 2026-07-20). Every other failure THROWS: a locked keychain or denied
+ *  ACL prompt reading as "absent" silently disarmed every fail-closed
+ *  live-owner guard and the mandatory pre-swap harvest, all of which key off
+ *  a null read (closing-review catch). stderr never carries the secret. */
 export async function readItem(t: KeychainTarget): Promise<string | null> {
   const p = Bun.spawn([SECURITY, "find-generic-password", "-s", t.service, "-a", t.account, "-w"], {
     stdout: "pipe",
-    stderr: "ignore",
+    stderr: "pipe",
   });
-  const out = await new Response(p.stdout).text();
+  const [out, err] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
   await p.exited;
-  if (p.exitCode !== 0) return null; // 44 = not found
+  if (p.exitCode === 44) return null;
+  if (p.exitCode !== 0) {
+    throw new Error(`keychain read failed (exit ${p.exitCode}): ${err.trim().slice(0, 200)} - a locked keychain or denied ACL must fail loudly, never read as absent`);
+  }
   return out.replace(/\n$/, ""); // security appends exactly one trailing newline
 }
 
-/** ps-safe write: the command line + secret arrive on stdin, never in argv.
- *  Bounded by security(1)'s ~4KB interactive line buffer. */
-async function writeViaInteractive(t: KeychainTarget, secret: string): Promise<void> {
-  const line =
+/** The full `security -i` line for a write; its LENGTH is the argv-fallback
+ *  gate, so it is assembled once, here. */
+function interactiveLine(t: KeychainTarget, secret: string): string {
+  return (
     `add-generic-password -U -a ${quoteDouble(t.account)} -s ${quoteDouble(t.service)} ` +
-    `-w ${quoteValue(secret)}\n`;
+    `-w ${quoteValue(secret)}\n`
+  );
+}
+
+/** ps-safe write: the command line + secret arrive on stdin, never in argv.
+ *  The caller guarantees the encoded line fits the interactive buffer. */
+async function writeViaInteractive(encodedLine: Uint8Array): Promise<void> {
   const p = Bun.spawn([SECURITY, "-i"], {
-    stdin: new TextEncoder().encode(line),
+    stdin: encodedLine,
     stdout: "ignore",
     stderr: "pipe",
   });
@@ -66,10 +87,15 @@ async function writeViaArgv(t: KeychainTarget, secret: string): Promise<void> {
 }
 
 /** Create-or-update an item (`-U`) with `secret` as its password. Prefers the
- *  ps-safe stdin path; falls back to argv only when the blob exceeds the ~4KB
- *  interactive line limit. Throws on failure. */
+ *  ps-safe stdin path; falls back to argv when the ASSEMBLED interactive line
+ *  would exceed the buffer (see INTERACTIVE_MAX_LINE - gating on the raw
+ *  secret length let quote expansion corrupt the item). Throws on failure. */
 export async function writeItem(t: KeychainTarget, secret: string): Promise<void> {
-  if (secret.length <= INTERACTIVE_MAX) return writeViaInteractive(t, secret);
+  // measured in UTF-8 BYTES, the unit the stdin buffer actually consumes:
+  // String.length counts UTF-16 code units and under-counts multibyte
+  // characters (cubic review catch, PR #35).
+  const encoded = new TextEncoder().encode(interactiveLine(t, secret));
+  if (encoded.length <= INTERACTIVE_MAX_LINE) return writeViaInteractive(encoded);
   return writeViaArgv(t, secret);
 }
 

package/src/lib/lock.ts

@@ -2,57 +2,79 @@
 // descriptor (macOS ships no flock(1) binary, and one codepath serves both
 // platforms). The lock is released when we close the fd (explicitly or on
 // process exit).
+//
+// The acquire is NON-BLOCKING (LOCK_EX|LOCK_NB) with an async retry loop: a
+// blocking LOCK_EX from this runtime freezes the whole event loop, and in
+// `xx serve` (many actors, one process) a second actor's blocking acquire
+// would stop the holder from ever resuming to release - a true single-process
+// deadlock; a cross-process holder would freeze the daemon for its whole
+// critical section (adversarial review catch, 2026-07-19). EWOULDBLOCK is
+// told apart from real failures via errno, so a bad fd still fails fast
+// instead of spinning.
 
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { dirname } from "node:path";
-import { dlopen, FFIType, suffix } from "bun:ffi";
+import { dlopen, FFIType, read } from "bun:ffi";
+import { delay } from "es-toolkit";
 
 // sys/file.h (identical on darwin + linux): LOCK_SH=1 LOCK_EX=2 LOCK_NB=4 LOCK_UN=8
 const LOCK_EX = 2;
+const LOCK_NB = 4;
 const LOCK_UN = 8;
+// errno.h: EWOULDBLOCK/EAGAIN is 35 on darwin, 11 on linux; EINTR is 4 on both.
+const EAGAIN = process.platform === "darwin" ? 35 : 11;
+const EINTR = 4;
+const RETRY_MS = 75;
 
-let _flock: ((fd: number, op: number) => number) | null = null;
+const FLOCK_DEF = { flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 } } as const;
 
-function flockFn(): (fd: number, op: number) => number {
-  if (_flock) return _flock;
-  // darwin: flock(2) is in libSystem; the bare name resolves via the dyld shared
-  // cache even though no physical .dylib exists on disk (verified 2026-07-08).
-  // linux: glibc's libc.so.6 (verified in-container 2026-07-09, arm64).
-  const candidates =
-    process.platform === "darwin"
-      ? ["libSystem.B.dylib", "/usr/lib/libSystem.B.dylib", `libc.${suffix}`]
-      : [`libc.so.6`, `libc.${suffix}`];
-  let lib: ReturnType<typeof dlopen> | null = null;
-  let lastErr: unknown;
-  for (const path of candidates) {
-    try {
-      lib = dlopen(path, {
-        flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
-      });
-      break;
-    } catch (e) {
-      lastErr = e;
-    }
+// darwin: flock(2) + __error live in libSystem; the bare name resolves via the
+// dyld shared cache even though no physical .dylib exists on disk (verified
+// 2026-07-08). linux: glibc's libc.so.6 + __errno_location (verified
+// in-container 2026-07-09, arm64). Exactly one verified path per platform -
+// a broken environment fails fast instead of falling through a guess list.
+function loadLibc() {
+  if (process.platform === "darwin") {
+    const lib = dlopen("libSystem.B.dylib", { ...FLOCK_DEF, __error: { args: [], returns: FFIType.ptr } });
+    return { flock: lib.symbols.flock, errnoPtr: lib.symbols.__error };
   }
-  if (!lib) throw new Error(`could not load flock(2): ${String(lastErr)}`);
-  const sym = lib.symbols.flock as unknown as (fd: number, op: number) => number;
-  _flock = sym;
-  return _flock;
+  const lib = dlopen("libc.so.6", { ...FLOCK_DEF, __errno_location: { args: [], returns: FFIType.ptr } });
+  return { flock: lib.symbols.flock, errnoPtr: lib.symbols.__errno_location };
+}
+
+let _libc: ReturnType<typeof loadLibc> | null = null;
+
+function libc(): ReturnType<typeof loadLibc> {
+  _libc ??= loadLibc();
+  return _libc;
+}
+
+function currentErrno(): number {
+  const p = libc().errnoPtr();
+  return p == null ? -1 : read.i32(p, 0);
 }
 
 /**
- * Acquire an exclusive advisory lock on `lockPath`, blocking until available.
- * Returns a handle whose release() drops the lock. The lock is process-scoped
- * (held via an open fd) so racing hooks in separate processes serialize.
+ * Acquire an exclusive advisory lock on `lockPath`, waiting (without blocking
+ * the event loop) until available. Returns a handle whose release() drops the
+ * lock. The lock is fd-scoped, so racing hooks in separate processes serialize
+ * and same-process actors queue on the retry loop.
  */
-export function acquireLock(lockPath: string): { release: () => void } {
+export async function acquireLock(lockPath: string): Promise<{ release: () => void }> {
   mkdirSync(dirname(lockPath), { recursive: true });
   const fd = openSync(lockPath, "a", 0o600);
-  const flock = flockFn();
-  const rc = flock(fd, LOCK_EX);
-  if (rc !== 0) {
+  const { flock } = libc();
+  try {
+    while (flock(fd, LOCK_EX | LOCK_NB) !== 0) {
+      const errno = currentErrno();
+      if (errno !== EAGAIN && errno !== EINTR) {
+        throw new Error(`flock LOCK_EX|LOCK_NB failed on ${lockPath} (errno ${errno})`);
+      }
+      await delay(RETRY_MS);
+    }
+  } catch (e) {
     closeSync(fd);
-    throw new Error(`flock LOCK_EX failed on ${lockPath} (rc=${rc})`);
+    throw e;
   }
   let released = false;
   const release = () => {
@@ -69,7 +91,7 @@ export function acquireLock(lockPath: string): { release: () => void } {
 
 /** Run `fn` while holding `lockPath`; always releases, even on throw. */
 export async function withLock<T>(lockPath: string, fn: () => Promise<T> | T): Promise<T> {
-  const held = acquireLock(lockPath);
+  const held = await acquireLock(lockPath);
   try {
     return await fn();
   } finally {

package/src/lib/log.ts

@@ -1,28 +1,57 @@
 // Append-only logging. NEVER logs secret material - callers must pass only
 // non-secret context (account uuids/emails, percentages, status strings).
 
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { z } from "zod";
 import { paths } from "./paths.ts";
 
+const LOG_MAX_BYTES = 5_000_000;
+
 /** Redact anything that looks like a token so an accidental pass-through can't leak. */
-export function redact(s: string): string {
+function redact(s: string): string {
   return s
     // JWT-ish / long opaque tokens
     .replace(/\b(sk-ant-[A-Za-z0-9._-]{6,})/g, "sk-ant-***")
     .replace(/\b([A-Za-z0-9_-]{40,})\b/g, (m) => `${m.slice(0, 4)}...(${m.length})`);
 }
 
+let echo: ((input: { event: string; parts: string }) => void) | null = null;
+
+/** Tee every subsequent log() line to a terminal printer. Only the serve
+ *  daemon opts in: hooks and the statusline own their stdout protocol, so the
+ *  echo stays off by default. The printer receives the same redacted parts the
+ *  file line gets. */
+export function setLogEcho(input: { printer: (input: { event: string; parts: string }) => void }): void {
+  echo = input.printer;
+}
+
 export function log(event: string, fields: Record<string, unknown> = {}): void {
+  let line = "";
   try {
+    line = Object.entries(fields)
+      .map(([k, v]) => {
+        const str = z.string().safeParse(v);
+        return `${k}=${redact(str.success ? str.data : JSON.stringify(v))}`;
+      })
+      .join(" ");
     mkdirSync(dirname(paths.logFile), { recursive: true });
-    const parts = Object.entries(fields).map(([k, v]) => {
-      const str = z.string().safeParse(v);
-      return `${k}=${redact(str.success ? str.data : JSON.stringify(v))}`;
-    });
-    appendFileSync(paths.logFile, `${new Date().toISOString()} ${event} ${parts.join(" ")}\n`);
+    // Rotation cap: the check timer logs every 180s and the serve daemon
+    // echoes every event, so an uncapped append-only file grows forever on a
+    // live install (closing-review critic gap). One .old generation bounds
+    // total disk at ~2x the cap; older history is disposable diagnostics.
+    if (existsSync(paths.logFile) && statSync(paths.logFile).size > LOG_MAX_BYTES) {
+      renameSync(paths.logFile, `${paths.logFile}.old`);
+    }
+    appendFileSync(paths.logFile, `${new Date().toISOString()} ${event} ${line}\n`);
   } catch {
     // logging must never throw into a hook / supervisor path
   }
+  // separate from the file sink: an unwritable log file must not also silence
+  // the terminal echo (that is exactly when the daemon needs to stay visible).
+  try {
+    echo?.({ event, parts: line });
+  } catch {
+    // the echo printer must never throw into the daemon either
+  }
 }

package/src/lib/oauth.ts

@@ -8,12 +8,16 @@
 //      live to answer HTTP 200 with plain Bearer auth (with or without the
 //      oauth beta header - we send it to match the CLI's OAuth convention).
 
-import { http } from "./http.ts";
+import { z } from "zod";
+import { http, safeErrorDetail } from "./http.ts";
 import { RefreshResponseSchema, RolesResponseSchema, type OAuthCreds, type RolesResponse } from "./types.ts";
 
-const TOKEN_URL = process.env.TOKENMAXXING_OAUTH_TOKEN_URL ?? "https://platform.claude.com/v1/oauth/token";
-const CLIENT_ID = process.env.TOKENMAXXING_OAUTH_CLIENT_ID ?? "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
-const ROLES_URL = process.env.TOKENMAXXING_OAUTH_ROLES_URL ?? "https://api.anthropic.com/api/oauth/claude_cli/roles";
+// zod-parsed like every other env override (repo rule): a set-but-EMPTY value
+// parses to undefined and the default applies, instead of posting to "".
+const EnvOverrideSchema = z.string().min(1).optional().catch(undefined);
+const TOKEN_URL = EnvOverrideSchema.parse(process.env.TOKENMAXXING_OAUTH_TOKEN_URL) ?? "https://platform.claude.com/v1/oauth/token";
+const CLIENT_ID = EnvOverrideSchema.parse(process.env.TOKENMAXXING_OAUTH_CLIENT_ID) ?? "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+const ROLES_URL = EnvOverrideSchema.parse(process.env.TOKENMAXXING_OAUTH_ROLES_URL) ?? "https://api.anthropic.com/api/oauth/claude_cli/roles";
 
 const DEFAULT_SCOPES = [
   "user:profile",
@@ -53,23 +57,26 @@ export async function refreshCredential(creds: OAuthCreds, now = Date.now()): Pr
       body: JSON.stringify(body),
     });
   } catch (e) {
-    throw new Error(`token endpoint unreachable: ${String((e as Error).message ?? e)}`);
+    throw new Error(`token endpoint unreachable: ${e instanceof Error ? e.message : String(e)}`);
   }
 
   const text = await res.text();
   if (!res.ok) {
     // invalid_grant → dead refresh token; anything else is transient/unknown.
+    // Bodies go through the safeErrorDetail allowlist, never raw: a token
+    // endpoint's failure body can echo request material.
     if (res.status === 400 && /invalid_grant/.test(text)) {
-      throw new InvalidGrantError(text.slice(0, 200));
+      throw new InvalidGrantError(safeErrorDetail({ text }));
     }
-    throw new Error(`token refresh failed (HTTP ${res.status}): ${text.slice(0, 200)}`);
+    throw new Error(`token refresh failed (HTTP ${res.status}): ${safeErrorDetail({ text })}`);
   }
 
   const parsed = RefreshResponseSchema.safeParse((() => {
     try { return JSON.parse(text); } catch { return null; }
   })());
   if (!parsed.success) {
-    throw new Error(`token endpoint returned unexpected body: ${text.slice(0, 120)}`);
+    // A success-status body holds live tokens: never echo any of it.
+    throw new Error(`token endpoint returned an unrecognized body (${text.length} bytes, withheld)`);
   }
   const json = parsed.data;
 
@@ -105,13 +112,13 @@ export async function fetchTokenOrg(accessToken: string): Promise<RolesResponse>
       headers: { Authorization: `Bearer ${accessToken}`, "anthropic-beta": "oauth-2025-04-20" },
     });
   } catch (e) {
-    throw new Error(`roles endpoint unreachable: ${String((e as Error).message ?? e)}`);
+    throw new Error(`roles endpoint unreachable: ${e instanceof Error ? e.message : String(e)}`);
   }
   const text = await res.text();
-  if (!res.ok) throw new Error(`roles check failed (HTTP ${res.status}): ${text.slice(0, 140)}`);
+  if (!res.ok) throw new Error(`roles check failed (HTTP ${res.status}): ${safeErrorDetail({ text })}`);
   const parsed = RolesResponseSchema.safeParse((() => {
     try { return JSON.parse(text); } catch { return null; }
   })());
-  if (!parsed.success) throw new Error(`roles endpoint returned unexpected body: ${text.slice(0, 120)}`);
+  if (!parsed.success) throw new Error(`roles endpoint returned an unrecognized body (${text.length} bytes, withheld)`);
   return parsed.data;
 }

package/src/lib/paths.ts

@@ -16,7 +16,7 @@ function env(name: string, fallback: string): string {
 }
 
 /** Root of all tokenmaxxing config + state. Default ~/.config/tokenmaxxing. */
-export const TM_HOME = env("TOKENMAXXING_HOME", join(HOME, ".config", "tokenmaxxing"));
+const TM_HOME = env("TOKENMAXXING_HOME", join(HOME, ".config", "tokenmaxxing"));
 
 export const paths = {
   home: TM_HOME,
@@ -25,6 +25,8 @@ export const paths = {
   usageJson: join(TM_HOME, "usage.json"),
   modelUsageJson: join(TM_HOME, "model-usage.json"),
   lastSwapJson: join(TM_HOME, "lastswap.json"),
+  /** the last depleted-wait decision, replayed to sibling hooks (self-expiring). */
+  depletedJson: join(TM_HOME, "depleted.json"),
   respawnDir: join(TM_HOME, "respawn"),
   binDir: join(TM_HOME, "bin"),
   supervisorLink: join(TM_HOME, "bin", "claude"),
@@ -36,20 +38,23 @@ export const paths = {
   credsDir: join(TM_HOME, "creds"),
 
   /** `xx serve` slack bridge: tokens + channel->repo links (0600: holds the
-   *  xoxb-/xapp- tokens), per-thread claude session records, and the git
-   *  worktrees threads run in. */
+   *  xoxb-/xapp- tokens), per-thread claude session records, and the
+   *  single-instance flock (a new daemon generation blocks on it until the
+   *  previous one - possibly still draining an in-flight turn - fully exits,
+   *  so two generations never act on the same thread records or cwd). */
   slackJson: join(TM_HOME, "slack.json"),
   slackThreadsDir: join(TM_HOME, "slack-threads"),
-  slackWorktreesDir: join(TM_HOME, "slack-worktrees"),
+  serveLockFile: join(TM_HOME, "serve-lock"),
 
   /** ~/.claude.json - holds the active `oauthAccount` identity object. */
   claudeJson: env("TOKENMAXXING_CLAUDE_JSON", join(HOME, ".claude.json")),
-  /** ~/.claude/settings.json - user-owned; we merge three entries into it. */
+  /** ~/.claude/settings.json - user-owned; we merge four entries into it. */
   claudeSettings: env(
     "TOKENMAXXING_CLAUDE_SETTINGS",
     join(env("CLAUDE_CONFIG_DIR", join(HOME, ".claude")), "settings.json"),
   ),
-  /** ~/.claude - for the credential-refresh lock and projects/ transcripts. */
+  /** ~/.claude - claude's config dir (settings.json, projects/ transcripts;
+   *  credDir() falls back to it). */
   claudeDir: env("CLAUDE_CONFIG_DIR", join(HOME, ".claude")),
 
   /** where the periodic-check timer units live (launchd / systemd user). */
@@ -57,11 +62,6 @@ export const paths = {
   systemdUserDir: env("TOKENMAXXING_SYSTEMD_USER_DIR", join(HOME, ".config", "systemd", "user")),
 } as const;
 
-/** Claude's own credential-refresh lock (verified path filled from facts). */
-export function claudeLockPath(): string {
-  return env("TOKENMAXXING_CLAUDE_LOCK", join(HOME, ".claude.lock"));
-}
-
 /** Codex home: where the live auth.json lives. Test override first, then
  *  codex's own CODEX_HOME env, then its default ~/.codex. */
 const CODEX_HOME = env("TOKENMAXXING_CODEX_HOME", env("CODEX_HOME", join(HOME, ".codex")));
@@ -86,6 +86,12 @@ export const codexPaths = {
    *  running account's parked token must never be refreshed or targeted (its
    *  live rotations supersede the parked copy, and reuse is punished). */
   presenceDir: join(TM_HOME, "codex-live"),
+  /** cross-session reconcile signals, one file per supervisorId: a deciding
+   *  actor saw that supervisor's session running on a pooled NON-LIVE account
+   *  (healthy or not - owner decisions 2026-07-20) while the live seat is
+   *  usable; the session's OWN Stop hook promotes the signal into a respawn
+   *  marker at its next turn boundary. */
+  reconcileDir: join(TM_HOME, "codex-reconcile"),
 } as const;
 
 /** Per-account parked codex credential file name: tokenmaxxing-codex-<id8>. */

package/src/lib/picker.ts

@@ -75,7 +75,10 @@ function blockingUntil(a: Account, ctx: PickCtx): number[] {
           blockedUntil(u.sevenDay, WEEK_MS, a.lastUsageAt, ctx.thresholds.weekly),
         ]
       : []),
-    ...gatedPerModelWindows(a, ctx.switchFamilies).map((w) => blockedUntil(w, WEEK_MS, a.lastUsageAt, ctx.thresholds.weekly)),
+    // per-model rows date by their OWN sample time when known: lastUsageAt
+    // advances on every engaged evaluation while the rows may be days older,
+    // which inflated the null-reset self-bound (closing-review catch).
+    ...gatedPerModelWindows(a, ctx.switchFamilies).map((w) => blockedUntil(w, WEEK_MS, a.lastPerModelAt ?? a.lastUsageAt, ctx.thresholds.weekly)),
   ];
 }
 
@@ -127,10 +130,15 @@ export function pacePressure(a: Account, now: number): number {
 /** The switch preference: furthest behind its own weekly pace first (highest
  *  pacePressure), tiebreak soonest weekly expiry then lowest 7-day usage.
  *  Ranks swaps only; display surfaces order by earliestReset instead. */
-export const swapPreference = (now: number) => [
+const swapPreference = (now: number) => [
   (a: Account) => -pacePressure(a, now),
   (a: Account) => weeklyExpiry(a, now),
-  (a: Account) => a.lastUsage?.sevenDay.usedPercentage ?? 0,
+  // unmeasured ranks LAST in this tiebreak (101 > any real percentage):
+  // `?? 0` made a never-sampled account look maximally safe and beat any
+  // measured one, swapping a healthy measured seat onto a complete unknown -
+  // the exact unmeasured-must-not-look-safe rule (closing-review catch);
+  // pacePressure already ranks unmeasured last by the same principle.
+  (a: Account) => a.lastUsage?.sevenDay.usedPercentage ?? 101,
 ];
 
 export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {

package/src/lib/proc.ts

@@ -0,0 +1,37 @@
+// Process identity beyond a bare PID: pids recycle, so anything that must act
+// on "the process I recorded earlier" (reaping an orphan, trusting a presence
+// file) pins pid + start time and treats a mismatch as a different process.
+
+import { z } from "zod";
+
+/** The ps lstart token for a pid, or null when no such process. pid + start
+ *  time is the standard process identity: equality with the token captured
+ *  at spawn proves this is still the SAME process, never a recycled pid.
+ *  LC_ALL=C pins the lstart rendering (cubic review catch): the capturing and
+ *  the comparing process can run under different locales (terminal vs
+ *  launchd), and a formatting mismatch would silently break the identity.
+ *  Tradeoff (flagged and accepted): lstart has one-second resolution, so a
+ *  pid recycled onto a process started within the SAME wall-clock second
+ *  would pass - landing on the exact pid AND second is vanishingly unlikely,
+ *  and finer start-time sources are per-platform native calls ps cannot give. */
+export function pidStartTime(pid: number): string | null {
+  const res = Bun.spawnSync(["ps", "-p", String(pid), "-o", "lstart="], { env: { ...process.env, LC_ALL: "C" } });
+  if (res.exitCode !== 0) return null;
+  const lstart = res.stdout.toString().trim();
+  return lstart === "" ? null : lstart;
+}
+
+/** Whether the pid names a LIVE process (signal-0 probe); EPERM still proves
+ *  existence. Distinguishes "pid is dead" from "ps could not answer", which a
+ *  null pidStartTime alone cannot. */
+export function pidExists(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    const errno = z.object({ code: z.string() }).safeParse(e);
+    if (errno.success && errno.data.code === "ESRCH") return false;
+    if (errno.success && errno.data.code === "EPERM") return true;
+    throw e;
+  }
+}