@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/core/guardrails.ts

@@ -0,0 +1,185 @@
+/**
+ * Guardrail policy values: the numeric backstops that bound runaway agent
+ * behavior (tool-call budgets, tool output byte caps, dispatch ledger size).
+ *
+ * These are durable operator policy, the same species as
+ * `compaction.threshold`, so their primary home is the `guardrails:` section
+ * of settings.yaml. The composition roots (orchestrator entry and worker
+ * runtime) wire that section in via {@link configureGuardrails}; consumers
+ * resolve values through {@link resolveGuardrail}, which layers a per-process
+ * env override on top for CI and one-off experiments:
+ *
+ *   env var  >  settings.yaml guardrails  >  built-in default
+ *
+ * Every value is a positive safe integer; invalid overrides fall through to
+ * the next layer rather than erroring.
+ */
+
+export interface GuardrailValues {
+	/**
+	 * Orchestrator per-turn soft tool-call budget. Crossing it blocks every
+	 * further call in the turn with a stop-and-summarize directive; the hard
+	 * interrupt ceiling sits a fixed margin above it (see engine/loop-guard.ts).
+	 * Sized as a backstop against a model spraying distinct unproductive calls,
+	 * not as a routine ceiling: verbatim retry spirals are the identical-call
+	 * detector's job, and legitimate deep work (a repo-wide audit) runs dozens
+	 * of productive calls in one turn.
+	 */
+	turnToolCallBudget: number;
+	/**
+	 * Lifetime cap on tool calls a dispatched worker may execute. It bounds
+	 * admitted calls, not attempts: a call the harness refuses (a reserve-window
+	 * steering block, a synthesis-lockout denial) never ran and never spends the
+	 * cap, because a worker must not be killed by the harness's own refusals.
+	 * Attempts stay bounded by the loop-block budget and the synthesis backstop.
+	 *
+	 * Sized so a recipe's declared budget is what actually binds. A writer that
+	 * produces a dozen files spends a call per file before a single grounding
+	 * read, so a ceiling tuned for a reporting agent silently made whole classes
+	 * of work impossible: `min(declared, cap)` in dispatch means the smaller of
+	 * the two always wins, and only the recipe knows the shape of its job.
+	 */
+	workerToolCallCap: number;
+	/** Dispatch run-ledger retention cap. */
+	maxDispatchRuns: number;
+	/** Per-call byte cap for the read tool (clamped to a 1KB floor at use). */
+	readMaxBytes: number;
+	/** Shared per-turn byte pool across all observation-producing tools. */
+	observationTurnBudgetBytes: number;
+	/**
+	 * Wall-clock cap in milliseconds for one internal generator dispatch (the
+	 * wiki documenter and the bootstrap scout). Backstop for a degenerate model
+	 * that keeps streaming without finishing: continuous output satisfies the
+	 * heartbeat watchdog, and a run mid-generation spends no tool calls, so
+	 * neither existing guard ends it. Healthy runs finish in minutes; this is
+	 * not a routine ceiling.
+	 */
+	internalDispatchTimeoutMs: number;
+}
+
+export const GUARDRAIL_DEFAULTS: GuardrailValues = {
+	turnToolCallBudget: 60,
+	workerToolCallCap: 150,
+	maxDispatchRuns: 1000,
+	readMaxBytes: 50 * 1024,
+	observationTurnBudgetBytes: 192 * 1024,
+	internalDispatchTimeoutMs: 15 * 60 * 1000,
+};
+
+/** Per-process env overrides, one per guardrail. */
+export const GUARDRAIL_ENV_VARS: Readonly<Record<keyof GuardrailValues, string>> = {
+	turnToolCallBudget: "CLIO_CODER_TURN_TOOL_CALL_BUDGET",
+	workerToolCallCap: "CLIO_CODER_WORKER_TOOL_CALL_CAP",
+	maxDispatchRuns: "CLIO_CODER_MAX_DISPATCH_RUNS",
+	readMaxBytes: "CLIO_CODER_READ_MAX_BYTES",
+	observationTurnBudgetBytes: "CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES",
+	internalDispatchTimeoutMs: "CLIO_CODER_INTERNAL_DISPATCH_TIMEOUT_MS",
+};
+
+/**
+ * Older env spellings that still read. `CLIO_CODER_MAX_RUNS` was the only
+ * guardrail whose variable was not the SCREAMING_SNAKE of its key, and CI
+ * environments already set it, so it keeps working behind the canonical name.
+ */
+const GUARDRAIL_ENV_ALIASES: Readonly<Partial<Record<keyof GuardrailValues, string>>> = {
+	maxDispatchRuns: "CLIO_CODER_MAX_RUNS",
+};
+
+/**
+ * One-shot annotation attached to the first tool result inside the reserve
+ * window. Advisory: the call that carried it still ran; only subsequent
+ * non-read calls are blocked.
+ */
+export function workerSynthesisReserveDirective(remaining: number, cap: number): string {
+	return (
+		`budget reserve: only ${remaining} of your ${cap} tool calls remain, and they are reserved for verification ` +
+		"reads and synthesis. Stop broad exploration now: re-read the locations you will cite, then answer in prose. " +
+		"Calls that are not reads will be blocked."
+	);
+}
+
+/**
+ * Block reason for a non-read call inside the reserve window. Deliberately
+ * does NOT start with the `workerToolCallCap reached (` machine prefix:
+ * reserve blocks are steering, not cap exhaustion, and must never trip
+ * {@link mentionsWorkerToolCallCap} or the worker abort predicates.
+ */
+export function workerSynthesisReserveBlockReason(tool: string, remaining: number, cap: number): string {
+	return (
+		`workerToolCallReserve: only ${remaining} of ${cap} tool calls remain and they are reserved for verification ` +
+		`reads and synthesis; ${tool} is not a read. Re-read any locations you will cite, then answer in prose from ` +
+		"what you have gathered."
+	);
+}
+
+export function isWorkerSynthesisReserveBlockReason(reason: string): boolean {
+	return /^workerToolCallReserve: only [1-9]\d* of [1-9]\d* tool calls remain/.test(reason);
+}
+
+export function workerToolCallCapExceededReason(cap: number): string {
+	return `workerToolCallCap reached (${cap}); abort run`;
+}
+
+export function isWorkerToolCallCapExceededReason(reason: string): boolean {
+	return /^workerToolCallCap reached \([1-9]\d*\); abort run$/.test(reason);
+}
+
+/**
+ * Cap-exhaustion synthesis directive. Emitted instead of the abort reason when
+ * the loop guard runs with the synthesis lockout (dispatched workers): the run
+ * gets one bounded text-only opportunity to report from what it gathered
+ * before the backstop ends it. The prefix keeps the cap telemetry recognizable
+ * in receipts and stderr diagnostics.
+ */
+export function workerToolCallCapSynthesisReason(cap: number): string {
+	return (
+		`workerToolCallCap reached (${cap}); tool calls are now disabled for the rest of this run. ` +
+		"Everything you retrieved is already in the conversation above. Answer the operator now, in plain prose, " +
+		"from what you have gathered. Do not write tool-call markup such as <tool_call> blocks; tool calls are " +
+		"disabled and will not run."
+	);
+}
+
+export function isWorkerToolCallCapSynthesisReason(reason: string): boolean {
+	return /^workerToolCallCap reached \([1-9]\d*\); tool calls are now disabled/.test(reason);
+}
+
+/**
+ * True when a receipt diagnostic (failureMessage/outcomeDetail) embeds the
+ * cap telemetry prefix. Unlike the anchored predicates above this matches
+ * anywhere in the text, because worker diagnostics merge the reason into a
+ * larger machine-written string. It is deliberately keyed on the guard's own
+ * prefix, never on free-form worker prose.
+ */
+export function mentionsWorkerToolCallCap(text: string | null | undefined): boolean {
+	return typeof text === "string" && /workerToolCallCap reached \([1-9]\d*\)/.test(text);
+}
+
+let configured: Partial<GuardrailValues> = {};
+
+/**
+ * Install the settings.yaml `guardrails:` section. Called once per process by
+ * the composition roots; later calls replace the whole layer (used by tests).
+ */
+export function configureGuardrails(values: Partial<GuardrailValues> | undefined): void {
+	configured = { ...(values ?? {}) };
+}
+
+function parsePositiveSafeInt(raw: string | undefined): number | undefined {
+	if (raw === undefined) return undefined;
+	const normalized = raw.trim();
+	if (!/^[1-9]\d*$/.test(normalized)) return undefined;
+	const parsed = Number(normalized);
+	return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+/** Resolve one guardrail: env override > configured settings > default. */
+export function resolveGuardrail(key: keyof GuardrailValues, env: NodeJS.ProcessEnv = process.env): number {
+	const alias = GUARDRAIL_ENV_ALIASES[key];
+	return (
+		parsePositiveSafeInt(env[GUARDRAIL_ENV_VARS[key]]) ??
+		(alias ? parsePositiveSafeInt(env[alias]) : undefined) ??
+		configured[key] ??
+		GUARDRAIL_DEFAULTS[key]
+	);
+}

package/src/core/headless-permission.ts

@@ -0,0 +1,21 @@
+/**
+ * What a headless run answers a tool call that needs an approval nobody can
+ * give. There is no operator on the other end of `clio-coder run`, so every ask-rail
+ * call below `full-auto` is denied with this sentence.
+ *
+ * It lives here rather than inline at the deny site because two surfaces read
+ * it: the orchestrator writes it, and the skill-eval harness recognizes it in
+ * an arm transcript to tell "the skill did not do the work" apart from "the
+ * harness never let it try". A recognizer holding its own copy of the sentence
+ * would silently stop matching the day the wording changed.
+ */
+export const HEADLESS_PERMISSION_DENIED_REASON =
+	"clio-coder run cannot confirm permission requests; rerun interactively to approve this action.";
+
+/**
+ * The stable clause of that sentence, for matching against transcripts where
+ * the remedy half may have been truncated by a preview or elision budget.
+ * `HEADLESS_PERMISSION_DENIED_REASON` starts with it, which a contract test
+ * pins.
+ */
+export const HEADLESS_PERMISSION_DENIED_MARKER = "clio-coder run cannot confirm permission requests";

package/src/core/init.ts

@@ -0,0 +1,223 @@
+/**
+ * Bootstrap Clio's config/data/state/cache directories on first install.
+ * Creates the full directory tree required by subsequent domains and writes
+ * defaults when absent. Idempotent.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_SETTINGS_YAML } from "./defaults.js";
+import { readClioVersion } from "./package-root.js";
+import { clioCacheDir, clioConfigDir, clioDataDir, clioStateDir, resolveClioDirs } from "./xdg.js";
+
+export interface InitReport {
+	configDir: string;
+	dataDir: string;
+	stateDir: string;
+	cacheDir: string;
+	createdPaths: string[];
+	touchedSettings: boolean;
+}
+
+const CONFIG_SUBDIRS = ["agents"] as const;
+const DATA_SUBDIRS = ["memory", "evidence", "evals"] as const;
+const STATE_SUBDIRS = ["sessions", "audit", "receipts", "interviews", "scratch"] as const;
+
+interface InstallMetadata {
+	version: string;
+	/**
+	 * When Clio was first installed on this machine, present only when that is
+	 * actually known. Absent on a record this process had to synthesize over a
+	 * state root that already existed, where the install time is unrecoverable.
+	 */
+	installedAt?: string;
+	upgradedAt?: string;
+	/**
+	 * When this record was rebuilt because it was missing or unreadable. A repair
+	 * is not an install and must never be written into `installedAt`: `clio-coder
+	 * doctor --fix` over a wiped state root reported the repair minute as the day
+	 * the user installed Clio, and every later run repeated it as fact.
+	 */
+	repairedAt?: string;
+	/**
+	 * The version on record before the most recent version change, kept so the
+	 * first interactive launch after an upgrade can say where it came from and
+	 * `doctor` can show it. Absent on a home that has never changed version.
+	 */
+	upgradedFrom?: string;
+	/**
+	 * The version whose upgrade notice the operator has already seen. Written
+	 * by the interactive boot, once per version, so the notice never repeats.
+	 */
+	noticedVersion?: string;
+	platform: string;
+	nodeVersion: string;
+}
+
+export function initializeClioHome(): InitReport {
+	enforceHomePrefixGuard();
+
+	// Probed from the resolved paths, before the accessors below create them:
+	// clioStateDir() makes the directory it is being asked about, so anything
+	// checked after it reports a first install on every run. A root that is
+	// already there means whatever this call is about to write is a repair.
+	const resolved = resolveClioDirs();
+	const preexistingHome = existsSync(resolved.state) || existsSync(resolved.config) || existsSync(resolved.data);
+
+	const configDir = clioConfigDir();
+	const dataDir = clioDataDir();
+	const stateDir = clioStateDir();
+	const cacheDir = clioCacheDir();
+
+	const created: string[] = [];
+
+	for (const dir of [configDir, dataDir, stateDir, cacheDir]) {
+		if (!existsSync(dir)) {
+			mkdirSync(dir, { recursive: true });
+			created.push(dir);
+		}
+	}
+
+	const subdirSets: ReadonlyArray<[string, ReadonlyArray<string>]> = [
+		[configDir, CONFIG_SUBDIRS],
+		[dataDir, DATA_SUBDIRS],
+		[stateDir, STATE_SUBDIRS],
+	];
+	for (const [root, subs] of subdirSets) {
+		for (const sub of subs) {
+			const full = join(root, sub);
+			if (!existsSync(full)) {
+				mkdirSync(full, { recursive: true });
+				created.push(full);
+			}
+		}
+	}
+
+	// Structure only: an existing settings.yaml is never read, validated, or
+	// rewritten here. Content validation belongs to readSettings/doctor.
+	const settingsPath = join(configDir, "settings.yaml");
+	let touched = false;
+	if (!existsSync(settingsPath)) {
+		writeFileSync(settingsPath, DEFAULT_SETTINGS_YAML, { encoding: "utf8", mode: 0o644 });
+		created.push(settingsPath);
+		touched = true;
+	}
+
+	const credentialsPath = join(configDir, "credentials.yaml");
+	if (!existsSync(credentialsPath)) {
+		writeFileSync(
+			credentialsPath,
+			"# Managed via `clio-coder auth`. Do not edit manually unless you know what you are doing.\n{}\n",
+			{
+				encoding: "utf8",
+				mode: 0o600,
+			},
+		);
+		chmodSync(credentialsPath, 0o600);
+		created.push(credentialsPath);
+	}
+
+	// installedAt is written exactly once, at first install. Any later
+	// version/platform/node change preserves it and stamps upgradedAt instead.
+	const installPath = join(stateDir, "install.json");
+	const installMetadata = readInstallMetadata(installPath);
+	const currentVersion = readClioVersion();
+	if (!installMetadata) {
+		const payload: InstallMetadata = {
+			version: currentVersion,
+			// A first install knows when it happened. A repair does not, and saying
+			// `installedAt: now` there is a fact this process invented.
+			...(preexistingHome ? { repairedAt: new Date().toISOString() } : { installedAt: new Date().toISOString() }),
+			platform: process.platform,
+			nodeVersion: process.version,
+		};
+		writeFileSync(installPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+		created.push(installPath);
+	} else if (
+		installMetadata.version !== currentVersion ||
+		installMetadata.platform !== process.platform ||
+		installMetadata.nodeVersion !== process.version
+	) {
+		// A version change is the upgrade the record is about; a node or platform
+		// change alone keeps whatever earlier transition was on record.
+		const upgradedFrom =
+			installMetadata.version !== currentVersion ? installMetadata.version : installMetadata.upgradedFrom;
+		const payload: InstallMetadata = {
+			version: currentVersion,
+			...(installMetadata.installedAt !== undefined ? { installedAt: installMetadata.installedAt } : {}),
+			...(installMetadata.repairedAt !== undefined ? { repairedAt: installMetadata.repairedAt } : {}),
+			...(upgradedFrom !== undefined ? { upgradedFrom } : {}),
+			...(installMetadata.noticedVersion !== undefined ? { noticedVersion: installMetadata.noticedVersion } : {}),
+			upgradedAt: new Date().toISOString(),
+			platform: process.platform,
+			nodeVersion: process.version,
+		};
+		writeFileSync(installPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+	}
+
+	return { configDir, dataDir, stateDir, cacheDir, createdPaths: created, touchedSettings: touched };
+}
+
+function readInstallMetadata(path: string): InstallMetadata | null {
+	if (!existsSync(path)) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<InstallMetadata>;
+		// Either stamp is enough to call the record ours. Requiring installedAt
+		// would make every repaired record look corrupt and get re-synthesized on
+		// the next run, moving the repair time forward each time.
+		if (
+			typeof parsed.version === "string" &&
+			(typeof parsed.installedAt === "string" || typeof parsed.repairedAt === "string") &&
+			typeof parsed.platform === "string" &&
+			typeof parsed.nodeVersion === "string"
+		) {
+			return {
+				version: parsed.version,
+				...(typeof parsed.installedAt === "string" ? { installedAt: parsed.installedAt } : {}),
+				...(typeof parsed.upgradedAt === "string" ? { upgradedAt: parsed.upgradedAt } : {}),
+				...(typeof parsed.repairedAt === "string" ? { repairedAt: parsed.repairedAt } : {}),
+				...(typeof parsed.upgradedFrom === "string" ? { upgradedFrom: parsed.upgradedFrom } : {}),
+				...(typeof parsed.noticedVersion === "string" ? { noticedVersion: parsed.noticedVersion } : {}),
+				platform: parsed.platform,
+				nodeVersion: parsed.nodeVersion,
+			};
+		}
+	} catch {
+		// Repaired below by overwriting install.json with current metadata.
+	}
+	return null;
+}
+
+/**
+ * Opt-in safety check that prevents tests from clobbering a parent process's
+ * sandbox when the parent has CLIO_CODER_CONFIG_DIR/CLIO_CODER_DATA_DIR/CLIO_CODER_STATE_DIR/
+ * CLIO_CODER_CACHE_DIR set and the test only overrides CLIO_CODER_HOME. Individual env
+ * vars take precedence over CLIO_CODER_HOME inside resolveClioDirs, so a test that
+ * forgets to override all five will silently inherit the parent's paths and
+ * write into the wrong sandbox.
+ *
+ * Enable by setting CLIO_CODER_REQUIRE_HOME_PREFIX=1 in the test env. The test
+ * harness in tests/harness/spawn.ts opts in by default. We deliberately do
+ * not enable this in production because dev installs may legitimately point
+ * individual dirs outside CLIO_CODER_HOME.
+ */
+function enforceHomePrefixGuard(): void {
+	if (process.env.CLIO_CODER_REQUIRE_HOME_PREFIX !== "1") return;
+	const home = process.env.CLIO_CODER_HOME?.trim();
+	if (!home) return;
+	const dirs = resolveClioDirs();
+	const offenders: string[] = [];
+	if (!dirs.config.startsWith(home)) offenders.push(`configDir=${dirs.config}`);
+	if (!dirs.data.startsWith(home)) offenders.push(`dataDir=${dirs.data}`);
+	if (!dirs.state.startsWith(home)) offenders.push(`stateDir=${dirs.state}`);
+	if (!dirs.cache.startsWith(home)) offenders.push(`cacheDir=${dirs.cache}`);
+	if (offenders.length === 0) return;
+	throw new Error(
+		`CLIO_CODER_REQUIRE_HOME_PREFIX guardrail tripped: resolved Clio directories escape CLIO_CODER_HOME=${home}. ` +
+			`Offending paths: ${offenders.join(", ")}. ` +
+			`Individual overrides CLIO_CODER_CONFIG_DIR, CLIO_CODER_DATA_DIR, CLIO_CODER_STATE_DIR, and CLIO_CODER_CACHE_DIR take precedence ` +
+			`over CLIO_CODER_HOME, so a test that sets only CLIO_CODER_HOME inherits whatever the parent process configured. ` +
+			`Override all five env vars in lockstep to scratch subdirs (CLIO_CODER_HOME plus CLIO_CODER_CONFIG_DIR, ` +
+			`CLIO_CODER_DATA_DIR, CLIO_CODER_STATE_DIR, CLIO_CODER_CACHE_DIR pointing under it), then call resetXdgCache().`,
+	);
+}

package/src/core/json-payload.ts

@@ -0,0 +1,58 @@
+/**
+ * The spans a model message may carry its JSON payload in, in the order they
+ * are tried: the whole message, the first fenced block, then the outermost
+ * brace span.
+ *
+ * A model asked for bare JSON reaches for a fence first, and prose in front of
+ * the fence is the next most common deviation, so a reader that only tries one
+ * span refuses payloads that are correct. The fence candidate is not enough on
+ * its own either: a payload whose own strings contain a fenced block, such as a
+ * "Commands" section holding a ```bash example, truncates at the inner close
+ * and has to fall through to the brace span.
+ *
+ * Every caller parses each candidate in turn and keeps the first that yields
+ * what it needs. None of them may return or throw on the first span that merely
+ * looks plausible: the context-bootstrap reader did exactly that and turned a
+ * complete handbook into "Unterminated string in JSON".
+ */
+function jsonPayloadCandidates(text: string): string[] {
+	const trimmed = text.trim();
+	const candidates = [trimmed];
+	const fenced = /```[A-Za-z0-9_-]*\s*\n?([\s\S]*?)```/.exec(trimmed)?.[1]?.trim();
+	if (fenced !== undefined && fenced.length > 0) candidates.push(fenced);
+	const start = trimmed.indexOf("{");
+	const end = trimmed.lastIndexOf("}");
+	if (start >= 0 && end > start) candidates.push(trimmed.slice(start, end + 1));
+	return candidates;
+}
+
+export type JsonObjectPayload =
+	| { ok: true; value: Record<string, unknown> }
+	| { ok: false; reason: "not-json" | "not-object" };
+
+/**
+ * The first JSON object a model message carries, searched over every span
+ * `jsonPayloadCandidates` names. `not-json` means no span parsed at all;
+ * `not-object` means something parsed and none of it was an object, so a
+ * fenced array is refused with the reason its caller already reports.
+ *
+ * Every reader of a model's JSON answer goes through here so that a validator,
+ * the reader that follows it, and a renderer of the same text agree on what
+ * the payload is. When they held separate ideas, a fenced code report passed
+ * its validator and then threw in the reader that re-parsed the raw text.
+ */
+export function parseJsonObjectPayload(text: string): JsonObjectPayload {
+	let parsedSomething = false;
+	for (const candidate of jsonPayloadCandidates(text)) {
+		let value: unknown;
+		try {
+			value = JSON.parse(candidate) as unknown;
+		} catch {
+			continue;
+		}
+		parsedSomething = true;
+		if (value === null || typeof value !== "object" || Array.isArray(value)) continue;
+		return { ok: true, value: value as Record<string, unknown> };
+	}
+	return { ok: false, reason: parsedSomething ? "not-object" : "not-json" };
+}

package/src/core/package-root.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PI_MONO_PACKAGES } from "../engine/pi-mono-names.js";
+
+let cached: string | null = null;
+let cachedClioVersion: string | null = null;
+let cachedPiMonoVersion: string | null = null;
+
+export function resolvePackageRoot(metaUrl = import.meta.url): string {
+	if (cached) return cached;
+	const override = process.env.CLIO_CODER_PACKAGE_ROOT?.trim();
+	if (override) {
+		cached = resolve(override);
+		return cached;
+	}
+	let dir = resolve(dirname(fileURLToPath(metaUrl)));
+	while (true) {
+		if (existsSync(join(dir, "package.json"))) {
+			cached = dir;
+			return dir;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) {
+			throw new Error(`Could not find package.json above ${dir}`);
+		}
+		dir = parent;
+	}
+}
+
+interface PartialPackageJson {
+	version?: string;
+	dependencies?: Record<string, string>;
+}
+
+function readPackageJson(): PartialPackageJson {
+	const root = resolvePackageRoot();
+	const raw = readFileSync(join(root, "package.json"), "utf8");
+	return JSON.parse(raw) as PartialPackageJson;
+}
+
+export function readClioVersion(): string {
+	if (cachedClioVersion) return cachedClioVersion;
+	const pkg = readPackageJson();
+	cachedClioVersion = pkg.version ?? "0.0.0";
+	return cachedClioVersion;
+}
+
+export function readPiMonoVersion(): string {
+	if (cachedPiMonoVersion) return cachedPiMonoVersion;
+	const pkg = readPackageJson();
+	cachedPiMonoVersion = pkg.dependencies?.[PI_MONO_PACKAGES.agentCore] ?? "unknown";
+	return cachedPiMonoVersion;
+}

