agent-device-lab 0.0.0-stage → 0.3.1

package/dist/core/migrate.js

@@ -0,0 +1,35 @@
+import { parseProfile } from './profile.js';
+import { CONTRACT_VERSIONS } from './versions.js';
+/**
+ * Migrate a raw profile object. An invalid profile throws `invalid_profile`, a newer one
+ * `profile_too_new` (both from `parseProfile`, so the rules are the ones `start` applies).
+ * A current profile is returned unchanged.
+ *
+ * schemaVersion 1 → 2: the `web` section becomes `services.web` (same keys: v2 infers an http check
+ * from the service url and `readiness.path`, so nothing is added), `app` points at it, and every other
+ * top-level field is kept in place.
+ */
+export function migrateProfile(raw) {
+    const parsed = parseProfile(raw, '/migrate/agentlab.json'); // throws on invalid or too new
+    const obj = raw;
+    const to = CONTRACT_VERSIONS.profile;
+    if (parsed.schemaVersion === to)
+        return { changed: false, from: to, to, profile: obj, notes: [] };
+    const notes = ['schemaVersion 1 → 2'];
+    const profile = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === 'schemaVersion')
+            profile.schemaVersion = to;
+        else if (key === 'web') {
+            profile.services = { web: structuredClone(value) };
+            profile.app = { service: 'web' };
+            notes.push('"web" became "services.web"', 'added "app": {"service": "web"}');
+        }
+        else if (key === 'app')
+            notes.push('dropped "app": schemaVersion 1 ignored it, and the application is now services.web');
+        else
+            profile[key] = value;
+    }
+    return { changed: true, from: 1, to, profile, notes };
+}
+//# sourceMappingURL=migrate.js.map

package/dist/core/observation.js

