@edgehero/pi-dispatch 0.1.0

package/src/session-key.mjs

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import { issueBranch } from "./branch.mjs";
+import { isForgeKind } from "./forges.mjs";
+
+/**
+ * session-key.mjs -- which persisted transcript, if any, a job runs on.
+ *
+ * PURE and TOTAL, no I/O, no throw. That is the same discipline filter.mjs holds, and for the same
+ * reason: the cross-repo and cross-PR safety of this whole feature lives in this one function, and a
+ * security-critical decision that needs a network to test is a decision nobody re-tests.
+ *
+ * DERIVED, NEVER LOOKED UP (DES-SESSION-KEY-IS-DERIVED-NOT-INDEXED). There is no index mapping "PR #123"
+ * to "the job that opened it" and there will not be one: an index is a query surface, and this project
+ * deliberately has no database (INT-RUN-HISTORY-FILE-CONTRACT). The key is computed from what the job
+ * already carries, so a mismatch is unrepresentable rather than merely unlikely.
+ *
+ * WHAT THE KEY ACTUALLY BINDS, stated honestly because the flattering version is wrong. It is tempting
+ * to say issue numbers never recycle, so `pi/issue-<n>` names one issue's lineage forever. It does not.
+ * `pi/issue-<n>` is asked for by a prompt and by a hard rule; nothing verifies that a pull request is
+ * actually on it, and a branch -- unlike an issue number -- can be deleted and re-created by anyone who
+ * can push. The key is a NAME, and its namespace is the base repository's push-access population. That
+ * is one step wider than the population CONST-NO-CONTEXT-FILES-MANDATORY already trusts. The residual
+ * is OQ-014; what bounds it is here, in the two rules below.
+ *
+ * Rule one: the repository half is always the BASE repo. A fork's `full_name` is attacker-chosen and
+ * must never select a directory. Rule two: a fork resolves NO KEY AT ALL -- returning null rather than
+ * setting a flag a later stage has to remember to check. Without it, a stranger who forks, names a
+ * branch `pi/issue-7` and gets a collaborator to act on the pull request would be handed issue 7's
+ * transcript.
+ *
+ * The returned string is a HASH, not a path built from the branch. A ref is attacker-influenced free
+ * text and validating it into a safe path segment is the losing half of that argument; hashing makes
+ * traversal unreachable. It also keeps a directory listing PII-free by construction, the same property
+ * `local:<basename>` gives the run record.
+ */
+
+/** Long enough that a collision is not a thing to reason about, short enough to read in a log line. */
+const KEY_LENGTH = 32;
+
+/**
+ * @param {object} job - The job data (`kind`, `repo`, `target`, `trigger`).
+ * @param {object} [resolved] - `{ headRef, headRepo }` for a pull/merge-request target, from the FORGE
+ *   API rather than the webhook payload. Absent or incomplete means no key, which is a cold start.
+ * @returns {string|null} A hex key, or `null` when this job has no durable identity to resume against.
+ */
+export function sessionKeyFor(job, resolved = {}) {
+	const parts = keyParts(job, resolved);
+	if (parts === null) return null;
+	// NUL-delimited so ("a", "bc") and ("ab", "c") cannot collide -- the same reasoning job-id.mjs uses.
+	return createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, KEY_LENGTH);
+}
+
+/**
+ * The key's material, before hashing. Exported for tests and for the operator-facing `doctor` line: the
+ * hash is deliberately unreadable, so the one place that can explain a directory is the function that
+ * built it.
+ */
+export function keyParts(job, resolved = {}) {
+	const kind = job?.kind;
+
+	// Keyed on "is this a forge job", never on a list of forge names. An enumeration that forgot one would
+	// not throw: every job on that forge would resolve no key and cold-start forever, which looks exactly
+	// like a deployment that never armed run.resume. `local` is handled below, on its own terms.
+	if (isForgeKind(kind)) {
+		const repo = job?.repo;
+		if (typeof repo !== "string" || repo === "") return null;
+
+		if (job?.target?.type === "pull_request") {
+			const { headRef, headRepo } = resolved;
+			if (typeof headRef !== "string" || headRef === "") return null;
+			// THE FORK GATE. Absence of a key, never a boolean: there is no later stage that could forget
+			// to check this, because there is nothing to check -- the job simply has no session.
+			if (typeof headRepo !== "string" || headRepo !== repo) return null;
+			return [kind, repo, headRef];
+		}
+
+		// An issue-triggered job's branch is the one its own envelope names, minted by the same function
+		// (branch.mjs) so the two cannot drift. issueBranch throws on a non-positive-integer number; this
+		// function is total, so that becomes "no key" rather than a failed job.
+		//
+		// ONE ARGUMENT, DELIBERATELY, and it must stay that way (REQ-REPLICA-RUNS). `issueBranch` takes an
+		// optional replica index and a replica job's envelope names `pi/issue-<n>-r<i>`, so this call is
+		// knowingly resolving a key for a branch that job was not told to push to. That is safe only because
+		// `triggers.mjs` refuses `run.replicas` together with `run.resume`: a replica job never resumes, so
+		// the key it would resolve is never read. Relax that refusal and every replica of one issue resolves
+		// the SAME key -- one transcript, N writers, fighting the store's one-writer lock. If the refusal
+		// ever goes, the replica index has to arrive here too. The coupling is stated in branch.mjs as well.
+		try {
+			return [kind, repo, issueBranch(job?.target?.number)];
+		} catch {
+			return null;
+		}
+	}
+
+	if (kind === "local") {
+		// A cron job's scheduler id is the strongest key here and the only one chosen by nobody untrusted:
+		// it is operator-authored, [A-Za-z0-9._-]+, unique across the triggers file, and stable across
+		// fires. A nightly job that remembers last night is the safest instance of this feature.
+		const id = job?.trigger?.id;
+		if (typeof id !== "string" || id === "") return null;
+		return ["local", "", id];
+	}
+
+	// Everything else -- a CLI `pi-dispatch run`, a chained /outbox child -- has no trigger entry that
+	// could have armed run.resume, so there is nothing to honour and no stable identity to key on. A job
+	// kind that is neither a forge nor local lands here too, which is the safe direction: no session.
+	return null;
+}

