total-recall-brain 3.22.0 → 3.23.0

package/src/core/mesh.mjs

@@ -6,19 +6,33 @@ import {
   findVfsDocumentByPath,
   listVfsDocumentsUnder,
 } from './vfs-documents.mjs';
+import { logger } from './logger.mjs';
+import { STATUS_TIMEOUT_MS, resolveTailscaleBinary } from './tailscale-cli.mjs';
 
 const CACHE_MS = 2_000;
+
 let cachedStatus = null;
 let cachedAt = 0;
 
 function readMeshStatus() {
   if (cachedStatus && Date.now() - cachedAt < CACHE_MS) return cachedStatus;
-  const result = spawnSync('tailscale', ['status', '--json'], {
+  // The CLI is not on PATH for macOS GUI installs, where it lives inside the
+  // app bundle — so resolve it the same way enrollment does.
+  const result = spawnSync(resolveTailscaleBinary(), ['status', '--json'], {
     encoding: 'utf8',
-    timeout: 2_000,
-    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: STATUS_TIMEOUT_MS,
+    stdio: ['ignore', 'pipe', 'pipe'],
   });
-  if (result.status !== 0 || !result.stdout) return null;
+  if (result.status !== 0 || !result.stdout) {
+    // Silence here is what made the failure indistinguishable from "no peers".
+    logger.info(
+      'mesh',
+      `Could not read mesh status: ${
+        result.error?.message || (result.stderr || '').trim().slice(0, 200) || 'no output'
+      }`,
+    );
+    return null;
+  }
   try {
     cachedStatus = JSON.parse(result.stdout);
     cachedAt = Date.now();
@@ -50,6 +64,21 @@ export function meshNodeDocSlug(hostname) {
   return slug || 'unknown-node';
 }
 
+/**
+ * Canonical identity for a node, independent of DNS suffix.
+ *
+ * A tailnet appends its own domain, so the same machine appears as `box`,
+ * `box.mesh`, and `box.mesh.example.org` depending on who is asking and when
+ * the tailnet was last renamed. Keying entities on the full name therefore
+ * mints a fresh duplicate document every time that suffix changes, which is
+ * how one host ended up with several entities describing it.
+ */
+export function meshNodeKey(hostname) {
+  const base = normalizeHostname(hostname);
+  if (!base) return '';
+  return meshNodeDocSlug(String(base).split('.')[0] || base);
+}
+
 function normalizeNode(node, self = false) {
   return {
     hostname: normalizeHostname(node?.DNSName) || node?.HostName || null,
@@ -105,24 +134,24 @@ export function mergeLivePeersWithEntities(peers, entities = []) {
   const byHost = new Map();
   const byIp = new Map();
   for (const ent of entities) {
-    const host = normalizeHostname(ent.hostname);
+    const host = meshNodeKey(ent.hostname);
     if (host) byHost.set(host, ent);
     if (ent.ip) byIp.set(String(ent.ip), ent);
   }
 
   const merged = peers.map((peer) => {
-    const host = normalizeHostname(peer.hostname);
+    const host = meshNodeKey(peer.hostname);
     const ent = (host && byHost.get(host)) || (peer.ip && byIp.get(String(peer.ip))) || null;
     return enrichPeerWithEntity(peer, ent);
   });
 
   const seen = new Set(
-    merged.map((m) => normalizeHostname(m.hostname) || m.ip).filter(Boolean),
+    merged.map((m) => meshNodeKey(m.hostname) || m.ip).filter(Boolean),
   );
 
   // Vault-only entities (registered but not currently on the mesh).
   for (const ent of entities) {
-    const key = normalizeHostname(ent.hostname) || ent.ip;
+    const key = meshNodeKey(ent.hostname) || ent.ip;
     if (!key || seen.has(key)) continue;
     seen.add(key);
     merged.push(
@@ -175,6 +204,9 @@ function enrichPeerWithEntity(peer, ent, extra = {}) {
         ? ent.interfaces
         : [],
     io: peer.io || ent?.io || null,
+    // Access is entity-only: the control server has no idea which account you
+    // log in as, so live discovery can never supply or override it.
+    access: ent?.access || null,
   };
 }
 
@@ -218,14 +250,111 @@ export function attachSelfInterfaces(nodes, interfacesSummary = null) {
 
 function findEntityForSelf(self, vaultRoot) {
   const entities = listMeshNodeEntities(vaultRoot);
-  const host = normalizeHostname(self.hostname);
+  const host = meshNodeKey(self.hostname);
   return (
-    entities.find((e) => normalizeHostname(e.hostname) === host) ||
+    entities.find((e) => meshNodeKey(e.hostname) === host) ||
     entities.find((e) => e.ip && self.ip && String(e.ip) === String(self.ip)) ||
     null
   );
 }
 
+/** Find an enriched node (live + vault) by hostname or address. */
+export function findMeshNode(nameOrAddress, vaultRoot = defaultVaultRoot()) {
+  const wanted = String(nameOrAddress || '').trim();
+  if (!wanted) return null;
+  const key = meshNodeKey(wanted);
+  const nodes = listEnrichedMeshNodes(vaultRoot);
+
+  return (
+    nodes.find((n) => String(n.ip) === wanted || String(n.lan_ip) === wanted) ||
+    nodes.find((n) => meshNodeKey(n.hostname) === key) ||
+    null
+  );
+}
+
+/**
+ * Record how to reach a node.
+ *
+ * Creates the entity when a peer has never had one — remote nodes only get a
+ * document when something writes to them, and access is usually the first
+ * thing anyone knows about a machine they did not install Total Recall on.
+ */
+export async function setMeshNodeAccess(nameOrAddress, accessPatch, options = {}) {
+  const vaultRoot = options.vaultRoot || defaultVaultRoot();
+  const node = findMeshNode(nameOrAddress, vaultRoot);
+  if (!node) return { written: false, reason: 'node-not-found' };
+
+  const entities = listMeshNodeEntities(vaultRoot);
+  const existing =
+    entities.find((e) => meshNodeKey(e.hostname) === meshNodeKey(node.hostname)) ||
+    entities.find((e) => e.ip && node.ip && String(e.ip) === String(node.ip)) ||
+    null;
+
+  // Merge rather than replace: setting only a port must not erase the user.
+  const merged = { ...(existing?.access || {}), ...accessPatch };
+  for (const [key, value] of Object.entries(merged)) {
+    if (value === null || value === undefined) delete merged[key];
+  }
+
+  const now = new Date().toISOString();
+  const { processViaPackageKernel } = await import('./ssss-kernel-bridge.mjs');
+  const vfsPath = existing?.vfs_path || `system/mesh-nodes/${meshNodeKey(node.hostname)}.md`;
+
+  const envelope = existing
+    ? {
+        type: 'patch',
+        path: vfsPath,
+        patches: {
+          access: merged,
+          timestamp: now,
+          // A patch is validated against the whole resulting document, and the
+          // earliest node entities were written before title/description became
+          // required. Without backfilling them here, every write to one of
+          // those documents fails validation forever — the node can never be
+          // given an access record, which is exactly what it needs most.
+          ...(existing.title ? {} : { title: node.hostname }),
+          ...(existing.description
+            ? {}
+            : { description: `Mesh node entity for ${node.hostname}.` }),
+        },
+      }
+    : {
+        type: 'operation',
+        path: vfsPath,
+        content: [
+          '---',
+          'type: mesh_node',
+          `title: ${JSON.stringify(node.hostname)}`,
+          `description: ${JSON.stringify(`Mesh node entity for ${node.hostname}.`)}`,
+          `timestamp: ${now}`,
+          `hostname: ${JSON.stringify(node.hostname)}`,
+          `ip: ${node.ip == null ? 'null' : JSON.stringify(node.ip)}`,
+          `status: ${node.online ? 'online' : 'offline'}`,
+          `os: ${node.os == null ? 'null' : JSON.stringify(node.os)}`,
+          `lan_ip: ${node.lan_ip == null ? 'null' : JSON.stringify(node.lan_ip)}`,
+          `access: ${JSON.stringify(merged)}`,
+          '---',
+          '',
+          '<!-- Access variables (login account, port, key path) live here so every',
+          '     machine and agent on the mesh resolves them the same way. -->',
+          '',
+        ].join('\n'),
+      };
+
+  const result = await processViaPackageKernel(
+    {
+      ...envelope,
+      idempotency_key: crypto.randomUUID(),
+      workspace_id: options.workspace_id || 'default',
+      actor: { role: 'system' },
+    },
+    vaultRoot,
+    { agentRole: 'system' },
+  );
+
+  return { written: !!result?.success, path: vfsPath, access: merged, result };
+}
+
 /**
  * Upsert **this** node's mesh_node entity from live discovery.
  * Does not hardcode device names — slug and fields come from Tailscale self.
@@ -241,7 +370,7 @@ export async function patchOwnMeshNode(options = {}) {
   const existing = findEntityForSelf(self, vaultRoot);
   const slug = existing
     ? path.basename(existing.vfs_path, '.md')
-    : meshNodeDocSlug(self.hostname);
+    : meshNodeKey(self.hostname);
   const vfsPath = existing?.vfs_path || `system/mesh-nodes/${slug}.md`;
   const now = new Date().toISOString();
   const status = self.online ? 'online' : 'offline';
@@ -280,6 +409,25 @@ export async function patchOwnMeshNode(options = {}) {
   const priorCaps = Array.isArray(existing?.capabilities) ? existing.capabilities : [];
   const capabilities = [...new Set([...priorCaps, ...ioChannels.map((c) => `io:${c}`)])];
 
+  // Which Tailscale build this machine runs decides whether the control server
+  // can authorise SSH to it, or whether callers still need their own keys.
+  // Recording it here makes it a mesh fact: every other node learns what this
+  // one can do without having to log in and look — which is the only way to
+  // find out otherwise, and needs the very access this may be missing.
+  // `getMeshSelf()` answered, so the client did run; only the build is in doubt.
+  const { classifyTailscaleVariant, meshSshFromVariant } = await import('./mesh-access.mjs');
+  const { hasTailscaleDaemon } = await import('./tailscale-cli.mjs');
+  const variant = classifyTailscaleVariant({
+    platform: process.platform,
+    hasClient: true,
+    hasDaemon: hasTailscaleDaemon(),
+  });
+  const access = {
+    ...(existing?.access || {}),
+    tailscale_variant: variant,
+    mesh_ssh: meshSshFromVariant(variant),
+  };
+
   const livePatches = {
     hostname: self.hostname,
     ip: self.ip,
@@ -291,6 +439,8 @@ export async function patchOwnMeshNode(options = {}) {
     transports: [...new Set(['mesh', ...(lanIp ? ['lan'] : [])])],
     io: ioProfile,
     capabilities,
+    // Merged, never replaced: probing must not erase a recorded login account.
+    access,
     ...requiredMeta,
   };
 
@@ -322,13 +472,15 @@ export async function patchOwnMeshNode(options = {}) {
       `os: ${self.os == null ? 'null' : JSON.stringify(self.os)}`,
       'role: null',
       'labels: []',
-      'capabilities: []',
       'notes: null',
       `lan_ip: ${lanIp == null ? 'null' : JSON.stringify(lanIp)}`,
       `transports: ${JSON.stringify(livePatches.transports)}`,
       `interfaces: ${JSON.stringify(interfacesSummary)}`,
       `io: ${JSON.stringify(ioProfile)}`,
+      // Emitted once. A duplicate YAML key is resolved by last-one-wins, so a
+      // stale earlier line survives review while contributing nothing.
       `capabilities: ${JSON.stringify(capabilities)}`,
+      `access: ${JSON.stringify(access)}`,
       '---',
       '',
       '<!-- Entity space: I/O (screen/touch/mic/speaker) + notes/labels via SSSS patch. Agents use io.channels / ui_hints. -->',

package/src/core/schema.mjs

@@ -966,6 +966,40 @@ const DeviceIoProfileSchema = z.object({
   platform: z.string().optional(),
 }).passthrough();
 
+/**
+ * How an operator (or agent) actually reaches this node.
+ *
+ * Identity and reachability come from the control server, but *operating* a
+ * node needs facts the control server never sees — which account to log in as
+ * above all. Without this, that knowledge lives in a local `~/.ssh/config` that
+ * no other machine and no agent can read, so every consumer rediscovers it by
+ * guessing. Recording it here makes access a mesh fact like any other.
+ *
+ * Secrets never belong on this document: `identity_file` is a path to a key,
+ * never key material.
+ */
+const MeshNodeAccessSchema = z.object({
+  /** Login account. The single most common reason a reachable node looks dead. */
+  ssh_user: z.string().min(1).nullable().optional(),
+  ssh_port: z.number().int().positive().max(65535).nullable().optional(),
+  /** Preferred address when it is neither the mesh IP nor the LAN IP. */
+  ssh_host: z.string().min(1).nullable().optional(),
+  /** Path to a private key — never the key itself. */
+  identity_file: z.string().min(1).nullable().optional(),
+  /**
+   * Which Tailscale build runs here. Only the open-source `tailscaled` build
+   * can serve Tailscale SSH; the sandboxed GUI builds cannot, so this is what
+   * decides whether keyless mesh SSH is even possible for the node.
+   */
+  tailscale_variant: z.enum(['daemon', 'sandboxed', 'missing', 'unknown']).optional(),
+  /** Whether control-plane-authorised SSH works, derived from the variant. */
+  mesh_ssh: z.enum(['available', 'unsupported', 'unknown']).optional(),
+  /** Where these values came from, so a probe can outrank a guess. */
+  source: z.enum(['probe', 'ssh_config', 'manual', 'unknown']).optional(),
+  /** Last time access was proven by an actual successful connection. */
+  verified_at: ssssDatetimeNullable().optional(),
+}).passthrough();
+
 export const MeshNodeSchema = z.object({
   type: z.literal('mesh_node'),
   title: z.string().min(1),
@@ -991,6 +1025,8 @@ export const MeshNodeSchema = z.object({
    * (touchscreen, mic, speaker, screen, keyboard, …).
    */
   io: DeviceIoProfileSchema.optional(),
+  /** Operational access — how to actually log in to this node. */
+  access: MeshNodeAccessSchema.optional(),
 }).passthrough();
 
 export const DaemonLeaderSchema = z.object({

package/src/core/secrets-keychain.mjs

@@ -0,0 +1,83 @@
+/**
+ * macOS Keychain as a master-password carrier.
+ *
+ * `secrets-rekey` knows how to update file carriers — a LaunchAgent plist, an
+ * env file — because it can stage, back up and atomically rename them. The
+ * Keychain is not a file, so it was simply not a carrier at all. That is fine
+ * right up until a shell profile reads the password from the Keychain, which is
+ * the arrangement macOS installs steer people toward: a rekey then re-encrypts
+ * the store, updates the carriers it knows about, and leaves the Keychain
+ * holding the retired password. Every interactive shell breaks at once, with an
+ * error — "Unsupported state or unable to authenticate data" — that describes
+ * the symptom and not the cause.
+ *
+ * Portability: this module is macOS-only by nature and reports itself
+ * unavailable everywhere else, so callers can treat it as optional.
+ *
+ * The password is passed to `security` on stdin, never in argv. Anything in
+ * argv is visible to every process on the machine through `ps`.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+const SECURITY_BIN = '/usr/bin/security';
+
+/**
+ * Service name Total Recall stores its own master password under. A product
+ * constant like the `TR_SECRETS_PASSWORD` variable name — not a device or user
+ * detail — and overridable per invocation.
+ */
+export const DEFAULT_KEYCHAIN_SERVICE = 'total-recall-secrets';
+
+/** Is the Keychain usable on this host? */
+export function keychainAvailable({ platform = process.platform } = {}) {
+  if (platform !== 'darwin') return false;
+  const probe = spawnSync(SECURITY_BIN, ['help'], { encoding: 'utf8', timeout: 5_000 });
+  return probe.status === 0 || probe.status === 1; // `help` exits non-zero on some releases
+}
+
+/**
+ * Current password held for a service/account, or null when there is no entry.
+ * The value is returned, never logged — callers compare it, they do not print it.
+ */
+export function readKeychainPassword({ service, account = process.env.USER }) {
+  if (!service) throw new Error('Keychain carrier requires a service name');
+  const res = spawnSync(
+    SECURITY_BIN,
+    ['find-generic-password', '-a', String(account), '-s', String(service), '-w'],
+    { encoding: 'utf8', timeout: 10_000 },
+  );
+  if (res.status !== 0) return null;
+  // `security` terminates the value with a newline that is not part of it.
+  return (res.stdout || '').replace(/\n$/, '') || null;
+}
+
+/**
+ * Create or replace the entry. `-U` updates in place when one already exists,
+ * which keeps this idempotent and atomic for a single item.
+ *
+ * Omitting a value after `-w` makes `security` prompt for the password and read
+ * it from stdin — twice, to confirm — which is how the secret is kept out of
+ * argv.
+ */
+export function writeKeychainPassword({ service, account = process.env.USER, password }) {
+  if (!service) throw new Error('Keychain carrier requires a service name');
+  if (!password) throw new Error('Refusing to write an empty Keychain password');
+  const res = spawnSync(
+    SECURITY_BIN,
+    ['add-generic-password', '-U', '-a', String(account), '-s', String(service), '-w'],
+    { input: `${password}\n${password}\n`, encoding: 'utf8', timeout: 10_000 },
+  );
+  if (res.status !== 0) {
+    // stderr may echo the prompt text but never the value itself.
+    throw new Error(
+      `Could not update Keychain entry ${service}: ${(res.stderr || '').trim().slice(0, 200) || `exit ${res.status}`}`,
+    );
+  }
+  return true;
+}
+
+/** `{ service, account }` → a stable label for logs and results. */
+export function describeKeychainCarrier(carrier) {
+  return `keychain:${carrier.service}(${carrier.account || process.env.USER})`;
+}

package/src/core/secrets-store.mjs

@@ -43,6 +43,28 @@ function secretsPassword() {
   return process.env.TR_SECRETS_PASSWORD || process.env.TR_MASTER_PASSWORD || null;
 }
 
+/**
+ * Is this buffer the plaintext JSON form of the store, rather than ciphertext?
+ *
+ * The encrypted form opens with a random 16-byte salt, so its first byte is
+ * `{` about once in every 256 stores — measured at 17 in 5000. Deciding the
+ * format from that byte alone therefore misreads roughly one store in every
+ * 256 as plain JSON. Reads survive it by falling back to decryption, but
+ * `migrateSecretsToEncryptedIfNeeded` does not: it reports perfectly good
+ * ciphertext as `not-json`, and its caller believes the store still needs
+ * migrating. The first byte is a cheap way to reject the common case; only
+ * parsing can settle the rest.
+ */
+export function isPlainJsonStore(buf) {
+  if (!buf?.length || buf[0] !== 0x7b /* { */) return false;
+  try {
+    const parsed = JSON.parse(buf.toString('utf8'));
+    return Boolean(parsed) && typeof parsed === 'object' && !Array.isArray(parsed);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Load raw secrets object synchronously
  */
@@ -53,7 +75,7 @@ export function loadSecretsSync(brainDir) {
   const buf = fs.readFileSync(filePath);
   const password = secretsPassword();
 
-  if (password && buf.length > 44 && buf[0] !== 0x7b) {
+  if (password && buf.length > 44 && !isPlainJsonStore(buf)) {
     try {
       return decryptSecretsSync(buf, password);
     } catch (err) {
@@ -88,8 +110,7 @@ export async function loadSecrets(brainDir) {
   const buf = fs.readFileSync(filePath);
   const password = secretsPassword();
 
-  // AES blob: starts with non-JSON (binary). Detect: first byte not `{`
-  if (password && buf.length > 44 && buf[0] !== 0x7b /* { */) {
+  if (password && buf.length > 44 && !isPlainJsonStore(buf)) {
     try {
       return await decryptSecrets(buf, password);
     } catch (err) {
@@ -146,8 +167,7 @@ export async function migrateSecretsToEncryptedIfNeeded(brainDir) {
     return { migrated: false, path: filePath, reason: 'no-password' };
   }
   const buf = fs.readFileSync(filePath);
-  // Already looks like AES blob (not starting with `{`)
-  if (buf.length > 44 && buf[0] !== 0x7b) {
+  if (buf.length > 44 && !isPlainJsonStore(buf)) {
     return { migrated: false, path: filePath, reason: 'already-encrypted' };
   }
   let obj;
@@ -173,7 +193,7 @@ export async function migrateSecretsToEncryptedIfNeeded(brainDir) {
 export async function validateSecretsBuffer(buffer) {
   const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
   const password = secretsPassword();
-  if (password && buf.length > 44 && buf[0] !== 0x7b) {
+  if (password && buf.length > 44 && !isPlainJsonStore(buf)) {
     const parsed = await decryptSecrets(buf, password);
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
       throw new Error('Decrypted secrets payload must be an object');

package/src/core/tailscale-cli.mjs

@@ -0,0 +1,69 @@
+/**
+ * Locating the Tailscale client.
+ *
+ * Kept separate from both discovery and enrollment because each needs the
+ * binary but neither should depend on the other to find it. Folding this into
+ * the enrollment module made status reads fail wherever enrollment was stubbed
+ * — the lookup silently became `undefined`, and every mesh query returned an
+ * error that looked like an empty mesh.
+ */
+
+import fs from 'node:fs';
+
+/**
+ * macOS ships the CLI inside the app bundle rather than on PATH, so a
+ * PATH-only lookup fails on exactly the machines people install first.
+ */
+export const FALLBACK_BINARIES = [
+  '/usr/local/bin/tailscale',
+  '/opt/homebrew/bin/tailscale',
+  '/Applications/Tailscale.app/Contents/MacOS/Tailscale',
+  '/usr/bin/tailscale',
+];
+
+/**
+ * Presence of a `tailscaled` is what separates the open-source build, which
+ * can serve Tailscale SSH, from the sandboxed GUI builds, which cannot.
+ */
+export const DARWIN_DAEMON_BINARIES = [
+  '/usr/local/bin/tailscaled',
+  '/opt/homebrew/bin/tailscaled',
+  '/usr/local/sbin/tailscaled',
+  '/opt/homebrew/sbin/tailscaled',
+];
+
+/**
+ * How long to wait on a `tailscale status` read.
+ *
+ * Measured at 1.2–1.7s on an idle machine, and longer whenever peers are spread
+ * over a WAN or the host is busy. A tight timeout does not degrade gracefully:
+ * the call returns nothing, the mesh reads as completely empty, and every
+ * lookup reports a node as missing rather than unknown — indistinguishable from
+ * a machine that was never enrolled. Shared so discovery and enrollment cannot
+ * disagree about how patient to be.
+ */
+export const STATUS_TIMEOUT_MS = 10_000;
+
+function existsSafe(candidate) {
+  try {
+    return fs.existsSync(candidate);
+  } catch {
+    // Permission errors fall through to the next candidate, then to PATH.
+    return false;
+  }
+}
+
+/** Resolve the Tailscale CLI, honoring an explicit override first. */
+export function resolveTailscaleBinary() {
+  const override = (process.env.TR_TAILSCALE_BIN || '').trim();
+  if (override) return override;
+  for (const candidate of FALLBACK_BINARIES) {
+    if (existsSafe(candidate)) return candidate;
+  }
+  return 'tailscale';
+}
+
+/** Is an open-source `tailscaled` present (the SSH-server-capable build)? */
+export function hasTailscaleDaemon() {
+  return DARWIN_DAEMON_BINARIES.some(existsSafe);
+}

package/src/server/index.mjs

@@ -28,6 +28,7 @@ import {
   requireScope
 } from './auth.mjs';
 import { logger, logEvents } from "../core/logger.mjs";
+import { readProcessCommand, serverEntryHint, shouldHonorPidLock } from './pid-lock.mjs';
 import { drainActiveEmbeddings } from './routes/sessions.mjs';
 import { agentDir as configAgentDir, brainDir as configBrainDir, port as configPort, host as configHost, nodeEnv } from '../core/config.mjs';
 import { getDaemonStatus, ensureDaemonRunning } from '../core/daemon-control.mjs';
@@ -55,13 +56,31 @@ function acquireServerPidLock() {
     if (fs.existsSync(SERVER_PID_FILE)) {
       const existingPid = parseInt(fs.readFileSync(SERVER_PID_FILE, 'utf8').trim(), 10);
       if (existingPid && !isNaN(existingPid)) {
-        try {
-          process.kill(existingPid, 0); // signal 0 = liveness check only
+        // Liveness alone is not enough: PIDs are recycled, and a stale lock
+        // pointing at a number the OS has since reassigned would block startup
+        // on every boot, blaming an instance that does not exist.
+        const verdict = shouldHonorPidLock(existingPid, {
+          isAlive: (pid) => {
+            try {
+              process.kill(pid, 0); // signal 0 = liveness check only
+              return true;
+            } catch {
+              return false;
+            }
+          },
+          readCommand: readProcessCommand,
+          entryHint: serverEntryHint(fileURLToPath(import.meta.url)),
+        });
+        if (verdict.honor) {
           logger.error('server', `Another server instance is already running (PID: ${existingPid}). Exiting.`);
           process.exit(1);
-        } catch {
-          logger.info('server', `Stale server PID file found (PID: ${existingPid} is dead). Overwriting.`);
         }
+        logger.info(
+          'server',
+          verdict.reason === 'pid-reused'
+            ? `Stale server PID file found (PID ${existingPid} now belongs to another program). Overwriting.`
+            : `Stale server PID file found (PID: ${existingPid} is dead). Overwriting.`,
+        );
       }
     }
   } catch {

package/src/server/pid-lock.mjs

@@ -0,0 +1,64 @@
+/**
+ * Deciding whether a PID lock is real.
+ *
+ * A lock file records the PID of the running server, and the obvious liveness
+ * test is `process.kill(pid, 0)` — it throws if nothing is there. What it
+ * cannot tell you is *what* is there. PIDs are recycled, aggressively so after
+ * a reboot, and the number in a stale lock file is as likely to belong to a
+ * system daemon as to anything of ours. Observed in the wild: a lock left
+ * pointing at PID 445, which the OS had since handed to `metrickitd`. The
+ * liveness check passed, the server exited with "another server instance is
+ * already running", and it did so on every boot from then on — an outage with
+ * an error message that sent you looking for a process that was never there.
+ *
+ * So liveness is necessary but not sufficient: the process has to look like
+ * this server before its lock is honored.
+ */
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+/**
+ * The tail of our own entry path (`server/index.mjs`), derived rather than
+ * written down so it stays correct wherever the package is installed and never
+ * hardcodes a checkout location.
+ */
+export function serverEntryHint(entryPath) {
+  return path.join(path.basename(path.dirname(entryPath)), path.basename(entryPath));
+}
+
+/** Read a process's command line, or null when it cannot be determined. */
+export function readProcessCommand(pid) {
+  try {
+    const res = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], {
+      encoding: 'utf8',
+      timeout: 5_000,
+    });
+    if (res.status !== 0 || !res.stdout) return null;
+    return res.stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Should the lock held by `pid` block startup?
+ *
+ * `isAlive` and `readCommand` are injected so the decision can be tested
+ * without spawning processes or guessing at PIDs.
+ */
+export function shouldHonorPidLock(pid, { isAlive, readCommand, entryHint }) {
+  if (!pid || !Number.isInteger(pid) || pid <= 0) return { honor: false, reason: 'invalid-pid' };
+  if (!isAlive(pid)) return { honor: false, reason: 'dead' };
+
+  const command = readCommand(pid);
+  // Without a readable command line we cannot distinguish a real instance from
+  // a recycled number. Honor the lock: a refusal to start is recoverable by
+  // deleting the file, whereas two servers sharing one brain is not.
+  if (!command) return { honor: true, reason: 'alive-command-unknown' };
+
+  if (!command.includes(entryHint)) {
+    return { honor: false, reason: 'pid-reused', command };
+  }
+  return { honor: true, reason: 'alive-and-ours', command };
+}