@@ -0,0 +1,161 @@
+import { redactUrlSecrets } from './url-redact.js';
+import { SCHEMA_VERSION } from './schema.js';
+/** Turn raw page data into a normalised observation with layout flags. Pure. */
+export function buildObservation(raw, ctx) {
+    const { pathname, search, hash } = new URL(raw.url);
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        sessionId: ctx.sessionId,
+        gen: ctx.gen,
+        docId: raw.docId,
+        // Tokens in the query or fragment never leave the page: see url-redact.ts.
+        url: redactUrlSecrets(raw.url),
+        route: redactUrlSecrets(pathname + search + hash),
+        title: raw.title,
+        viewport: raw.viewport,
+        scroll: raw.scroll,
+        documentWidth: raw.documentWidth,
+        layoutViewportWidth: raw.layoutViewportWidth,
+        headings: raw.headings,
+        ...(raw.dialog !== undefined ? { dialog: raw.dialog } : {}),
+        controls: raw.controls,
+        omitted: raw.omitted,
+        inert: raw.inert,
+        messages: raw.messages,
+        ...(raw.focused ? { focused: raw.focused } : {}),
+        layout: layoutFlags(raw),
+        console: { errors: ctx.consoleErrors },
+        network: { failed: ctx.failedRequests },
+        findings: 0,
+    };
+}
+/**
+ * First-slice layout signals, measured in CSS px. This is not the responsive scanner: it only reports
+ * document-level horizontal overflow and observed controls that extend past the layout viewport.
+ */
+export function layoutFlags(raw) {
+    const flags = [];
+    const vw = raw.viewport.width;
+    if (raw.documentWidth > vw + 1) {
+        flags.push({
+            kind: 'horizontal-overflow',
+            severity: 'medium',
+            key: 'overflow',
+            message: `document is ${raw.documentWidth}px wide, viewport is ${vw}px (page pans sideways)` +
+                (raw.layoutViewportWidth && raw.layoutViewportWidth > vw + 1 ? `; mobile browser widened the layout viewport to ${raw.layoutViewportWidth}px` : ''),
+            evidence: { documentWidth: raw.documentWidth, viewportWidth: vw, excessPx: raw.documentWidth - vw, ...(raw.layoutViewportWidth ? { layoutViewportWidth: raw.layoutViewportWidth } : {}) },
+        });
+    }
+    for (const c of raw.controls) {
+        if (!c.clip)
+            continue;
+        const beyond = Math.min(c.clip.px, c.rect.w);
+        const hiddenShare = beyond / Math.max(c.rect.w, 1);
+        flags.push({
+            kind: 'control-clipped',
+            severity: hiddenShare >= 0.5 ? 'high' : 'medium',
+            key: `clipped:${c.ref}`,
+            ref: c.ref,
+            message: `${c.role} "${c.name}" extends ${c.clip.px}px past the ${c.clip.side} edge of the ${vw}px viewport` +
+                (hiddenShare >= 1 ? ' (entirely outside the initial view)' : ` (${Math.round(hiddenShare * 100)}% outside)`),
+            evidence: { left: c.rect.x, right: c.rect.x + c.rect.w, width: c.rect.w, viewportWidth: vw, side: c.clip.side, pastEdgePx: c.clip.px },
+        });
+    }
+    return flags;
+}
+const summary = (c) => ({ ref: c.ref, role: c.role, name: c.name });
+const TRACKED = ['name', 'value', 'disabled', 'checked', 'pressed', 'expanded', 'selected', 'required', 'invalid'];
+/** Compare two observations. Refs are identity; a new document resets the baseline. Pure. */
+export function diffObservations(prev, next) {
+    const changes = {
+        added: [], removed: [], changed: [], rerendered: [], covered: 0, uncovered: 0,
+        messagesAdded: [], messagesRemoved: [], headingsAdded: [], headingsRemoved: [],
+        layoutAdded: [], layoutResolved: [], none: false,
+    };
+    if (!prev) {
+        changes.reset = { reason: 'no-baseline' };
+        return changes;
+    }
+    if (prev.route !== next.route)
+        changes.route = { from: prev.route, to: next.route };
+    if (prev.title !== next.title)
+        changes.title = { from: prev.title, to: next.title };
+    if (prev.docId !== next.docId) {
+        changes.reset = { reason: 'navigation' };
+        return changes;
+    }
+    if (prev.dialog !== next.dialog)
+        changes.dialog = { from: prev.dialog, to: next.dialog };
+    const before = new Map(prev.controls.map((c) => [c.ref, c]));
+    const after = new Map(next.controls.map((c) => [c.ref, c]));
+    const prevInert = new Map(prev.inert.map((c) => [c.ref, c]));
+    const nextInert = new Set(next.inert.map((c) => c.ref));
+    const appeared = [];
+    for (const [ref, c] of after) {
+        const old = before.get(ref);
+        if (!old) {
+            if (prevInert.has(ref))
+                changes.uncovered++;
+            else
+                appeared.push(c);
+            continue;
+        }
+        const fields = [];
+        for (const key of TRACKED) {
+            const a = old[key] ?? (key === 'value' || key === 'name' ? undefined : false);
+            const b = c[key] ?? (key === 'value' || key === 'name' ? undefined : false);
+            if (a !== b)
+                fields.push({ field: key, from: a, to: b });
+        }
+        if (fields.length)
+            changes.changed.push({ ...summary(c), fields });
+    }
+    // Gone from view: previously observed controls, plus controls that disappeared while covered by a dialog.
+    const vanished = [];
+    for (const [ref, c] of before) {
+        if (after.has(ref))
+            continue;
+        if (nextInert.has(ref))
+            changes.covered++;
+        else
+            vanished.push(summary(c));
+    }
+    for (const [ref, c] of prevInert)
+        if (!after.has(ref) && !nextInert.has(ref))
+            vanished.push(c);
+    // Re-render heuristic: a vanished and an appeared control with the same role and name are the same
+    // thing drawn again. Match by identity of role+name only, never by list position.
+    const pool = new Map();
+    for (const v of vanished) {
+        const key = `${v.role}\u0000${v.name}`;
+        pool.set(key, [...(pool.get(key) ?? []), v]);
+    }
+    for (const c of appeared) {
+        const match = pool.get(`${c.role}\u0000${c.name}`)?.shift();
+        if (match)
+            changes.rerendered.push({ ...summary(c), from: match.ref, to: c.ref });
+        else
+            changes.added.push(summary(c));
+    }
+    changes.removed = [...pool.values()].flat();
+    const msgKey = (m) => `${m.role}\u0000${m.text}`;
+    const prevMsgs = new Set(prev.messages.map(msgKey));
+    const nextMsgs = new Set(next.messages.map(msgKey));
+    changes.messagesAdded = next.messages.filter((m) => !prevMsgs.has(msgKey(m)));
+    changes.messagesRemoved = prev.messages.filter((m) => !nextMsgs.has(msgKey(m)));
+    changes.headingsAdded = next.headings.filter((h) => !prev.headings.includes(h));
+    changes.headingsRemoved = prev.headings.filter((h) => !next.headings.includes(h));
+    if (prev.focused !== next.focused)
+        changes.focus = { from: prev.focused, to: next.focused };
+    const prevFlags = new Set(prev.layout.map((f) => f.key));
+    const nextFlags = new Set(next.layout.map((f) => f.key));
+    changes.layoutAdded = next.layout.filter((f) => !prevFlags.has(f.key));
+    // A flag whose control merely left the observation (e.g. covered by a dialog) is not "resolved".
+    changes.layoutResolved = prev.layout.filter((f) => !nextFlags.has(f.key) && (!f.ref || after.has(f.ref)));
+    changes.none = !changes.route && !changes.title && !changes.dialog && !changes.added.length && !changes.removed.length &&
+        !changes.changed.length && !changes.rerendered.length && !changes.covered && !changes.uncovered && !changes.messagesAdded.length &&
+        !changes.messagesRemoved.length && !changes.headingsAdded.length && !changes.headingsRemoved.length &&
+        !changes.focus && !changes.layoutAdded.length && !changes.layoutResolved.length;
+    return changes;
+}
+//# sourceMappingURL=observation.js.map

