session-peer 0.1.0-preview.0

package/RELEASING.md

@@ -0,0 +1,153 @@
+# Releasing session-peer previews
+
+The package is publication-ready (`private:false`), not automatically published.
+Merging, pushing, tagging or publishing a GitHub release does not run publish.yml.
+Only an explicitly approved manual dispatch can upload. Python session-peer and
+its Relay release train remain independent.
+
+## Before the first dispatch
+
+1. Merge the reviewed preparation PR and require main's exact-commit `cli` CI
+   (`release gate`) to pass. Match versions in package.json, lockfile,
+   src/protocol.ts and four READMEs. Only `X.Y.Z-preview.N` versions and the
+   `preview` dist-tag are supported; stable publication needs another review.
+2. In GitHub Settings → Environments, create **npm** with at least one required
+   reviewer. Restrict deployments to protected main. A solo maintainer may also
+   be the dispatcher: this is explicit approval, not two-person separation.
+   Do not bypass protection. Preflight rejects missing environments or reviewer
+   rules. This PR does not create or relax environment protection.
+3. Confirm npm account 2FA, package-name ownership and creation permissions.
+   A registry 404 does not reserve the name. Review VALIDATION.md and architecture
+   coverage; historical real-TUI ACKs predate the command rename. Do not claim
+   full native-agent architecture coverage from CI fixtures.
+4. For the initial **0.1.0-preview.0 only**, repository secret **NPM_TOKEN** supplies
+   bootstrap authentication. Use a short-expiry, least-privilege granular token
+   permitting this new package. Noninteractive direct publication requires a token
+   allowed to bypass npm's 2FA prompt. Secret existence does not establish its
+   permissions. Do not weaken account policy automatically: stop if unsuitable
+   and use an approved local interactive first publish instead.
+   Never put credentials in files, logs, issues or chat. Builds/tests/packing
+   never receive this secret.
+5. Obtain final approval for the exact main commit, version and mode. A merged
+   preparation PR is not publication approval. Optional GitHub draft release
+   notes must target that same commit; the workflow creates no tag or release.
+   Runtime changes require separate reviewed evidence.
+
+## First package: bootstrap-token
+
+### Initial failed attempt (2026-09-27)
+
+[Run 36308424358](https://github.com/abruption/session-peer-ts/actions/runs/36308424358)
+attempted the old npm name `session-peer-ts@0.1.0-preview.0`. Build and artifact
+checks passed, but the registry refused the PUT with HTTP 403 / E_STAGE_REQUIRED:
+the supplied token could only stage, and the package did not exist. A Sigstore
+provenance entry was created before that rejection; it is not proof of npm
+publication. Both npm names returned 404 during the subsequent read-only check.
+
+The intended npm name is now **session-peer**; the GitHub repository remains
+**abruption/session-peer-ts**. Renaming does not fix the authentication restriction.
+Do not rerun the old workflow or switch it to staging: a new package cannot be
+created by staging. Before an approved new attempt, the owner must resolve the
+initial direct-publication authorization or perform an approved interactive
+first publish with 2FA. Do not disable 2FA, automatically replace credentials or
+assume changing a token option bypasses current npm policy. The stored secret's
+value and settings were not inspected. This PR does not reattempt publication.
+
+### Inputs after authentication is resolved
+
+Actions → **npm preview publication** → Run workflow → **main**:
+
+- mode: `bootstrap-token`
+- version: `0.1.0-preview.0`
+- confirmation: `session-peer@0.1.0-preview.0 bootstrap-token`
+
+Preflight requires current main SHA, successful exact-commit main CI and the
+protected npm environment. Bootstrap refuses **any existing registry package**
+under this name. The prepare job tests without publication credentials, packs
+twice, compares hashes, checks the allowlist and tests installation/uninstallation
+of the exact tarball. Its retained artifact includes tarball and manifest.json
+(commit, SHA-256 and SHA-512 integrity). Actions are pinned by commit; release
+builds use Node 24/npm 11.15.0 without dependency caches or lifecycle scripts.
+
+After environment approval, a fresh job downloads the artifact without rebuilding,
+rechecks main/CI/registry and validates its contents. Only one `npm publish`
+step receives NPM_TOKEN (`--tag preview --access public --provenance
+--ignore-scripts`). OIDC permission is also granted for provenance. Upload
+network retries are disabled. Do not rerun failed or uncertain publication.
+
+Verification compares registry integrity and preview tag, rejects accidental
+latest promotion, requires registry attestation metadata, runs `npm audit
+signatures`, and fresh-installs/uninstalls the published version. Only a passed
+verification completes bootstrap release; a successful upload alone does not.
+Bounded read-only propagation checks are not upload retries.
+
+## Register npm Trusted Publisher after the first release
+
+npmjs.com → package **session-peer** → Settings → Trusted publishing:
+
+| Field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization or user | `abruption` |
+| Repository | `session-peer-ts` |
+| Workflow filename | `publish.yml` (no directory prefix) |
+| Environment name | `npm` |
+| Allowed actions | Stage-only: `npm stage publish`, not direct `npm publish` |
+
+The workflow must exist on main. npm does not validate the connection on save;
+validate it with the next authorized staged version. GitHub-hosted runners are
+required. Public GitHub + public npm OIDC publishing provides provenance.
+
+After verifying bootstrap and configuring trust, revoke its token in npm and
+remove GitHub NPM_TOKEN. Set npm publishing access to **Require two-factor
+authentication and disallow tokens**. These account changes need owner approval
+and are not performed by this workflow. trusted-stage never references NPM_TOKEN;
+an OIDC failure must not cause token fallback. Remove the bootstrap branch in a
+follow-up PR.
+
+## Later previews: trusted-stage
+
+Prepare a new immutable preview version through a PR. Dispatch main with mode
+`trusted-stage`, its exact version and confirmation
+`session-peer@<version> trusted-stage`. The same gates apply. The package must
+already exist; published versions are refused. One `npm stage publish` runs
+with OIDC and the preview tag.
+
+**A successful staged run is pending approval, not a public release.** Record its
+stage ID from npm output. Review its tarball against the retained manifest and
+approve with 2FA in npmjs.com or interactive `npm stage approve`. OIDC cannot
+approve, list or view stages. Public registry metadata cannot reveal pending
+stages, so collisions fail at the registry and need manual inspection, not retries.
+
+After approval, check out the exact source commit and download that run artifact
+into `release-dist/`. With Node 24 and npm 11.15.0:
+
+```sh
+node scripts/release.mjs artifact
+node scripts/release.mjs verify
+```
+
+Neither command publishes. verify uses public reads, an isolated no-lifecycle
+install and signature checks; it needs no publish token. Do not announce release
+completion until it passes. Stable promotion and fleet installation remain
+separate decisions.
+
+## Failure handling
+
+Missing/invalid token, 2FA challenge, missing environment, bad OIDC mapping,
+non-404 registry errors, stale main, conflicting versions, upload timeout and
+hash mismatch are stop conditions. Never automatically change auth mode, retry
+upload, unpublish, move a tag, reuse a version or promote latest to obtain green
+checks. Inspect registry/staged state and retained evidence first. Read-only
+verification of the exact artifact may be repeated; publication may not.
+A broken/partial public release requires a reviewed new version and approval.
+
+## Sources
+
+- [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
+- [npm staged publishing](https://docs.npmjs.com/staged-publishing)
+- [npm stage CLI and token/2FA behavior](https://docs.npmjs.com/cli/v11/commands/npm-stage)
+
+Requirements checked 2026-09-27: OIDC needs npm ≥11.5.1, staging ≥11.15.0, both
+with Node ≥22.14.0. Application support remains Node 22.13+ within 22.x and 24.x;
+release-tool requirements are separate.

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security policy
+
+Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/abruption/session-peer-ts/security/advisories/new),
+not public issues, PRs or comments. Alternatively email
+[support@abruption.dev](mailto:support@abruption.dev?subject=%5Bsession-peer-ts%5D%20Security)
+with `[session-peer-ts] Security`. Email is private contact, not an end-to-end
+encrypted submission mechanism. Start with a redacted description only.
+
+Include commit/version, install method, OS, architecture, Node and native agent
+versions on each endpoint, affected command, attacker access, impact and a minimal
+reproduction using dummy sessions/paths/messages. Remove credentials, tokens,
+keys, message content, session IDs and personal hosts/paths. Do not attach agent
+homes, SQLite DBs, transcripts, browser profiles or .env files. Rotate exposed
+secrets with their provider; deleting a comment does not revoke a secret.
+
+Review is manual and best-effort, with no response or fix deadline. The project is
+an unpublished preview; reports on any commit are welcome but no stable support
+or backport promise exists. English and Korean reports are welcome. Disclosure
+is coordinated with the reporter; private reports are not automatically public.

package/VALIDATION.md

@@ -0,0 +1,77 @@
+# Validation record — 2026-09-27 KST
+
+This is preview evidence, not an npm release or a claim of complete Python parity.
+Python reference: v1.0.2, commit `47c23713d0a2a3c11ebde6186afd8c43489b8b65`.
+
+## Automated checks
+
+- 14 tests pass locally on macOS arm64 / Node 22.14.0.
+- Real fixture SQLite DBs, Unix inbox sockets and separate C processes holding
+  actual advisory locks; Python is the discovery oracle, not the implementation.
+- Refused inactive/ambiguous/wrong-owner cases; one native fixture queue call;
+  native nonzero after spawn and SSH response loss remain unknown with no retry.
+- Package file allowlist, same-build repeat SHA-256, clean prefix installation,
+  empty-PATH discovery and uninstall pass. npm audit reports 0 vulnerabilities.
+- CI defines macOS/Linux × Node 22/24; see the repository Actions results for
+  those runs rather than treating this local check as their substitute.
+
+## Real TUI and SSH checks
+
+Dedicated, newly created Claude/Codex test TUIs only. The user approved trusting
+the two otherwise empty test folders. Agent permissions were not changed.
+Each route passed discovery and no-delivery dry-run before exactly one send.
+ACKs below were observed as separate **assistant response lines in the owned
+live tmux panes**, not copied from submitted prompts, queues or transcript files.
+
+| Route | Native target | Submission | Actual response |
+| --- | --- | --- | --- |
+| Mac mini local | Claude Code 2.1.281 | posted | `ACK TS186-LOCAL-CLAUDE-8fc721d0` |
+| Mac mini local | Codex CLI 0.157.1 | queued | `ACK TS186-LOCAL-CODEX-cb042ac9` |
+| Mac mini → MacBook SSH | Claude Code 2.1.281 | posted | `ACK TS186-SSH-CLAUDE-f0275ade` |
+| Mac mini → MacBook SSH, structured Reply-To URI as destination | Codex CLI 0.157.1 | queued | `ACK TS186-SSH-CODEX-a771e96c` |
+
+Local Node: 22.14.0. Remote MacBook: 24.20.0, selected by a task-owned wrapper
+because its normal PATH selected unsupported Node 26. KR Linux Node 24.16.0
+also passed real SSH version negotiation and empty Claude discovery. KR native
+agent delivery was not tested. No service was restarted or global CLI replaced.
+
+The CLI itself still reports `consumptionConfirmed:false`; external ACK review
+does not change that contract. This is a one-shot functional test, not a soak.
+Local self-SSH was denied by the existing SSH authentication configuration; no
+credentials or host-key bypass were introduced. Reverse SSH was not asserted.
+
+## Historical runtime build checked on both Macs
+
+Compiled module SHA-256 values matched between the local build and the isolated
+MacBook installation used for the SSH ACK tests:
+
+```text
+0b708f1211330ff489b6a405e0ebb71d2b3b392acdb19c216dba18e7b23016c7  cli.js
+1d8c41dfc174d950e2196c64f93b324f09befa388a5b303439c390a526ffda48  discovery.js
+c3187c99c46364730e46e35ef23d8f3a37e541593b2a6f9c3945dce979e7e99c  process.js
+b716fed8fe6c8c04047f8485a6e3f982d6e64e5638df570b3b8c2a128f88c81e  protocol.js
+dd946024a61ce8721c273d47e911494c0c8facd62facd9b791a451b90cb702bf  send.js
+c441567e83c64c7d5735708936e9a42b68dd9ea0cdf0ef95538da7919d550496  writer.js
+```
+
+These hashes and real-TUI ACKs precede the public command rename to
+`session-peer` (the npm package was then named `session-peer-ts`). The rename changes the
+CLI version banner to `session-peer 0.1.0-preview.0 (typescript)` and the default
+SSH executable to `session-peer`; it does not change native delivery logic.
+Fresh package-install and SSH fixture tests cover the renamed entry point and
+reject a different implementation on remote PATH before sending. The earlier
+ACKs are not represented as a new live test of the renamed build.
+
+The npm package name was subsequently changed to `session-peer` before a
+successful publication; the GitHub repository remains `session-peer-ts`.
+Package identity, tarball naming and publication confirmations are covered by
+package/release fixtures, not claimed as new live ACK evidence.
+
+## Not covered / not released
+
+Windows, native x64 agent interaction, IPv6 literals, Relay/MCP/wake, full Python
+CLI parity, automatic reverse-route detection, npm registry publishing and
+provenance are outside this historical evidence. Publication preparation now
+removes the private flag, but actual publishing still needs separate approval
+and the gates in RELEASING.md. Native dependency prebuild availability must be tested
+on each architecture claimed by a future release.

package/dist/cli.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { hostname } from 'node:os';
+import { claude, codex, Refusal } from './discovery.js';
+import { executable, run, UnknownOutcome } from './process.js';
+import { checkMessage, send } from './send.js';
+import { envelope, host, reply, VERSION, VERSION_LINE } from './protocol.js';
+export function parse(args) {
+    const command = args[0];
+    if (command !== 'list' && command !== 'send')
+        throw new Refusal('unsupported_command');
+    const values = new Map(), flags = new Set();
+    for (let i = 1; i < args.length; i++) {
+        const token = args[i];
+        const split = token.indexOf('=');
+        const key = split > 0 ? token.slice(0, split) : token;
+        if (['--json', '--all', '--dry-run', '--no-from', '--no-reply-to', '--no-update-notice'].includes(key)) {
+            if (flags.has(key) || split > 0)
+                throw new Refusal('invalid_option');
+            flags.add(key);
+        }
+        else if (['--agent', '--codex-home', '--codex-bin', '--output-format', '--to', '--message', '-m', '--host', '--remote-bin', '--reply-address'].includes(key)) {
+            const name = key === '-m' ? '--message' : key;
+            const value = split > 0 ? token.slice(split + 1) : args[++i];
+            if (value === undefined || values.has(name))
+                throw new Refusal('invalid_option');
+            values.set(name, value);
+        }
+        else
+            throw new Refusal('unsupported_option');
+    }
+    if (!flags.has('--json') && values.get('--output-format') !== 'json')
+        throw new Refusal('json_output_required');
+    if (values.has('--output-format') && values.get('--output-format') !== 'json')
+        throw new Refusal('unsupported_output_format');
+    if (command === 'list') {
+        if (!['claude', 'codex'].includes(values.get('--agent') ?? ''))
+            throw new Refusal('explicit_supported_agent_required');
+        if (values.get('--agent') === 'codex' && !values.get('--codex-home'))
+            throw new Refusal('explicit_codex_home_required');
+        if (values.get('--agent') !== 'codex' && values.has('--codex-home'))
+            throw new Refusal('inapplicable_option');
+        if (['--to', '--message', '--codex-bin', '--reply-address'].some(k => values.has(k)) || ['--dry-run', '--no-from', '--no-reply-to'].some(k => flags.has(k)))
+            throw new Refusal('inapplicable_option');
+    }
+    else {
+        if (!values.get('--to') || values.has('--agent') || flags.has('--all'))
+            throw new Refusal('invalid_send_options');
+        if (flags.has('--no-reply-to') && values.has('--reply-address'))
+            throw new Refusal('conflicting_reply_options');
+        if (values.get('--to').startsWith('session-peer:')) {
+            const route = reply(values.get('--to'));
+            for (const [key, value] of [['--host', route.host], ['--codex-home', route.home]]) {
+                if (values.has(key) && values.get(key) !== value)
+                    throw new Refusal('reply_route_conflict');
+                if (value !== undefined)
+                    values.set(key, value);
+            }
+            values.set('--to', route.to);
+        }
+    }
+    if (values.has('--host'))
+        host(values.get('--host'));
+    if (values.has('--remote-bin')) {
+        if (!values.has('--host') || !/^\/[\x20-\x7e]+$/.test(values.get('--remote-bin')))
+            throw new Refusal('invalid_remote_bin');
+    }
+    return { command, values, flags };
+}
+async function input() {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const part = Buffer.from(chunk);
+        bytes += part.length;
+        if (bytes > 4_100_000)
+            throw new Refusal('input_too_large');
+        chunks.push(part);
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new Refusal('invalid_utf8');
+    }
+}
+const quote = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+async function remote(options, message) {
+    const { values, flags, command } = options;
+    const target = host(values.get('--host'));
+    const binary = values.get('--remote-bin') ?? 'session-peer';
+    const ssh = executable('ssh');
+    const base = ['-T', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'ConnectTimeout=10', '--', target];
+    const preflight = await run(ssh, [...base, `${quote(binary)} --version`], { timeout: 15000 });
+    if (preflight.interrupted || preflight.code !== 0 || preflight.stdout.trim() !== VERSION_LINE)
+        throw new Refusal('remote_version_unverified', 1);
+    const args = [command, '--json'];
+    for (const [key, value] of values)
+        if (['--agent', '--codex-home', '--codex-bin', '--to'].includes(key))
+            args.push(key, value);
+    if (flags.has('--all'))
+        args.push('--all');
+    if (flags.has('--dry-run'))
+        args.push('--dry-run');
+    if (command === 'send')
+        args.push('--message', message, '--no-from', '--no-reply-to');
+    const done = await run(ssh, [...base, `${quote(binary)} --stdio-request`], {
+        timeout: 90000, input: JSON.stringify({ schemaVersion: 1, args })
+    });
+    const uncertain = () => { if (command === 'send' && !flags.has('--dry-run') && done.spawned)
+        throw new UnknownOutcome(); throw new Refusal('remote_response_unverified', 1); };
+    if (done.interrupted || !done.spawned)
+        return uncertain();
+    let value;
+    try {
+        value = JSON.parse(done.stdout);
+    }
+    catch {
+        return uncertain();
+    }
+    if (!value || value.schemaVersion !== 1 || value.command !== command || typeof value.ok !== 'boolean' || typeof value.host !== 'string' ||
+        ![0, 1, 2].includes(done.code ?? -1) || (value.ok !== (done.code === 0)))
+        return uncertain();
+    const expectedStatus = flags.has('--dry-run') ? 'validated' : values.get('--to')?.startsWith('codex:') ? 'queued' : 'posted';
+    if (command === 'send' && (value.consumptionConfirmed !== false ||
+        (value.ok && (value.submitted !== !flags.has('--dry-run') || value.status !== expectedStatus)) ||
+        (!value.ok && !((value.submitted === false && value.status === 'refused') || (value.submitted === null && value.status === 'unknown')))))
+        return uncertain();
+    return { ...value, host: target, sshHost: target };
+}
+let command = 'unknown';
+try {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (!((major === 22 && minor >= 13) || major === 24))
+        throw new Refusal('unsupported_node_version');
+    if (!['darwin', 'linux'].includes(process.platform))
+        throw new Refusal('unsupported_platform');
+    let args = process.argv.slice(2);
+    if (args.length === 1 && args[0] === '--version')
+        console.log(VERSION_LINE);
+    else if (args.length === 1 && ['--help', '-h'].includes(args[0]))
+        console.log('session-peer (TypeScript preview): list --agent claude|codex --json; send --to TARGET --message TEXT --json [--dry-run] [--host HOST] [--remote-bin ABSOLUTE_PATH]. Codex requires --codex-home. Relay/MCP/wake/Windows unsupported.');
+    else {
+        const wire = args.length === 1 && args[0] === '--stdio-request';
+        if (wire) {
+            let request;
+            try {
+                request = JSON.parse(await input());
+            }
+            catch {
+                throw new Refusal('invalid_remote_request');
+            }
+            const record = request;
+            if (!record || record.schemaVersion !== 1 || !Array.isArray(record.args) || record.args.some(a => typeof a !== 'string'))
+                throw new Refusal('invalid_remote_request');
+            args = record.args;
+        }
+        command = ['list', 'send'].includes(args[0] ?? '') ? args[0] : 'unknown';
+        const options = parse(args);
+        if (wire && (options.values.has('--host') || options.values.has('--remote-bin')))
+            throw new Refusal('nested_transport_forbidden');
+        let message;
+        if (command === 'send') {
+            message = options.values.get('--message');
+            if (message === undefined || message === '-') {
+                if (wire)
+                    throw new Refusal('remote_message_required');
+                message = await input();
+            }
+            message = envelope(message, options.flags.has('--no-from'), options.values.get('--reply-address'));
+            checkMessage(message, options.values.get('--to').startsWith('codex:'));
+        }
+        let result;
+        if (options.values.has('--host'))
+            result = await remote(options, message);
+        else if (command === 'send')
+            result = await send({ to: options.values.get('--to'), home: options.values.get('--codex-home'), codexBin: options.values.get('--codex-bin'), message: message, dryRun: options.flags.has('--dry-run') });
+        else
+            result = options.values.get('--agent') === 'claude' ? claude(options.flags.has('--all')) : await codex(options.values.get('--codex-home'), options.flags.has('--all'));
+        console.log(JSON.stringify({ schemaVersion: 1, host: hostname(), command, ok: result.ok !== false, version: VERSION, referenceVersion: '1.0.2', ...result }));
+        process.exitCode = result.ok === false ? 1 : 0;
+    }
+}
+catch (error) {
+    const unknown = error instanceof UnknownOutcome;
+    const failure = error instanceof Refusal ? error : new Refusal('operation_failed', 1);
+    console.log(JSON.stringify({ schemaVersion: 1, host: hostname(), command, ok: false,
+        error: unknown ? 'outcome_unknown' : failure.code, status: unknown ? 'unknown' : 'refused',
+        submitted: unknown ? null : false, consumptionConfirmed: false, retryAllowed: false }));
+    process.exitCode = unknown ? 1 : failure.exitCode;
+}

package/dist/discovery.js

@@ -0,0 +1,148 @@
+// Deliberately read-only: no subprocess, network, socket connection or DB writes.
+import { readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+export class Refusal extends Error {
+    code;
+    exitCode;
+    constructor(code, exitCode = 2) {
+        super(code);
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+function missing(error) {
+    return ['ENOENT', 'ENOTDIR'].includes(error.code ?? '');
+}
+export function canonical(path) {
+    if (path === '~' || path.startsWith('~/'))
+        path = join(homedir(), path.slice(2));
+    else if (path.startsWith('~'))
+        throw new Refusal('unsupported_home_expansion');
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch (error) {
+        if (!missing(error))
+            throw new Refusal('home_resolution_failed', 1);
+        const parent = dirname(absolute);
+        return parent === absolute ? absolute : join(canonical(parent), absolute.slice(parent.length));
+    }
+}
+function alive(pid) {
+    if (pid <= 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export function claude(all) {
+    const directory = join(process.env.CLAUDE_CONFIG_DIR || process.env.ANTHROPIC_CONFIG_DIR || join(homedir(), '.claude'), 'sessions');
+    let entries;
+    try {
+        entries = readdirSync(directory).sort();
+    }
+    catch (error) {
+        if (missing(error))
+            entries = [];
+        else
+            throw new Refusal('claude_discovery_failed', 1);
+    }
+    const sessions = [];
+    for (const entry of entries) {
+        if (!/^[0-9]+\.json$/.test(entry))
+            continue;
+        let record;
+        try {
+            const value = JSON.parse(readFileSync(join(directory, entry), 'utf8'));
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                continue;
+            record = value;
+        }
+        catch {
+            continue;
+        }
+        const pid = record.pid;
+        if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid > 2147483647)
+            continue;
+        const matches = pid === Number(entry.slice(0, -5));
+        const live = matches && alive(pid);
+        const socket = typeof record.messagingSocketPath === 'string' ? record.messagingSocketPath : '';
+        let inbox = false;
+        if (socket) {
+            try {
+                inbox = statSync(socket).isSocket();
+            }
+            catch { /* Inaccessible is not reachable. */ }
+        }
+        const row = { agent: 'claude', pid, socket, alive: live, reachable: live && inbox };
+        for (const key of ['name', 'status', 'cwd', 'kind', 'version', 'tmux'])
+            row[key] = record[key] ?? null;
+        if (!matches)
+            row.staleReason = 'record_pid_mismatch';
+        if (all || row.reachable)
+            sessions.push(row);
+    }
+    return { sessions, discovery: { claude: { status: 'ok' } } };
+}
+export async function codex(path, all) {
+    const home = canonical(path);
+    const file = join(home, 'state_5.sqlite');
+    const item = { codexHome: home, stateDb: file, sources: ['argument'] };
+    let sessions = [];
+    let code;
+    try {
+        if (!statSync(file).isFile())
+            code = 'state_db_not_regular';
+    }
+    catch (error) {
+        code = missing(error) ? 'state_db_missing' : 'state_db_read_failed';
+    }
+    if (!code) {
+        try {
+            // Lazy import: Claude-only commands don't initialize experimental SQLite.
+            const { DatabaseSync } = await import('node:sqlite');
+            const db = new DatabaseSync(file, { readOnly: true });
+            try {
+                db.exec('PRAGMA query_only=ON; PRAGMA trusted_schema=OFF; PRAGMA busy_timeout=3000');
+                const columns = new Set(db.prepare('PRAGMA table_info(threads)').all().map(row => row.name));
+                const required = ['id', 'title', 'cwd', 'updated_at', 'archived', 'rollout_path'];
+                if (!required.every(name => columns.has(name)))
+                    throw new Error('unsupported_schema');
+                const name = columns.has('name') ? "COALESCE(NULLIF(name, ''), NULLIF(title, ''), id)" : "COALESCE(NULLIF(title, ''), id)";
+                const rows = db.prepare(`SELECT id, ${name} AS display_name, cwd, updated_at, archived FROM threads ${all ? '' : 'WHERE archived = 0'} ORDER BY updated_at DESC, id ASC`).all();
+                sessions = rows.map(row => {
+                    if (typeof row.id !== 'string' || !row.id || typeof row.display_name !== 'string' ||
+                        typeof row.updated_at !== 'number' || !Number.isSafeInteger(row.updated_at) ||
+                        typeof row.archived !== 'number' || (row.cwd !== null && typeof row.cwd !== 'string')) {
+                        throw new Error('unsupported_row');
+                    }
+                    // Python slicing counts Unicode code points, not JS UTF-16 units.
+                    const firstLine = row.display_name.split(/[\n\r\v\f\x1c-\x1e\x85\u2028\u2029]/u)[0] ?? '';
+                    return { agent: 'codex', id: row.id, name: [...firstLine].slice(0, 120).join(''),
+                        cwd: row.cwd, updatedAt: row.updated_at, archived: Boolean(row.archived),
+                        codexHome: home, stateDb: file };
+                });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch {
+            code = 'state_db_read_failed';
+            sessions = [];
+        }
+    }
+    const failed = Boolean(code);
+    Object.assign(item, failed ? { status: 'error', code, error: code } : { status: 'ok', sessionCount: sessions.length });
+    const discovery = { status: failed ? 'error' : 'ok', homes: [item] };
+    if (failed)
+        discovery.error = 'Codex home discovery is incomplete; inspect homes and errors';
+    return { sessions, codexHome: home, discovery: { codex: discovery }, ok: !failed,
+        ...(failed ? { error: 'Discovery failed for: codex' } : {}) };
+}

package/dist/process.js

@@ -0,0 +1,43 @@
+import { spawn } from 'node:child_process';
+import { accessSync, constants, realpathSync, statSync } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { Refusal } from './discovery.js';
+export class UnknownOutcome extends Error {
+}
+export function executable(name) {
+    const paths = isAbsolute(name) ? [name] : name.includes('/') ? [] :
+        (process.env.PATH ?? '').split(delimiter).filter(Boolean).map(p => join(p, name));
+    for (const path of paths) {
+        try {
+            accessSync(path, constants.X_OK);
+            if (statSync(path).isFile())
+                return realpathSync(path);
+        }
+        catch { }
+    }
+    throw new Refusal('executable_unavailable', 1);
+}
+export function run(binary, args, options = {}) {
+    return new Promise(resolve => {
+        let stdout = '', bytes = 0, spawned = false, interrupted = false;
+        const child = spawn(binary, args, { shell: false, env: options.env ?? process.env, stdio: ['pipe', 'pipe', 'pipe'] });
+        const stop = () => { interrupted = true; child.kill('SIGKILL'); };
+        const timer = setTimeout(stop, options.timeout ?? 3000);
+        child.once('spawn', () => { spawned = true; });
+        child.stdin.on('error', () => { });
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (part) => {
+            bytes += Buffer.byteLength(part);
+            if (bytes > (options.limit ?? 1024 * 1024))
+                stop();
+            else
+                stdout += part;
+        });
+        // Drain but never report native stderr (it may contain message text/credentials).
+        child.stderr.on('data', (part) => { bytes += part.length; if (bytes > (options.limit ?? 1024 * 1024))
+            stop(); });
+        child.once('error', () => { interrupted = true; });
+        child.once('close', code => { clearTimeout(timer); resolve({ code, stdout, spawned, interrupted }); });
+        child.stdin.end(options.input);
+    });
+}