@edgehero/pi-dispatch 1.1.0 → 1.2.0

package/.env.example

@@ -56,10 +56,20 @@ PI_JOB_IMAGE=pi-job:latest          # the DEFAULT job image. Any trigger may nam
                                     # Enforced at OPEN as well as at boot: a stale transcript is a live input to a future job, not debris
 # PI_SESSION_MAX_BYTES=             # default 8388608 (8 MiB); a transcript larger than this is not resumed; 0 = no cap
                                     # Not disk hygiene -- an oversized transcript is a prefill nobody sized PI_MAX_TOKENS for
+# PI_SESSION_MAX_AGE_DAYS=          # unset/0 = no bound. How old the CONVERSATION may be, read from the session header's own timestamp
+                                    # A DIFFERENT CLOCK from PI_SESSIONS_TTL_DAYS, not a finer setting of it: that one reads mtime, which every COMPLETED run refreshes,
+                                    # so a lineage that keeps finishing work never expires however old its first turn is. This one measures from the first turn
+                                    # A header with no readable timestamp is refused rather than assumed young (reason: conversation-too-old)
+# PI_SESSION_MAX_RESUME_CHAIN=      # unset/0 = no bound. How many times in a row one key may be resumed before the next job starts fresh
+                                    # The bound a long lineage actually needs: age and size grow slowly, a chain grows once per run
+                                    # The count is kept whether or not the bound is set, so setting it later takes effect on the next job rather than N jobs later
+# PI_SESSION_MAX_CONTEXT_PCT=       # unset = no bound; 1-100. Refuse a resume when the saved session's context is already this full, e.g. 80
+                                    # A SAFETY bound before an economic one: past pi's compaction threshold a resumed job replays a model-written summary of the transcript,
+                                    # written while that model was reading attacker-authored text (specs/open-questions.md, OQ-003). This ceiling is the host's own, and pi's threshold stays pi's
+                                    # The measurement comes from the job image's runner, so it is inert until you are running an image that reports it and each key has completed one run since
 # PI_SESSIONS_ALLOW_GH_SOURCE=      # unset = a run.resume job REFUSES to mint under GITHUB_AUTH_SOURCE=gh, pre-spend
                                     # That source is your whole gh login: full-scope and non-expiring, and a transcript is a FILE -- any command that echoed an auth header persists it
                                     # Prefer GITHUB_AUTH_SOURCE=app or a short-expiry fine-grained PAT. Set exactly 1 to accept the trade explicitly (SECURITY.md, docs/sessions.md)
-                                    # Not disk hygiene -- an oversized transcript is a prefill nobody sized PI_MAX_TOKENS for
 # PI_TRIGGERS_FILE=                 # ABSOLUTE path to the unified triggers.json, read by BOTH worker and receiver (a relative path resolves against the service's WorkingDirectory).
                                     # Unset = cron disabled for the worker; the receiver falls back to ./triggers.json in the folder it starts from (what `pi-dispatch init` scaffolds)
                                     # and refuses to start when neither exists (it holds the label/comment/pull_request trigger config)

package/deploy/worker-env-wrapper.cmd

@@ -72,6 +72,14 @@ if defined ENV_SETUP (
   )
 )
 