package/dist/core/ownership.js

@@ -0,0 +1,142 @@
+import { chmodSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describeMemberStop, stopGroup } from './process-group.js';
+import { checkIdentity, identify } from './process-identity.js';
+const ownedDir = (stateDir) => join(stateDir, 'owned');
+const recordFile = (stateDir, sessionId) => join(ownedDir(stateDir), `${sessionId}.json`);
+export function recordOwnership(stateDir, sessionId, services) {
+    mkdirSync(ownedDir(stateDir), { recursive: true, mode: 0o700 });
+    const record = { sessionId, owner: identify(process.pid), recordedAt: new Date().toISOString(), services };
+    const file = recordFile(stateDir, sessionId);
+    writeFileSync(file, JSON.stringify(record, null, 2), { mode: 0o600 });
+    chmodSync(file, 0o600);
+}
+export function releaseOwnership(stateDir, sessionId) {
+    rmSync(recordFile(stateDir, sessionId), { force: true });
+}
+/** Records in <stateDir>/owned; unreadable or malformed files are ignored. */
+export function readOwnership(stateDir) {
+    let names;
+    try {
+        names = readdirSync(ownedDir(stateDir));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names.filter((f) => f.endsWith('.json'))) {
+        try {
+            const r = JSON.parse(readFileSync(join(ownedDir(stateDir), n), 'utf8'));
+            if (typeof r.sessionId === 'string' && Array.isArray(r.services))
+                out.push(r);
+        }
+        catch { /* not a record */ }
+    }
+    return out;
+}
+/** An owner that is neither gone nor reused: a live session, or one whose identity cannot be checked. */
+const ownerPresent = (r) => {
+    const c = checkIdentity(r.owner);
+    return c !== 'gone' && c !== 'reused';
+};
+/** Run names (directories under runs/) that a live owner's record names: never pruned. */
+export function liveSessionIds(stateDir) {
+    return new Set(readOwnership(stateDir).filter(ownerPresent).map((r) => r.sessionId));
+}
+/**
+ * Stop recorded services the lab started: only owned process groups whose leader's identity still
+ * matches (SIGTERM, then SIGKILL after `graceMs` if the group has not emptied). If the leader (the
+ * shell wrapper) is gone, each recorded group member whose own identity still matches is signalled
+ * individually; any other process left in the group is reported, never signalled. A one-shot service's
+ * stop command is named for the person to run; its containers cannot be proved to still be the ones the
+ * lab started. Returns human-readable notes.
+ */
+export async function stopRecordedServices(records, opts = {}) {
+    const graceMs = opts.graceMs ?? 5000;
+    const notes = [];
+    const single = records.length === 1;
+    for (const s of [...records].reverse()) {
+        const label = single ? 'owned server' : `owned service "${s.name}"`;
+        if (!s.owned) {
+            notes.push(single ? 'reused server left running' : `service "${s.name}" was reused; left running`);
+            continue;
+        }
+        if (s.mode === 'oneshot') {
+            if (s.stopCommand)
+                notes.push(`${label} was started by a one-shot command; to stop it, run \`${s.stopCommand}\` in ${s.cwd}`);
+            continue;
+        }
+        const check = checkIdentity(s.identity);
+        if (check === 'unverifiable') {
+            notes.push(`${label} pid ${s.pid ?? '?'} cannot be verified; not signalled (check it manually)`);
+            continue;
+        }
+        const r = await stopGroup(s.identity, s.members ?? [], { graceMs });
+        if (r.via === 'group') {
+            notes.push(`stopped ${label} process group ${s.identity.pid}${r.graceful ? '' : ` (SIGKILL after ${graceMs}ms)`}`);
+            continue;
+        }
+        const detail = describeMemberStop(r, graceMs);
+        const lead = check === 'gone' ? `${label} had already exited` : `${label} pid ${s.pid} now belongs to another process; not signalled`;
+        notes.push(detail ? `${lead}; ${detail}` : lead);
+    }
+    return notes;
+}
+/**
+ * Clean up after sessions that died without stopping their services. A record whose owner is still the
+ * process that wrote it (a live session) is never touched, and neither is one whose owner cannot be
+ * verified. Returns notes; each handled record is removed.
+ */
+export async function reapOrphans(stateDir) {
+    const notes = [];
+    for (const r of readOwnership(stateDir)) {
+        if (ownerPresent(r))
+            continue;
+        const owned = r.services.filter((s) => s.owned);
+        if (owned.length) {
+            const stopped = await stopRecordedServices(owned);
+            notes.push(...stopped.map((n) => `session ${r.sessionId} ended without cleanup: ${n}`));
+        }
+        releaseOwnership(stateDir, r.sessionId);
+    }
+    return notes;
+}
+/**
+ * Delete the oldest runs beyond the `keep` most recent (0 keeps all), never one in `protect`. Returns
+ * the deleted run names. Run names sort chronologically (s-YYYYMMDDHHMMSS-xxxx).
+ */
+export function pruneRuns(stateDir, keep, protect) {
+    if (!(keep > 0))
+        return [];
+    const runs = join(stateDir, 'runs');
+    let names;
+    try {
+        names = readdirSync(runs).filter((n) => { try {
+            return statSync(join(runs, n)).isDirectory();
+        }
+        catch {
+            return false;
+        } });
+    }
+    catch {
+        return [];
+    }
+    names.sort();
+    const removed = [];
+    for (const n of names.slice(0, Math.max(0, names.length - keep))) {
+        if (protect.has(n))
+            continue;
+        rmSync(join(runs, n), { recursive: true, force: true });
+        removed.push(n);
+    }
+    return removed;
+}
+/** AGENTLAB_KEEP_RUNS, default 20; 0 keeps everything. */
+export function keepRuns(env = process.env) {
+    const v = env.AGENTLAB_KEEP_RUNS;
+    if (v === undefined || v === '')
+        return 20;
+    const n = Number(v);
+    return Number.isInteger(n) && n >= 0 ? n : 20;
+}
+//# sourceMappingURL=ownership.js.map

