@logicseek/hello-cc 0.1.8 → 1.0.0

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';
+}

package/lib/process/pty-lifecycle.mjs

@@ -0,0 +1,149 @@
+import { waitForLiveProcessIdentity } from './identity.mjs';
+
+export function trackPtyExit(child) {
+  let exitEvent = null;
+  let resolveExit;
+  const promise = new Promise((resolve) => { resolveExit = resolve; });
+
+  child.onExit((event) => {
+    if (exitEvent !== null) return;
+    exitEvent = event;
+    resolveExit(event);
+  });
+
+  return {
+    promise,
+    get event() {
+      return exitEvent;
+    }
+  };
+}
+
+export function installPtyTerminationHandlers(child, options = {}) {
+  const emitter = options.emitter || process;
+  const setTimer = options.setTimer || setTimeout;
+  const clearTimer = options.clearTimer || clearTimeout;
+  const forceKillMs = Math.max(0, Number(options.forceKillMs ?? 1200));
+  let signal = null;
+  let forceKillTimer = null;
+
+  const onTerminate = (requestedSignal) => {
+    if (signal !== null) return;
+    signal = requestedSignal;
+    try { child.kill(requestedSignal === 'SIGTERM' ? 'SIGHUP' : requestedSignal); } catch {}
+    forceKillTimer = setTimer(() => {
+      try { child.kill('SIGKILL'); } catch {}
+    }, forceKillMs);
+    forceKillTimer?.unref?.();
+  };
+  const onSigint = () => onTerminate('SIGINT');
+  const onSigterm = () => onTerminate('SIGTERM');
+  emitter.once('SIGINT', onSigint);
+  emitter.once('SIGTERM', onSigterm);
+
+  return {
+    get signal() {
+      return signal;
+    },
+    dispose() {
+      emitter.off('SIGINT', onSigint);
+      emitter.off('SIGTERM', onSigterm);
+      if (forceKillTimer !== null) clearTimer(forceKillTimer);
+      forceKillTimer = null;
+    }
+  };
+}
+
+export function ptyTerminationSignal(wrapperSignal, childSignal) {
+  return wrapperSignal || childSignal || null;
+}
+
+export function ptyStartupFailureDisposition({ termination, childPid, childIdentity = null }) {
+  return {
+    status: termination.exited ? 'exited' : 'blocked',
+    eventType: termination.exited
+      ? 'run.session.exited'
+      : 'run.session.termination_unconfirmed',
+    preserveEvidence: !termination.exited,
+    childPid,
+    childIdentity
+  };
+}
+
+async function waitForTrackedExit(exit, timeoutMs, sleep) {
+  if (exit.event !== null) return { exited: true, event: exit.event };
+  const timedOut = Symbol('timed-out');
+  const result = await Promise.race([
+    exit.promise,
+    sleep(timeoutMs).then(() => timedOut)
+  ]);
+  return result === timedOut
+    ? { exited: false, event: null }
+    : { exited: true, event: result };
+}
+
+export async function stopPtyAfterStartupFailure(child, exit, options = {}) {
+  const graceMs = Math.max(0, Number(options.graceMs ?? 150));
+  const killTimeoutMs = Math.max(0, Number(options.killTimeoutMs ?? 1000));
+  const sleep = options.sleep || ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+
+  if (exit.event !== null) return { exited: true, event: exit.event };
+  try { child.kill('SIGHUP'); } catch {}
+  const graceful = await waitForTrackedExit(exit, graceMs, sleep);
+  if (graceful.exited) return graceful;
+
+  try { child.kill('SIGKILL'); } catch {}
+  return waitForTrackedExit(exit, killTimeoutMs, sleep);
+}
+
+export async function capturePtyStartupEvidence({
+  childPid,
+  wrapperPid,
+  exit,
+  waitForIdentity = waitForLiveProcessIdentity,
+  timeoutMs = 2000
+}) {
+  const identityCapture = Promise.all([
+    waitForIdentity(wrapperPid, { timeoutMs }),
+    waitForIdentity(childPid, { timeoutMs })
+  ]).then(([wrapperEvidence, childEvidence]) => ({
+    type: 'identity',
+    wrapperEvidence,
+    childEvidence
+  }));
+  const earlyExit = exit.promise.then((exitEvent) => ({ type: 'exit', exitEvent }));
+  const first = await Promise.race([identityCapture, earlyExit]);
+
+  if (first.type === 'exit' || exit.event !== null) {
+    return {
+      state: 'failed',
+      reason: 'child_exited_before_identity',
+      exitEvent: first.exitEvent || exit.event
+    };
+  }
+  if (first.wrapperEvidence.state !== 'live' || !first.wrapperEvidence.identity) {
+    return {
+      state: 'failed',
+      reason: 'wrapper_identity_unavailable',
+      exitEvent: null,
+      childIdentity: first.childEvidence.state === 'live'
+        ? first.childEvidence.identity
+        : null
+    };
+  }
+  if (first.childEvidence.state === 'dead') {
+    return {
+      state: 'failed',
+      reason: 'child_exited_before_identity',
+      exitEvent: null
+    };
+  }
+
+  return {
+    state: 'ready',
+    wrapperIdentity: first.wrapperEvidence.identity,
+    childIdentity: first.childEvidence.state === 'live'
+      ? first.childEvidence.identity
+      : null
+  };
+}

package/lib/runtime/buffer-directory-lease.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { withFileLock } from '../shared/file-lock.mjs';
+
+const BUFFER_DIRECTORY_LEASE_NAME = '.hcc-buffer-directory.lease';
+
+function canonicalDirectory(value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError('buffer directory must be a non-empty path');
+  }
+  const resolved = path.resolve(value);
+  const canonical = fs.realpathSync.native(resolved);
+  const stat = fs.statSync(canonical);
+  if (!stat.isDirectory()) throw new TypeError(`buffer directory is not a directory: ${resolved}`);
+  return canonical;
+}
+
+export function bufferDirectoryLeaseTarget(directory) {
+  return path.join(canonicalDirectory(directory), BUFFER_DIRECTORY_LEASE_NAME);
+}
+
+export function withBufferDirectoryLease(directory, fn, options = {}) {
+  if (typeof fn !== 'function') throw new TypeError('buffer directory lease callback must be a function');
+  const target = bufferDirectoryLeaseTarget(directory);
+  const lockOptions = {
+    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    ...(options.retryMs === undefined ? {} : { retryMs: options.retryMs }),
+    ...(options.nonblocking === undefined ? {} : { nonblocking: options.nonblocking })
+  };
+  return withFileLock(target, () => fn(path.dirname(target)), lockOptions);
+}
+
+export function withBufferDirectoryLeases(directories, fn, options = {}) {
+  if (typeof fn !== 'function') throw new TypeError('buffer directory leases callback must be a function');
+  const targets = [...new Set((directories || []).map(bufferDirectoryLeaseTarget))].sort();
+  const acquire = options.withLease || ((target, nested) => withFileLock(target, nested, {
+    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    ...(options.retryMs === undefined ? {} : { retryMs: options.retryMs }),
+    ...(options.nonblocking === undefined ? {} : { nonblocking: options.nonblocking })
+  }));
+
+  const visit = (index) => index >= targets.length
+    ? fn()
+    : acquire(targets[index], () => visit(index + 1));
+  return visit(0);
+}