@edgehero/pi-dispatch 1.6.0 → 1.7.0

package/src/run-history.mjs

@@ -114,7 +114,34 @@ export function parseExitTurns(text) {
  * Read-only telemetry, exactly like `parseExitTurns`: NEVER throws and MUST NOT feed exit-code or retry
  * classification (INT-RUNNER-EXIT-CODE-PROTOCOL). A malformed or non-object `tokens` (or one missing a
  * numeric `total`) is `null`, never a partial that could poison the daily token counter.
+ *
+ * The admitted object is REBUILT through `rebuildTokens` rather than returned as it arrived. See that
+ * function for why: the pass-through it replaces is what made this comment's "integer token counts and
+ * numeric cost only" false one level below `buildRecord`'s literal.
+ */
+/**
+ * The CLOSED `session.reason` enum, verbatim from `INT-RUN-HISTORY-FILE-CONTRACT`. Three producers write
+ * this field (resolve, runner, promote) and the contract has always called the set closed; until this
+ * list existed, nothing enforced it and the runner's half was an unchecked string. Kept here rather than
+ * beside the store because this module is where the container's copy is admitted, and an enum that lives
+ * anywhere but the admission point is a comment, not a check.
  */
+const SESSION_REASONS = new Set([
+	"resumed",
+	"absent",
+	"expired",
+	"conversation-too-old",
+	"resume-chain-too-long",
+	"context-too-full",
+	"too-large",
+	"unparseable",
+	"not-a-regular-file",
+	"pi-version-changed",
+	"locked",
+	"promote-failed",
+	"disabled",
+]);
+
 /**
  * The runner's `session` object off the exit line: `{ resumed: <bool>, reason: "<enum>" }` or null when
  * the container died before emitting one (REQ-RESUMABLE-SESSION).
@@ -125,7 +152,8 @@ export function parseExitTurns(text) {
  * without both numbers it is indistinguishable from an ordinary cold start. A feature that fails open
  * must still say that it did.
  *
- * PII-free by construction: a boolean and a fixed enum. No key, no branch name, no path.
+ * PII-free by construction: a boolean and a fixed enum. No key, no branch name, no path -- and since the
+ * `SESSION_REASONS` check below, that sentence is enforced rather than merely intended.
  */
 export function parseExitSession(text) {
 	if (typeof text !== "string") return null;
@@ -137,7 +165,14 @@ export function parseExitSession(text) {
 		if (parsed?.event !== "exit") continue;
 		const sess = parsed?.session;
 		if (sess && typeof sess === "object" && !Array.isArray(sess) && typeof sess.resumed === "boolean") {
-			return { resumed: sess.resumed, reason: typeof sess.reason === "string" ? sess.reason : null };
+			// The reason is checked against the CLOSED enum, not merely against `typeof === "string"`, which
+			// is what it used to be. The container owns this value, so an unchecked string put an
+			// attacker-shapeable one into a record whose PII-free property rests on holding none -- while
+			// the comment above claimed "a boolean and a fixed enum". An unrecognised token reads as `null`
+			// (the runner said nothing this contract can represent) rather than being carried through: the
+			// enum is documented CLOSED in INT-RUN-HISTORY-FILE-CONTRACT, so a value outside it was already
+			// contract-violating and every consumer already handles null.
+			return { resumed: sess.resumed, reason: SESSION_REASONS.has(sess.reason) ? sess.reason : null };
 		}
 		return null;
 	}
@@ -176,6 +211,43 @@ export function parseExitContext(text) {
 	return null;
 }
 
+/**
+ * The keys the runner actually emits, in its own emission order: the metered snapshot
+ * (`image/runner/src/usage-meter.mjs` -> `snapshot`) plus the token-budget fallback
+ * (`image/runner/run-job.mjs` -> `pickTotals`, which sends the first four and `metered: false`). Order
+ * matters because it is what makes a conformant runner's object round-trip byte-identically through the
+ * rebuild below, so the record's bytes do not move for anyone running a real image.
+ */
+const TOKEN_KEYS = ["input", "output", "total", "cost", "metered", "rootTotal", "otherTotal", "looseTotal", "sessions", "calls", "unresolved", "unpriced"];
+
+/**
+ * Rebuild the billed totals from a closed key list rather than passing the container's object through.
+ *
+ * This function exists because the pass-through was a hole. `parseExitTokens` used to `return t`
+ * verbatim whenever `t.total` was a number, so any key the container invented -- a path, a branch name,
+ * a string it read out of the workspace -- rode into the durable record, and from there into anything
+ * that mirrors it. The record's PII-free-by-construction property held at `buildRecord`'s own level and
+ * NOT one level down, while this module's own comment claimed "integer token counts and numeric cost
+ * only". `parseExitUsage` already rebuilds for exactly this reason and says so; this is the sibling that
+ * did not, and the asymmetry was an oversight rather than a decision.
+ *
+ * A key the runner omitted stays OMITTED rather than becoming null: the fallback shape legitimately
+ * carries only five of the twelve, and a null there would read as "measured zero" for a number nobody
+ * measured. `typeof === "number"` rather than `Number.isFinite`, deliberately, so this narrows WHICH
+ * KEYS survive and never which objects are admitted -- the admission gate above is unchanged.
+ */
+function rebuildTokens(t) {
+	const out = {};
+	for (const key of TOKEN_KEYS) {
+		if (key === "metered") {
+			if (typeof t.metered === "boolean") out.metered = t.metered;
+		} else if (typeof t[key] === "number") {
+			out[key] = t[key];
+		}
+	}
+	return out;
+}
+
 export function parseExitTokens(text) {
 	if (typeof text !== "string") return null;
 	const lines = text.split("\n");
@@ -185,7 +257,7 @@ export function parseExitTokens(text) {
 		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		const t = parsed?.tokens;
-		if (t && typeof t === "object" && !Array.isArray(t) && typeof t.total === "number") return t;
+		if (t && typeof t === "object" && !Array.isArray(t) && typeof t.total === "number") return rebuildTokens(t);
 		return null;
 	}
 	return null;
@@ -306,7 +378,7 @@ function rebuildUsage(u) {
  * default to `null` when the outcome does not carry them, so the record shape is stable whether or not
  * the source reports those fields.
  */
-export function buildRecord({ job, result, error, startedAt, endedAt }) {
+export function buildRecord({ job, result, error, startedAt, endedAt, host = null }) {
 	const data = job.data ?? {};
 	const kind = data.kind ?? job.name;
 	const source = result ?? error ?? {};
@@ -369,6 +441,28 @@ export function buildRecord({ job, result, error, startedAt, endedAt }) {
 		// BRANCH NAME ARE DELIBERATELY ABSENT: this record's PII-free-by-construction property rests on it
 		// holding no attacker-chosen string, and a branch name is exactly that.
 		session: source.session ?? null,
+		// Which machine ran this (issue #57). Additive, nullable, an explicit literal, TAIL position: every
+		// prior addition took the tail, and "field order is the serialisation order" is this record's
+		// contract, so the tail is the only placement that leaves twenty-four existing positions untouched.
+		// Unconditional rather than a conditional spread, on the same contract sentence and on the
+		// `tokens`/`usage`/`session` precedent that null-with-the-key-present is this record's normal case.
+		//
+		// ADMISSIBILITY, which has to engage this record's own sentences rather than sidestep them. The
+		// PII-free-by-construction property rests on holding NO ATTACKER-CHOSEN STRING, and `host`
+		// satisfies that absolutely: there is no path from a webhook payload, an issue body, a branch name
+		// or a folder to this value. It is fixed once at boot from one environment variable against a
+		// charset that excludes `/` and `\`, so it cannot even be path-shaped -- which is the property
+		// `targetFor` drops a local folder to its basename to get.
+		//
+		// What it is NOT is anonymous, and that is worth writing down rather than glossing. The default is
+		// `os.hostname()`, and on a personal machine a hostname is often a person's name. The honest word
+		// is OPERATOR-DISCLOSED: the operator names their own machines, this record is written to their own
+		// disk, that name is already on every packet the machine sends, and `PI_WORKER_NAME` is the
+		// documented answer for anyone who wants something else here.
+		//
+		// Passed in rather than read from a module-level value, so `buildRecord` stays pure and every
+		// existing caller keeps getting `null` without knowing this field exists.
+		host,
 	};
 }
 

package/src/schedules.mjs

@@ -23,7 +23,7 @@ import { parseTriggers } from "./triggers.mjs";
  * valid deployment. `readFileSync`/`existsSync` are injectable so tests exercise the full path with no
  * real filesystem.
  */
-export function loadSchedules(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+export function loadSchedules(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync, fleet = false } = {}) {
 	const path = config.triggersFile;
 	if (path === null || path === undefined) return []; // cron disabled
 
@@ -33,14 +33,77 @@ export function loadSchedules(config, { readFileSync = fsReadFileSync, existsSyn
 
 	const triggers = parseTriggers(readFileSync(path, "utf8"), path);
 
-	return triggers.filter((t) => t.on.type === "cron").map((t) => normalizeCronSchedule(t, path, existsSync));
+	return triggers.filter((t) => t.on.type === "cron").map((t) => normalizeCronSchedule(t, path, existsSync, fleet));
 }
 
-function normalizeCronSchedule({ on, run }, path, existsSync) {
+/**
+ * The cron set AS AUTHORED, before any placement decision (issue #57).
+ *
+ * This is the object two hosts have to agree about, and it is deliberately not `loadSchedules`'s output.
+ * That function resolves PLACEMENT -- it replaces every trigger whose folder is on another machine with
+ * a stub -- so its result differs per host BY CONSTRUCTION. Fingerprinting it would make every correctly
+ * configured fleet refuse itself forever: mini1 owns `/a`, mini2 owns `/b`, their sets never match, and
+ * neither ever reconciles again. What they share is the FILE, so the file is what gets hashed.
+ *
+ * Pure and fs-free apart from the read: no `existsSync`, because existence is exactly the question that
+ * makes two honest hosts differ.
+ */
+export function authoredCron(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+	const path = config.triggersFile;
+	if (path === null || path === undefined) return null; // cron disabled: no opinion at all (see cronFingerprint)
+	if (!existsSync(path)) return null;
+	try {
+		return parseTriggers(readFileSync(path, "utf8"), path)
+			.filter((t) => t.on.type === "cron")
+			.map((t) => ({ schedulerId: t.on.id, pattern: t.on.pattern, run: t.run }));
+	} catch {
+		// A file this host cannot parse is not an opinion about what should be scheduled. It refuses boot
+		// elsewhere and keeps last-good on reload; here it must not become a fingerprint that disagrees
+		// with every peer.
+		return null;
+	}
+}
+
+/**
+ * Split a schedule set into the triggers THIS host serves and the ones it does not (issue #57).
+ *
+ * `loadSchedules` already refused everything a pure validator could refuse and everything the filesystem
+ * could answer for a trigger this host owns. What is left is the third question, and it is the one Gap 2
+ * is about: a folder that is not here is not necessarily a mistake, it may simply be another machine's.
+ *
+ * Exported so the split is testable without an fs, and so a caller can report what it will not be running.
+ */
+export function servedSchedules(schedules) {
+	const served = [];
+	const unserved = [];
+	for (const s of schedules) (s.unserved ? unserved : served).push(s);
+	return { served, unserved };
+}
+
+function normalizeCronSchedule({ on, run }, path, existsSync, fleet) {
 	// The pure validator already guaranteed a non-empty, `:`-free, charset-valid, unique id and a
 	// well-formed pattern; folder existence is the one fs-dependent check it deferred to here.
+	//
+	// ON A FLEET THAT IS THE WRONG QUESTION. `INT-TRIGGERS-FILE-CONTRACT` splits this as "type here,
+	// reality where it can be known", and issue #57 adds a third level: PLACEMENT, where the fleet is
+	// known. A folder that is absent on THIS machine may simply belong to another one, and refusing the
+	// worker's boot for it takes every unrelated trigger -- every forge job, every other folder -- offline
+	// with it. That is the sentence #57's own acceptance forbids.
+	//
+	// `fleet` is `PI_WORKER_NAME` being DECLARED, deliberately, and not a registry read. Two reasons, and
+	// both are failures I would otherwise have shipped. A registry read here would make a fleet-wide
+	// restart into a fleet-wide boot refusal, because every host would come up seeing no peers yet. And it
+	// would have to happen after the Valkey client exists, which is BELOW the four destructive boot sweeps
+	// -- so a single-host deployment with one typo'd folder would reap containers, prune history and delete
+	// sandboxes on every restart before refusing. Declaring a name is the operator saying "this is a
+	// fleet", it is known before anything runs, and it keeps a single-host deployment byte-identical.
 	if (!existsSync(run.folder)) {
-		throw configError(`cron trigger "${on.id}": run.folder does not exist: ${run.folder} (${path})`);
+		if (!fleet) {
+			throw configError(`cron trigger "${on.id}": run.folder does not exist: ${run.folder} (${path})`);
+		}
+		// Not mine. Its skillsDir is not my business either: `isAbsolute` is OS-dependent, and judging
+		// another host's path on my platform is the exact mistake the shared validator refuses to make.
+		return { schedulerId: on.id, unserved: "folder-absent" };
 	}
 
 	// `run.skillsDir` gets the same treatment, and for the same reason (REQ-PER-TRIGGER-SKILLS): the pure