From 1ac673d737f8f39be8b6dfca580252b8f4525fe0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 13 Nov 2026 13:24:18 -0800 Subject: [PATCH 1/3] chore(quest): claim quest/m0/gate-ledger-compat.md Quest-Claim: ece40e4c52c8533c From 32b1b0e557f0630b32f7ac8fd5de85a5348c419f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 13 Nov 2026 13:45:46 -0800 Subject: [PATCH 2/3] fix(gate): keep each PID namespace's admissions in a ledger of its own A gate in its own PID namespace, such as a bwrap --unshare-pid sandbox sharing the home directory, could not see other gates' processes and dropped their admissions a minute after admission. The ledger path now names the namespace and a format version, and a running gate re-records a dropped admission on every sample with a warning. Co-Authored-By: Claude Opus 5.5 --- README.md | 9 +++-- quest/m0/gate-ledger-compat.md | 36 ------------------ src/cli/gate.ts | 68 +++++++++++++++++++++++++++------- test/gate.test.ts | 35 +++++++++++++++-- 4 files changed, 92 insertions(+), 56 deletions(-) delete mode 100644 quest/m0/gate-ledger-compat.md diff --git a/README.md b/README.md index 1028a651..e8f21f44 100644 --- a/README.md +++ b/README.md @@ -1210,10 +1210,13 @@ they kept every CPU busy. macOS, Windows, and Linux without a systemd user manager have no scope to measure, so the load average alone decides there. A user's admissions on one host are recorded under -`~/.cache/quest/admissions/`, whatever the caller's environment or -login session. The home directory comes from the user database, not `$HOME`; +`~/.cache/quest/admissions-v2/`, whatever the caller's environment or +login session. A gate judges whether another still runs by its process ID, so +on Linux each PID namespace, such as a sandbox's, keeps a ledger of its own, +named `-pid`, and its gates do not count the host's. A gate +that finds its running admission dropped records it again and warns. The home directory comes from the user database, not `$HOME`; an account missing from it, as in arbitrary-UID containers, uses -`/tmp/quest-/admissions/`, and refuses that directory unless only +`/tmp/quest-/admissions-v2/`, and refuses that directory unless only its UID can write it. Two kinds of command go ahead of the rest. `quest gate --quick ` waits diff --git a/quest/m0/gate-ledger-compat.md b/quest/m0/gate-ledger-compat.md deleted file mode 100644 index e74f9b9e..00000000 --- a/quest/m0/gate-ledger-compat.md +++ /dev/null @@ -1,36 +0,0 @@ -# [S] A gate never loses a running command's admission from the ledger - -## Goal - -Every gate on a host, whatever quest build runs it, keeps a running -command's admission in the shared ledger -(`~/.cache/quest/admissions/`) until the command ends, so other -gates keep counting its cores. - -## Plan - -Found while measuring [moq-dev/quest#673](https://github.com/moq-dev/quest/pull/673) -on the maintainer's host: one gated moq check, longer than a minute, failed -with `gate lost its admission ... from the ledger` while another session ran -a `quest-0.1.0` gate. That label does not identify the build: the dev -shell's `quest-pinned` reported 0.1.0 at every revision through 7fe97931 -(2026-11-08), and every pin since -e3b292b7 (2026-11-03) already keeps running admissions -(`running.has(admission)` in `src/cli/gate.ts`). So the cause is not yet -known; first reproduce it, such as with two current gates, or a current -gate beside the pinned one, each running a command over a minute. - -The loss is also silent when the dropped command's measured cores stay -constant: `measure` reads the ledger every sample but looks for its own -admission only when the cores change, so the -command finishes and the other gates undercount it the whole time. - -Decisions: - -- ✅ Keep this quest. Rejected: dropping it until the loss is seen again. -- ✅ Once the cause is known, version the ledger's path or format, so - builds that disagree never share one file. Rejected: bumping only - `quest-pinned`; deciding after the reproduction. -- ✅ A running gate that finds its admission missing re-records it with a - warning, checking on every sample, not only when the cores change. - Rejected: failing the command; carrying on silently. diff --git a/src/cli/gate.ts b/src/cli/gate.ts index 7ee4c2c5..74f2490e 100644 --- a/src/cli/gate.ts +++ b/src/cli/gate.ts @@ -10,6 +10,7 @@ import { lstatSync, mkdirSync, openSync, + readlinkSync, readdirSync, readFileSync, rmSync, @@ -227,19 +228,42 @@ export function accountHome(): string | null { } /** - * Every caller of one user on one host shares this directory, whatever its - * environment or login sessions. It is named for the host, since a home - * directory may be shared between machines. An account missing from the user - * database, as in arbitrary-UID containers, has no home of its own, so it - * shares one in `tmp` keyed by its UID. + * The Linux PID namespace this process runs in, such as a sandbox's own, or undefined elsewhere. + * A gate only sees the process IDs of its namespace, so it cannot tell whether a gate in another + * one still runs, and would drop that gate's admission a minute after it was admitted. + */ +export function pidNamespace(): string | undefined { + if (process.platform !== "linux") return undefined; + try { + return /^pid:\[(\d+)\]$/.exec(readlinkSync("/proc/self/ns/pid"))?.[1]; + } catch { + return undefined; + } +} + +/** + * The ledger's format version, part of its path, so builds whose ledgers disagree never share one. + * Bump it with any change to what an admission records or how a gate keeps one. + */ +export const LEDGER_VERSION = 2; + +/** + * Every caller of one user on one host and PID namespace shares this directory, whatever its + * environment or login sessions. It is named for the host, since a home directory may be shared + * between machines, and for the namespace, since a gate judges another's admission by its + * process ID (see `pidNamespace`). An account missing from the user database, as in arbitrary-UID + * containers, has no home of its own, so it shares one in `tmp` keyed by its UID. */ export function claimDirectory( home = accountHome(), host = hostname(), uid = process.getuid?.(), tmp = "/tmp", + namespace: string | null = pidNamespace() ?? null, ): string { - if (home !== null) return join(home, ".cache", "quest", "admissions", host); + const name = namespace === null ? host : `${host}-pid${namespace}`; + const ledger = `admissions-v${LEDGER_VERSION}`; + if (home !== null) return join(home, ".cache", "quest", ledger, name); // Other users can create this name first, so it must be a directory only this UID can write. const root = join(tmp, `quest-${uid}`); try { @@ -250,7 +274,7 @@ export function claimDirectory( const stat = lstatSync(root); if (!stat.isDirectory() || stat.uid !== uid || (stat.mode & 0o022) !== 0) throw new Error(`gate cannot trust ${root}: it must be a directory that only UID ${uid} can write`); - return join(root, "admissions", host); + return join(root, ledger, name); } /** A version cut short, as by power loss, is read as empty: its commands ended with the host. */ @@ -611,11 +635,17 @@ export async function admit( * SETTLE_MS, and keep its admission's `cores` at the most CPUs it kept busy over one sample in the * last RECENT_MS, rounded, so other callers count it at its busiest rather than at a lull. */ -export async function measure(host: Host, admission: { id: string; unit: string }, signal: AbortSignal) { +export async function measure( + host: Host, + admission: { id: string; unit: string }, + signal: AbortSignal, + lost?: (id: string) => void, +) { const samples: { at: number; cores: number }[] = []; // The command's scope starts with no CPU use, so a burst before the first sample still counts. let previous = { at: host.now(), usage: 0 }; - let recorded = 0; + // The admission as last read, to record again should another gate drop it. + let known: Admission = { id: admission.id, at: host.now(), pid: process.pid, start: processStart(process.pid) }; for (;;) { try { await host.sleep(SETTLE_MS, signal); @@ -632,11 +662,19 @@ export async function measure(host: Host, admission: { id: string; unit: string } while (samples.length > 0 && samples[0].at <= at - RECENT_MS) samples.shift(); const cores = Math.round(Math.max(0, ...samples.map((sample) => sample.cores))); - for (let ledger = host.ledger(); cores !== recorded; ledger = host.ledger()) { + // Checked every sample, so an admission another gate dropped counts again within one. + for (let ledger = host.ledger(); ; ledger = host.ledger()) { const mine = ledger.admissions.find(({ id }) => id === admission.id); - if (mine === undefined) throw new Error(`gate lost its admission ${admission.id} from the ledger`); - const updated = ledger.admissions.map((entry) => (entry === mine ? { ...mine, cores } : entry)); - if (host.publish(ledger, updated)) recorded = cores; + if (mine !== undefined) known = mine; + if (mine !== undefined && (mine.cores ?? 0) === cores) break; + const updated = + mine === undefined + ? [...ledger.admissions, { ...known, cores }] + : ledger.admissions.map((other) => (other === mine ? { ...mine, cores } : other)); + if (host.publish(ledger, updated)) { + if (mine === undefined) lost?.(admission.id); + break; + } } } } @@ -972,7 +1010,9 @@ async function gated( // Held as a value until the command ends, so a failure never goes unhandled meanwhile. const measuring = admitted !== undefined && unit !== undefined - ? measure(admitted.host, { id: admitted.id, unit }, stop.signal).then( + ? measure(admitted.host, { id: admitted.id, unit }, stop.signal, (id) => + process.stderr.write(`quest gate: recorded admission ${id} again after another gate dropped it\n`), + ).then( () => undefined, (error: unknown) => ({ error }), ) diff --git a/test/gate.test.ts b/test/gate.test.ts index e67a4d94..29db95a6 100644 --- a/test/gate.test.ts +++ b/test/gate.test.ts @@ -30,6 +30,7 @@ import { type Admission, type Host, hostLimits, + LEDGER_VERSION, linuxMemory, measure, type Owner, @@ -281,6 +282,31 @@ test("a gate records its command's burst before the first sample", async () => { expect(published).toEqual([`4 at ${SETTLE_MS}`, `0 at ${SETTLE_MS + RECENT_MS}`]); }); +test("a gate records its admission again once another gate drops it, even while its cores hold", async () => { + const state = { now: 0, load: 0, memory: Infinity }; + const host = testHost(tempDir(), state); + host.publish(host.ledger(), [{ id: "build", at: 0, ...me }]); + host.usage = () => 0; + const stop = new AbortController(); + let samples = 3; + host.sleep = async () => { + if (samples-- === 0) { + stop.abort(); + throw stop.signal.reason; + } + state.now += SETTLE_MS; + // Before the second sample, a gate in another PID namespace drops it as gone. + if (samples === 1) host.publish(host.ledger(), [{ id: "other", at: state.now, ...me }]); + }; + const lost: string[] = []; + await measure(host, { id: "build", unit: "quest-gate-build.scope" }, stop.signal, (id) => lost.push(id)); + expect(lost).toEqual(["build"]); + expect(host.ledger().admissions).toEqual([ + { id: "other", at: 2 * SETTLE_MS, ...me }, + { id: "build", at: 0, ...me, cores: 0 }, + ]); +}); + test("a priority caller waits for memory, never for load, even while a gated command runs", async () => { const directory = tempDir(); const state = { now: 0, load: 99, memory: 0 }; @@ -680,8 +706,11 @@ test("Linux memory reads the container cgroup mounted as the root", () => { test("every caller on this host shares one ledger, whatever its environment or sessions", () => { // A home directory shared between machines keeps each host's admissions apart. - expect(claimDirectory("/home/u", "a")).toBe(join("/home/u", ".cache", "quest", "admissions", "a")); + const ledger = `admissions-v${LEDGER_VERSION}`; + expect(claimDirectory("/home/u", "a", 1, "/tmp", null)).toBe(join("/home/u", ".cache", "quest", ledger, "a")); expect(claimDirectory("/home/u", "b")).not.toBe(claimDirectory("/home/u", "a")); + // So does a PID namespace, such as a sandbox's, whose gates cannot see the others' processes. + expect(claimDirectory("/home/u", "a", 1, "/tmp", "7")).toBe(join("/home/u", ".cache", "quest", ledger, "a-pid7")); // A login session's runtime directory comes and goes; an overridden HOME is still this // account. Runtimes may read both once at startup, so each caller is a new process. const gate = fileURLToPath(new URL("../src/cli/gate.ts", import.meta.url)); @@ -702,9 +731,9 @@ test.skipIf(process.platform === "win32")("an account without a home shares a pr const uid = process.getuid!(); const tmp = tempDir(); const root = join(tmp, `quest-${uid}`); - expect(claimDirectory(null, "a", uid, tmp)).toBe(join(root, "admissions", "a")); + expect(claimDirectory(null, "a", uid, tmp, null)).toBe(join(root, `admissions-v${LEDGER_VERSION}`, "a")); expect(statSync(root).mode & 0o777).toBe(0o700); - expect(claimDirectory(null, "a", uid, tmp)).toBe(join(root, "admissions", "a")); + expect(claimDirectory(null, "a", uid, tmp, null)).toBe(join(root, `admissions-v${LEDGER_VERSION}`, "a")); // Another user may create the name first, writable by them or owned by them. chmodSync(root, 0o777); expect(() => claimDirectory(null, "a", uid, tmp)).toThrow("only UID"); From c1024577f30ec4c3ca585edd5101f177b9c67821 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 13 Nov 2026 14:07:10 -0800 Subject: [PATCH 3/3] fix(gate): version the agents ledger with LEDGER_VERSION and rewrap README Co-Authored-By: Claude Opus 5.5 --- README.md | 10 ++++++---- src/cli/admission.ts | 3 ++- src/cli/gate.ts | 2 +- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e8f21f44..b5a47248 100644 --- a/README.md +++ b/README.md @@ -1214,10 +1214,12 @@ A user's admissions on one host are recorded under login session. A gate judges whether another still runs by its process ID, so on Linux each PID namespace, such as a sandbox's, keeps a ledger of its own, named `-pid`, and its gates do not count the host's. A gate -that finds its running admission dropped records it again and warns. The home directory comes from the user database, not `$HOME`; -an account missing from it, as in arbitrary-UID containers, uses -`/tmp/quest-/admissions-v2/`, and refuses that directory unless only -its UID can write it. +that finds its running admission dropped records it again and warns. The home +directory comes from the user database, not `$HOME`; an account missing from +it, as in arbitrary-UID containers, uses +`/tmp/quest-/admissions-v2/`, and refuses that directory unless +only its UID can write it. `quest agent` keeps its admissions beside them, in +`agents-v2/`. Two kinds of command go ahead of the rest. `quest gate --quick ` waits at most a minute, then starts the command whatever the host's load, memory, and diff --git a/src/cli/admission.ts b/src/cli/admission.ts index 4fc0d169..003ba463 100644 --- a/src/cli/admission.ts +++ b/src/cli/admission.ts @@ -7,6 +7,7 @@ import { type Admission, type Host, type Limits, + LEDGER_VERSION, SETTLE_MS, type Waiting, claimDirectory, @@ -82,7 +83,7 @@ export async function admit(deps: AdmissionDependencies, signal: AbortSignal, he } /** The agents' ledger of this host, beside the gate's. */ -const agentsDirectory = (gate: string) => join(dirname(dirname(gate)), "agents", basename(gate)); +const agentsDirectory = (gate: string) => join(dirname(dirname(gate)), `agents-v${LEDGER_VERSION}`, basename(gate)); /** The admission `quest agent` runs with: the host's own limits and ledgers. */ export function processAdmission(notice: (text: string) => void): AdmissionDependencies { diff --git a/src/cli/gate.ts b/src/cli/gate.ts index 74f2490e..ca6a8da2 100644 --- a/src/cli/gate.ts +++ b/src/cli/gate.ts @@ -242,7 +242,7 @@ export function pidNamespace(): string | undefined { } /** - * The ledger's format version, part of its path, so builds whose ledgers disagree never share one. + * The format version of the gate and agents ledgers, part of their paths, so builds whose ledgers disagree never share one. * Bump it with any change to what an admission records or how a gate keeps one. */ export const LEDGER_VERSION = 2;