Skip to content

Commit 1628711

Browse files
thymikeeclaude
andcommitted
refactor(gate): run every host-locked command through runLockedCommand
Move the publish, activate, finish protocol and the signal-to-exit-code mapping into scripts/check-affected so validation runs and heavy gates share one owner. Restore the testing and pull-request rules that the previous revision dropped, and cover a signal that arrives while the locked command is running. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent 7f60f18 commit 1628711

10 files changed

Lines changed: 207 additions & 111 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,11 +48,11 @@ The versioned CLI help owns command semantics. To drive an app, start with the s
4848
- In a new worktree, run `pnpm install --frozen-lockfile && pnpm build` before you test.
4949
- Do not change other worktrees, devices, sessions, dirty files, or experiments. Do not use `git stash`; all worktrees share it.
5050
- Do not copy `.env` into a worktree. For host credentials, source the main checkout's file by its absolute path.
51-
- Give each parallel worker different files and a different device. `pnpm check:affected --run`, `pnpm check`, and heavy `pnpm gate` ids run one at a time automatically.
51+
- Give each parallel worker different files and a different device. `pnpm check:affected --run`, `pnpm check`, and heavy `pnpm gate` ids share one lock.
5252
- The layering scan reads only tracked files. Stage new modules before you trust its result.
5353
- When you rename a file, move its Fallow baseline entry. Do not regenerate unrelated baselines.
5454

55-
The validation lock reclaims provably dead owners. An unknown owner blocks.
55+
The validation lock automatically reclaims provably dead owners. An unknown owner continues to block.
5656
If the wait times out, report the printed owner and the lock state. Do not remove the lock manually.
5757

5858
## Agent docs

‎docs/agents/pull-requests.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Apply authorization already given. Merging and releasing need separate authoriza
1414
Follow [validation](testing.md).
1515
Record the `check:affected --run --head` receipt in the PR body. A serialized gate stage can validate the pushed head instead.
1616
For unresolved failures, follow the blocked-validation table.
17-
A blocker is not a pass.
17+
An authorized incomplete draft can record a blocker. A blocker is not a pass.
1818
Push once per review round. Each push restarts CI. Drafts skip device lanes.
1919

2020
For device-facing changes, follow [device verification](device-verification.md).

‎docs/agents/testing.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,10 @@
99

1010
Serialized validation requires macOS or Linux.
1111
On Windows, use plan mode or focused checks.
12-
Both broad commands acquire the same host lock.
13-
These `pnpm gate` ids acquire the same lock: `unit`, `unit-ci`, `provider-integration`, `fuzz-parsers`, `mutation`, `mutation-affected`, and `concurrency-torture`.
14-
A gate inside a locked validation reuses that lock. A GitHub runner takes no lock.
12+
Both broad commands and heavy `pnpm gate` ids acquire the same host lock.
1513
Wait for the owner to finish, or cancel your waiter with Ctrl-C.
16-
A wait ends after two hours. A nested `pnpm check` or `pnpm check:affected --run` fails immediately.
14+
Do not add lock wrappers. Do not delete lock files.
15+
A wait ends after two hours. Nested validation fails immediately.
1716
Focused tests do not lock. Avoid subprocess-heavy tests beside a broad gate.
1817

1918
The runner prints progress and a receipt path. The receipt contains:
@@ -35,6 +34,7 @@ Execution stops at the first failure. Unexecuted checks remain `not-run`.
3534

3635
Only a passed receipt with `exactCommit: true` proves validation at the named commit.
3736
A dirty-tree pass is local feedback. Detected checkout changes invalidate the run.
37+
Initial/final checks detect persistent changes. They do not sandbox the checkout.
3838
During validation, stop all edits.
3939

4040
## Interpret selection
@@ -45,6 +45,7 @@ A full selection for these changes is intentional.
4545
Read `failOpenReasons` in plan JSON or `plan.failOpenReasons` in a receipt.
4646
Do not reduce selection to get a pass.
4747

48+
Read required-check status on the PR.
4849
The receipt lists skipped checks and owners in `results[].reason`.
4950
GitHub owns:
5051

@@ -62,6 +63,7 @@ Do not add tests that assert prose.
6263
## A gate failed
6364

6465
Keep failure attribution separate from validation status.
66+
Never call a failing gate passed.
6567

6668
| Evidence | Next action | Outcome |
6769
| --- | --- | --- |

‎scripts/check-affected/command-execution.ts‎

