Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
`<unit>: Consumed 1.386s CPU time over 1.357s wall clock time, 8.1M memory
peak.` to the user journal (`journalctl --user -u <unit>`) 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.
Expand Down
42 changes: 0 additions & 42 deletions quest/m0/benchmark/gate-record-cpu.md

This file was deleted.

8 changes: 5 additions & 3 deletions src/cli/gate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -925,16 +925,17 @@ 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(
{
kind: "gate",
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 },
Expand All @@ -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,
Expand Down
5 changes: 3 additions & 2 deletions src/cli/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -203,8 +203,9 @@ export function main(argv: string[], out: Output): number | Promise<number> {
"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 " +
Expand Down
22 changes: 16 additions & 6 deletions test/gate.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1544,26 +1544,34 @@ 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();
const [line, ...rest] = lines(file);
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 () => {
Expand Down Expand Up @@ -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");
Expand All @@ -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,
Expand Down
Loading