+REM WEAKER THAN THE .sh TWIN ON SIGNALS, deliberately and stated rather than discovered (issue #221).
+REM cmd has no `trap`, so there is no wrapper-level handling of a stop that arrives while `.env` is being
+REM read or while the setup script above is still running: whatever the service manager does to the tree
+REM is what happens. nssm stops with a console event to the process group (AppStopMethodConsole), so the
+REM worker is reached directly rather than through this file, which is why the .sh twin's forwarding
+REM problem has no equivalent here. The asymmetry is recorded in DES-SERVICE-ENV-SETUP-SEAM and is not
+REM closed.
+REM
 REM The argv runs verbatim -- absolute node, absolute script, composed by `pi-dispatch service` (see
 REM the .sh twin for the whole contract).
 %*

package/deploy/worker-env-wrapper.sh

@@ -36,6 +36,34 @@ if [ "$#" -eq 0 ]; then
 	exit 1
 fi
 
+# STOP HANDLING IS ARMED HERE, above everything below that can block (issue #221). It closes two windows,
+# both of which used to swallow a stop in silence.
+#
+# Until this line TERM/INT carry their DEFAULT disposition, and the sourcing below can take arbitrarily
+# long: PI_ENV_SETUP is an operator's secrets manager, so docs/secrets.md's own worked example makes a
+# network round trip inside it. A stop landing there killed this shell where it stood, mid-preparation,
+# with nothing anywhere saying the environment had been half-built. That is reachable from this project's
+# own CLI, not just from the daemon: `pi-dispatch service stop` on macOS is `launchctl kill SIGTERM` at
+# this pid.
+#
+# The other window is two instructions wide, and is closed by the re-send after `child=$!` below. The
+# handler is a FUNCTION rather than a trap string because it is installed twice -- here, and again after
+# the sourcing -- and one behaviour spelled out in two places is one behaviour that can drift.
+signaled=0
+child=
+wrapper_on_stop() {
+	signaled=1
+	# `child` is empty until the fork below has been assigned, and `kill -TERM ""` kills nothing and
+	# fails silently, so a stop arriving before then has no pid to reach. It is not lost: the re-send
+	# after `child=$!` re-delivers it, and the launch gate refuses to start at all if nothing was
+	# started yet.
+	[ -n "$child" ] && kill -TERM "$child" 2>/dev/null
+	# Never leave a nonzero status behind. `rc=$?` is read immediately after the `wait` this interrupts,
+	# and the double wait at the bottom keys on rc >= 128.
+	return 0
+}
+trap wrapper_on_stop TERM INT
+
 # The env-setup seam (issue #209): `pi-dispatch service render|install --env-setup <path>` puts an
 # operator-typed path here -- the plist's EnvironmentVariables dict on macOS, nssm's AppEnvironmentExtra
 # on Windows -- so a secrets manager can fill this process's environment without anyone hand-editing a
@@ -74,6 +102,25 @@ if [ -n "$env_setup" ]; then
 	set +a
 fi
 
+# RE-ASSERTED after the sourcing, and this is not belt-and-braces. A sourced script runs in THIS shell,
+# so a `trap ... TERM` inside one REPLACES the handler above and the drain silently disappears -- a
+# manager's cleanup helper does exactly that. One line restores it. What it cannot undo is a script that
+# IGNORES TERM (`trap '' TERM`): a signal discarded while it was ignored is already gone, and the child
+# forked below would inherit SIG_IGN and be unable to trap TERM at all. That is why docs/secrets.md now
+# tells operators not to touch signals in a setup script.
+trap wrapper_on_stop TERM INT
+
+# A stop that arrived while the environment was being prepared is honoured by NOT STARTING. Launching now
+# would hand the service manager a worker it has already asked to go away: it would reserve a budget slot
+# and take a job, and then need a drain nobody is waiting for. Exit 0 because 0 is the only code launchd's
+# KeepAlive/SuccessfulExit=false leaves stopped -- the same reason the exit-2 conversion at the bottom
+# exists. Not 2, because nothing was refused; not 1, because nothing failed; the manager's own instruction
+# was carried out, and this says so rather than exiting mute.
+if [ "$signaled" -eq 1 ]; then
+	echo "worker-env-wrapper: stopped before the worker started -- a stop signal arrived while the environment was being prepared, so the command was never launched; exiting 0 (nothing to restart)" >&2
+	exit 0
+fi
+
 # `exec` is deliberately GONE here (it used to hand this shell's pid straight to node): intercepting
 # the exit code needs a parent still alive after node exits. launchd's KeepAlive/SuccessfulExit=false
 # relaunches ANY nonzero exit -- including EXIT_POLICY (2, worker/src/exit-code.mjs), the determinate
@@ -81,13 +128,19 @@ fi
 # deliberately never retry. A relaunch loop against a paid provider is a bill, so the conversion at
 # the bottom turns exit 2 into the clean exit KeepAlive leaves stopped.
 #
-# SIGTERM still reaches node without exec: the trap forwards TERM/INT to the child, and `wait` (unlike
-# a foreground command in sh, which blocks trap delivery) is interruptible by a trapped signal, so the
-# forwarding is immediate and node gets its full graceful drain.
-signaled=0
-trap 'signaled=1; kill -TERM "$child" 2>/dev/null' TERM INT
+# SIGTERM still reaches node without exec: the handler armed at the top forwards TERM/INT to the child,
+# and `wait` (unlike a foreground command in sh, which blocks trap delivery) is interruptible by a trapped
+# signal, so the forwarding is immediate and node gets its full graceful drain.
 "$@" &
 child=$!
+# THE FORK WINDOW (issue #221). `$!` is only readable in the parent AFTER the fork, so between the two
+# lines above a child exists and its pid does not. A stop landing there ran the handler with nothing to
+# forward to, set `signaled`, and was then never looked at again -- so this wrapper waited out the
+# command's ENTIRE natural lifetime while the service manager believed it had asked it to stop. Re-sending
+# once the pid is known costs one `[` on the healthy path and is the whole difference between a graceful
+# drain and a hang as long as the job. Issue #207 found this same drop through the test that saw it and
+# fixed only the test; #221 is the same window firing through a different one.
+[ "$signaled" -eq 1 ] && kill -TERM "$child" 2>/dev/null
 wait "$child"
 rc=$?
 # The double wait is load-bearing: a trapped signal interrupts the FIRST wait early (rc = 128+signum)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Self-hosted job harness for the pi coding agent: a BullMQ worker that drains the queue, mints scoped forge tokens, and runs one container per job — plus the pi-dispatch CLI (init, up, doctor, service).",
   "keywords": [

package/src/config.mjs

@@ -258,6 +258,22 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		// A bound on how large a transcript may be before it stops being resumed. Not disk hygiene: an
 		// oversized transcript is a prefill an operator never sized PI_MAX_TOKENS for.
 		sessionMaxBytes: nonNegativeInt(env, "PI_SESSION_MAX_BYTES", 8 * 1024 * 1024), // 0 = no cap
+		// How old the CONVERSATION may be, which is a different clock from sessionsTtlDays above and not a
+		// finer setting of it: the TTL reads the transcript's mtime, which the PROMOTE rename refreshes (the
+		// resolve copy does not, measured -- copyFileSync stamps the destination), so it measures time since
+		// the last COMPLETED run on this key. A key whose runs keep completing never expires however old its
+		// first turn is. This one reads the session header's own timestamp.
+		// OFF by default (0) rather than defaulted to a number: an age an operator did not choose is an
+		// opinion about their lineages that this project has no basis for.
+		sessionMaxAgeDays: nonNegativeInt(env, "PI_SESSION_MAX_AGE_DAYS", 0), // 0 = no age bound
+		// How many times in a row one key may be resumed before the next job starts fresh. The bound a long
+		// lineage actually needs: age and size both grow slowly while a chain grows once per run.
+		sessionMaxResumeChain: nonNegativeInt(env, "PI_SESSION_MAX_RESUME_CHAIN", 0), // 0 = no chain bound
+		// How full the saved context may be before a resume is refused, as a percentage of the model's own
+		// window. A PERCENTAGE, so `optionalBoundedInt` on softHoldPct's precedent rather than the 0 = off
+		// sentinel its two neighbours use: 0% would mean "never resume anything", which is a different
+		// request from "no bound", and 101 is a typo rather than a ceiling.
+		sessionMaxContextPct: optionalBoundedInt(env, "PI_SESSION_MAX_CONTEXT_PCT", 1, 100), // null = no context bound
 		chainDepthMax: nonNegativeInt(env, "PI_CHAIN_DEPTH_MAX", CHAIN_DEPTH_MAX_DEFAULT), // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
 		chainMaxPerJob: nonNegativeInt(env, "PI_CHAIN_MAX_PER_JOB", CHAIN_MAX_PER_JOB_DEFAULT), // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
 		dispatchRunPerHour: nonNegativeInt(env, "PI_DISPATCH_RUN_PER_HOUR", 3), // DES-ADMIN-VIA-PI-EXTENSION; 0 = disable dispatch_run

package/src/doctor.mjs

@@ -1132,8 +1132,37 @@ export async function collectChecks(env, seams) {
 				ok: true,
 				warn: true,
 				label: `${resuming} trigger(s) persist agent transcripts to ${sessionsDir} -- PII-bearing, host-only, never committed`,
-				fix: "confirm it is outside every git repo and on a disk you would put issue text on; PI_SESSIONS_TTL_DAYS bounds how long a transcript stays resumable",
+				fix: "confirm it is outside every git repo and on a disk you would put issue text on; PI_SESSIONS_TTL_DAYS, PI_SESSION_MAX_AGE_DAYS, PI_SESSION_MAX_RESUME_CHAIN and PI_SESSION_MAX_CONTEXT_PCT each bound a different thing about how much history one key accumulates (docs/sessions.md)",
 			});
+			// Which of the four bounds are actually on, as a FACT LINE rather than a warning: how long a
+			// lineage may run is an operator's call, not a defect, and doctor's warnings are for things that
+			// need a decision. The line exists because these knobs are unset by default and silent when
+			// unset, so the only way to tell a deliberate "no bound" from a forgotten one is to print it.
+			const bounds = [
+				["PI_SESSIONS_TTL_DAYS", env.PI_SESSIONS_TTL_DAYS, "14"],
+				["PI_SESSION_MAX_AGE_DAYS", env.PI_SESSION_MAX_AGE_DAYS, "off"],
+				["PI_SESSION_MAX_RESUME_CHAIN", env.PI_SESSION_MAX_RESUME_CHAIN, "off"],
+				["PI_SESSION_MAX_CONTEXT_PCT", env.PI_SESSION_MAX_CONTEXT_PCT, "off"],
+			];
+			checks.push({
+				ok: true,
+				label: `Resume bounds: ${bounds.map(([name, value, fallback]) => `${name}=${value === undefined || value === "" ? fallback : value}`).join(", ")}`,
+			});
+			// The one bound that can be set and still do nothing, and the operator cannot see it from here.
+			// Its measurement is reported by the JOB IMAGE's runner (INT-RUNNER-EXIT-CODE-PROTOCOL), so an
+			// image older than that field reports none, the gate passes on no measurement by design, and the
+			// bound is inert with nothing anywhere saying so. There is deliberately no image capability to
+			// check against -- capabilities are an inclusion list for what the host DEMANDS of an image, and
+			// telemetry is not that -- so this warning is the whole detection surface, which is exactly why
+			// it exists rather than being left to a doc.
+			if (env.PI_SESSION_MAX_CONTEXT_PCT) {
+				checks.push({
+					ok: true,
+					warn: true,
+					label: `PI_SESSION_MAX_CONTEXT_PCT=${env.PI_SESSION_MAX_CONTEXT_PCT} needs a job image whose runner reports context usage`,
+					fix: `an older image reports none, and a bound with no measurement passes rather than guessing, so on such an image this bound does nothing at all. On an image that does report one the reading is kept whether or not the bound is set, so it applies from the next job. Each run's own record (${env.PI_LOGS_DIR || "the logs directory"}/<jobId>.json) carries session.reason, which names the gate that refused`,
+				});
+			}
 		}
 	}
 

