From 0020681468d59ecf8e39710806eded46dc8b78c0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 02:06:12 -0800 Subject: [PATCH 1/2] chore(quest): claim quest/m0/benchmark/gate-record-cpu.md Quest-Claim: 17818385a9cc39bc From d89c18eefacdc9d3c7732d5100fe85ffe5d68427 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 02:08:06 -0800 Subject: [PATCH 2/2] feat(gate): carry each run's CPU and end time in the QUEST_GATE_RECORD line Co-Authored-By: Claude Sonnet 5.5 --- README.md | 14 ++++++--- quest/m0/benchmark/gate-record-cpu.md | 42 --------------------------- src/cli/gate.ts | 8 +++-- src/cli/main.ts | 5 ++-- test/gate.test.ts | 22 ++++++++++---- 5 files changed, 34 insertions(+), 57 deletions(-) delete mode 100644 quest/m0/benchmark/gate-record-cpu.md diff --git a/README.md b/README.md index d930cb7f..20b0c24b 100644 --- a/README.md +++ b/README.md @@ -1318,17 +1318,23 @@ run on Linux or macOS, including those the agent's parallel shells and subagents start, then appends one JSON line to that file, however the run ends: ```json -{"command":["cargo","test"],"directory":"/home/me/src/app","started":"2026-11-12T19:40:01.120Z","admitted":"2026-11-12T19:40:31.452Z","unit":"quest-gate-0d6c3f9e-5a51-4c1b-9d0e-2f4b8a7c6e10.scope","exit":0,"cancelled":false,"error":null} +{"command":["cargo","test"],"directory":"/home/me/src/app","started":"2026-11-12T19:40:01.120Z","admitted":"2026-11-12T19:40:31.452Z","ended":"2026-11-12T19:41:02.810Z","cpu":58210,"unit":"quest-gate-0d6c3f9e-5a51-4c1b-9d0e-2f4b8a7c6e10.scope","exit":0,"cancelled":false,"error":null} ``` -- `started` and `admitted` give the wait. A run cancelled before admission has - a null `admitted`. +- `started`, `admitted`, and `ended` give the wait (`admitted` minus `started`) + and the wall time (`ended` minus `admitted`). A run cancelled before + admission has a null `admitted`; `ended` is set however the run ends. +- `cpu` is the CPU milliseconds the command and its descendants used, read from + its scope's `cpu.stat` as the wait log's is. It is null where the gate owns + the command only as a process group, such as on macOS, and for a run that + never ran. - `unit` is the command's systemd user scope, null where the gate owns it another way, such as on macOS. Once the scope ends, systemd logs `: Consumed 1.386s CPU time over 1.357s wall clock time, 8.1M memory peak.` to the user journal (`journalctl --user -u `) at info level when the scope used a notable amount, such as a second of CPU, and at debug level - otherwise. The memory peak needs systemd 255 and Linux 5.19. + otherwise. The journal still holds the memory peak, which needs systemd 255 + and Linux 5.19. - `exit` is the status the gate returns, `cancelled` whether it was cancelled, and `error` the gate's own failure, such as a scope it cannot confirm stopped. diff --git a/quest/m0/benchmark/gate-record-cpu.md b/quest/m0/benchmark/gate-record-cpu.md deleted file mode 100644 index 8e8db620..00000000 --- a/quest/m0/benchmark/gate-record-cpu.md +++ /dev/null @@ -1,42 +0,0 @@ -# [XS] The gate record carries each run's CPU and end time - -## Goal - -Each `QUEST_GATE_RECORD` line also carries the run's CPU and when it -ended, so a reader such as Kixel Quest's job page -([kixel-ai/kixel.quest](https://github.com/kixel-ai/kixel.quest)'s -`quest/m1/jobs.md`) gets a gated command's wait, CPU, and wall time from -the record alone, without joining its `unit` to the systemd journal. - -Non-goals: CPU where the gate owns the command only as a process group, -such as on macOS, which stays null as in the wait log; peak memory, which -stays in the journal; and Windows, which still refuses the variable. - -## Plan - -Decided 2026-11-15 (maintainer, `/quest-complete` of -[kixel-ai/kixel.quest#56](https://github.com/kixel-ai/kixel.quest/pull/56), -then `/quest-plan`): ✅ Linux, reusing the measurement -`measuredRun` in `src/cli/supervise.ts` makes (rejected: also a -reaped-children lower bound on process-group gates, which means rewriting -the group owner for a macOS host that has not arrived; no quest, with the -job page reading the `gated` list from uploaded session records, which -arrive only after a session sends them). - -This reverses part of the 2026-11-13 decision in -[moq-dev/quest#685](https://github.com/moq-dev/quest/pull/685), which -kept in-gate CPU measurement out of the record for its ~470 lines. Gating -measures each outermost run's CPU from its scope's `cpu.stat` for the wait -log anyway, so the record takes the same values rather than measuring -again. - -Agent's choices, for the implementer to revisit: - -- Add `ended` (ISO timestamp, set however the run ends, a run cancelled - in the queue included, as the wait log's `end` is) and `cpu` in - milliseconds (null where the wait log's is, and for a run that never - ran). `ended` follows the record's `started` and `admitted` rather than - the wait log's `end`; `cpu` and its unit match the wait log's. -- Keep `unit`, which still names the scope's journal line for peak memory. -- Update the README's "Record each run" section to say where CPU and wall - time come from. diff --git a/src/cli/gate.ts b/src/cli/gate.ts index c96b0753..204a3f17 100644 --- a/src/cli/gate.ts +++ b/src/cli/gate.ts @@ -925,8 +925,9 @@ export async function gate(command: string[], options: GateOptions = {}): Promis // The status the CLI exits with for a gate's own failure. status = 1; } + const iso = (ms: number) => new Date(ms).toISOString(); + const ended = iso(Date.now()); if (waits) { - const iso = (ms: number) => new Date(ms).toISOString(); try { logWait( { @@ -934,7 +935,7 @@ export async function gate(command: string[], options: GateOptions = {}): Promis command: argvName(command, runs(process.env, directory)), start: iso(started), admitted: observed.admitted === undefined ? null : iso(observed.admitted), - end: iso(Date.now()), + end: ended, cpu: observed.cpu ?? null, }, { cwd: directory }, @@ -952,13 +953,14 @@ export async function gate(command: string[], options: GateOptions = {}): Promis if (failure !== undefined) throw failure; return status; } - const iso = (ms: number) => new Date(ms).toISOString(); const line = Buffer.from( `${JSON.stringify({ command, directory, started: iso(started), admitted: observed.admitted === undefined ? null : iso(observed.admitted), + ended, + cpu: observed.cpu ?? null, unit: observed.unit ?? null, exit: status, cancelled: cancel.signal.aborted, diff --git a/src/cli/main.ts b/src/cli/main.ts index 61d1a789..d3824367 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -203,8 +203,9 @@ export function main(argv: string[], out: Output): number | Promise { "kill-on-close Job Object. Exits with the command's status, or 128 plus the signal's number once " + "cancelled.\n\n" + "With QUEST_GATE_RECORD naming an absolute path, an outermost gate on Linux or macOS appends one JSON " + - "line per run to that file, however the run ends: its command, directory, when it started and was " + - "admitted, its systemd scope, whose journal holds its CPU time and peak memory, and its exit status. " + + "line per run to that file, however the run ends: its command, directory, when it started, was " + + "admitted, and ended, its CPU milliseconds (null without a systemd scope), its systemd scope, whose " + + "journal holds its peak memory, and its exit status. " + "A file it cannot write fails the gate.\n\n" + "In an agent session, where CLAUDE_CODE_SESSION_ID or CODEX_THREAD_ID is set, an outermost gate also logs " + "its time queued and running under $XDG_STATE_HOME/quest/waits for the session's record; a log it cannot " + diff --git a/test/gate.test.ts b/test/gate.test.ts index 7b9dcd32..f0bcccbe 100644 --- a/test/gate.test.ts +++ b/test/gate.test.ts @@ -1544,13 +1544,17 @@ describe.skipIf(process.platform === "win32")("the run record", () => { (process.listeners(name).at(-1) as () => void)(); } - test("an outermost run appends one line with its wait, scope, and exit", async () => { + test("an outermost run appends one line with its wait, end, CPU, scope, and exit", async () => { const dir = tempDir(); const file = join(dir, "record.jsonl"); const cgroup = join(dir, "cgroup"); outermost(file); const scoped = owner(process.env).unit !== undefined; - const command = ["/bin/sh", "-c", `cat /proc/self/cgroup > ${quote(cgroup)} 2>/dev/null; exit 3`]; + const command = [ + "/bin/sh", + "-c", + `cat /proc/self/cgroup > ${quote(cgroup)} 2>/dev/null; i=0; while [ $i -lt 20000 ]; do i=$((i+1)); done; exit 3`, + ]; const before = Date.now(); expect(await gate(command, { host: ledger() })).toBe(3); const after = Date.now(); @@ -1558,12 +1562,16 @@ describe.skipIf(process.platform === "win32")("the run record", () => { expect(rest).toEqual([]); expect(statSync(file).mode & 0o777).toBe(0o600); expect(line).toMatchObject({ command, directory: process.cwd(), exit: 3, cancelled: false, error: null }); - const times = [before, Date.parse(line.started), Date.parse(line.admitted), after]; + const times = [before, Date.parse(line.started), Date.parse(line.admitted), Date.parse(line.ended), after]; expect(times).toEqual([...times].sort((a, b) => a - b)); // The unit names the scope the command actually ran in, so a reader can find its journal lines. - if (scoped) + if (scoped) { expect(readFileSync(cgroup, "utf8").trim()).toMatch(new RegExp(`/${line.unit.replaceAll(".", "\\.")}$`)); - else expect(line.unit).toBeNull(); + expect(line.cpu).toBeGreaterThan(0); + } else { + expect(line.unit).toBeNull(); + expect(line.cpu).toBeNull(); + } }); test("in an agent session, an outermost run logs its command, wait, run, and CPU for the session's record", async () => { @@ -1604,7 +1612,7 @@ describe.skipIf(process.platform === "win32")("the run record", () => { expect(readdirSync(dir)).toEqual([]); }); - test("a run cancelled while queued is recorded with no admission or scope", async () => { + test("a run cancelled while queued is recorded with no admission, CPU, or scope", async () => { const dir = tempDir(); const file = join(dir, "record.jsonl"); const ran = join(dir, "ran"); @@ -1618,6 +1626,8 @@ describe.skipIf(process.platform === "win32")("the run record", () => { expect(lines(file)).toEqual([ expect.objectContaining({ admitted: null, + ended: expect.any(String), + cpu: null, unit: null, exit: 128 + constants.signals.SIGHUP, cancelled: true,