Lines changed: 16 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
import fs from 'node:fs';
22
import path from 'node:path';
3-
import { runCmdStreaming } from '@agent-device/host-kit/command';
4-
import { VALIDATION_PARENT_ENV, type ValidationLock } from './host-lock.ts';
3+
import { runLockedCommand, type ValidationLock } from './host-lock.ts';
54
import type { CheckResult, ValidationRun } from './execution.ts';
65
import type { TestReport } from './test-report.ts';
76

@@ -25,42 +24,23 @@ export async function executeValidationCommand(
2524
() => run.report(`[running] ${result.id} ${Math.round((Date.now() - started) / 1000)}s`),
2625
15_000,
2726
);
28-
let commandPid: number | undefined;
2927
try {
30-
lock.recordCommand(run.receiptPath, null);
31-
const output = await runCmdStreaming(
32-
process.execPath,
33-
['--experimental-strip-types', path.join(import.meta.dirname, 'command.ts'), ...command],
34-
{
35-
cwd,
36-
allowFailure: true,
37-
captureOutput: false,
38-
detached: true,
39-
kill: { signal: 'SIGTERM', graceMs: 5000 },
40-
signal: run.controller.signal,
41-
stdin: 'run\n',
42-
onSpawn: (child) => {
43-
commandPid = child.pid;
44-
if (commandPid) lock.recordCommand(run.receiptPath, commandPid);
45-
},
46-
env: {
47-
...process.env,
48-
[VALIDATION_PARENT_ENV]: run.receiptPath,
49-
AGENT_DEVICE_VALIDATION_REPORT: reportPrefix,
50-
},
51-
onStdoutChunk: (chunk) => {
52-
fs.writeSync(descriptor, chunk);
53-
},
54-
onStderrChunk: (chunk) => {
55-
fs.writeSync(descriptor, chunk);
56-
},
28+
const exitCode = await runLockedCommand(lock, run.receiptPath, command, {
29+
cwd,
30+
env: { ...process.env, AGENT_DEVICE_VALIDATION_REPORT: reportPrefix },
31+
signal: run.controller.signal,
32+
onStdoutChunk: (chunk) => {
33+
fs.writeSync(descriptor, chunk);
5734
},
58-
);
59-
result.exitCode = output.exitCode;
60-
result.status = output.exitCode === 0 ? 'passed' : 'failed';
61-
run.report(`[${result.status}] ${result.id}; exit=${output.exitCode}`);
62-
if (output.exitCode !== 0) reportFailureTail(logPath, run.report);
63-
return output.exitCode;
35+
onStderrChunk: (chunk) => {
36+
fs.writeSync(descriptor, chunk);
37+
},
38+
});
39+
result.exitCode = exitCode;
40+
result.status = exitCode === 0 ? 'passed' : 'failed';
41+
run.report(`[${result.status}] ${result.id}; exit=${exitCode}`);
42+
if (exitCode !== 0) reportFailureTail(logPath, run.report);
43+
return exitCode;
6444
} catch (error) {
6545
result.status = run.controller.signal.aborted ? 'cancelled' : 'failed';
6646
result.reason = error instanceof Error ? error.message : String(error);
@@ -71,7 +51,6 @@ export async function executeValidationCommand(
7151
result.durationMs = Date.now() - started;
7252
collectTestReports(result, run.directory, reportPrefix);
7353
run.save();
74-
await lock.finishCommand(commandPid);
7554
}
7655
}
7756

‎scripts/check-affected/execution.ts‎

Lines changed: 3 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import fs from 'node:fs';
22
import path from 'node:path';
33
import { executeValidationCommand } from './command-execution.ts';
44
import { acquireValidationLock } from './host-lock.ts';
5+
import { abortOnTerminationSignal } from './termination.ts';
56
import { gitValue, readCheckoutState, type CheckoutState } from './checkout-state.ts';
67
import type { TestReport } from './test-report.ts';
78
import type { CheckId, CheckPlan } from './model.ts';
@@ -118,22 +119,7 @@ function openValidationRun(cwd: string, args: ValidationArgs) {
118119
const save = () => fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
119120
const report = (line: string) => process.stderr.write(`${line}\n`);
120121
const controller = new AbortController();
121-
const cancellation = { code: 0 };
122-
const interrupt = () => {
123-
cancellation.code = 130;
124-
controller.abort();
125-
};
126-
const terminate = () => {
127-
cancellation.code = 143;
128-
controller.abort();
129-
};
130-
const hangup = () => {
131-
cancellation.code = 129;
132-
controller.abort();
133-
};
134-
process.on('SIGHUP', hangup);
135-
process.on('SIGINT', interrupt);
136-
process.on('SIGTERM', terminate);
122+
const { cancellation, dispose } = abortOnTerminationSignal(controller);
137123
return {
138124
receipt,
139125
directory,
@@ -142,11 +128,7 @@ function openValidationRun(cwd: string, args: ValidationArgs) {
142128
cancellation,
143129
save,
144130
report,
145-
dispose: () => {
146-
process.off('SIGHUP', hangup);
147-
process.off('SIGINT', interrupt);
148-
process.off('SIGTERM', terminate);
149-
},
131+
dispose,
150132
};
151133
}
152134

‎scripts/check-affected/host-lock.test.ts‎

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import fs from 'node:fs';
33
import os from 'node:os';
44
import path from 'node:path';
55
import { test } from 'node:test';
6-
import { acquireValidationLock, VALIDATION_PARENT_ENV } from './host-lock.ts';
6+
import { acquireValidationLock, runLockedCommand, VALIDATION_PARENT_ENV } from './host-lock.ts';
77

88
test(
99
'host lock excludes a waiter, supports cancellation, then admits it after release',
@@ -72,3 +72,49 @@ test('unsupported hosts reject validation before writing lock state', async () =
7272
fs.rmSync(directory, { recursive: true, force: true });
7373
}
7474
});
75+
76+
test(
77+
'a locked command publishes ownership while it runs and clears it when it finishes',
78+
{ skip: process.platform === 'win32' },
79+
async () => {
80+
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'validation-run-'));
81+
const lock = path.join(directory, 'gate.lock');
82+
const activePath = `${lock}.active.json`;
83+
const env = { ...process.env };
84+
delete env[VALIDATION_PARENT_ENV];
85+
try {
86+
const owner = await acquireValidationLock(new AbortController().signal, lock, () => {}, env);
87+
const observed: string[] = [];
88+
const exitCode = await runLockedCommand(
89+
owner,
90+
'/fixture/receipt.json',
91+
[
92+
process.execPath,
93+
'-e',
94+
`process.stdout.write(process.env.${VALIDATION_PARENT_ENV}); process.exit(3)`,
95+
],
96+
{
97+
cwd: directory,
98+
env,
99+
signal: new AbortController().signal,
100+
onStdoutChunk: (chunk) => {
101+
const active = JSON.parse(fs.readFileSync(activePath, 'utf8')) as {
102+
receipt: string;
103+
pid: number;
104+
activation: string;
105+
};
106+
observed.push(chunk, active.receipt, active.activation);
107+
assert.ok(active.pid > 0);
108+
},
109+
onStderrChunk: () => {},
110+
},
111+
);
112+
assert.equal(exitCode, 3);
113+
assert.deepEqual(observed, ['/fixture/receipt.json', '/fixture/receipt.json', 'stdin']);
114+
assert.equal(fs.existsSync(activePath), false);
115+
await owner.release();
116+
} finally {
117+
fs.rmSync(directory, { recursive: true, force: true });
118+
}
119+
},
120+
);