package/src/processor.mjs

@@ -44,7 +44,7 @@ export async function runJob(job, deps) {
 		// REQ-EGRESS-ALLOWLIST. Default admits everything, so a wiring that omits it behaves exactly as a
 		// deployment with no egress policy does -- which is also what the real factory returns when unarmed.
 		egressPreflight = async () => ({ ok: true }),
-		// (session, { piVersion }) => { promoted, reason, bytes }. Promotes this job's transcript back into
+		// (session, { piVersion, context }) => { promoted, reason, bytes }. Promotes this job's transcript back into
 		// the store, on a COMPLETED exit only. Never throws. The default is a no-op so a wiring that omits
 		// it behaves exactly as before -- no store, no promotion, no session in the record.
 		promoteSession = () => null,
@@ -351,7 +351,7 @@ export async function runJob(job, deps) {
 			return { outcome: "policy", reason: budget.reason, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: true }; // return => not retried
 		}
 
-		const { code, aborted, turns, tokens, session, usage } = await runContainer({ job, token, prepared });
+		const { code, aborted, turns, tokens, session, usage, context } = await runContainer({ job, token, prepared });
 		log("container_exit", { exitCode: code, aborted });
 
 		// Record token spend post-run (the check-AFTER half of the lagging token cap). The container ran,
@@ -388,7 +388,7 @@ export async function runJob(job, deps) {
 				// (CONST-RETRY-INFRA-ONLY). Same completed-only rule INT-OUTBOX-CONTRACT already uses, and
 				// it sits beside the chain collection for the same reason: both must happen before the
 				// `finally` deletes jobDir. Never throws.
-				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion }) : null;
+				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion, context }) : null;
 				return {
 					outcome: "completed",
 					exitCode: code,
@@ -455,7 +455,8 @@ export async function runJob(job, deps) {
  * and with one number alone it is indistinguishable from an ordinary cold start.
  *
  * The runner's verdict WINS on `resumed`, because it is the one that observed the outcome. The host's
- * reason is kept when the runner has none to give (a container that died before its exit line).
+ * reason is kept when the runner has none to give (a container that died before its exit line), AND when
+ * the host itself refused -- see the second precedence rule below.
  *
  * PII-free by construction: a boolean, a fixed enum, an integer. The key and the branch name are
  * deliberately absent -- this record holds no attacker-chosen string, and a branch name is one.
@@ -463,12 +464,30 @@ export async function runJob(job, deps) {
 function mergeSession(prepared, fromRunner, promoted = null) {
 	const host = prepared?.session;
 	if (!host && !fromRunner) return null;
+	// A HOST GATE THAT REFUSED OUTRANKS THE RUNNER'S `absent`, and without this rule it never reached a
+	// record at all. A refused read stages a 0-byte file rather than nothing (session-store.mjs, where the
+	// reasoning is pi's EEXIST race), the container is handed that file either way, and pi opens it and
+	// finds no messages -- so the runner reports `absent` on EVERY host refusal. Letting that win overwrote
+	// the answer with a restatement of the question: `expired` and `pi-version-changed` reached no
+	// completed record in the feature's whole life, and `docs/sessions.md`'s promise that every cold start
+	// is nameable in the record was false for them.
+	//
+	// Narrow on purpose, `host.resume === false` and the runner's token exactly `absent`. When the host
+	// DID stage a transcript and the runner still reports `absent`, the two genuinely disagree, and that
+	// disagreement is the event this object exists to show; the runner keeps winning there. So does its
+	// `unparseable`, which reports a degrade the host could not see.
+	const hostRefused = host?.resume === false && typeof host.reason === "string";
 	return {
 		resumed: fromRunner ? fromRunner.resumed : false,
 		// A promotion that was refused is the more useful reason to surface: "locked" or
 		// "not-a-regular-file" says why the NEXT run will cold-start, which is the thing an operator
 		// chasing "it never resumes" needs. It only ever replaces a reason on the completed path.
-		reason: (promoted && !promoted.promoted ? promoted.reason : null) ?? fromRunner?.reason ?? host?.reason ?? null,
+		reason:
+			(promoted && !promoted.promoted ? promoted.reason : null) ??
+			(hostRefused && fromRunner?.reason === "absent" ? host.reason : null) ??
+			fromRunner?.reason ??
+			host?.reason ??
+			null,
 		bytes: promoted?.bytes ?? host?.bytes ?? null,
 	};
 }

package/src/run-container.mjs

@@ -30,7 +30,7 @@ export function makeRunContainer({
 	image, // the DEPLOYMENT default (PI_JOB_IMAGE); a trigger's own run.image overrides it per job
 	hostEnv = process.env,
 	onOutput = (c) => process.stdout.write(c),
-	openJobLog = () => ({ write() {}, close: async () => ({ turns: null, tokens: null, session: null, usage: null }) }),
+	openJobLog = () => ({ write() {}, close: async () => ({ turns: null, tokens: null, session: null, usage: null, context: null }) }),
 	spawnFn = spawn,
 	globalPiDir = null, // REQ-GLOBAL-PI-OVERLAY: operator's global pi overlay dir, mounted :ro; null = off
 	allowGlobalExtensions = true, // REQ-GLOBAL-PI-OVERLAY: the staged overlay's extensions load unless PI_GLOBAL_ALLOW_EXTENSIONS=0
@@ -47,7 +47,7 @@ export function makeRunContainer({
 	// async so a synchronous throw (e.g. buildContainerEnv on an unconfigured provider) surfaces as
 	// a rejection, uniformly awaitable by the processor and by tests.
 	return async function runContainer({ job, token, prepared, name, signal }) {
-		if (signal?.aborted) return { code: 137, aborted: true, turns: null, tokens: null, session: null, usage: null }; // killed before it could start
+		if (signal?.aborted) return { code: 137, aborted: true, turns: null, tokens: null, session: null, usage: null, context: null }; // killed before it could start
 
 		// Closed env allowlist: only the provider key + the declared PI_* vars. Throws (config) if
 		// the provider is unconfigured -- the processor turns that into a pre-spend refusal.
@@ -147,20 +147,25 @@ export function makeRunContainer({
 			});
 			child.on("close", async (code) => {
 				const aborted = signal?.aborted === true; // capture BEFORE the await
-				// A rejecting sink.close is swallowed so a misbehaving sink cannot hang the run; turns/tokens/session/usage fall back to null.
+				// A rejecting sink.close is swallowed so a misbehaving sink cannot hang the run; turns/tokens/session/usage/context fall back to null.
 				let turns = null;
 				let tokens = null;
 				let session = null;
 				let usage = null;
+				let context = null;
 				try {
-					({ turns, tokens, session, usage } = await sink.close());
+					// `context = null` is a DEFAULT rather than a plain destructure: an injected sink that
+					// predates the field returns no such key, and `undefined` would then reach the record's
+					// shape where every other absence is spelled `null`.
+					({ turns, tokens, session, usage, context = null } = await sink.close());
 				} catch {
 					turns = null;
 					tokens = null;
 					session = null;
 					usage = null;
+					context = null;
 				}
-				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage } : { code: code ?? 1, aborted: false, turns, tokens, session, usage });
+				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage, context } : { code: code ?? 1, aborted: false, turns, tokens, session, usage, context });
 			});
 		});
 

package/src/run-history.mjs

@@ -110,6 +110,43 @@ export function parseExitSession(text) {
 	return null;
 }
 
+/**
+ * The container's report of how full its context was when the run ended (issue #186). Shaped exactly
+ * like `parseExitSession` above and, like it, PASSED THROUGH rather than rebuilt: both integers are
+ * host-bounded numbers, so `parseExitUsage`'s revalidating rebuild is not what this needs -- that one
+ * exists because the ledger carries id STRINGS.
+ *
+ * Absent means ABSENT, never zero. A runner predating this field, a run pi could give no context window
+ * for, and a compaction that left the count unknown all produce no key at all, and the session store
+ * reads that as "no measurement" and passes rather than inventing a denominator.
+ */
+export function parseExitContext(text) {
+	if (typeof text !== "string") return null;
+	const lines = text.split("\n");
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const line = lines[i].trim();
+		if (line === "") continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue; // docker/agent noise or a truncated final line
+		}
+		if (parsed?.event !== "exit") continue;
+		const c = parsed?.context;
+		// A window of 0 is not a denominator, and a negative count is not a measurement. SAFE integers
+		// specifically: `Number.isInteger` accepts up to ~1.8e308, and anything from 1e21 up stringifies to
+		// exponential notation, which the session store's own decimal round-trip then rejects on read --
+		// so a value in that range would be written into the store and be unreadable forever after, with
+		// the gate failing open on a measurement that said the context was full.
+		if (c && typeof c === "object" && !Array.isArray(c) && Number.isSafeInteger(c.tokens) && Number.isSafeInteger(c.window) && c.tokens >= 0 && c.window > 0) {
+			return { tokens: c.tokens, window: c.window };
+		}
+		return null;
+	}
+	return null;
+}
+
 export function parseExitTokens(text) {
 	if (typeof text !== "string") return null;
 	const lines = text.split("\n");
@@ -389,11 +426,12 @@ export function makeLogSink({ logsDir, enabled, fs = nodeFs, log = () => {} }) {
 		}
 
 		async function close({ timeoutMs = 2000 } = {}) {
-			// Capture turns/tokens/session/usage from the tail first, so they survive even if the flush errors or times out.
+			// Capture turns/tokens/session/usage/context from the tail first, so they survive even if the flush errors or times out.
 			const turns = parseExitTurns(tail);
 			const tokens = parseExitTokens(tail);
 			const session = parseExitSession(tail);
 			const usage = parseExitUsage(tail);
+			const context = parseExitContext(tail);
 			try {
 				if (stream !== null) {
 					const s = stream;
@@ -417,7 +455,7 @@ export function makeLogSink({ logsDir, enabled, fs = nodeFs, log = () => {} }) {
 			} catch (err) {
 				log("log_sink_error", { jobId, reason: err?.message });
 			}
-			return { turns, tokens, session, usage };
+			return { turns, tokens, session, usage, context };
 		}
 
 		return { write, close };

package/src/session-store.mjs

@@ -44,6 +44,54 @@ import { sessionKeyFor } from "./session-key.mjs";
 export const SESSION_FILE_NAME = "current.jsonl";
 const PI_VERSION_FILE = "pi-version";
 const LOCK_FILE = "lock";
+/**
+ * How many times in a row this key's transcript has been HANDED TO A CONTAINER. A counter rather than a
+ * derivation, because there is nothing to derive it from: the run record deliberately carries no session
+ * key (DES-SESSION-KEY-IS-DERIVED-NOT-INDEXED), so counting past runs would need the key->record index
+ * that entry refuses. One integer beside the transcript it describes is not that index; it is keyed state
+ * written where the key already is, and it answers exactly one question rather than being a query
+ * surface. Maintained even when no bound is set, deliberately -- see the write in promoteSession.
+ *
+ * IT COUNTS THE HOST'S DELIVERIES, NOT PI'S CONTINUATIONS, and that is the whole security of this bound.
+ * It counted pi's `resumed` first, on the reasoning that a transcript pi declined to continue extended
+ * nothing. That reasoning is wrong here, because the agent owns /session and therefore chooses what pi
+ * makes of the file: a transcript carrying a valid header and payload on lines pi's parser DROPS is
+ * delivered by the host every run while pi reports zero messages, so the counter reset every run and the
+ * chain bound never fired -- measured, not theorised. The host's own decision to hand the file over is
+ * the one fact in this exchange that nothing inside the container can influence.
+ */
+const RESUME_CHAIN_FILE = "resume-chain";
+/**
+ * How full the context was when the run that wrote this transcript ended, as `<tokens> <window>`. Both
+ * numbers, not a precomputed percentage: the denominator is what makes the numerator readable later, and
+ * an operator looking at a refusal should be able to see what it was judged against.
+ *
+ * Reported BY THE CONTAINER, which is the only place the number exists: pi computes it from the session
+ * it is holding. That puts it at the same trust level as `turns` and `tokens`, and the residual is
+ * recorded in OQ-003 rather than papered over -- there is no host-side alternative that is not equally
+ * agent-influenced, since the transcript itself is agent-written.
+ */
+const CONTEXT_FILE = "context";
+/** Both sidecar formats are a handful of bytes. Generous, and still nowhere near a job's wall clock. */
+const SIDECAR_MAX_BYTES = 4096;
+/**
+ * The host-effective provider and model as one token, or null when the job names neither.
+ *
+ * CONSERVATIVE BY CONSTRUCTION: the sidecar is whitespace-delimited, so a value carrying a space would
+ * split the record and be read back as a different field. Rather than escape, refuse: anything outside
+ * the charset the run record already validates model ids against is no identity, and no identity means
+ * the reading stays usable rather than being thrown away.
+ */
+function modelIdentity(job) {
+	const provider = typeof job?.provider === "string" ? job.provider : "";
+	const model = typeof job?.model === "string" ? job.model : "";
+	if (provider === "" || model === "") return null;
+	// Lowercased first, the same normalisation the run record's own model ids get, so a trigger written
+	// `Claude-Sonnet` and one written `claude-sonnet` are one model rather than two -- and so that a
+	// perfectly ordinary id does not fall out of the charset below and silently stop stamping.
+	const id = `${provider}/${model}`.toLowerCase();
+	return /^[a-z0-9][a-z0-9._:/-]{0,127}$/.test(id) ? id : null;
+}
 
 /**
  * Read-path outcomes. Every one is a named cold start rather than a bare `false`: a feature that fails
@@ -56,6 +104,9 @@ export function makeSessionStore({
 	sessionsDir,
 	ttlDays,
 	maxBytes,
+	maxAgeDays = 0,
+	maxResumeChain = 0,
+	maxContextPct = null,
 	log = () => {},
 	now = () => Date.now(),
 	fs = { copyFileSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync },
@@ -83,11 +134,16 @@ export function makeSessionStore({
 			// CLI run, an unresolvable head ref), so it gets no mount and no transcript on disk.
 			if (key === null) return null;
 
+			// The model this job will actually run, for the context bound. A key is (kind, repo, ref) and
+			// carries NO model, so two triggers on one issue can name different ones, and the same token
+			// count is 78% of a 32k window and 2.5% of a 1M one. Carried on the session object rather than
+			// read again at promote time, so the reading is stamped with the model that produced it.
+			const modelId = modelIdentity(job);
 			const hostDir = join(jobDir, "session");
 			const staged = join(hostDir, SESSION_FILE_NAME);
 			fs.mkdirSync(hostDir, { recursive: true, mode: 0o700 });
 
-			const verdict = readCanonical(key, piVersion);
+			const verdict = readCanonical(key, piVersion, modelId);
 			if (verdict.resume) {
 				fs.copyFileSync(canonicalFile(key), staged);
 			} else {
@@ -98,7 +154,7 @@ export function makeSessionStore({
 				fs.writeFileSync(staged, "");
 			}
 			log("session_resolved", { key, resume: verdict.resume, reason: verdict.reason });
-			return { hostDir, key, ...verdict };
+			return { hostDir, key, modelId, ...verdict };
 		} catch (err) {
 			// A history fault must never fail the prepare that asked.
 			log("session_store_failed", { phase: "resolve", reason: err?.message });
@@ -114,7 +170,7 @@ export function makeSessionStore({
 	 * 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 } = {}) {
+	function promoteSession(session, { piVersion = null, context = null } = {}) {
 		// The second DI-seam backstop, and unreachable for the same reason as the `!sessionsDir` return
 		// above: sessionKeyFor is total and binary (null, or 32 hex chars), so resolveSession returns null
 		// rather than a keyless session, and processor.mjs only calls this when prepare handed it one. Kept
@@ -137,16 +193,42 @@ export function makeSessionStore({
 			let fd;
 			try {
 				fd = fs.openSync(lock, "wx"); // exclusive create IS the lock; no daemon, no lease
-			} catch {
+			} catch (err) {
+				// EEXIST is the only failure that MEANS locked. A read-only directory, a full disk or a
+				// vanished store all failed to create the lock too, and reporting those as `locked` sends an
+				// operator looking for a stuck lock file that does not exist. Anything else falls through to
+				// the outer catch and reports `promote-failed`, which is what actually happened.
+				if (err?.code !== "EEXIST") throw err;
 				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`;
+				try {
+					// `copyFileSync` follows a link at the DESTINATION, so a link planted at this name would
+					// receive the whole transcript and leave the canonical path pointing at it. The key
+					// directory's name is derived rather than random, so the path is precomputable by anyone
+					// who knows the repository and the branch; unlinking removes the link, never its target.
+					fs.unlinkSync(tmp);
+				} catch {
+					// Absent is the desired state.
+				}
 				fs.copyFileSync(staged, tmp);
 				fs.renameSync(tmp, canonicalFile(session.key));
 				fs.writeFileSync(join(dir, PI_VERSION_FILE), String(piVersion ?? ""));
+				// The two sidecars, immediately after the swap and under the same lock. NOT part of the swap
+				// itself, which is one rename and cannot be widened: what the lock buys them is that no
+				// other job can interleave, and what the ordering buys them is that they never describe a
+				// transcript older than the one now in place.
+				//
+				// EACH IS CAUGHT SEPARATELY, and that is not defensiveness for its own sake. These writes
+				// run AFTER the transcript is already promoted, so letting one throw would return
+				// `promote-failed` for a promotion that demonstrably happened -- a record that says the next
+				// run will cold start when it will in fact resume, which is worse than the bookkeeping loss
+				// it is reporting.
+				writeSidecar(dir, RESUME_CHAIN_FILE, session.key, chainValue(session));
+				writeContextSidecar(dir, session, context);
 			} finally {
 				fs.closeSync(fd);
 				try {
@@ -164,6 +246,79 @@ export function makeSessionStore({
 		}
 	}
 
+	/**
+	 * The counter's next value. `session.resume` is the HOST's own decision to hand this key's transcript
+	 * to a container, which is the only half of the exchange the container cannot influence; `resumed` (the
+	 * container's verdict) is deliberately ignored for the counter and kept in the signature only because
+	 * the record's own merge still wants it. A cold start resets, so a lineage always gets a fresh start
+	 * from its next COMPLETED run -- a run that never completes promotes nothing and resets nothing, which
+	 * is the safe direction: the key simply keeps cold-starting.
+	 */
+	function chainValue(session) {
+		return String(session.resume === true ? readResumeChain(session.key) + 1 : 0);
+	}
+
+	/**
+	 * One sidecar write. Two properties, both deliberate.
+	 *
+	 * **It cannot write THROUGH a link.** `writeFileSync` follows one, which would turn a planted symlink
+	 * in a key directory into a truncating write of any worker-writable file, with the container's own
+	 * integers as the payload. Writing a temp and renaming over the name replaces whatever is there --
+	 * link included -- with a regular file, and never opens the link's target. The temp is unlinked first
+	 * for the same reason, since a planted link at THAT name would be the same hole one step along. The
+	 * read side's `lstat` guard is the other half of this; neither is sufficient alone.
+	 *
+	 * **It is never fatal.** This runs AFTER the transcript is already promoted, so throwing would return
+	 * `promote-failed` for a promotion that demonstrably happened, telling an operator the next run will
+	 * cold start when it will in fact resume. The bookkeeping loss is logged and the truth is kept.
+	 */
+	function writeSidecar(dir, name, key, value) {
+		const file = join(dir, name);
+		const tmp = `${file}.incoming`;
+		try {
+			try {
+				fs.unlinkSync(tmp);
+			} catch {
+				// Absent is the desired state.
+			}
+			fs.writeFileSync(tmp, value);
+			fs.renameSync(tmp, file);
+		} catch (err) {
+			log("session_sidecar_failed", { key, file: name, reason: err?.message });
+		}
+	}
+
+	/**
+	 * The context sidecar, whose three cases are all different.
+	 *
+	 * A run that RESUMED and measured nothing keeps the previous reading: the transcript it promoted is
+	 * the old one extended, so the last real measurement is the closest true statement available, and a
+	 * zero would read as "the context emptied", which cannot have happened.
+	 *
+	 * A COLD START, though, promoted a transcript that shares nothing with the one the old reading
+	 * described, so the reading must GO. Keeping it is what turned a single high measurement into a key
+	 * that refused itself forever: the gate read a stale number, cold-started, and the cold start left the
+	 * same number behind for the next run to read. That loop had no exit that did not involve deleting the
+	 * store by hand.
+	 */
+	function writeContextSidecar(dir, session, context) {
+		const file = join(dir, CONTEXT_FILE);
+		if (session.resume !== true) {
+			try {
+				fs.unlinkSync(file);
+			} catch {
+				// Absent is the desired state, so failing to remove what is not there is success.
+			}
+			return;
+		}
+		if (!context) return;
+		// The model rides along because the ratio is meaningless without it: a key is (kind, repo, ref) and
+		// carries no model, so two triggers on one issue can run different ones, and 25k tokens is 78% of a
+		// 32k window and 2.5% of a 1M one. A reading from another model is not a reading about this one.
+		const stamp = session.modelId ? ` ${session.modelId}` : "";
+		writeSidecar(dir, CONTEXT_FILE, session.key, `${context.tokens} ${context.window}${stamp}`);
+	}
+
 	function keyDir(key) {
 		return join(sessionsDir, key);
 	}
@@ -172,7 +327,7 @@ export function makeSessionStore({
 	}
 
 	/** The read path, gate by gate. The FIRST miss wins and names itself. */
-	function readCanonical(key, piVersion) {
+	function readCanonical(key, piVersion, modelId) {
 		const file = canonicalFile(key);
 		const check = inspectFile(file);
 		if (!check.ok) return COLD(check.reason);
@@ -184,26 +339,150 @@ export function makeSessionStore({
 		// 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");
+		// Through the same guarded read as the two sidecars below it. This one predates them and was the
+		// one unguarded read left in the key directory; a symlink here would have decided a gate on the
+		// contents of some other file entirely.
+		const stamped = readSidecar(key, PI_VERSION_FILE);
+		if (stamped === null || stamped !== piVersion) return COLD("pi-version-changed");
+
+		// How many times in a row this key has already been resumed. Placed HERE, ahead of the header read,
+		// for two reasons. It is a small sidecar read exactly like the pi-version arm above it, so refusing
+		// on it skips pulling a transcript that may be megabytes; and unlike every other arm it asks about
+		// the LINEAGE rather than the file, so it needs nothing the file could tell it.
+		//
+		// The cost of that placement, stated rather than left to be discovered: a transcript that is both
+		// chain-exhausted AND corrupt reports the chain. That is the intentional refusal of the two, and the
+		// corruption is not hidden, only deferred -- this cold start's own promotion resets the counter, so
+		// the very next run reads the file and reports `unparseable`.
+		//
+		// FAILS OPEN on absence, which is the opposite of the age gate one arm down and deliberate. Every
+		// key that existed before this counter did has no file, and reading that as "already exhausted"
+		// would cold-start an operator's entire store the day they set the bound.
+		if (maxResumeChain > 0 && readResumeChain(key) >= maxResumeChain) return COLD("resume-chain-too-long");
+
+		// How full the context already is, against a ceiling the HOST owns. Not a duplicate of pi's own
+		// compaction threshold and deliberately not read from it: pi's is settable in a serviced repo's
+		// .pi/settings.json, so it is a line the repository can move, and this one cannot be. Past that
+		// threshold what a resumed job replays is not the transcript but a model-written summary of it,
+		// produced while that model was reading attacker-authored text (OQ-003), so this is a safety bound
+		// before it is an economic one.
+		//
+		// FAILS OPEN and INVENTS NO DENOMINATOR. No sidecar (every key promoted before this shipped, and
+		// every key under an image whose runner predates it), a compaction that left pi's own count
+		// unknown, or a window of zero all mean the gate has nothing to act on, and a gate with nothing to
+		// act on passes. A bytes-against-window guess was rejected rather than used as a fallback: the
+		// transcript is the whole branch INCLUDING what compaction folded away, so it over-reads exactly
+		// past the threshold this exists to catch, and there is no bytes-to-tokens calibration here to
+		// make it mean anything.
+		if (maxContextPct !== null) {
+			const seen = readContext(key);
+			// A reading STAMPED WITH ANOTHER MODEL is not a reading about this one, and using it is wrong in
+			// both directions: it refuses a job whose window is far larger than the one that was measured,
+			// and it passes one whose window is far smaller. Unknown on either side stays usable, so a
+			// deployment that names no model per trigger keeps the bound it had.
+			const foreign = seen !== null && seen.modelId !== null && modelId !== null && seen.modelId !== modelId;
+			if (seen !== null && !foreign && (seen.tokens * 100) / seen.window >= maxContextPct) return COLD("context-too-full");
 		}
-		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.
+		// Cheapest real shape check, and the last one before the header's own contents are used: 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.
+		let header = null;
 		try {
 			const head = String(fs.readFileSync(file, "utf8")).split("\n", 1)[0];
-			if (JSON.parse(head)?.type !== "session") return COLD("unparseable");
+			header = JSON.parse(head);
+			if (header?.type !== "session") return COLD("unparseable");
 		} catch {
 			return COLD("unparseable");
 		}
+
+		// The CONVERSATION's age, and it is a DIFFERENT CLOCK from `expired` above rather than a finer
+		// setting of it. The TTL reads the transcript's mtime, which the PROMOTE rename refreshes -- and only
+		// that: `copyFileSync` stamps its destination, never its source, so the resolve half leaves the
+		// canonical file's mtime alone (measured, because the obvious reading of the two call sites says
+		// otherwise). So `expired` is time since the last COMPLETED run on this key, and a lineage whose runs
+		// keep completing never expires however old its first turn is. pi's header carries the instant the
+		// session was created, so this
+		// costs no new persisted state -- the line is already read and parsed one gate up, and until now
+		// only its `type` was looked at.
+		//
+		// The arm is LAST because the earlier gates are cheaper and because a corrupt file is corrupt rather
+		// than old: `unparseable` must keep winning over this, or a damaged transcript would be reported as
+		// a lineage that aged out.
+		//
+		// UNREADABLE FAILS CLOSED, on the pi-version gate's precedent one arm up: a header with no usable
+		// timestamp cannot be shown to be young enough, and "assume it matches" is the direction that
+		// silently keeps resuming. Like `pi-version-changed`, one token covers all three causes (absent,
+		// wrong type, unparseable).
+		//
+		// A timestamp in the FUTURE passes, deliberately. It buys nothing to refuse one: the agent owns
+		// /session, so anything able to write a future timestamp is equally able to write the current one,
+		// and refusing would convert ordinary clock skew between a container and its host into a cold start
+		// for every key on the deployment.
+		if (maxAgeDays > 0) {
+			const started = Date.parse(typeof header.timestamp === "string" ? header.timestamp : "");
+			if (!Number.isFinite(started)) return COLD("conversation-too-old");
+			if (now() - started > maxAgeDays * 86400000) return COLD("conversation-too-old");
+		}
 		return { resume: true, reason: "resumed", bytes: check.bytes };
 	}
 
+	/**
+	 * Every sidecar read goes through here, and it is the same load-bearing check `inspectFile` makes on
+	 * the transcript: **`lstat`, regular files only.** The canonical store is host-only and never mounted,
+	 * so nothing in a container can plant a link here -- but the directory NAME is derived rather than
+	 * random (`sha256(kind, repo, ref)`), so anyone who knows the repository and the branch can compute it
+	 * and pre-create the path. `readFileSync` and `writeFileSync` both follow links, which would turn a
+	 * planted symlink into a read of any worker-readable file on the gate's path, and a promotion into a
+	 * truncating write of any worker-writable one. The transcript has been guarded against exactly this
+	 * since the feature shipped; these files inherit it rather than being the exception.
+	 *
+	 * SIZE-BOUNDED for the same reason the transcript is. Both formats are a handful of bytes, `maxBytes`
+	 * does not cover them, and reading a 2.5 GiB file on the job's own path costs half a minute of wall
+	 * clock before any container starts.
+	 */
+	function readSidecar(key, name) {
+		try {
+			const file = join(keyDir(key), name);
+			const st = fs.lstatSync(file);
+			if (!st.isFile() || st.size === 0 || st.size > SIDECAR_MAX_BYTES) return null;
+			return String(fs.readFileSync(file, "utf8")).trim();
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * The consecutive-delivery counter for a key, or 0 when there is not a readable one. Never throws and
+	 * never guesses: a missing, empty, corrupt or negative counter is 0, so the only way to be refused by
+	 * the chain bound is for this store to have written a number that reaches it.
+	 */
+	function readResumeChain(key) {
+		const raw = readSidecar(key, RESUME_CHAIN_FILE);
+		if (raw === null) return 0;
+		const n = Number.parseInt(raw, 10);
+		// `String(n) === raw` is the same anti-truncation guard config.mjs applies to every integer knob,
+		// and it is what keeps a corrupt "3.5" from being read as a chain of three.
+		return Number.isInteger(n) && n > 0 && String(n) === raw ? n : 0;
+	}
+
+	/**
+	 * The stored context occupancy for a key, or `null` when there is no measurement. Never throws, never
+	 * guesses, and never returns a partial: anything it cannot read as two positive integers is no
+	 * measurement at all, which the caller treats as "pass" rather than as zero.
+	 */
+	function readContext(key) {
+		const raw = readSidecar(key, CONTEXT_FILE);
+		if (raw === null) return null;
+		const [rawTokens, rawWindow, rawModel] = raw.split(/\s+/);
+		const tokens = Number.parseInt(rawTokens, 10);
+		const window = Number.parseInt(rawWindow, 10);
+		if (!Number.isInteger(tokens) || !Number.isInteger(window) || tokens < 0 || window <= 0) return null;
+		if (String(tokens) !== rawTokens || String(window) !== rawWindow) return null;
+		return { tokens, window, modelId: rawModel ?? null };
+	}
+
 	/**
 	 * lstat, REGULAR FILES ONLY -- and this is the one line in the file that is load-bearing security
 	 * rather than hygiene.

package/src/start.mjs

@@ -298,6 +298,9 @@ export async function startWorker(
 		sessionsDir: config.sessionsDir,
 		ttlDays: config.sessionsTtlDays,
 		maxBytes: config.sessionMaxBytes,
+		maxAgeDays: config.sessionMaxAgeDays,
+		maxResumeChain: config.sessionMaxResumeChain,
+		maxContextPct: config.sessionMaxContextPct,
 		log,
 	});
 	// Boot sweep, beside the log reaper and for the same reason it is beside rather than inside it: these