@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
189 lines (181 loc) • 8.74 kB
text/typescript
/**
* Read-only classification of the tracked runtime record pair a guarded stop
* re-verifies before acting.
*
* "ocx stop --expect-*" asks "is the recorded runtime still the approved one",
* which collapses several observations into one boolean: a missing or invalid
* "ocx.pid", a dead, foreign or unverifiable recorded process, and a missing,
* invalid or PID-mismatched "runtime-port.json" all read as "not verified".
* The approval-changed refusal used to report only that umbrella fact, so a
* desktop log could not tell a stale record from a permission failure.
*
* This probe walks the same checks in the same order as "readPid()" followed
* by "readRuntimePort(pid)", but reports which one failed instead. Each state
* record is still read exactly once per call -- a guarded stop asks once, and
* caching the bytes would only carry a stale answer into a decision about a
* record that may have been rewritten. The process-identity question, though,
* is answered by the same cache-backed observation "readPid()" itself makes
* ("inspectOcxStartProcessIdentity"): a cached verdict serves this probe with
* no native command at all, and a miss performs the same single command-line
* probe readPid would, so this probe can never disagree with the admission
* readPid just granted or denied for the same PID. It performs no mutation, no
* signal beyond the same "process.kill(pid, 0)" liveness read, and no stop
* decision -- the refusal itself is unchanged; only its detail gains a cause.
*
* Two distinctions are deliberate:
*
* - "permission-denied" is reported only for a real EACCES/EPERM observed on a
* record read or the liveness signal. An "unverifiable" identity observation
* -- an unreadable process command line -- is not proof of a permission
* boundary, and no account or elevation cause is inferred from it.
* - No path, command line, stderr text, or token leaves this module: the refusal
* causes below are fixed strings and the detail built from them is a fixed
* sentence.
*/
import { readFileSync } from "node:fs";
import {
getPidPath,
getRuntimePortPath,
inspectOcxStartProcessIdentity,
isValidRuntimePortState,
parsePidFile,
} from "./process-state";
import type { OcxStartIdentityObservation } from "./process-state";
/** The single check that failed, as a stable machine-readable token. */
export type TrackedRecordRefusal =
| "pid-record-absent"
| "pid-record-permission-denied"
| "pid-record-unreadable"
| "pid-record-invalid"
| "process-not-running"
| "process-identity-mismatch"
| "process-unverifiable"
| "runtime-record-absent"
| "runtime-record-permission-denied"
| "runtime-record-unreadable"
| "runtime-record-invalid"
| "runtime-record-pid-mismatch"
| "unverified";
export type TrackedRecordInspection =
| { status: "verified"; pid: number; port: number; hostname: string | undefined }
| { status: "refused"; reason: TrackedRecordRefusal };
/**
* Injectable read-only seams. Tests must supply fakes for "signal" and either
* "identity" or the process-state exec seams ("setProcessCommandLineExecForTests"
* and friends) so no real "process.kill" or native command probe runs; the
* defaults are exactly what the production caller uses, including the shared
* identity cache.
*/
export interface TrackedRecordProbeDeps {
/** Read a state record like "readFileSync(path, 'utf-8')"; throw with errno codes. */
readFile?: (path: string) => string;
/** The "process.kill(pid, 0)" liveness read; throws like it (ESRCH/EPERM/...). */
signal?: (pid: number) => void;
/** The shared start-identity observation; the default consults the real cache. */
identity?: (pid: number) => OcxStartIdentityObservation;
}
function readRecordFile(
readFile: (path: string) => string,
path: string,
absent: TrackedRecordRefusal,
denied: TrackedRecordRefusal,
unreadable: TrackedRecordRefusal,
): { ok: true; raw: string } | { ok: false; reason: TrackedRecordRefusal } {
try {
return { ok: true, raw: readFile(path) };
} catch (error) {
const code = (error as NodeJS.ErrnoException).code;
if (code === "EACCES" || code === "EPERM") return { ok: false, reason: denied };
if (code === "ENOENT") return { ok: false, reason: absent };
return { ok: false, reason: unreadable };
}
}
/**
* Classify why the tracked runtime record cannot back a guarded stop, or return
* the verified target when every check still holds. One read per record, in the
* same order the stop path already performs them.
*/
export function inspectTrackedRuntimeRecord(
deps: TrackedRecordProbeDeps = {},
): TrackedRecordInspection {
const readFile = deps.readFile ?? ((path: string) => readFileSync(path, "utf-8"));
const signal = deps.signal ?? ((pid: number) => { process.kill(pid, 0); });
const identity = deps.identity ?? inspectOcxStartProcessIdentity;
try {
const pidFile = readRecordFile(
readFile, getPidPath(), "pid-record-absent", "pid-record-permission-denied", "pid-record-unreadable",
);
if (!pidFile.ok) return { status: "refused", reason: pidFile.reason };
const pid = parsePidFile(pidFile.raw);
if (pid === null) return { status: "refused", reason: "pid-record-invalid" };
try {
signal(pid);
} catch (error) {
const code = (error as NodeJS.ErrnoException).code;
if (code === "ESRCH") return { status: "refused", reason: "process-not-running" };
// EPERM still names a live process; identity is decided by the shared
// observation below, exactly as readPid decides it. Any other signal
// error can only be reported as unverifiable.
if (code !== "EPERM") return { status: "refused", reason: "process-unverifiable" };
}
const observation = identity(pid);
if (observation === "unverifiable") {
return { status: "refused", reason: "process-unverifiable" };
}
if (observation === "mismatch") {
return { status: "refused", reason: "process-identity-mismatch" };
}
const runtimeFile = readRecordFile(
readFile, getRuntimePortPath(),
"runtime-record-absent", "runtime-record-permission-denied", "runtime-record-unreadable",
);
if (!runtimeFile.ok) return { status: "refused", reason: runtimeFile.reason };
let parsed: unknown;
try {
parsed = JSON.parse(runtimeFile.raw);
} catch {
return { status: "refused", reason: "runtime-record-invalid" };
}
if (!isValidRuntimePortState(parsed)) {
return { status: "refused", reason: "runtime-record-invalid" };
}
if (parsed.pid !== pid) {
return { status: "refused", reason: "runtime-record-pid-mismatch" };
}
return { status: "verified", pid, port: parsed.port, hostname: parsed.hostname };
} catch {
return { status: "refused", reason: "unverified" };
}
}
/**
* Fixed refusal causes for the approval-changed detail. Every entry is a
* complete sentence fragment and contains no path, command line, stderr, or
* token, so the resulting detail is safe to surface in a caller's log or UI.
*/
const TRACKED_REFUSAL_CAUSES: Record<TrackedRecordRefusal, string> = {
"pid-record-absent": "the recorded PID file is absent",
"pid-record-permission-denied": "reading the recorded PID file was denied",
"pid-record-unreadable": "the recorded PID file could not be read",
"pid-record-invalid": "the recorded PID file is not a valid record",
"process-not-running": "the recorded process is no longer running",
"process-identity-mismatch": "the recorded process does not match the expected start command",
"process-unverifiable": "the recorded process identity could not be verified",
"runtime-record-absent": "the tracked runtime record is absent",
"runtime-record-permission-denied": "reading the tracked runtime record was denied",
"runtime-record-unreadable": "the tracked runtime record could not be read",
"runtime-record-invalid": "the tracked runtime record is not a valid record",
"runtime-record-pid-mismatch": "the tracked runtime record names a different PID",
"unverified": "the tracked runtime record could not be re-verified",
};
/**
* The guarded stop's tracked() callback shape: the verified target, or the
* fixed cause of the single check that failed. Read-only; decides nothing.
*/
export function describeTrackedRuntimeTarget(
deps: TrackedRecordProbeDeps = {},
): { pid: number; port: number; hostname: string | undefined } | { untracked: string } {
const inspection = inspectTrackedRuntimeRecord(deps);
return inspection.status === "verified"
? { pid: inspection.pid, port: inspection.port, hostname: inspection.hostname }
: { untracked: TRACKED_REFUSAL_CAUSES[inspection.reason] };
}