package/dist/core/process-group.js

@@ -0,0 +1,206 @@
+import { execFileSync } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
+import { redactSecrets } from './feed.js';
+import { checkIdentity, identify } from './process-identity.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const COMMAND_MAX = 100;
+function shorten(text) {
+    const t = redactSecrets(text.replace(/\s+/g, ' ').trim());
+    return t.length > COMMAND_MAX ? `${t.slice(0, COMMAND_MAX)}…` : t;
+}
+/** Live (not zombie) processes whose process group is `pgid`, including the leader if it is still there. */
+export function listGroup(pgid) {
+    if (!Number.isInteger(pgid) || pgid <= 0)
+        return [];
+    const out = [];
+    if (process.platform === 'linux') {
+        let names;
+        try {
+            names = readdirSync('/proc');
+        }
+        catch {
+            return [];
+        }
+        for (const n of names) {
+            if (!/^\d+$/.test(n))
+                continue;
+            try {
+                const stat = readFileSync(`/proc/${n}/stat`, 'utf8');
+                // Fields after the last ')': state, ppid, pgrp.
+                const f = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+                if (Number(f[2]) !== pgid || f[0] === 'Z')
+                    continue;
+                let command = '';
+                try {
+                    command = readFileSync(`/proc/${n}/cmdline`, 'utf8').split('\0').join(' ');
+                }
+                catch { /* exited */ }
+                if (!command.trim())
+                    command = stat.slice(stat.indexOf('(') + 1, stat.lastIndexOf(')'));
+                out.push({ pid: Number(n), command: shorten(command) });
+            }
+            catch { /* exited while scanning */ }
+        }
+        return out;
+    }
+    try {
+        const text = execFileSync('ps', ['-axo', 'pid=,pgid=,stat=,command='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        for (const line of text.split('\n')) {
+            const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+            if (m && Number(m[2]) === pgid && !m[3].startsWith('Z'))
+                out.push({ pid: Number(m[1]), command: shorten(m[4]) });
+        }
+    }
+    catch { /* ps unavailable */ }
+    return out;
+}
+/**
+ * The members of the leader's process group right now, each with its own identity (the leader itself is
+ * not included). Only while the leader is verifiably the recorded process: then the pgid is its group.
+ */
+export function snapshotMembers(leader) {
+    if (!leader || checkIdentity(leader) !== 'same')
+        return undefined;
+    const out = [];
+    for (const p of listGroup(leader.pid)) {
+        if (p.pid === leader.pid)
+            continue;
+        const id = identify(p.pid);
+        if (id)
+            out.push({ ...id, command: p.command });
+    }
+    return out;
+}
+const keyOf = (m) => `${m.pid}:${m.startTime}`;
+/** A new snapshot added to what was recorded before; members that have since exited are dropped. */
+export function mergeMembers(previous, snapshot) {
+    const merged = new Map();
+    for (const m of previous)
+        if (checkIdentity(m) === 'same')
+            merged.set(keyOf(m), m);
+    for (const m of snapshot)
+        merged.set(keyOf(m), m);
+    return [...merged.values()];
+}
+/** Still running: the identity matches and the process is not a zombie. */
+function live(m) {
+    if (checkIdentity(m) !== 'same')
+        return false;
+    return !isZombie(m.pid);
+}
+/** Is this pid a zombie? (A killed child that nobody has reaped yet is no longer running.) */
+function isZombie(pid) {
+    if (process.platform === 'linux') {
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+            return stat.slice(stat.lastIndexOf(')') + 2).startsWith('Z');
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        return execFileSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().startsWith('Z');
+    }
+    catch {
+        return false;
+    }
+}
+export const describeProcess = (p) => `${p.command || '?'} (pid ${p.pid})`;
+/**
+ * Stop what a service started. With the leader verified (`same`) the whole group is signalled (SIGTERM,
+ * then SIGKILL after `graceMs` if it has not emptied). With the leader gone, each recorded member whose
+ * identity still matches is signalled on its own; nothing unrecorded is ever signalled, only reported.
+ * A leader that is `reused` or `unverifiable` is never signalled at all, and its group is not scanned.
+ * `liveLeaderPid` is for a caller that still holds the unreaped child handle of the leader.
+ */
+export async function stopGroup(leader, members, opts) {
+    const sig = opts.signal ?? 'SIGTERM';
+    // A caller that still holds the unreaped child handle has already proved the leader pid is its own.
+    const check = opts.liveLeaderPid ? 'same' : checkIdentity(leader);
+    const result = { via: 'none', leader: check, graceful: true, stopped: [], survivors: [], unverified: [] };
+    if (check === 'same') {
+        const pgid = opts.liveLeaderPid ?? leader.pid;
+        const signal = (s) => { try {
+            process.kill(-pgid, s);
+        }
+        catch { /* group already gone */ } };
+        const groupAlive = () => { try {
+            process.kill(-pgid, 0);
+            return true;
+        }
+        catch (err) {
+            return err.code === 'EPERM';
+        } };
+        signal(sig);
+        const deadline = Date.now() + opts.graceMs;
+        while (groupAlive() && Date.now() < deadline)
+            await sleep(50);
+        result.via = 'group';
+        result.graceful = !groupAlive();
+        if (!result.graceful) {
+            signal('SIGKILL');
+            for (let i = 0; i < 40 && groupAlive(); i++)
+                await sleep(50);
+        }
+        return result;
+    }
+    if (check === 'unverifiable')
+        return result;
+    // The leader is gone (or its pid now belongs to something else): only recorded, still-matching members.
+    const targets = members.filter((m) => checkIdentity(m) === 'same');
+    const as = (m) => ({ pid: m.pid, command: m.command });
+    const send = (list, s) => {
+        for (const m of list) {
+            // Re-check just before signalling: the pid must still be the recorded process.
+            if (checkIdentity(m) === 'same') {
+                try {
+                    process.kill(m.pid, s);
+                }
+                catch { /* gone */ }
+            }
+        }
+    };
+    if (targets.length) {
+        result.via = 'members';
+        send(targets, sig);
+        const deadline = Date.now() + opts.graceMs;
+        while (targets.some(live) && Date.now() < deadline)
+            await sleep(50);
+        const stillRunning = targets.filter(live);
+        result.graceful = stillRunning.length === 0;
+        if (stillRunning.length) {
+            send(stillRunning, 'SIGKILL');
+            for (let i = 0; i < 40 && targets.some(live); i++)
+                await sleep(50);
+        }
+        result.stopped = targets.map(as);
+        result.survivors = targets.filter(live).map(as);
+    }
+    // A gone leader's pid cannot be reused while its group still has members, so what is left is that group.
+    if (check === 'gone' && leader) {
+        const known = new Set(members.map(keyOf));
+        result.unverified = listGroup(leader.pid).filter((p) => {
+            const id = identify(p.pid);
+            return !id || !known.has(keyOf(id));
+        });
+    }
+    return result;
+}
+/** Notes for a person about a stop that went through members (or left unrecorded processes behind). */
+export function describeMemberStop(r, graceMs) {
+    const parts = [];
+    if (r.stopped.length) {
+        const survivors = new Set(r.survivors.map((p) => p.pid));
+        const gone = r.stopped.filter((p) => !survivors.has(p.pid));
+        if (gone.length)
+            parts.push(`stopped ${gone.length === 1 ? 'recorded member' : 'recorded members'} ${gone.map(describeProcess).join(', ')}${r.graceful ? '' : ` (SIGKILL after ${graceMs}ms)`}`);
+        if (r.survivors.length)
+            parts.push(`recorded ${r.survivors.length === 1 ? 'member' : 'members'} still running after SIGKILL: ${r.survivors.map(describeProcess).join(', ')}`);
+    }
+    if (r.unverified.length) {
+        parts.push(`${r.unverified.length} ${r.unverified.length === 1 ? 'process remains' : 'processes remain'} in the group unverified and ${r.unverified.length === 1 ? 'was' : 'were'} not signalled: ${r.unverified.map(describeProcess).join(', ')} (stop ${r.unverified.length === 1 ? 'it' : 'them'} yourself if ${r.unverified.length === 1 ? 'it is' : 'they are'} part of the service)`);
+    }
+    return parts.join('; ');
+}
+//# sourceMappingURL=process-group.js.map

package/dist/core/process-identity.js

@@ -0,0 +1,56 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+export function identify(pid) {
+    if (!pid || !Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    if (process.platform === 'linux') {
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+            // Field 2 (comm) may contain spaces and parentheses; fields after the last ')' start at field 3.
+            const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+            const startTime = fields[19]; // field 22
+            if (!startTime)
+                return undefined;
+            return { pid, startTime, bootId: bootId() };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    try {
+        const startTime = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        return startTime ? { pid, startTime } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Compare a recorded identity with whatever currently holds that PID. */
+export function checkIdentity(recorded) {
+    if (!recorded?.pid || !recorded.startTime)
+        return 'unverifiable';
+    const current = identify(recorded.pid);
+    if (!current)
+        return 'gone';
+    if (current.startTime !== recorded.startTime)
+        return 'reused';
+    if (recorded.bootId && current.bootId && recorded.bootId !== current.bootId)
+        return 'reused';
+    return 'same';
+}
+export function isSameProcess(recorded) {
+    return checkIdentity(recorded) === 'same';
+}
+let cachedBootId;
+function bootId() {
+    if (cachedBootId === undefined) {
+        try {
+            cachedBootId = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+        }
+        catch {
+            cachedBootId = '';
+        }
+    }
+    return cachedBootId || undefined;
+}
+//# sourceMappingURL=process-identity.js.map