package/src/core/path-canonical.ts

@@ -0,0 +1,37 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Resolve symlinks for an absolute path as far as the filesystem currently
+ * exists. Existing targets return their real path; missing targets return the
+ * real path of the deepest existing parent plus the unresolved tail.
+ */
+export function canonicalizeExistingPath(absPath: string): string {
+	const resolved = path.resolve(absPath);
+	try {
+		return path.resolve(realpathSync(resolved));
+	} catch {
+		// Fall through to parent-prefix canonicalization for missing targets and
+		// paths whose final component cannot be resolved.
+	}
+
+	const tail: string[] = [];
+	let cursor = resolved;
+	while (true) {
+		const parent = path.dirname(cursor);
+		if (parent === cursor) {
+			try {
+				return path.resolve(realpathSync(cursor), ...tail);
+			} catch {
+				return resolved;
+			}
+		}
+		tail.unshift(path.basename(cursor));
+		cursor = parent;
+		try {
+			return path.resolve(realpathSync(cursor), ...tail);
+		} catch {
+			// Keep walking toward the filesystem root.
+		}
+	}
+}

package/src/core/process-identity.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Process identity for durable owner records. A pid alone cannot tell "the
+ * holder is gone" from "the pid was reused", so records carry the owner's birth
+ * token as well; every adjudicator in the tree reads it from here.
+ */
+
+function readProcStartTime(pid: number): string | null {
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+		const close = stat.lastIndexOf(")");
+		const fields = stat.slice(close + 2).split(" ");
+		return fields[19] ?? null; // field 22; slice begins at field 3
+	} catch {
+		return null;
+	}
+}
+/**
+ * True when this platform can distinguish "pid is gone" from "pid cannot be
+ * inspected". Where it can, a missing token proves the owner is dead. Where it
+ * cannot, a missing token proves nothing, so reclamation falls back to a
+ * liveness signal and the lease expiry rather than assuming the owner died.
+ */
+export const BIRTH_TOKEN_SOURCE_AVAILABLE = readProcStartTime(process.pid) !== null;
+
+export function processBirthToken(pid = process.pid): string | null {
+	const started = readProcStartTime(pid);
+	if (started !== null) return started;
+	return BIRTH_TOKEN_SOURCE_AVAILABLE ? null : `pid-${pid}`;
+}
+export function processAlive(pid: number): boolean {
+	if (!Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		// EPERM means the pid exists but belongs to another user.
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}