‎scripts/check-affected/host-lock.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import fs from 'node:fs';
22
import os from 'node:os';
33
import path from 'node:path';
44
import { setTimeout } from 'node:timers/promises';
5+
import { runCmdStreaming } from '@agent-device/host-kit/command';
56
import {
67
publishFileSync,
78
inspectProcessLock,
@@ -17,6 +18,7 @@ import {
1718
} from '@agent-device/host-kit/process';
1819

1920
export const VALIDATION_PARENT_ENV = 'AGENT_DEVICE_VALIDATION_PARENT';
21+
const COMMAND_RUNNER = path.join(import.meta.dirname, 'command.ts');
2022
const HOST_LOCK_PATH = path.join(os.homedir(), '.cache', 'agent-device', 'validation.lock');
2123

2224
export type ValidationLock = {
@@ -71,6 +73,49 @@ export async function acquireValidationLock(
7173
}
7274
}
7375

76+
// Owns the order orphan reclaim depends on: publish ownership, activate the command, then finish.
77+
export async function runLockedCommand(
78+
lock: ValidationLock,
79+
receipt: string,
80+
command: readonly string[],
81+
options: {
82+
cwd: string;
83+
env: NodeJS.ProcessEnv;
84+
signal: AbortSignal;
85+
onStdoutChunk: (chunk: string) => void;
86+
onStderrChunk: (chunk: string) => void;
87+
},
88+
): Promise<number> {
89+
const [executable, ...args] = command as [string, ...string[]];
90+
let commandPid: number | undefined;
91+
try {
92+
lock.recordCommand(receipt, null);
93+
const output = await runCmdStreaming(
94+
process.execPath,
95+
['--experimental-strip-types', COMMAND_RUNNER, executable, ...args],
96+
{
97+
cwd: options.cwd,
98+
allowFailure: true,
99+
captureOutput: false,
100+
detached: true,
101+
kill: { signal: 'SIGTERM', graceMs: 5000 },
102+
signal: options.signal,
103+
stdin: 'run\n',
104+
onSpawn: (child) => {
105+
commandPid = child.pid;
106+
if (commandPid) lock.recordCommand(receipt, commandPid);
107+
},
108+
env: { ...options.env, [VALIDATION_PARENT_ENV]: receipt },
109+
onStdoutChunk: options.onStdoutChunk,
110+
onStderrChunk: options.onStderrChunk,
111+
},
112+
);
113+
return output.exitCode;
114+
} finally {
115+
await lock.finishCommand(commandPid);
116+
}
117+
}
118+
74119
function recordValidationCommand(lockDirPath: string, receipt: string, pid: number | null): void {
75120
publishFileSync({
76121
destination: `${lockDirPath}.active.json`,
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
const SIGNAL_EXIT_CODES = { SIGHUP: 129, SIGINT: 130, SIGTERM: 143 } as const;
2+
3+
// Aborts the controller on a termination signal and records the conventional shell exit code.
4+
export function abortOnTerminationSignal(controller: AbortController): {
5+
cancellation: { code: number };
6+
dispose: () => void;
7+
} {
8+
const cancellation = { code: 0 };
9+
const handlers = (Object.keys(SIGNAL_EXIT_CODES) as (keyof typeof SIGNAL_EXIT_CODES)[]).map(
10+
(signal) =>
11+
[
12+
signal,
13+
() => {
14+
cancellation.code = SIGNAL_EXIT_CODES[signal];
15+
controller.abort();
16+
},
17+
] as const,
18+
);
19+
for (const [signal, handler] of handlers) process.on(signal, handler);
20+
return {
21+
cancellation,
22+
dispose: () => {
23+
for (const [signal, handler] of handlers) process.off(signal, handler);
24+
},
25+
};
26+
}

‎scripts/gate/host-locked.test.ts‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ import { executeGate, requiresHostLock } from './host-locked.ts';
1111

1212
const skip = process.platform === 'win32';
1313
const cleanEnv = (extra: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv => {
14-
const env = { ...process.env, ...extra };
14+
const env = { ...process.env };
1515
delete env[VALIDATION_PARENT_ENV];
1616
delete env.GITHUB_ACTIONS;
1717
return { ...env, ...extra };
@@ -214,3 +214,43 @@ test(
214214
}
215215
},
216216
);
217+
218+
test(
219+
'a signal while the locked command runs stops it and still releases the lock',
220+
{ skip },
221+
async () => {
222+
const { lockDirPath, marker, cleanup } = fixture();
223+
try {
224+
const running = executeGate({
225+
id: 'unit-ci',
226+
command: [
227+
process.execPath,
228+
'-e',
229+
`require('node:fs').writeFileSync(${JSON.stringify(marker)}, String(process.pid)); setInterval(() => {}, 1000)`,
230+
],
231+
cwd: process.cwd(),
232+
env: cleanEnv(),
233+
lockDirPath,
234+
});
235+
await new Promise<void>((resolve) => {
236+
const poll = setInterval(() => {
237+
if (fs.existsSync(marker) && fs.readFileSync(marker, 'utf8')) {
238+
clearInterval(poll);
239+
resolve();
240+
}
241+
}, 20);
242+
});
243+
assert.ok(
244+
fs.existsSync(`${lockDirPath}.active.json`),
245+
'ownership is published while running',
246+
);
247+
process.emit('SIGTERM');
248+
assert.equal(await running, 143);
249+
assert.throws(() => process.kill(Number(fs.readFileSync(marker, 'utf8')), 0), /ESRCH/);
250+
assert.equal(fs.existsSync(lockDirPath), false, 'gate must release the lock');
251+
assert.equal(fs.existsSync(`${lockDirPath}.active.json`), false);
252+
} finally {
253+
cleanup();
254+
}
255+
},
256+
);

0 commit comments

Comments
 (0)