package/src/session-store.mjs

@@ -0,0 +1,249 @@
+import {
+	copyFileSync,
+	lstatSync,
+	mkdirSync,
+	openSync,
+	closeSync,
+	readFileSync,
+	readdirSync,
+	renameSync,
+	rmSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { sessionKeyFor } from "./session-key.mjs";
+
+/**
+ * session-store.mjs -- the host side of a resumable session (INT-SESSION-STORE-CONTRACT).
+ *
+ * THE CANONICAL STORE IS NEVER MOUNTED. A job gets a per-job COPY, under its own jobDir, and only a
+ * `completed` run's output is promoted back. Three properties fall out of that one decision, and each
+ * would need its own mechanism otherwise:
+ *
+ *   - CONST-RETRY-INFRA-ONLY survives. A policy or infra exit discards the container's writes entirely,
+ *     so attempt 2 starts from exactly what attempt 1 did. Promote on every exit and "retry" quietly
+ *     stops meaning re-run and starts meaning continue.
+ *   - CONST-ISOLATION-CONTAINER-PER-JOB's "every mount operator- or worker-supplied, none host-wide"
+ *     stays true verbatim: /session is per-job exactly as /job is. A container can name its own copy and
+ *     nothing else, so a compromised agent that computes another repo's key still cannot reach it -- the
+ *     mount is the capability, and the hash is not one.
+ *   - The validation happens host-side, on both edges, where the agent cannot influence it.
+ *
+ * NEVER THROWS. Every path returns `{ resume, reason, ... }` or null-ish, because a disk fault must not
+ * fail a prepare that only asked whether there was a transcript -- the posture makeFindPreviousRun
+ * already sets. The one fail-CLOSED case lives in the processor, not here: a trigger that armed
+ * run.resume while PI_SESSIONS_DIR is unset is a pre-spend policy refusal, because running it silently
+ * without persistence is the failure validatePackagesFlag's own comment describes.
+ */
+
+/** Container-side name, fixed. Nothing key-derived crosses the boundary -- see makeSessionStore. */
+export const SESSION_FILE_NAME = "current.jsonl";
+const PI_VERSION_FILE = "pi-version";
+const LOCK_FILE = "lock";
+
+/**
+ * Read-path outcomes. Every one is a named cold start rather than a bare `false`: a feature that fails
+ * open is otherwise indistinguishable from a feature nobody switched on, which is precisely how "we
+ * never resumed once in three months" goes unnoticed.
+ */
+const COLD = (reason) => ({ resume: false, reason, bytes: null });
+
+export function makeSessionStore({
+	sessionsDir,
+	ttlDays,
+	maxBytes,
+	log = () => {},
+	now = () => Date.now(),
+	fs = { copyFileSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync },
+}) {
+	/**
+	 * Stage this job's /session directory and decide whether it resumes.
+	 *
+	 * @param {object} job - the job data.
+	 * @param {object} opts - `{ jobDir, resolved, piVersion }`. `resolved` is `{ headRef, headRepo }` from
+	 *   the FORGE API for a pull/merge-request target; `piVersion` is the job image's declared version.
+	 * @returns {object|null} `{ hostDir, resume, reason, bytes, key }`, or `null` when this job gets no
+	 *   /session mount at all (unarmed, or no key) -- which is byte-identical to a pre-feature job.
+	 */
+	function resolveSession(job, { jobDir, resolved = {}, piVersion = null } = {}) {
+		try {
+			if (!sessionsDir) return null; // feature unavailable; the processor refuses armed triggers earlier
+			const key = sessionKeyFor(job, resolved);
+			// No key is not a failure and not a degradation: this job has no durable identity (a fork PR, a
+			// CLI run, an unresolvable head ref), so it gets no mount and no transcript on disk.
+			if (key === null) return null;
+
+			const hostDir = join(jobDir, "session");
+			const staged = join(hostDir, SESSION_FILE_NAME);
+			fs.mkdirSync(hostDir, { recursive: true, mode: 0o700 });
+
+			const verdict = readCanonical(key, piVersion);
+			if (verdict.resume) {
+				fs.copyFileSync(canonicalFile(key), staged);
+			} else {
+				// A 0-BYTE FILE, not an absent one. pi's setSessionFile then takes its empty-file branch and
+				// writes its own header at this exact path, which marks the manager flushed -- so _persist
+				// never reaches its openSync(path, "wx"), and the EEXIST race stops being a race. The host
+				// never has to know pi's file format to get that.
+				fs.writeFileSync(staged, "");
+			}
+			log("session_resolved", { key, resume: verdict.resume, reason: verdict.reason });
+			return { hostDir, key, ...verdict };
+		} catch (err) {
+			// A history fault must never fail the prepare that asked.
+			log("session_store_failed", { phase: "resolve", reason: err?.message });
+			return null;
+		}
+	}
+
+	/**
+	 * Promote the container's transcript back into the store. Called ONLY for a `completed` exit.
+	 *
+	 * Validates the agent's output before it becomes an input to a future job, then swaps it in under an
+	 * exclusive per-key lock. A job that cannot take the lock discards rather than clobbers: two jobs on
+	 * one key is a real shape (REQ-QUEUE-BURST-NO-DROP), and last-write-wins there would interleave two
+	 * agents' turns into one transcript.
+	 */
+	function promoteSession(session, { piVersion = null } = {}) {
+		if (!session?.key) return { promoted: false, reason: "no-key" };
+		try {
+			const staged = join(session.hostDir, SESSION_FILE_NAME);
+			const check = inspectFile(staged);
+			if (!check.ok) {
+				log("session_promote_skipped", { key: session.key, reason: check.reason });
+				return { promoted: false, reason: check.reason };
+			}
+
+			const dir = keyDir(session.key);
+			fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+			const lock = join(dir, LOCK_FILE);
+			let fd;
+			try {
+				fd = fs.openSync(lock, "wx"); // exclusive create IS the lock; no daemon, no lease
+			} catch {
+				log("session_promote_skipped", { key: session.key, reason: "locked" });
+				return { promoted: false, reason: "locked" };
+			}
+			try {
+				// Atomic swap: a reader either sees the old file or the new one, never a half-written one.
+				const tmp = `${canonicalFile(session.key)}.incoming`;
+				fs.copyFileSync(staged, tmp);
+				fs.renameSync(tmp, canonicalFile(session.key));
+				fs.writeFileSync(join(dir, PI_VERSION_FILE), String(piVersion ?? ""));
+			} finally {
+				fs.closeSync(fd);
+				try {
+					fs.unlinkSync(lock);
+				} catch {
+					// A leaked lock file wedges this key until the reaper sweeps it. Logged, never thrown.
+					log("session_lock_stuck", { key: session.key });
+				}
+			}
+			log("session_promoted", { key: session.key, bytes: check.bytes });
+			return { promoted: true, reason: "promoted", bytes: check.bytes };
+		} catch (err) {
+			log("session_store_failed", { phase: "promote", reason: err?.message });
+			return { promoted: false, reason: "promote-failed" };
+		}
+	}
+
+	function keyDir(key) {
+		return join(sessionsDir, key);
+	}
+	function canonicalFile(key) {
+		return join(keyDir(key), SESSION_FILE_NAME);
+	}
+
+	/** The read path, gate by gate. The FIRST miss wins and names itself. */
+	function readCanonical(key, piVersion) {
+		const file = canonicalFile(key);
+		const check = inspectFile(file);
+		if (!check.ok) return COLD(check.reason);
+
+		if (ttlDays > 0 && now() - check.mtimeMs > ttlDays * 86400000) return COLD("expired");
+
+		// A transcript outlives the pi that wrote it, and pi's own docs record what then breaks: an older
+		// session's stored tool-call arguments may no longer match the current tool schema. We cannot
+		// repair that mid-run, so a version change is a cold start rather than a mid-run failure. An
+		// image that declares no version never resumes -- the safe direction, never "assume it matches".
+		if (piVersion === null) return COLD("pi-version-changed");
+		let stamped = null;
+		try {
+			stamped = String(fs.readFileSync(join(keyDir(key), PI_VERSION_FILE), "utf8")).trim();
+		} catch {
+			return COLD("pi-version-changed");
+		}
+		if (stamped !== piVersion) return COLD("pi-version-changed");
+
+		// Cheapest real shape check, and the last one: the first line must be a pi session header. Anything
+		// else the runner would throw on, so refusing here keeps the container's degrade path for genuine
+		// surprises rather than for a file we could already tell was wrong.
+		try {
+			const head = String(fs.readFileSync(file, "utf8")).split("\n", 1)[0];
+			if (JSON.parse(head)?.type !== "session") return COLD("unparseable");
+		} catch {
+			return COLD("unparseable");
+		}
+		return { resume: true, reason: "resumed", bytes: check.bytes };
+	}
+
+	/**
+	 * lstat, REGULAR FILES ONLY -- and this is the one line in the file that is load-bearing security
+	 * rather than hygiene.
+	 *
+	 * The agent owns /session. A symlink it plants there resolves on the HOST when we read it back, so a
+	 * plain `stat` + `readFileSync` would hand the next job on this key the contents of any file the
+	 * worker user can read. INT-CONTAINER-JOB-INPUTS already documents this attack in the other direction
+	 * (`fs.readFile` off the clone following a symlink into a worker-host file). The repo's own habit is
+	 * the wrong one here: makeLogReaper uses statSync, which follows.
+	 */
+	function inspectFile(file) {
+		let st;
+		try {
+			st = fs.lstatSync(file);
+		} catch {
+			return { ok: false, reason: "absent" };
+		}
+		if (!st.isFile()) return { ok: false, reason: "not-a-regular-file" };
+		if (st.size === 0) return { ok: false, reason: "absent" }; // a staged-but-unwritten transcript
+		if (maxBytes > 0 && st.size > maxBytes) return { ok: false, reason: "too-large" };
+		return { ok: true, bytes: st.size, mtimeMs: st.mtimeMs };
+	}
+
+	/**
+	 * Boot-time sweep. A SIBLING of makeLogReaper rather than a widening of it: that one's `.log`/`.json`
+	 * filter and logsDir scope are a documented contract, and these files have a different retention
+	 * policy and a different PII class. Same never-throws shape, same `0 = keep forever` sentinel.
+	 *
+	 * Age at boot is the smaller half. The gate that matters is the one in readCanonical, which runs at
+	 * OPEN -- a worker that never restarts would otherwise keep resuming a transcript indefinitely, and a
+	 * stale transcript is a live input to a future job rather than debris (OQ-007).
+	 */
+	function reapSessions() {
+		if (!sessionsDir || ttlDays === 0) return;
+		const cutoff = now() - ttlDays * 86400000;
+		let names;
+		try {
+			names = fs.readdirSync(sessionsDir);
+		} catch (err) {
+			log("session_reaper_skipped", { reason: err?.message });
+			return;
+		}
+		for (const name of names) {
+			try {
+				const dir = join(sessionsDir, name);
+				const st = fs.lstatSync(join(dir, SESSION_FILE_NAME));
+				if (st.mtimeMs < cutoff) {
+					fs.rmSync(dir, { recursive: true, force: true });
+					log("reaped_session", { key: name });
+				}
+			} catch (err) {
+				log("session_reaper_skipped", { key: name, reason: err?.message });
+			}
+		}
+	}
+
+	return { resolveSession, promoteSession, reapSessions };
+}