@logicseek/hello-cc 0.1.9 → 1.0.0

package/lib/db/schema.mjs

@@ -1,6 +1,7 @@
+import { aggregateCleanupFailure } from '../shared/cleanup-error.mjs';
 import { CliError } from '../shared/errors.mjs';
 
-export const DB_SCHEMA_VERSION = 5;
+export const DB_SCHEMA_VERSION = 7;
 
 const sleepBuffer = new SharedArrayBuffer(4);
 const sleepView = new Int32Array(sleepBuffer);
@@ -21,6 +22,18 @@ function isSqliteBusy(err) {
     /SQLITE_BUSY|SQLITE_LOCKED|database is locked|database is busy/i.test(text);
 }
 
+function failedRollbackMetadata(db, context) {
+  let transactionActive = null;
+  try {
+    transactionActive = Boolean(db.isTransaction);
+  } catch {}
+  return {
+    context,
+    transactionActive,
+    connectionUsable: false
+  };
+}
+
 export function execWithBusyRetry(db, sql, { attempts = 30, delayMs = 100, ignoreBusy = false } = {}) {
   for (let attempt = 0; attempt < attempts; attempt += 1) {
     try {
@@ -47,14 +60,49 @@ export function tx(db, fn) {
   } catch (err) {
     try {
       db.exec('ROLLBACK;');
-    } catch {
-      // Ignore rollback failures; the original error is more useful.
+    } catch (cleanupError) {
+      throw aggregateCleanupFailure(
+        err,
+        cleanupError,
+        'Write transaction failed and rollback also failed',
+        failedRollbackMetadata(db, 'Write transaction rollback')
+      );
     }
     throw err;
   }
 }
 
-export function initSchema(db, { beforePostMigrationIndexes = null } = {}) {
+// Deferred read transaction: gives a consistent snapshot for multi-table reads
+// without taking a write lock (unlike tx's BEGIN IMMEDIATE). Use for read-only
+// snapshot assembly so peers/tasks/locks counts cannot drift mid-read (conc-06).
+export function readTx(db, fn, options = {}) {
+  db.exec('BEGIN;');
+  try {
+    const result = fn();
+    db.exec('COMMIT;');
+    return result;
+  } catch (err) {
+    try {
+      db.exec('ROLLBACK;');
+    } catch (cleanupError) {
+      throw aggregateCleanupFailure(
+        err,
+        cleanupError,
+        `${options.cleanupContext || 'Read transaction'} failed and rollback also failed`,
+        failedRollbackMetadata(
+          db,
+          `${options.cleanupContext || 'Read transaction'} rollback`
+        )
+      );
+    }
+    throw err;
+  }
+}
+
+export function initSchema(db, {
+  beforeMigration = null,
+  beforePostMigrationIndexes = null
+} = {}) {
   const existingVersion = readSchemaVersion(db);
   if (existingVersion > DB_SCHEMA_VERSION) {
     throw new CliError('DB_SCHEMA_TOO_NEW', `Database schema version ${existingVersion} is newer than this hcc (${DB_SCHEMA_VERSION})`, {
@@ -62,6 +110,17 @@ export function initSchema(db, { beforePostMigrationIndexes = null } = {}) {
       supported_schema_version: DB_SCHEMA_VERSION
     });
   }
+  const hasExistingSchema = Boolean(db.prepare(`
+    SELECT 1
+    FROM sqlite_master
+    WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+    LIMIT 1
+  `).get());
+  if (existingVersion < DB_SCHEMA_VERSION &&
+      (existingVersion > 0 || hasExistingSchema) &&
+      typeof beforeMigration === 'function') {
+    beforeMigration({ fromVersion: existingVersion, toVersion: DB_SCHEMA_VERSION });
+  }
   createBaseSchema(db);
   runSchemaMigrations(db);
   if (typeof beforePostMigrationIndexes === 'function') beforePostMigrationIndexes(db);
@@ -88,6 +147,8 @@ function createBaseSchema(db) {
       worktree TEXT,
       branch TEXT,
       pid INTEGER,
+      pid_start_token TEXT,
+      pid_command_hash TEXT,
       status TEXT NOT NULL DEFAULT 'idle',
       capabilities TEXT,
       created_at INTEGER NOT NULL,
@@ -155,7 +216,8 @@ function createBaseSchema(db) {
       task_id INTEGER,
       reason TEXT,
       expires_at INTEGER NOT NULL,
-      created_at INTEGER NOT NULL
+      created_at INTEGER NOT NULL,
+      ttl_sec INTEGER NOT NULL DEFAULT 900
     );
 
     CREATE TABLE IF NOT EXISTS handoffs (
@@ -294,6 +356,35 @@ function runSchemaMigrations(db) {
           CREATE INDEX IF NOT EXISTS idx_locks_base_scope ON locks(base_resource, scope);
         `);
       }
+    },
+    {
+      version: 6,
+      name: 'persist lock ttl',
+      up(database) {
+        const hadTtlColumn = tableColumns(database, 'locks').has('ttl_sec');
+        addColumnIfMissing(database, 'locks', 'ttl_sec', 'ttl_sec INTEGER NOT NULL DEFAULT 900');
+        database.exec(hadTtlColumn
+          ? `
+              UPDATE locks
+              SET ttl_sec = 900
+              WHERE ttl_sec IS NULL OR ttl_sec <= 0;
+            `
+          : `
+              UPDATE locks
+              SET ttl_sec = CASE
+                WHEN expires_at > created_at THEN MIN(expires_at - created_at, 3600)
+                ELSE 900
+              END;
+            `);
+      }
+    },
+    {
+      version: 7,
+      name: 'peer process identity fingerprints',
+      up(database) {
+        addColumnIfMissing(database, 'peers', 'pid_start_token', 'pid_start_token TEXT');
+        addColumnIfMissing(database, 'peers', 'pid_command_hash', 'pid_command_hash TEXT');
+      }
     }
   ];
   let version = readSchemaVersion(db);
@@ -304,6 +395,12 @@ function runSchemaMigrations(db) {
     });
   }
   const applied = new Set(db.prepare('SELECT version FROM schema_migrations').all().map((row) => Number(row.version)));
+  // Already fully migrated: skip the write transaction entirely. Read-only
+  // commands (hcc status/peers/task list) then open the DB without taking a
+  // RESERVED write lock or appending WAL frames on every connect (conc-01).
+  if (version === DB_SCHEMA_VERSION && migrations.every((m) => applied.has(m.version))) {
+    return;
+  }
   tx(db, () => {
     for (const migration of migrations) {
       if (version >= migration.version && applied.has(migration.version)) continue;

package/lib/db/stores/peers.mjs

@@ -7,6 +7,7 @@ import {
   mergePeerBinding,
   mergeRuntimeBinding
 } from '../../core/peers/bindings.mjs';
+import { providerSessionPeerId } from '../../core/peers/session.mjs';
 
 function defaultNow() {
   return Math.floor(Date.now() / 1000);
@@ -14,6 +15,23 @@ function defaultNow() {
 
 function noopEvent() {}
 
+function crossesV1ProviderIdentityBoundary(binding, conflict) {
+  const providerSession = bindingProviderSessionValue(binding);
+  if (!providerSession || !binding?.provider) return false;
+  const v1Peer = providerSessionPeerId(binding.provider, providerSession);
+  return binding.peer === v1Peer && conflict?.peer !== v1Peer;
+}
+
+function withoutProviderSession(binding) {
+  return {
+    ...binding,
+    provider_session_id: null,
+    provider_session_name: null,
+    resume_mode: 'unknown',
+    resume_arg: null
+  };
+}
+
 export function createPeerBindingStore(deps = {}) {
   const now = typeof deps.now === 'function' ? deps.now : defaultNow;
   const addEvent = typeof deps.addEvent === 'function' ? deps.addEvent : noopEvent;
@@ -125,6 +143,22 @@ export function createPeerBindingStore(deps = {}) {
     const conflictRuntime = bindingHasRuntime(conflict);
     const providerSession = bindingProviderSessionValue(next);
     const override = Boolean(options.override);
+    const preV1Conflict = crossesV1ProviderIdentityBoundary(next, conflict);
+    const passiveObservation = !incomingRuntime || next.resume_mode === 'detected';
+
+    if (preV1Conflict && passiveObservation) {
+      next = withoutProviderSession(next);
+      return { peer: next.peer, binding: next, merged_from: null };
+    }
+
+    if (preV1Conflict && incomingRuntime && !override) {
+      throw new CliError('PROVIDER_SESSION_IN_USE', `${next.provider} session ${providerSession} is already bound to ${conflict.peer}`, {
+        peer: conflict.peer,
+        provider: conflict.provider,
+        provider_session: providerSession,
+        runtime_target: conflict.runtime_target || null
+      });
+    }
 
     if (override && incomingRuntime) {
       db.prepare('DELETE FROM peer_bindings WHERE peer = ?').run(conflict.peer);

package/lib/integrations/peers/identity.mjs

@@ -84,28 +84,74 @@ function detectCliKindFromProcess(args, env) {
   return null;
 }
 
-export function readAncestorCliInfo() {
-  if (ancestorCliInfoCache !== undefined) return ancestorCliInfoCache;
-  if (process.platform !== 'linux') {
-    ancestorCliInfoCache = null;
-    return ancestorCliInfoCache;
+export function findLinuxAncestorCliInfo(startPid, options = {}) {
+  const read = typeof options.read === 'function'
+    ? options.read
+    : (pid) => ({
+        args: readProcCmdline(pid),
+        env: readProcEnv(pid),
+        parent: readProcParentPid(pid)
+      });
+  let pid = Number(startPid);
+  const seen = new Set();
+  for (let depth = 0; Number.isInteger(pid) && pid > 1 && depth < 12 && !seen.has(pid); depth += 1) {
+    seen.add(pid);
+    const row = read(pid);
+    if (!row) return null;
+    const args = Array.isArray(row.args) ? row.args : [];
+    const env = row.env && typeof row.env === 'object' && !Array.isArray(row.env) ? row.env : {};
+    const kind = detectCliKindFromProcess(args, env);
+    if (kind) return { pid, kind, args, env };
+    pid = Number(row.parent);
   }
+  return null;
+}
 
-  let pid = process.ppid;
+export function parseMacAncestorLine(text) {
+  const line = String(text ?? '').trimEnd();
+  if (!line || line.includes('\n') || line.includes('\r')) return null;
+  const match = line.match(/^\s*([0-9]+)\s+(.+?)\s*$/);
+  if (!match) return null;
+  const ppid = Number(match[1]);
+  const command = match[2];
+  if (!Number.isSafeInteger(ppid) || ppid < 0 || !command) return null;
+  return { ppid, command };
+}
+
+function inspectMacAncestor(pid) {
+  const result = spawnSync('ps', ['-ww', '-o', 'ppid=', '-o', 'command=', '-p', String(pid)], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, LC_ALL: 'C', LANG: 'C' }
+  });
+  if (result.error || result.status !== 0) return null;
+  return result.stdout || '';
+}
+
+export function findMacAncestorCliInfo(startPid, options = {}) {
+  const inspect = typeof options.inspect === 'function' ? options.inspect : inspectMacAncestor;
+  let pid = Number(startPid);
   const seen = new Set();
-  for (let depth = 0; pid && pid > 1 && depth < 12 && !seen.has(pid); depth += 1) {
+  for (let depth = 0; Number.isInteger(pid) && pid > 1 && depth < 12 && !seen.has(pid); depth += 1) {
     seen.add(pid);
-    const args = readProcCmdline(pid);
-    const env = readProcEnv(pid);
-    const kind = detectCliKindFromProcess(args, env);
-    if (kind) {
-      ancestorCliInfoCache = { pid, kind, args, env };
-      return ancestorCliInfoCache;
-    }
-    pid = readProcParentPid(pid);
+    const parsed = parseMacAncestorLine(inspect(pid));
+    if (!parsed) return null;
+    const kind = detectCliKindFromProcess([parsed.command], {});
+    // `ps command` is sufficient for provider-kind detection but is not a
+    // lossless argv encoding. Do not feed it to resume-ID parsing.
+    if (kind) return { pid, kind, args: [], env: {}, command: parsed.command };
+    pid = parsed.ppid;
   }
+  return null;
+}
 
-  ancestorCliInfoCache = null;
+export function readAncestorCliInfo() {
+  if (ancestorCliInfoCache !== undefined) return ancestorCliInfoCache;
+  ancestorCliInfoCache = process.platform === 'linux'
+    ? findLinuxAncestorCliInfo(process.ppid)
+    : process.platform === 'darwin'
+      ? findMacAncestorCliInfo(process.ppid)
+      : null;
   return ancestorCliInfoCache;
 }
 

package/lib/integrations/shims/script.mjs

@@ -57,8 +57,59 @@ if [ -z "$HCC_ROOT" ]; then
   exec "$REAL_BIN" "$@"
 fi
 
-sanitize_peer_part() {
-  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9._-]/-/g; s/^-*//; s/-*$//' | cut -c 1-32
+# sess-04: sha1 hash of the FULL provider id/name, first 8 hex chars — must
+# match the JS shortHash() exactly (lib/core/peers/format.mjs). Name-based ids
+# that share a prefix used to collide into the same peer id.
+is_sha1_hex() {
+  [ "\${#1}" -eq 40 ] || return 1
+  case "$1" in
+    *[!0-9a-f]*) return 1 ;;
+  esac
+  return 0
+}
+
+peer_hash() {
+  local HASH=""
+  local OUTPUT=""
+
+  if command -v openssl >/dev/null 2>&1; then
+    OUTPUT=$(printf '%s' "$1" | openssl dgst -sha1 2>/dev/null || true)
+    HASH=$(printf '%s\n' "$OUTPUT" | awk 'NR == 1 { print $NF }' | tr '[:upper:]' '[:lower:]')
+    is_sha1_hex "$HASH" || HASH=""
+  fi
+
+  if [ -z "$HASH" ] && command -v sha1sum >/dev/null 2>&1; then
+    OUTPUT=$(printf '%s' "$1" | sha1sum 2>/dev/null || true)
+    HASH=$(printf '%s\n' "$OUTPUT" | awk 'NR == 1 { print $1 }' | tr '[:upper:]' '[:lower:]')
+    is_sha1_hex "$HASH" || HASH=""
+  fi
+
+  if [ -z "$HASH" ] && command -v shasum >/dev/null 2>&1; then
+    OUTPUT=$(printf '%s' "$1" | shasum 2>/dev/null || true)
+    HASH=$(printf '%s\n' "$OUTPUT" | awk 'NR == 1 { print $1 }' | tr '[:upper:]' '[:lower:]')
+    is_sha1_hex "$HASH" || HASH=""
+  fi
+
+  # A hello-cc environment always has node on PATH (hcc itself is a node CLI),
+  # so this fallback guarantees registration even on minimal systems without
+  # openssl/sha1sum/shasum. Digest must match the JS shortHash exactly.
+  if [ -z "$HASH" ] && command -v node >/dev/null 2>&1; then
+    HASH=$(printf '%s' "$1" | node -e 'let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>process.stdout.write(require("node:crypto").createHash("sha1").update(d).digest("hex")))' 2>/dev/null || true)
+    is_sha1_hex "$HASH" || HASH=""
+  fi
+
+  if ! is_sha1_hex "$HASH"; then
+    printf '%s\n' 'hello-cc: unable to derive peer id: no SHA-1 command produced a valid digest' >&2
+    return 1
+  fi
+
+  printf '%.8s' "$HASH"
+}
+
+provider_peer_id() {
+  local HASH_PART=""
+  HASH_PART=$(peer_hash "$1") || return 1
+  printf '%s-%s' '${tool.kind}' "$HASH_PART"
 }
 
 tty_peer_part() {
@@ -96,13 +147,13 @@ done
 if [ -n "$HCC_PEER" ]; then
   PEER_ID="$HCC_PEER"
 elif [ -n "$SESSION_ID" ]; then
-  PEER_ID="${tool.kind}-\$(sanitize_peer_part "\${SESSION_ID:0:8}")"
+  PEER_ID=$(provider_peer_id "$SESSION_ID") || exec "$REAL_BIN" "$@"
 elif [ -n "$RESUME_ID" ] && [ "$IS_FORK" != "1" ]; then
-  PEER_ID="${tool.kind}-\$(sanitize_peer_part "\${RESUME_ID:0:8}")"
+  PEER_ID=$(provider_peer_id "$RESUME_ID") || exec "$REAL_BIN" "$@"
 elif [ -n "$CLAUDE_CODE_SESSION_ID" ]; then
-  PEER_ID="${tool.kind}-\$(sanitize_peer_part "\${CLAUDE_CODE_SESSION_ID:0:8}")"
+  PEER_ID=$(provider_peer_id "$CLAUDE_CODE_SESSION_ID") || exec "$REAL_BIN" "$@"
 elif [ -n "$SESSION_NAME" ] && [ "$IS_FORK" != "1" ] && [ "$IS_CONTINUE" != "1" ]; then
-  PEER_ID="${tool.kind}-\$(sanitize_peer_part "$SESSION_NAME")"
+  PEER_ID=$(provider_peer_id "$SESSION_NAME") || exec "$REAL_BIN" "$@"
 else
   PEER_ID="${tool.kind}-\$(tty_peer_part)"
 fi
@@ -289,8 +340,59 @@ if [ -z "$HCC_ROOT" ]; then
   exec "$REAL_BIN" "$@"
 fi
 
-sanitize_peer_part() {
-  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9._-]/-/g; s/^-*//; s/-*$//' | cut -c 1-32
+# sess-04: sha1 hash of the FULL provider id/name, first 8 hex chars — must
+# match the JS shortHash() exactly (lib/core/peers/format.mjs). Name-based ids
+# that share a prefix used to collide into the same peer id.
+is_sha1_hex() {
+  [ "\${#1}" -eq 40 ] || return 1
+  case "$1" in
+    *[!0-9a-f]*) return 1 ;;
+  esac
+  return 0
+}
+
+peer_hash() {
+  local HASH=""
+  local OUTPUT=""
+
+  if command -v openssl >/dev/null 2>&1; then
+    OUTPUT=$(printf '%s' "$1" | openssl dgst -sha1 2>/dev/null || true)
+    HASH=$(printf '%s\n' "$OUTPUT" | awk 'NR == 1 { print $NF }' | tr '[:upper:]' '[:lower:]')
+    is_sha1_hex "$HASH" || HASH=""
+  fi
+
+  if [ -z "$HASH" ] && command -v sha1sum >/dev/null 2>&1; then
+    OUTPUT=$(printf '%s' "$1" | sha1sum 2>/dev/null || true)
+    HASH=$(printf '%s\n' "$OUTPUT" | awk 'NR == 1 { print $1 }' | tr '[:upper:]' '[:lower:]')
+    is_sha1_hex "$HASH" || HASH=""
+  fi
+
+  if [ -z "$HASH" ] && command -v shasum >/dev/null 2>&1; then
+    OUTPUT=$(printf '%s' "$1" | shasum 2>/dev/null || true)
+    HASH=$(printf '%s\n' "$OUTPUT" | awk 'NR == 1 { print $1 }' | tr '[:upper:]' '[:lower:]')
+    is_sha1_hex "$HASH" || HASH=""
+  fi
+
+  # A hello-cc environment always has node on PATH (hcc itself is a node CLI),
+  # so this fallback guarantees registration even on minimal systems without
+  # openssl/sha1sum/shasum. Digest must match the JS shortHash exactly.
+  if [ -z "$HASH" ] && command -v node >/dev/null 2>&1; then
+    HASH=$(printf '%s' "$1" | node -e 'let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>process.stdout.write(require("node:crypto").createHash("sha1").update(d).digest("hex")))' 2>/dev/null || true)
+    is_sha1_hex "$HASH" || HASH=""
+  fi
+
+  if ! is_sha1_hex "$HASH"; then
+    printf '%s\n' 'hello-cc: unable to derive peer id: no SHA-1 command produced a valid digest' >&2
+    return 1
+  fi
+
+  printf '%.8s' "$HASH"
+}
+
+provider_peer_id() {
+  local HASH_PART=""
+  HASH_PART=$(peer_hash "$1") || return 1
+  printf '%s-%s' '${tool.kind}' "$HASH_PART"
 }
 
 tty_peer_part() {
@@ -326,7 +428,7 @@ done
 if [ -n "$HCC_PEER" ]; then
   PEER_ID="$HCC_PEER"
 elif [ "$SUBCMD" = "resume" ] && [ -n "$RESUME_ID" ]; then
-  PEER_ID="${tool.kind}-\$(sanitize_peer_part "\${RESUME_ID:0:8}")"
+  PEER_ID=$(provider_peer_id "$RESUME_ID") || exec "$REAL_BIN" "$@"
 else
   PEER_ID="${tool.kind}-\$(tty_peer_part)"
 fi

package/lib/process/identity.mjs

@@ -0,0 +1,192 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+
+function hashCommand(command) {
+  return createHash('sha256').update(String(command ?? '').trim()).digest('hex');
+}
+
+function parseLinuxStat(text) {
+  const stat = String(text ?? '');
+  const prefix = stat.match(/^\s*\d+\s+\(/);
+  if (!prefix) return null;
+
+  const close = stat.lastIndexOf(')');
+  if (close < prefix[0].length - 1 || !/^\s/.test(stat.slice(close + 1))) return null;
+
+  const fields = stat.slice(close + 1).trim().split(/\s+/);
+  const state = fields[0];
+  const startTicks = fields[19];
+  if (fields.length < 20 || !/^[RSDZTWXxKtPI]$/.test(state) ||
+      !/^\d+$/.test(startTicks) || BigInt(startTicks) <= 0n) return null;
+  return { state, startTicks };
+}
+
+export function parseLinuxStatStartTicks(text) {
+  return parseLinuxStat(text)?.startTicks || null;
+}
+
+export function parsePsStartIdentity(text) {
+  const line = String(text ?? '').trimEnd();
+  if (line.includes('\n') || line.includes('\r')) return null;
+
+  const tab = line.indexOf('\t');
+  if (tab < 0) return null;
+
+  const startToken = line.slice(0, tab).trim();
+  const command = line.slice(tab + 1).trim();
+  return startToken && command ? { startToken, command } : null;
+}
+
+function probeProcess(pid) {
+  try {
+    process.kill(pid, 0);
+    return 'present';
+  } catch (error) {
+    if (error?.code === 'ESRCH') return 'dead';
+    if (error?.code === 'EPERM') return 'present';
+    return 'unknown';
+  }
+}
+
+function linuxObservation(pid) {
+  const first = parseLinuxStat(fs.readFileSync(`/proc/${pid}/stat`, 'utf8'));
+  if (!first) return { state: 'unknown', identity: null };
+  if (['Z', 'X', 'x'].includes(first.state)) return { state: 'dead', identity: null };
+  const bootId = fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+  const command = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8')
+    .split('\0')
+    .filter(Boolean)
+    .join(' ');
+  const confirmed = parseLinuxStat(fs.readFileSync(`/proc/${pid}/stat`, 'utf8'));
+
+  if (!confirmed) return { state: 'unknown', identity: null };
+  if (['Z', 'X', 'x'].includes(confirmed.state)) return { state: 'dead', identity: null };
+  if (!bootId || !command.trim() || confirmed.startTicks !== first.startTicks) {
+    return { state: 'unknown', identity: null };
+  }
+  return {
+    state: 'live',
+    identity: {
+      pid,
+      startToken: `${bootId}:${first.startTicks}`,
+      commandHash: hashCommand(command)
+    }
+  };
+}
+
+function run(command, args, environment) {
+  const options = {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  };
+  if (environment) options.env = environment;
+  return spawnSync(command, args, options);
+}
+
+function parseMacBootToken(text) {
+  const match = String(text ?? '').match(
+    /^\s*\{\s*sec\s*=\s*(\d+)\s*,\s*usec\s*=\s*(\d+)\s*\}/
+  );
+  if (!match) return null;
+
+  const seconds = BigInt(match[1]);
+  const microseconds = Number(match[2]);
+  if (seconds <= 0n || !Number.isInteger(microseconds) ||
+      microseconds < 0 || microseconds > 999999) return null;
+  return `${seconds}:${microseconds}`;
+}
+
+function macIdentity(pid) {
+  const boot = run('sysctl', ['-n', 'kern.boottime']);
+  if (boot.error || boot.status !== 0) return null;
+  const bootToken = parseMacBootToken(boot.stdout);
+  if (!bootToken) return null;
+
+  const psEnvironment = { ...process.env, TZ: 'UTC', LC_ALL: 'C', LANG: 'C' };
+  const started = run('ps', ['-p', String(pid), '-o', 'lstart='], psEnvironment);
+  const command = run('ps', ['-p', String(pid), '-o', 'command='], psEnvironment);
+  const confirmedStarted = run('ps', ['-p', String(pid), '-o', 'lstart='], psEnvironment);
+  if (started.error || command.error || confirmedStarted.error) return null;
+  if (started.status !== 0 ||
+      command.status !== 0 || confirmedStarted.status !== 0) return null;
+
+  const commandOutput = String(command.stdout ?? '').trim();
+  const parsed = parsePsStartIdentity(
+    `${String(started.stdout ?? '').trim()}\t${commandOutput}\n`
+  );
+  const confirmed = parsePsStartIdentity(
+    `${String(confirmedStarted.stdout ?? '').trim()}\t${commandOutput}\n`
+  );
+  if (!parsed || !confirmed || confirmed.startToken !== parsed.startToken) return null;
+
+  return {
+    pid,
+    startToken: `${bootToken}:${parsed.startToken}`,
+    commandHash: hashCommand(parsed.command)
+  };
+}
+
+function isCompleteIdentity(value) {
+  return Number.isInteger(value?.pid) && value.pid > 0 &&
+    typeof value.startToken === 'string' && value.startToken.trim().length > 0 &&
+    typeof value.commandHash === 'string' && /^[a-f0-9]{64}$/.test(value.commandHash);
+}
+
+export async function waitForLiveProcessIdentity(value, options = {}) {
+  const inspect = options.inspect || inspectProcessIdentity;
+  const monotonicNow = options.monotonicNow || (() => performance.now());
+  const wait = options.sleep || ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+  const timeoutMs = Math.max(0, Number(options.timeoutMs ?? 250));
+  const intervalMs = Math.max(1, Number(options.intervalMs ?? 5));
+  const deadline = monotonicNow() + timeoutMs;
+
+  while (true) {
+    const observed = inspect(value);
+    if (observed?.state === 'dead') return { state: 'dead', identity: null };
+    if (observed?.state === 'live' && isCompleteIdentity(observed.identity)) return observed;
+
+    const remainingMs = deadline - monotonicNow();
+    if (remainingMs <= 0) return { state: 'unknown', identity: null };
+    await wait(Math.min(intervalMs, remainingMs));
+  }
+}
+
+export function inspectProcessIdentity(value) {
+  let pid;
+  try {
+    pid = Number(value);
+  } catch {
+    return { state: 'unknown', identity: null };
+  }
+  if (!Number.isInteger(pid) || pid <= 0) return { state: 'unknown', identity: null };
+
+  const initialState = probeProcess(pid);
+  if (initialState === 'dead') return { state: 'dead', identity: null };
+  if (initialState === 'unknown') return { state: 'unknown', identity: null };
+
+  let identity = null;
+  try {
+    if (process.platform === 'linux') {
+      const observed = linuxObservation(pid);
+      if (observed.state === 'dead') return observed;
+      identity = observed.identity;
+    }
+    else if (process.platform === 'darwin') identity = macIdentity(pid);
+  } catch {
+    identity = null;
+  }
+
+  const finalState = probeProcess(pid);
+  if (finalState === 'dead') return { state: 'dead', identity: null };
+  if (finalState === 'unknown' || !isCompleteIdentity(identity)) {
+    return { state: 'unknown', identity: null };
+  }
+  return { state: 'live', identity };
+}
+
+export function compareProcessIdentity(stored, current) {
+  if (!isCompleteIdentity(stored) || !isCompleteIdentity(current)) return 'unknown';
+  return stored.pid === current.pid &&
+    stored.startToken === current.startToken ? 'live' : 'dead';
+}