@edgehero/pi-dispatch 1.10.3 → 2.0.0

package/src/session-store.mjs

@@ -1,9 +1,11 @@
 import {
 	copyFileSync,
+	fstatSync,
 	lstatSync,
 	mkdirSync,
 	openSync,
 	closeSync,
+	readSync,
 	readFileSync,
 	readdirSync,
 	renameSync,
@@ -11,8 +13,12 @@ import {
 	unlinkSync,
 	writeFileSync,
 } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { join } from "node:path";
+import { scrubCredentials } from "./redact.mjs";
 import { sessionKeyFor } from "./session-key.mjs";
+import { resolveBackendName } from "./backend-registry.mjs";
+import { UNATTRIBUTED_BACKEND } from "./backends.mjs";
 
 /**
  * session-store.mjs -- the host side of a resumable session (INT-SESSION-STORE-CONTRACT).
@@ -72,7 +78,75 @@ const RESUME_CHAIN_FILE = "resume-chain";
  * 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. */
+/**
+ * The venue whose container produced the transcript beside it (issue #277): a backend name, one line.
+ *
+ * A SIDECAR, NOT KEY MATERIAL. `DES-SESSION-KEY-IS-DERIVED-NOT-INDEXED` makes the key a pure function of
+ * (kind, repo, ref), and a venue in the key would fork a trigger moved between venues into a second lineage
+ * that nothing ever sweeps. As a sidecar it GATES the one lineage instead: the move costs one cold start.
+ *
+ * ABSENT READS AS `UNATTRIBUTED_BACKEND`, never as the deployment default. Every transcript written before this
+ * stamp existed ran on `local`, and the default is a setting that can move under it.
+ */
+const VENUE_FILE = "venue";
+/**
+ * What the venue stamp reads while a promotion is swapping the transcript under it. It matches no venue:
+ * parentheses are outside the charset every backend name is validated against (a test pins every name this
+ * build knows to it), so a key left holding this cold-starts on every venue until a promotion completes.
+ */
+const VENUE_PENDING = "(pending)";
+
+/**
+ * Per-promotion suffix for the transcript's in-flight copy, paired with the pid.
+ *
+ * The tmp name USED to be a fixed `<canonical>.incoming`, which was self-cleaning and harmless while the
+ * per-key lock guaranteed one writer. The stale-lock takeover concedes a window with two, and a SHARED tmp
+ * path voids exactly the atomicity the swap exists for: B's unlink removes A's in-flight copy, B's copy
+ * replaces it, and whichever renames second can put the other's half-written file at the canonical path --
+ * an agent handed a truncated conversation with no gate able to see it. `triggers-file.mjs` learned this
+ * on `triggers.json` and its `tmpPathFor` says the same thing.
+ *
+ * RANDOM BYTES, not just a pid and a counter, and the pid is why: two workers can share one. Two
+ * containers where node is pid 1, or two hosts on one shared `PI_SESSIONS_DIR` -- which is the very
+ * `OQ-031` shape the takeover's own skew analysis invokes -- produce byte-identical `<canonical>.1.0.incoming`
+ * names, measured, and a shared destination does tear (two processes copying 4 MiB to one path mixed both
+ * writers' bytes in 1 sample of 110). A pid-and-counter name separates two promotions inside ONE process,
+ * which is the one case that cannot happen, and leaves the case that can. The random half is what actually
+ * separates writers; the pid and counter stay because they make a straggler attributable.
+ *
+ * The cost is that a crash between the copy and the rename leaves a uniquely named straggler instead of one
+ * the next promotion overwrites; the reaper's recursive sweep of the key takes it with everything else --
+ * except under `PI_SESSIONS_TTL_DAYS=0`, where that sweep does not run at all, so stragglers accumulate
+ * there where the old shared name was self-cleaning. The same TTL-0 caveat the lock's takeover carries.
+ *
+ * The SIDECAR temps keep the shared name deliberately, and the asymmetry is the point rather than an
+ * oversight: a sidecar's worst case under a concurrent writer is a missing or half-written sidecar, and
+ * every one of those reads back as `null` and produces a cold start, which this store already treats as
+ * the safe outcome. The transcript's worst case is a corrupt transcript, which it does not.
+ */
+let tmpSeq = 0;
+
+/**
+ * A promotion lock older than this is a crashed writer's, not a live one's.
+ *
+ * `triggers-file.mjs` holds the same idiom at ten seconds; this is 360 times that, because the work under
+ * the two locks is not comparable. A trigger write is a read, one mutate and two syscalls. A
+ * promotion is a COPY of the container's transcript -- up to `PI_SESSION_MAX_BYTES`, 8 MiB by default --
+ * plus a rename and four small sidecar writes.
+ *
+ * AN ASSERTION ABOUT STORAGE, NOT A DERIVATION, and said plainly because `PI_SESSION_MAX_BYTES=0` is a
+ * supported setting and there is then no configured bound to derive from. An hour covers roughly three
+ * gigabytes at a megabyte a second, which is a slower store than anything this project will meet.
+ *
+ * WHAT MAKES A GENEROUS NUMBER THE RIGHT TRADE IS THE ASYMMETRY. Too short steals a LIVE writer's lock,
+ * and with the release-by-path residual below that degrades into the lock being functionally absent. Too
+ * long only delays recovery on a key nobody is watching, at one extra cold start per job until it passes.
+ *
+ * A CONSTANT RATHER THAN A KNOB, on triggers-file's precedent: the one value an operator would reach for
+ * is zero, and zero here means no lock at all.
+ */
+const LOCK_STALE_MS = 3_600_000;
+/** Every sidecar format is 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.
@@ -93,6 +167,15 @@ function modelIdentity(job) {
 	return /^[a-z0-9][a-z0-9._:/-]{0,127}$/.test(id) ? id : null;
 }
 
+/**
+ * A venue name as the store handles it: a non-empty string, else `null`. A promotion stamps `String(venue)`,
+ * and `String(undefined)` is the word `undefined`, which is a valid-looking name; normalising first means a
+ * session with no resolvable venue is stamped with nothing rather than with that.
+ */
+function normaliseVenue(venue) {
+	return typeof venue === "string" && venue !== "" ? venue : null;
+}
+
 /**
  * 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
@@ -107,9 +190,12 @@ export function makeSessionStore({
 	maxAgeDays = 0,
 	maxResumeChain = 0,
 	maxContextPct = null,
+	// The deployment's default venue, `PI_BACKENDS[0]`, for a job that names none (#277). `null` is a
+	// dependency-injection seam, and a job whose venue cannot be resolved never resumes.
+	defaultBackend = null,
 	log = () => {},
 	now = () => Date.now(),
-	fs = { copyFileSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync },
+	fs = { copyFileSync, fstatSync, lstatSync, mkdirSync, openSync, closeSync, readSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync },
 }) {
 	/**
 	 * Stage this job's /session directory and decide whether it resumes.
@@ -121,6 +207,8 @@ export function makeSessionStore({
 	 *   /session mount at all (unarmed, or no key) -- which is byte-identical to a pre-feature job.
 	 */
 	function resolveSession(job, { jobDir, resolved = {}, piVersion = null } = {}) {
+		// Declared outside the try so a fault can take back what this call staged (below).
+		let hostDir = null;
 		try {
 			// Unreachable in a wired worker, and deliberately kept: resolveSession is only ever called for a
 			// job that armed run.resume (prepare-github.mjs), and processor.mjs refuses exactly that job
@@ -139,13 +227,91 @@ export function makeSessionStore({
 			// 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");
+			// The venue this job will run in, resolved exactly as the registry dispatches it (#277). Carried on
+			// the session like `modelId`, so the promotion stamps the venue that produced the transcript rather
+			// than re-deriving one later.
+			const venue = normaliseVenue(resolveBackendName(job, defaultBackend));
+			hostDir = join(jobDir, "session");
 			const staged = join(hostDir, SESSION_FILE_NAME);
 			fs.mkdirSync(hostDir, { recursive: true, mode: 0o700 });
 
-			const verdict = readCanonical(key, piVersion, modelId);
+			// The identity is split off the verdict rather than carried on it: this return is spread onto the
+			// session object the processor holds for the WHOLE run, and an inode number is bookkeeping for the
+			// next few lines, not state a promotion an hour later should be able to read.
+			const { ident: judged = null, dirIdent: judgedDir = null, ...judgedVerdict } = readCanonical(key, piVersion, modelId, venue);
+			let verdict = judgedVerdict;
 			if (verdict.resume) {
-				fs.copyFileSync(canonicalFile(key), staged);
+				// THE BYTES COME OFF THE DESCRIPTOR THAT WAS JUDGED, never off the path a second time.
+				//
+				// The gates above ran by PATH, and so did this copy until issue #375's gate round: it was
+				// `copyFileSync(canonicalFile(key), staged)` followed by re-checks that also re-resolved the path.
+				// Every one of those resolutions is a separate walk of the same name, so an attacker who is a
+				// symlink DURING the copy and the original directory again before the re-check matched all three
+				// arms while the bytes came from somewhere else entirely. Measured on the pre-fix code by a plain
+				// second process doing rename/symlink/rename in a loop: 195 of 757 successful resumes in the
+				// review round's own harness, and 23 of 654 in a 90-second run of this file's, staged an
+				// attacker's transcript and reported `resumed`. The same shape one level down -- the
+				// A, B, A round trip on `current.jsonl` itself -- is what this contract used to state as a
+				// residual the identity re-check could only shrink.
+				//
+				// One `open` answers both. The descriptor is bound to the inode at the instant it is taken, so
+				// `fstat` on it cannot be lied to by a later swap, and bytes read from it cannot come from a file
+				// that replaced the name afterwards. What a swap can still do is make this refuse: the identity
+				// will not match what the gates judged, and the job cold-starts, which is the safe direction.
+				//
+				// Streamed in bounded chunks rather than read whole: `PI_SESSION_MAX_BYTES` defaults to 8 MiB but
+				// `0` means NO CAP, and buffering an uncapped transcript into memory to copy it would be a new
+				// way to hurt a host that the old `copyFileSync` never had.
+				let fd = null;
+				try {
+					fd = fs.openSync(canonicalFile(key), "r");
+					const opened = identityOf(fs.fstatSync(fd));
+					// TWO CHECKS, and neither subsumes the other. The gate round proved that the hard way, twice.
+					//
+					// The DESCRIPTOR check says the bytes about to be staged come off the inode this open took,
+					// and nothing can re-point it afterwards. It is what closes the A, B, A across the copy.
+					//
+					// The BY-PATH check after the copy says the name still resolves to the file the GATES judged.
+					// It is what the descriptor cannot say: every gate above ran by path, so a link planted after
+					// the first of those lstats has the whole ladder judge the attacker's files, and then the
+					// descriptor agrees with a `judged` that is already the attacker's. Dropping this check for
+					// one round reintroduced exactly that (measured: 2 attacker transcripts staged in 16,594
+					// resumes, where the by-path version staged none), and it is also what keeps the venue arm
+					// reachable: a promotion that wrote its `(pending)` sentinel and has not yet swapped moves no
+					// identity at all, so an identity-gated ladder never asks about it.
+					const swapped = () => {
+						const dirNow = inspectKeyDir(key);
+						return dirNow.reason === "key-not-a-directory"
+							? "key-not-a-directory"
+							: dirNow.ident !== judgedDir
+								? "transcript-replaced" // another REAL directory at the name: the gates judged its files
+								: readVenue(key) !== venue
+									? "venue-changed"
+									: readIdentity(canonicalFile(key)) !== judged
+										? "transcript-replaced"
+										: null;
+					};
+					// VENUE FIRST inside `swapped()`, as it has been since #277: a cross-venue promotion trips
+					// both and `venue-changed` names WHY where `transcript-replaced` only says something moved.
+					// The directory arm is ahead of both (issue #375), because a name that is not a directory is
+					// neither a venue move nor a swap.
+					const raced = opened !== judged ? (swapped() ?? "transcript-replaced") : null;
+					if (raced !== null) {
+						// A 0-byte staged file, the shape every cold start gets. If emptying fails, the catch
+						// below removes the staged directory rather than leave a copy behind.
+						fs.writeFileSync(staged, "");
+						verdict = COLD(raced);
+					} else {
+						copyFromDescriptor(fd, staged, verdict.bytes);
+						const after = swapped();
+						if (after !== null) {
+							fs.writeFileSync(staged, "");
+							verdict = COLD(after);
+						}
+					}
+				} finally {
+					if (fd !== null) fs.closeSync(fd);
+				}
 			} 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
@@ -154,10 +320,22 @@ export function makeSessionStore({
 				fs.writeFileSync(staged, "");
 			}
 			log("session_resolved", { key, resume: verdict.resume, reason: verdict.reason });
-			return { hostDir, key, modelId, ...verdict };
+			return { hostDir, key, modelId, venue, ...verdict };
 		} catch (err) {
 			// A history fault must never fail the prepare that asked.
 			log("session_store_failed", { phase: "resolve", reason: err?.message });
+			// `null` means NO MOUNT AND NOTHING WRITTEN, so make the second half true, best effort. A fault after
+			// the copy -- a partial copy, or the venue re-check failing to empty a transcript another venue just
+			// promoted (#277) -- would otherwise leave that file under the job dir, which is mounted `/job:ro`:
+			// no `/session`, but the transcript readable at `/job/session/current.jsonl` all the same.
+			if (hostDir !== null) {
+				try {
+					fs.rmSync(hostDir, { recursive: true, force: true });
+				} catch {
+					// If this fails too, the copy stays under the job dir, which the container mounts before
+					// teardown removes it. Two consecutive disk faults on one path; nothing further to try.
+				}
+			}
 			return null;
 		}
 	}
@@ -170,6 +348,88 @@ 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.
 	 */
+	/**
+	 * Take the per-key promotion lock, with ONE stale takeover. Returns `{ fd }`, or `{ locked: true }` when
+	 * a LIVE writer holds it. Throws only for non-EEXIST failures, which is the doctrine this call site
+	 * already carried: a read-only directory, a full disk or a vanished store all fail to create the lock
+	 * too, and reporting those as `locked` sends an operator hunting a stuck file that does not exist.
+	 *
+	 * WITHOUT THIS, A PROCESS KILLED INSIDE THE LOCK WEDGED THE KEY FOREVER (issue #336). Later promotions
+	 * reported `locked` until the reaper swept the key, and the reaper keys on the TRANSCRIPT's mtime: a key
+	 * whose first promotion died before any transcript landed had none to key on, and with
+	 * `PI_SESSIONS_TTL_DAYS=0` the reaper does not run at all. A takeover works in both of those, which is
+	 * why it is the primary fix and the reaper's own repair is the secondary one.
+	 *
+	 * `lstatSync`, never `statSync`. The injected `fs` deliberately carries no `statSync`, this module's
+	 * whole doctrine is lstat-in-a-key-directory, and a DANGLING link planted at this name throws ENOENT
+	 * under `stat` on every attempt, which is the same wedge in a different coat.
+	 *
+	 * TWO DIFFERENT CLOCKS, and the comparison is between them: `now()` is this process's, `mtimeMs` is the
+	 * FILESYSTEM's, which on a network mount is a server's. `OQ-031` already records two hosts sharing one
+	 * working tree as a live hazard, and a shared `PI_SESSIONS_DIR` is exactly that shape. Both signs of the
+	 * skew are bad, and differently. A server more than `LOCK_STALE_MS` BEHIND makes every live lock read as
+	 * stale, so the takeover fires on every attempt and the conceded double-take window stops being rare;
+	 * worse, `releaseLock` unlinks by PATH rather than by fd, so once A's lock is stolen A's release deletes
+	 * B's. A server AHEAD makes the difference negative, so a genuinely crashed writer's lock is NEVER
+	 * swept -- which is precisely today's behaviour, so under that skew this degrades to the status quo
+	 * rather than to something worse. Nothing here closes either; `triggers-file.mjs` states the same pair.
+	 */
+	function takeLock(dir, key) {
+		const lock = join(dir, LOCK_FILE);
+		let sweptAgeMs = null;
+		for (let attempt = 0; attempt < 2; attempt++) {
+			try {
+				const fd = fs.openSync(lock, "wx"); // exclusive create IS the lock; no daemon, no lease
+				// Logged only AFTER the retake create SUCCEEDED. The unlink alone proves nothing, since a rival
+				// sweeper can win the recreate race, and a takeover line for a lock we did not get would send an
+				// operator reading a history that never happened.
+				if (sweptAgeMs !== null) log("session_lock_stale_taken", { key, ageMs: sweptAgeMs });
+				return { fd };
+			} catch (err) {
+				if (err?.code !== "EEXIST") throw err;
+				let mtimeMs;
+				try {
+					mtimeMs = fs.lstatSync(lock).mtimeMs;
+				} catch {
+					// Released between our open and our stat: the next create answers.
+					continue;
+				}
+				if (now() - mtimeMs <= LOCK_STALE_MS) return { locked: true };
+				try {
+					fs.unlinkSync(lock);
+				} catch {
+					// Someone else swept it first; the retry create answers who won.
+				}
+				sweptAgeMs = Math.round(now() - mtimeMs);
+			}
+		}
+		return { locked: true };
+	}
+
+	/**
+	 * Make the key directory, or answer that the name is not one (issue #375). The write-side twin of
+	 * `inspectKeyDir`, separate because it CREATES: the read path must never make a directory for a key it is
+	 * only asking about.
+	 *
+	 * An lstat that fails with anything but ENOENT is re-thrown, which the outer catch reports as
+	 * `promote-failed`: a disk fault is not evidence about the shape of the name, and reporting it as one
+	 * would send an operator hunting a symlink that does not exist. That is `takeLock`'s doctrine one step
+	 * earlier.
+	 */
+	function ensureKeyDir(dir) {
+		let st = null;
+		try {
+			st = fs.lstatSync(dir);
+		} catch (err) {
+			if (err?.code !== "ENOENT") throw err;
+		}
+		if (st === null) {
+			fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+			st = fs.lstatSync(dir); // the second lstat: a link planted between the two is caught here
+		}
+		return st.isDirectory() ? `${st.dev}:${st.ino}` : 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
@@ -187,38 +447,150 @@ export function makeSessionStore({
 			}
 
 			const dir = keyDir(session.key);
-			fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+			// LSTAT BEFORE CREATE, and again after (issue #375). Recursive `mkdir` succeeds silently on an
+			// existing link to a directory, so asking it first and checking afterwards would accept exactly the
+			// shape this refuses; asking first means nothing already at the name is ever handed to `mkdir` at all,
+			// and the outcome does not depend on how `mkdir` treats a link, a file or a dangling link. Placed
+			// BEFORE `takeLock`, so a refused promotion never creates a lock file through a link either.
+			//
+			// The entry is NOT removed. It is not ours: this store creates key directories and nothing else, so
+			// whatever is sitting there was put there by an operator or by an attacker, and a sweep that deletes
+			// either is a worse answer than a refusal an operator can read. The key stays cold until they clear
+			// it, which is the loud direction.
+			const madeDir = ensureKeyDir(dir);
+			if (madeDir === null) {
+				log("session_promote_skipped", { key: session.key, reason: "key-not-a-directory" });
+				return { promoted: false, reason: "key-not-a-directory" };
+			}
+			// Is the key directory still the one `ensureKeyDir` made or found? SHAPE ALONE IS NOT ENOUGH, and
+			// the gate round proved it: a swap to another REAL directory passed a shape-only re-check and the
+			// promotion wrote the transcript and all four sidecars into it while reporting `promoted: true`.
+			const sameDir = () => inspectKeyDir(session.key).ident === madeDir;
 
 			const lock = join(dir, LOCK_FILE);
-			let fd;
-			try {
-				fd = fs.openSync(lock, "wx"); // exclusive create IS the lock; no daemon, no lease
-			} 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;
+			// `locked` still means a LIVE writer and nothing else. A lock older than any plausible promotion is
+			// taken over rather than believed (see `takeLock`); anything that is not EEXIST still falls through
+			// to the outer catch and reports `promote-failed`, which is what actually happened.
+			const taken = takeLock(dir, session.key);
+			if (taken.locked) {
 				log("session_promote_skipped", { key: session.key, reason: "locked" });
 				return { promoted: false, reason: "locked" };
 			}
+			const fd = taken.fd;
 			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.
+				// RE-CHECKED UNDER THE LOCK (issue #375's gate round). `ensureKeyDir` ran before the lock, so a
+				// link swapped in between the two would take every write below it outside the store: measured on
+				// the first draft, the transcript and all four sidecars landed in the attacker's directory and
+				// the promotion still reported `promoted: true`. Asking again here closes that segment, and
+				// costs one lstat on a path already in the page cache.
+				//
+				// It does NOT close the whole window, and the residual is stated rather than implied: a swap
+				// after THIS check still redirects the writes, because Node exposes no `openat`/`renameat` and
+				// every write below therefore resolves the name again. What the re-check after the swap does is
+				// make that case reportable rather than silent.
+				//
+				// What the refusal costs where the swap landed after the lock was taken: the lock file is in the
+				// REAL key and `releaseLock` unlinks by path, which now resolves elsewhere, so the real key keeps
+				// a lock nobody holds and the next promotions report `locked` until the staleness takeover sweeps
+				// it an hour later. That is the same unlink-by-path residual `takeLock` already states for a
+				// takeover, reached by a different route, and it is the honest cost of refusing here rather than
+				// writing into whatever the name now points at.
+				if (!sameDir()) {
+					log("session_promote_skipped", { key: session.key, reason: "key-not-a-directory" });
+					return { promoted: false, reason: "key-not-a-directory" };
 				}
+				// Atomic swap: a reader either sees the old file or the new one, never a half-written one.
+				// PER WRITER (see `tmpSeq`), not the fixed `.incoming` this shared before the lock could be taken
+				// over. The random half is what separates two writers; the pid and counter are there to make a
+				// straggler attributable, and neither is a writer identity on its own. The removal below stays
+				// regardless: a name that is hard to guess is not a name that cannot be guessed.
+				const tmp = `${canonicalFile(session.key)}.${process.pid}.${tmpSeq++}.${randomBytes(6).toString("hex")}.incoming`;
+				// `copyFileSync` follows a link at the DESTINATION, so anything left at this name would receive
+				// the whole transcript. `removeTemp` takes every shape; see its own comment for why one call
+				// could not.
+				removeTemp(tmp);
 				fs.copyFileSync(staged, tmp);
+				// THE VENUE STAMP IS INVALIDATED BEFORE THE SWAP, and fatally (#277). Removing a stamp does not
+				// invalidate it, because an absent stamp reads as `local`; stamping only after the rename would
+				// leave a window, and a failed post-swap write a permanent state, in which one venue's transcript
+				// sits under another venue's stamp and the next job there resumes it. So every promotion first
+				// writes a stamp no venue matches. If that write fails, nothing has been swapped and the outer
+				// catch reports `promote-failed`; if the process dies after it, the key cold-starts everywhere
+				// until a promotion completes. A process KILLED inside this lock also leaks the lock itself, as it
+				// always has -- but it no longer wedges the key in the shapes that used to be permanent: the next
+				// promotion takes a lock older than `LOCK_STALE_MS` over, and the reaper reaches a key with no
+				// transcript through the directory's own mtime (issue #336). A lock whose mtime is in the FUTURE is
+				// still never stale, so under `PI_SESSIONS_TTL_DAYS=0` such a key stays wedged. Unconditional rather than only
+				// on a venue change, so the decision needs no read of the stamp under the lock and there is no
+				// branch to get wrong.
+				replaceSidecar(dir, VENUE_FILE, VENUE_PENDING);
+				// The temp's identity, read BEFORE the rename, is what makes the A, B, A reportable (issue #390).
+				// `rename` preserves the inode, so after a rename that landed where it was meant to, the canonical
+				// name holds THIS file. If the directory was swapped for the rename and swapped back afterwards,
+				// the canonical name resolves into the real key again and holds its OLD transcript, or nothing --
+				// a different inode either way. That is a fact the shape re-check below cannot see, because by
+				// then the shape is right again.
+				const tmpIdent = readIdentity(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
+				// DETECTION for the segment prevention cannot reach (issue #375's gate round). A link swapped in
+				// after the check above takes this rename and every sidecar write with it, and the old code then
+				// reported `promoted: true` for a transcript that landed outside the store: the operator's record
+				// said the next run would resume work that is not there. This cannot undo the write, the bytes
+				// being already wherever the name pointed, and it catches such a swap only while it is STILL
+				// STANDING here.
+				if (!sameDir()) {
+					log("session_promote_skipped", { key: session.key, reason: "key-not-a-directory" });
+					return { promoted: false, reason: "key-not-a-directory" };
+				}
+				// AND THE A, B, A, which the check above cannot see because by then the shape is right again
+				// (issue #390). Measured with a deterministic probe before this existed: `{"promoted":true,
+				// "reason":"promoted"}` with the transcript in the attacker's directory and the real key holding
+				// only `pi-version`, `resume-chain` and `venue` -- the next job on that key cold-starts as
+				// `absent` while the record says the work was promoted, which is the silent no-op `CLAUDE.md`
+				// calls the worst outcome available. A 45 second unsynchronised live race did not hit the exact
+				// ordering (16,591 promotions, 3 refusals, 0 lies), so this is a deterministic-window finding
+				// rather than a frequent one, and its precondition is the one the whole store concedes: write
+				// access to `PI_SESSIONS_DIR`.
+				//
+				// DETECTION, NOT PREVENTION, like its neighbour: the bytes are already wherever the name pointed
+				// and nothing here can recall them. What it buys is that the RECORD stops claiming otherwise.
+				// A shape-only comparison would not do it -- the round that added the checks above proved a swap
+				// to another REAL directory passes one -- so this compares the inode the rename preserved.
+				if (tmpIdent === null || readIdentity(canonicalFile(session.key)) !== tmpIdent) {
+					log("session_promote_skipped", { key: session.key, reason: "transcript-diverted" });
+					return { promoted: false, reason: "transcript-diverted" };
+				}
+				// The real stamp FIRST of the post-swap writes, and the ordering is the contract. It is the only one
+				// whose absence MISATTRIBUTES rather than cold-starts: between the rename and this write the key reads
+				// `(pending)` and cold-starts on every venue, so every write placed ahead of it lengthens that window,
+				// and `pi-version`, the chain counter and the context reading all degrade to a cold start instead.
+				// (It used to be ordered ahead of the pi-version write because THAT write could throw. It no longer
+				// can, and the ordering that survives is this one.) A session with no venue (a DI seam) leaves the
+				// sentinel on purpose: no stamp is better than a guessed one.
+				const venue = normaliseVenue(session.venue);
+				if (venue !== null) writeSidecar(dir, VENUE_FILE, session.key, venue);
+				// THROUGH `writeSidecar` like every other sidecar (issue #336). It was the one plain write left, and
+				// it carried both halves of that exception: `writeFileSync` FOLLOWS a link, so a symlink planted at
+				// this name -- at a path anyone who knows the repository and the branch can compute -- turned a
+				// promotion into a truncating write of the link's target with the pi version as its payload; and it
+				// sat inside the try, so a failure AFTER the swap reported `promote-failed` for a promotion that had
+				// landed.
+				//
+				// A FAILED STAMP IS SAFE IN BOTH DIRECTIONS, which is why this one needs no sentinel of its own and
+				// the venue stamp does. With no prior stamp the next read gets `null` and cold-starts. With one, it
+				// survives beside the new transcript -- and it is still TRUE, because this job resumed only if that
+				// stamp already matched its own image's pi, and a job runs one image. The remaining case, a job that
+				// cold-started under a new pi and then failed this write, leaves the OLD version beside the new
+				// transcript, and the next job on that image reads a mismatch and cold-starts. Stale-but-true, or a
+				// cold start. Never a transcript resumed under a version that did not write it.
+				//
+				// `String(piVersion ?? "")` is load-bearing and must not be simplified to skipping the write: an empty
+				// file is refused by `readSidecar`'s own size check and reads as `null`, so a promotion that knows no
+				// version INVALIDATES the stamp. Skipping instead would leave a PREVIOUS version beside a transcript
+				// written by an unknown pi, and the next matching job would resume it.
+				writeSidecar(dir, PI_VERSION_FILE, session.key, String(piVersion ?? ""));
+				// The chain and context 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.
 				//
@@ -234,7 +606,8 @@ export function makeSessionStore({
 				try {
 					fs.unlinkSync(lock);
 				} catch {
-					// A leaked lock file wedges this key until the reaper sweeps it. Logged, never thrown.
+					// A lock left behind here is taken over by the next promotion once it is stale (`takeLock`).
+					// Logged, never thrown: the promotion itself succeeded.
 					log("session_lock_stuck", { key: session.key });
 				}
 			}
@@ -273,21 +646,59 @@ export function makeSessionStore({
 	 * 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);
+			replaceSidecar(dir, name, value);
 		} catch (err) {
 			log("session_sidecar_failed", { key, file: name, reason: err?.message });
 		}
 	}
 
+	/**
+	 * Remove whatever is at a temp path, whatever SHAPE it has, before anything writes there.
+	 *
+	 * ONE RULE BECAUSE CHOOSING BETWEEN THE TWO CALLS WAS GOT WRONG TWICE, in opposite directions.
+	 * `unlinkSync` alone cannot remove a DIRECTORY planted at the name, and at the venue sentinel -- the one
+	 * sidecar write that is fatal -- that wedged every promotion on the key forever. `rmSync` alone does not
+	 * remove a DANGLING SYMLINK: it resolves the path, finds nothing, and with `force` reports success while
+	 * leaving the link (measured, and it is the same measurement the reaper's removal note records further down
+	 * this file -- measured there for the reaper, and not carried here until it had cost a round). The next write then follows the surviving link and creates a file at its target, which
+	 * is the write-through-a-link hole this whole series exists to close, and if that target is unreachable
+	 * the write throws and the key is wedged again.
+	 *
+	 * So: `unlinkSync` first, which takes a file or a link INCLUDING a dangling one; then `rmSync` for the
+	 * one shape it cannot take. A directory is removed with its subtree, which is bounded to a temp name
+	 * inside the key directory and is the point rather than a side effect: nothing may be left at that name.
+	 */
+	function removeTemp(path) {
+		try {
+			fs.unlinkSync(path);
+			return;
+		} catch (err) {
+			if (err?.code === "ENOENT") return; // absent is the desired state
+		}
+		try {
+			fs.rmSync(path, { recursive: true, force: true });
+		} catch {
+			// Nothing further to try HERE, and the honest bound is worth stating: if both calls fail, anything
+			// left at the name is still there and the write that follows may go THROUGH it. The only way both
+			// fail is a key directory this process cannot write, and `takeLock`'s own exclusive create fails
+			// first in that state, so a promotion never reaches here with it -- which is why this is a bound
+			// rather than a hole.
+		}
+	}
+
+	/**
+	 * `writeSidecar`'s link-safe temp-and-rename, and it THROWS. For the one write whose failure must stop a
+	 * promotion rather than be logged past it: the venue sentinel, which runs before the swap (#277).
+	 */
+	function replaceSidecar(dir, name, value) {
+		const file = join(dir, name);
+		const tmp = `${file}.incoming`;
+		removeTemp(tmp);
+		fs.writeFileSync(tmp, value);
+		fs.renameSync(tmp, file);
+	}
+
 	/**
 	 * The context sidecar, whose three cases are all different.
 	 *
@@ -326,20 +737,138 @@ export function makeSessionStore({
 		return join(keyDir(key), SESSION_FILE_NAME);
 	}
 
+	/**
+	 * Copy an already-open transcript to `dest`, in bounded chunks, and never more than `bytes`.
+	 *
+	 * The source is a DESCRIPTOR rather than a path, which is the whole point (issue #375): the bytes a job
+	 * resumes must come off the same inode the gates judged, and any second resolution of the name is a second
+	 * chance for something else to be standing there. `copyFileSync` cannot take one, so this is the copy.
+	 *
+	 * BOUNDED BY THE JUDGED SIZE, not by what the file turns out to hold. `inspectFile` capped the size
+	 * against `PI_SESSION_MAX_BYTES` and the record reports that number, and a transcript still being written
+	 * grows between the two: measured on the first draft of this copy, a file growing under it staged 2,460,306
+	 * bytes against a 1,000,000 cap while the record said 306. Reading exactly what was judged makes the cap
+	 * and the record true again. A SHORT read is refused rather than truncated silently, because a transcript
+	 * cut off mid-line is a transcript pi will reject anyway. What REFUSES either case is the by-path identity
+	 * re-check in `resolveSession`, since a transcript that grew or shrank has an identity that moved; this
+	 * bound is what stops an unbounded append from being read at all, and it is deliberately not the thing
+	 * that decides the verdict. A short read therefore needs no flag of its own: the re-check has it.
+	 *
+	 * 64 KiB because it is one buffer per resume and a transcript is usually a few hundred KiB; the loop is
+	 * what keeps an uncapped `PI_SESSION_MAX_BYTES` from becoming a memory bound.
+	 *
+	 * THREE EQUIVALENT MUTANTS LIVE IN THIS FUNCTION, recorded so the next reader does not re-derive them
+	 * (issue #391), because the lines around them ARE pinned and the difference is not visible by reading:
+	 *
+	 *   - the buffer SIZING, `Math.min(64 * 1024, Math.max(1, bytes))` to a bare `64 * 1024`. The per-read
+	 *     clamp in the loop (`Math.min(buf.length, bytes - copied)`) is what bounds the read, so the sizing
+	 *     only decides how much memory a small file allocates.
+	 *   - the LOOP CONDITION, `copied < bytes` to `copied <= bytes`, for the same reason.
+	 *   - `Math.max(1, bytes)` to `bytes`, which is dead defensive code: `inspectFile` refuses a 0-byte
+	 *     transcript as `absent`, so `bytes === 0` never reaches this function at all. That unreachability
+	 *     is the thing a next reader is most likely to re-derive, which is why it is written down.
+	 *
+	 * All three were run against the whole suite and produce byte-identical staged output across transcript
+	 * sizes either side of 64 KiB. What is NOT equivalent, and IS pinned by a descriptor count: the close
+	 * below, the one in `resolveSession` that opened the descriptor this is handed, and the LOCK's close in
+	 * `promoteSession` -- each of which leaks one descriptor per resume or per promotion in a process
+	 * designed to run for weeks.
+	 */
+	function copyFromDescriptor(fd, dest, bytes) {
+		const buf = Buffer.allocUnsafe(Math.min(64 * 1024, Math.max(1, bytes)));
+		let out = null;
+		let copied = 0;
+		try {
+			out = fs.openSync(dest, "w");
+			while (copied < bytes) {
+				const read = fs.readSync(fd, buf, 0, Math.min(buf.length, bytes - copied), null);
+				if (read === 0) break;
+				fs.writeFileSync(out, buf.subarray(0, read));
+				copied += read;
+			}
+		} finally {
+			if (out !== null) fs.closeSync(out);
+		}
+	}
+
+	/**
+	 * Is the key's own name a real directory? `inspectFile`'s rule, one level up (issue #375).
+	 *
+	 * Every other read and write in here is an `lstat` on a name INSIDE the key directory, which is exactly
+	 * what a key directory that is ITSELF a symlink defeats: the link is the directory, so each of those
+	 * lstats resolves through it and every guarantee in this file lands wherever it points. Measured before
+	 * the fix: a link planted at the derived path made `resolveSession` return `resumed` from a transcript
+	 * outside the store, and `promoteSession` write `current.jsonl`, `pi-version`, `venue` and `resume-chain`
+	 * through it. `mkdirSync(dir, { recursive: true })` succeeds on an existing link to a directory, so
+	 * nothing on the write path noticed either.
+	 *
+	 * THE FINAL COMPONENT ONLY, deliberately. `PI_SESSIONS_DIR` and its ancestors may legitimately be links:
+	 * macOS's own temp root is `/var -> private/var`, and moving the whole store behind a link is a supported
+	 * layout. A `realpath` or an ancestor walk would refuse those, and would refuse every test fixture on
+	 * this platform. The name this checks is the DERIVED one, which is what an attacker who knows the
+	 * repository and the branch can precompute, and which nothing but this module should be creating.
+	 *
+	 * It answers the SHAPE only. It carried a `dev:ino` identity for the post-copy re-check in the first draft
+	 * of this change, and the gate round removed the need for it: the staged bytes now come off one descriptor
+	 * (see `resolveSession`), so a directory swapped under a job cannot change what that job reads, and there
+	 * is nothing left for a directory identity to protect.
+	 */
+	function inspectKeyDir(key) {
+		let st;
+		try {
+			st = fs.lstatSync(keyDir(key));
+		} catch {
+			// EVERY failure reads as `absent`, not only ENOENT, and that is this edge's posture rather than an
+			// oversight: `inspectFile` one level down has always done the same, and a read that cannot ask costs a
+			// job its history and nothing else. Its write-side twin `ensureKeyDir` takes the opposite trade
+			// deliberately, because a promotion that cannot ask must not report the key's SHAPE as the reason.
+			// The cost, stated: an unreadable store cold-starts silently, indistinguishable from a fresh key.
+			return { ok: false, reason: "absent" };
+		}
+		if (!st.isDirectory()) return { ok: false, reason: "key-not-a-directory" };
+		// `dev:ino` and NOTHING else. The file rule's `dev:ino:size:mtime` is wrong for a directory: both move
+		// on every entry a promotion creates inside the key (64 -> 96 -> 1376 bytes on APFS, measured), so a
+		// re-check built on it reports a race on every quiet run. BOTH edges compare this identity: the write
+		// edge against what `ensureKeyDir` made or found, the read edge against what the gates were computed
+		// from. Comparing the SHAPE alone on either edge lets a swap for another REAL directory through, which
+		// is how it was found on the write edge and, one round later, on this one.
+		return { ok: true, ident: `${st.dev}:${st.ino}` };
+	}
+
 	/** The read path, gate by gate. The FIRST miss wins and names itself. */
-	function readCanonical(key, piVersion, modelId) {
+	function readCanonical(key, piVersion, modelId, venue) {
+		// FIRST, because every gate below it is an lstat inside this directory and none of them can see that
+		// the directory is not one. A regular file or a link to one read as `absent` before this arm existed,
+		// through the ENOTDIR their inner lstat threw; they are now named for what they are.
+		const dirCheck = inspectKeyDir(key);
+		if (!dirCheck.ok) return COLD(dirCheck.reason);
+
+
 		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");
 
+		// The VENUE the transcript was written in (#277). Placed HERE, after the arms a venue move cannot cause
+		// -- a transcript that is absent, not a regular file, too large or past its TTL is all of those on every
+		// venue -- and AHEAD of both pi-version arms, because a venue move CAN cause those: image preflight is
+		// dispatched per venue, so another venue can report another pi or none. The first miss names itself,
+		// and before this arm a venue move named itself as a version change. Without it, a trigger moved
+		// between venues staged the old venue's transcript into the new venue's container with nothing refusing.
+		//
+		// FAILS CLOSED: a job whose venue cannot be resolved (a DI seam) never resumes, the pi-version gate's
+		// polarity. The token also covers a stamp left pending by an interrupted promotion and a stamp that is
+		// present but unreadable -- a misnaming stated rather than hidden, as `pi-version-changed` already does
+		// for an unreadable version stamp.
+		if (venue === null || readVenue(key) !== venue) return COLD("venue-changed");
+
 		// 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");
-		// Through the same guarded read as the two sidecars below it. This one predates them and was the
+		// Through the same guarded read as the other sidecars. 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);
@@ -425,7 +954,7 @@ export function makeSessionStore({
 			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 };
+		return { resume: true, reason: "resumed", bytes: check.bytes, ident: check.ident, dirIdent: dirCheck.ident };
 	}
 
 	/**
@@ -453,6 +982,25 @@ export function makeSessionStore({
 		}
 	}
 
+	/**
+	 * The venue stamped beside a key's transcript (#277).
+	 *
+	 * ABSENT and UNREADABLE are different answers, and conflating them either way is a defect. An absent stamp
+	 * is a transcript from before venues were recorded, which ran on `local`. A stamp that exists but cannot
+	 * be read -- not a regular file, empty, oversized, unreadable -- matches nothing (`null`), so the key
+	 * cold-starts. Absence is decided by `lstat` and ENOENT ALONE: `stat` or `existsSync` would follow a
+	 * DANGLING symlink planted at this name, report it absent, and resume a transcript as `local` on the
+	 * strength of a link that points nowhere. Any other `lstat` failure is not absence either.
+	 */
+	function readVenue(key) {
+		try {
+			fs.lstatSync(join(keyDir(key), VENUE_FILE));
+		} catch (err) {
+			return err?.code === "ENOENT" ? UNATTRIBUTED_BACKEND : null;
+		}
+		return readSidecar(key, VENUE_FILE);
+	}
+
 	/**
 	 * 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
@@ -493,6 +1041,33 @@ export function makeSessionStore({
 	 * (`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.
 	 */
+	/**
+	 * The canonical file's IDENTITY as one comparable token: device, inode, size, mtime.
+	 *
+	 * ONE STRING RATHER THAN FOUR FIELDS, so the comparison is one `!==` and there is no partial compare to
+	 * get wrong. `ino` is the field that does the work: a promotion renames a freshly created `.incoming`
+	 * file into place, so the inode behind the canonical path is a DIFFERENT one after every completed swap
+	 * -- including the A, B, A round trip whose venue stamp matches again, which is why this catches what the
+	 * venue re-check cannot. `dev` is what makes `ino` meaningful, since an inode number is unique per
+	 * device. `size` and `mtimeMs` narrow the inode-REUSE residual and nothing else: the swapped-away inode
+	 * is freed by its own rename and its number may be handed straight back to the next `.incoming` file.
+	 */
+	function identityOf(st) {
+		return `${st.dev}:${st.ino}:${st.size}:${st.mtimeMs}`;
+	}
+
+	/**
+	 * The identity now at a path, or `null` when there is nothing readable there -- which compares unequal to
+	 * every real identity, so a transcript that VANISHED between the gate and the re-check cold-starts too.
+	 */
+	function readIdentity(file) {
+		try {
+			return identityOf(fs.lstatSync(file));
+		} catch {
+			return null;
+		}
+	}
+
 	function inspectFile(file) {
 		let st;
 		try {
@@ -503,17 +1078,20 @@ export function makeSessionStore({
 		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 };
+		return { ok: true, bytes: st.size, mtimeMs: st.mtimeMs, ident: identityOf(st) };
 	}
 
 	/**
-	 * 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.
+	 * The DISK sweep: at boot, and on the retention timer thereafter (`PI_SWEEP_INTERVAL_HOURS`, issue
+	 * #292). 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, and safe to re-run --
+	 * it carries no state between calls.
 	 *
-	 * 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).
+	 * Age on disk is the smaller half. The gate that matters is the one in readCanonical, which runs at
+	 * OPEN, because a stale transcript is a live INPUT to a future job rather than debris. Until #292 that
+	 * gate was also carrying the disk half alone, since a worker that never restarts never re-swept
+	 * (OQ-007, RESOLVED).
 	 */
 	function reapSessions() {
 		if (!sessionsDir || ttlDays === 0) return;
@@ -522,19 +1100,66 @@ export function makeSessionStore({
 		try {
 			names = fs.readdirSync(sessionsDir);
 		} catch (err) {
-			log("session_reaper_skipped", { reason: err?.message });
+			log("session_reaper_skipped", { reason: scrubCredentials(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) {
+				// THE ENTRY ITSELF FIRST (issue #375), so nothing here is ever judged THROUGH a link. Before this,
+				// a link whose target held a transcript was judged on that target's mtime, and the link was
+				// removed once the target aged: the sweep's decision came from a file outside the store. Now only
+				// a real directory is a key on this path, on both edges, which is the same rule `resolveSession`
+				// and `promoteSession` now apply.
+				//
+				// `session_not_reaped`, NOT `session_reaper_skipped`. OQ-007's #337 amendment reserves the
+				// `*_reaper_skipped` names for what a pass could not establish, and says that giving an everyday
+				// verdict the fault's name puts an ordinary outcome into the grep an operator reads as trouble.
+				// This pass established exactly what this entry is and decided to leave it, which is a verdict.
+				const entry = fs.lstatSync(dir);
+				if (!entry.isDirectory()) {
+					log("session_not_reaped", { key: name, reason: "key-not-a-directory" });
+					continue;
+				}
+				let mtimeMs;
+				try {
+					mtimeMs = fs.lstatSync(join(dir, SESSION_FILE_NAME)).mtimeMs;
+				} catch (err) {
+					// ENOENT ALONE falls back to the DIRECTORY's own mtime (issue #336). A key whose first promotion
+					// died before any transcript landed has none to key on, so this loop used to log-and-skip it on
+					// every pass forever, and anything leaked inside it -- a lock, an in-flight copy -- outlived the
+					// store. A directory's mtime moves on every entry created or removed inside it, so a live key is
+					// refreshed by its own promotions and a dead one is stamped at whatever last touched it.
+					//
+					// ENOENT-ONLY rather than unconditional, and that is the whole safety of it: an EIO or an EACCES
+					// on the transcript is a disk fault, and a disk fault is not evidence that a key is old. Those
+					// keep today's log-and-skip.
+					if (err?.code !== "ENOENT") throw err;
+					const dst = entry; // the entry's own stat, already taken and already proven a directory
+					// The entry was already proven a real directory above (issue #375), so this arm is now only about
+					// a key that has no transcript yet, and `dst` is that same stat rather than a second one.
+					//
+					// What the removal below is and is not, measured rather than assumed, because the obvious reading
+					// is wrong: `rmSync(p, { recursive: true, force: true })` does NOT follow a symlink. On a link to
+					// a real directory it removes the LINK and leaves the target untouched, and on a dangling link it
+					// does nothing at all. So a link's TARGET was never at risk here even before this change; what
+					// has changed is that a link is no longer JUDGED, which it was whenever its target held a
+					// readable transcript -- the sweep's decision then came from a file outside the store entirely.
+					mtimeMs = dst.mtimeMs;
+				}
+				if (mtimeMs < cutoff) {
+					// ONE recursive remove, on the transcript's age where there is one and the directory's own where
+					// there is not (above). Removing the
+					// transcript first (so an absent stamp, which reads as `local`, can never sit beside a readable
+					// transcript mid-sweep) was tried under #277 and withdrawn: a remove that then failed transiently
+					// left the directory with no transcript, which this loop never looks at again, so a leaked lock
+					// in it wedged the key for good. The race it closed needs a promotion landing on an EXPIRED key
+					// during its own sweep on a deployment with a second venue; INT-SESSION-STORE-CONTRACT names it.
 					fs.rmSync(dir, { recursive: true, force: true });
 					log("reaped_session", { key: name });
 				}
 			} catch (err) {
-				log("session_reaper_skipped", { key: name, reason: err?.message });
+				log("session_reaper_skipped", { key: name, reason: scrubCredentials(err?.message) });
 			}
 		}
 	}