Skip to content

Commit 3f02d56

Browse files
committed
fix(doctor): scope the node-modules probe to a local source checkout
The probe ran unconditionally from findProjectRoot(), so it fired in two contexts it cannot diagnose: - Packaged installs. Published packages ship neither pnpm-lock.yaml (not in the package.json `files` allowlist) nor an installed snapshot, so every end user's `doctor` gained a spurious node-modules line and a degraded overall status. - `--remote`, where the daemon's own root describes the server deployment rather than the caller's worktree, so the answer could not address #1963 at all. Whether a root is a source checkout is now decided by the presence of pnpm-lock.yaml itself rather than a heuristic about install location, and 'no-source-checkout' is a distinct result rather than a warning, so the packaged case cannot be represented as a defect. The probe returns undefined there and the route appends no check, matching how doctor already models an out-of-scope question (the device family is likewise absent under --remote). The fresh-worktree catch is preserved: a lockfile with no installed snapshot is still a hard failure. The check:affected preflight is unchanged in behavior. Route-level assertions cover all three contexts (source, packaged, remote); each was verified to fail against the pre-fix wiring.
1 parent 433d75f commit 3f02d56

8 files changed

Lines changed: 221 additions & 59 deletions

File tree

‎scripts/check-affected/run.test.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -262,7 +262,7 @@ test('runChecks fails fast on a stale install before running format or any other
262262
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
263263
execute,
264264
cwd: '.',
265-
checkLockfileSync: () => ({ inSync: false, reason: 'stale' }),
265+
checkLockfileSync: () => ({ status: 'out-of-sync', reason: 'stale' }),
266266
});
267267
assert.equal(code, 1);
268268
assert.deepEqual(executed, [], 'no check — including format — may run against a stale install');
@@ -281,13 +281,13 @@ test('runChecks fails fast when node_modules was never installed in this checkou
281281
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
282282
execute,
283283
cwd: '.',
284-
checkLockfileSync: () => ({ inSync: false, reason: 'install-missing' }),
284+
checkLockfileSync: () => ({ status: 'out-of-sync', reason: 'install-missing' }),
285285
});
286286
assert.equal(code, 1);
287287
assert.deepEqual(executed, []);
288288
});
289289

290-
test('runChecks does not block on a missing lockfile — that is a different failure than a stale install', async () => {
290+
test('runChecks does not block when there is no source checkout to compare against', async () => {
291291
const executed: string[][] = [];
292292
const execute: CommandExecutor = async (command) => {
293293
executed.push(command);
@@ -300,7 +300,7 @@ test('runChecks does not block on a missing lockfile — that is a different fai
300300
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
301301
execute,
302302
cwd: '.',
303-
checkLockfileSync: () => ({ inSync: false, reason: 'lockfile-missing' }),
303+
checkLockfileSync: () => ({ status: 'no-source-checkout' }),
304304
});
305305
assert.equal(code, 0);
306306
assert.ok(executed.length > 0, 'checks still run when there is nothing to compare against');
@@ -319,7 +319,7 @@ test('runChecks proceeds normally when the install is in sync', async () => {
319319
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
320320
execute,
321321
cwd: '.',
322-
checkLockfileSync: () => ({ inSync: true }),
322+
checkLockfileSync: () => ({ status: 'in-sync' }),
323323
});
324324
assert.equal(code, 0);
325325
assert.ok(executed.some((command) => command.includes('format:check')));
@@ -341,7 +341,7 @@ test('runChecks names the real cause on stderr instead of surfacing as an unrela
341341
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
342342
execute: async () => 0,
343343
cwd: '.',
344-
checkLockfileSync: () => ({ inSync: false, reason: 'stale' }),
344+
checkLockfileSync: () => ({ status: 'out-of-sync', reason: 'stale' }),
345345
});
346346
assert.equal(code, 1);
347347
assert.ok(

‎scripts/check-affected/run.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ export async function runChecks(
203203
// that look like real diffs/failures on files the change never touched. Naming the
204204
// real cause here means an agent never "fixes" formatting that was never wrong.
205205
const lockfileSync = checkLockfileSync(cwd);
206-
if (!lockfileSync.inSync && lockfileSync.reason !== 'lockfile-missing') {
206+
if (lockfileSync.status === 'out-of-sync') {
207207
reportStaleInstall(lockfileSync.reason);
208208
return 1;
209209
}

‎src/daemon/handlers/__tests__/session-doctor-node-modules.test.ts‎

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,9 @@ test('node-modules doctor check passes when the installed snapshot matches the c
2222
writeInstalledSnapshot(root, 'lockfileVersion: 9.0\n');
2323

2424
const check = nodeModulesLockfileCheck(root);
25-
assert.equal(check.id, 'node-modules');
26-
assert.equal(check.status, 'pass');
27-
assert.match(check.summary, /matches pnpm-lock\.yaml/);
25+
assert.equal(check?.id, 'node-modules');
26+
assert.equal(check?.status, 'pass');
27+
assert.match(check?.summary ?? '', /matches pnpm-lock\.yaml/);
2828
});
2929

3030
test('node-modules doctor check fails with the stale-install message when hashes disagree', () => {
@@ -33,34 +33,37 @@ test('node-modules doctor check fails with the stale-install message when hashes
3333
writeInstalledSnapshot(root, 'lockfileVersion: 9.0\n');
3434

3535
const check = nodeModulesLockfileCheck(root);
36-
assert.equal(check.status, 'fail');
37-
assert.equal(check.summary, STALE_NODE_MODULES_MESSAGE);
38-
assert.equal(check.command, 'pnpm install');
39-
assert.deepEqual(check.evidence, { repoRoot: root, reason: 'stale' });
36+
assert.equal(check?.status, 'fail');
37+
assert.equal(check?.summary, STALE_NODE_MODULES_MESSAGE);
38+
assert.equal(check?.command, 'pnpm install');
39+
assert.deepEqual(check?.evidence, { repoRoot: root, reason: 'stale' });
4040
});
4141

42-
test('node-modules doctor check fails with the stale-install message when node_modules was never installed here', () => {
42+
test('node-modules doctor check fails when a source checkout was never installed', () => {
4343
const root = mkdtempForTestSync('agent-device-doctor-node-modules-missing-install-');
4444
writeLockfile(root, 'lockfileVersion: 9.0\n');
4545

4646
const check = nodeModulesLockfileCheck(root);
47-
assert.equal(check.status, 'fail');
48-
assert.equal(check.summary, STALE_NODE_MODULES_MESSAGE);
49-
assert.deepEqual(check.evidence, { repoRoot: root, reason: 'install-missing' });
47+
assert.equal(check?.status, 'fail');
48+
assert.equal(check?.summary, STALE_NODE_MODULES_MESSAGE);
49+
assert.deepEqual(check?.evidence, { repoRoot: root, reason: 'install-missing' });
5050
});
5151

52-
test('node-modules doctor check stays informational when the checkout has no lockfile at all', () => {
53-
const root = mkdtempForTestSync('agent-device-doctor-node-modules-missing-lockfile-');
52+
test('node-modules doctor check is omitted entirely for a packaged install with no source checkout', () => {
53+
// The defect this guards: a published agent-device ships neither pnpm-lock.yaml nor an
54+
// installed snapshot, so an unconditional probe gave every end user a spurious
55+
// node-modules line and dragged the overall doctor status down with it.
56+
const root = mkdtempForTestSync('agent-device-doctor-node-modules-packaged-');
57+
fs.mkdirSync(path.join(root, 'dist'), { recursive: true });
58+
fs.writeFileSync(path.join(root, 'package.json'), '{"name":"agent-device"}\n');
5459

55-
const check = nodeModulesLockfileCheck(root);
56-
assert.equal(check.status, 'warn');
57-
assert.match(check.summary, /pnpm-lock\.yaml not found/);
60+
assert.equal(nodeModulesLockfileCheck(root), undefined);
5861
});
5962

6063
test("node-modules doctor check defaults to this checkout's own root, matching real doctor wiring", () => {
6164
// session-doctor.ts calls nodeModulesLockfileCheck() with no argument; this repo's own
6265
// install is expected to be in sync while the suite runs (pnpm install was run for it).
6366
const check = nodeModulesLockfileCheck();
64-
assert.equal(check.id, 'node-modules');
65-
assert.equal(check.status, 'pass');
67+
assert.equal(check?.id, 'node-modules');
68+
assert.equal(check?.status, 'pass');
6669
});

‎src/daemon/handlers/session-doctor-node-modules.ts‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,34 @@ import {
55
import { findProjectRoot } from '../../utils/version.ts';
66
import type { DoctorCheck } from '@agent-device/contracts/observability';
77

8-
export function nodeModulesLockfileCheck(repoRoot: string = findProjectRoot()): DoctorCheck {
8+
/**
9+
* The stale-install probe for #1963, scoped to what it can actually diagnose.
10+
*
11+
* Returns `undefined` — no check line at all — when the root holds no source checkout.
12+
* A published agent-device ships neither pnpm-lock.yaml nor an installed snapshot, so
13+
* every packaged `doctor` run would otherwise carry a lockfile line that means nothing
14+
* to an end user and would drag the overall status down with it. Doctor already models
15+
* an out-of-scope question as an absent check rather than an informational one: under
16+
* `--remote` the whole device-inventory family is omitted, and the route tests assert
17+
* that absence. This follows that vocabulary.
18+
*
19+
* The caller is responsible for the other scope gate: this must not run under `--remote`,
20+
* where the daemon's own root would describe the server's deployment rather than the
21+
* caller's worktree. session-doctor.ts enforces that by calling this only after the
22+
* remote branch has already returned.
23+
*/
24+
export function nodeModulesLockfileCheck(
25+
repoRoot: string = findProjectRoot(),
26+
): DoctorCheck | undefined {
927
const result = checkLockfileInstallSync(repoRoot);
10-
if (result.inSync) {
28+
if (result.status === 'no-source-checkout') return undefined;
29+
if (result.status === 'in-sync') {
1130
return {
1231
id: 'node-modules',
1332
status: 'pass',
1433
summary: 'node_modules matches pnpm-lock.yaml.',
1534
};
1635
}
17-
if (result.reason === 'lockfile-missing') {
18-
return {
19-
id: 'node-modules',
20-
status: 'warn',
21-
summary: 'pnpm-lock.yaml not found; cannot verify node_modules is in sync.',
22-
evidence: { repoRoot, reason: result.reason },
23-
};
24-
}
2536
return {
2637
id: 'node-modules',
2738
status: 'fail',

‎src/daemon/handlers/session-doctor.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,6 @@ export async function handleDoctorCommand(params: {
6666
summary: `agent-device ${readVersion()} using ${stateDir}`,
6767
evidence: { version: readVersion(), stateDir },
6868
},
69-
nodeModulesLockfileCheck(),
7069
...remoteConnectionChecks(req, { required: options.remote }),
7170
...sessionChecks(sessionStore, sessionName, session, { remote: options.remote }),
7271
);
@@ -75,6 +74,14 @@ export async function handleDoctorCommand(params: {
7574
return doctorResponse(checks, options);
7675
}
7776

77+
// Local-only from here down. The worktree/lockfile probe must stay below this
78+
// return: under --remote the daemon's own root describes the server deployment,
79+
// not the caller's checkout, so the answer could not address #1963 anyway. The
80+
// probe also returns undefined when there is no source checkout (a packaged
81+
// install), leaving no check line rather than a meaningless one.
82+
const nodeModules = nodeModulesLockfileCheck();
83+
if (nodeModules) appendDoctorCheck(checks, nodeModules);
84+
7885
const inventory = await appendDeviceInventoryCheck(checks, req, session);
7986
await appendToolchainChecks(checks, session?.device.platform ?? inventory?.platform);
8087
const appCheckDevice = await appendLocalDoctorChecks({

‎src/utils/lockfile-install-sync.test.ts‎

Lines changed: 31 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ test('reports in sync when the installed snapshot byte-matches the checked-out l
2020
writeLockfile(root, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
2121
writeInstalledSnapshot(root, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
2222

23-
assert.deepEqual(checkLockfileInstallSync(root), { inSync: true });
23+
assert.deepEqual(checkLockfileInstallSync(root), { status: 'in-sync' });
2424
});
2525

2626
test('reports stale when the installed snapshot content differs from the checked-out lockfile', () => {
@@ -31,31 +31,52 @@ test('reports stale when the installed snapshot content differs from the checked
3131
);
3232
writeInstalledSnapshot(root, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
3333

34-
assert.deepEqual(checkLockfileInstallSync(root), { inSync: false, reason: 'stale' });
34+
assert.deepEqual(checkLockfileInstallSync(root), { status: 'out-of-sync', reason: 'stale' });
3535
});
3636

37-
test('reports install-missing when node_modules/.pnpm/lock.yaml does not exist', () => {
37+
test('reports install-missing when a source checkout has no installed snapshot', () => {
3838
const root = mkdtempForTestSync('agent-device-lockfile-sync-no-install-');
3939
writeLockfile(root, 'lockfileVersion: 9.0\n');
4040

41-
assert.deepEqual(checkLockfileInstallSync(root), { inSync: false, reason: 'install-missing' });
41+
assert.deepEqual(checkLockfileInstallSync(root), {
42+
status: 'out-of-sync',
43+
reason: 'install-missing',
44+
});
4245
});
4346

4447
test('reports install-missing for a fresh worktree that has no node_modules directory at all', () => {
4548
const root = mkdtempForTestSync('agent-device-lockfile-sync-fresh-worktree-');
4649
writeLockfile(root, 'lockfileVersion: 9.0\n');
4750
// Deliberately no node_modules directory — the exact state of a brand new
48-
// `git worktree add`, before its first `pnpm install`.
51+
// `git worktree add`, before its first `pnpm install`. This must stay a real
52+
// finding: it is the resolve-to-main-checkout trap #1963 names.
4953
assert.equal(fs.existsSync(path.join(root, 'node_modules')), false);
5054

51-
assert.deepEqual(checkLockfileInstallSync(root), { inSync: false, reason: 'install-missing' });
55+
assert.deepEqual(checkLockfileInstallSync(root), {
56+
status: 'out-of-sync',
57+
reason: 'install-missing',
58+
});
5259
});
5360

54-
test('reports lockfile-missing when the checkout has no pnpm-lock.yaml', () => {
61+
test('reports no-source-checkout when there is no pnpm-lock.yaml — the packaged-install shape', () => {
62+
// A published agent-device: package.json `files` ships bin/ and dist/ but never the
63+
// lockfile, and an npm tarball never carries node_modules. Neither file is present,
64+
// and the answer must be "not applicable" rather than any kind of defect.
65+
const root = mkdtempForTestSync('agent-device-lockfile-sync-packaged-');
66+
fs.mkdirSync(path.join(root, 'dist'), { recursive: true });
67+
fs.writeFileSync(path.join(root, 'package.json'), '{"name":"agent-device"}\n');
68+
69+
assert.deepEqual(checkLockfileInstallSync(root), { status: 'no-source-checkout' });
70+
});
71+
72+
test('reports no-source-checkout even when a node_modules snapshot exists without a lockfile', () => {
73+
// The lockfile is the discriminator, not the snapshot: a consuming project could have
74+
// its own node_modules around the packaged install without that making our root a
75+
// source checkout to diagnose.
5576
const root = mkdtempForTestSync('agent-device-lockfile-sync-no-lockfile-');
5677
writeInstalledSnapshot(root, 'lockfileVersion: 9.0\n');
5778

58-
assert.deepEqual(checkLockfileInstallSync(root), { inSync: false, reason: 'lockfile-missing' });
79+
assert.deepEqual(checkLockfileInstallSync(root), { status: 'no-source-checkout' });
5980
});
6081

6182
test('is not fooled by two worktrees sharing the same repo but different lockfile states', () => {
@@ -71,6 +92,6 @@ test('is not fooled by two worktrees sharing the same repo but different lockfil
7192
);
7293
writeInstalledSnapshot(worktreeB, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
7394

74-
assert.deepEqual(checkLockfileInstallSync(worktreeA), { inSync: true });
75-
assert.deepEqual(checkLockfileInstallSync(worktreeB), { inSync: false, reason: 'stale' });
95+
assert.deepEqual(checkLockfileInstallSync(worktreeA), { status: 'in-sync' });
96+
assert.deepEqual(checkLockfileInstallSync(worktreeB), { status: 'out-of-sync', reason: 'stale' });
7697
});

‎src/utils/lockfile-install-sync.ts‎

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -20,38 +20,49 @@ export const STALE_NODE_MODULES_MESSAGE =
2020
'node_modules was installed from a different lockfile; run pnpm install';
2121

2222
export type LockfileInstallSyncResult =
23-
| { readonly inSync: true }
23+
// The root holds no pnpm-lock.yaml, so there is no source checkout here to diagnose.
24+
// A published agent-device install is exactly this: package.json `files` ships bin/,
25+
// dist/ and the helper artifacts, never the lockfile, and an npm tarball never carries
26+
// node_modules. Callers must treat this as "question does not apply", not as a defect
27+
// — reporting a stale install here would fire on every end user's packaged `doctor`.
28+
| { readonly status: 'no-source-checkout' }
29+
| { readonly status: 'in-sync' }
2430
| {
25-
readonly inSync: false;
26-
// 'lockfile-missing': no pnpm-lock.yaml in the checkout — a broken checkout, not a
27-
// stale install, but the caller has nothing to compare against either way.
28-
// 'install-missing': no node_modules/.pnpm/lock.yaml — never installed here, which
29-
// is exactly the "fresh worktree" trap: without its own install, module resolution
30-
// silently walks up to another checkout's node_modules.
31+
readonly status: 'out-of-sync';
32+
// 'install-missing': pnpm-lock.yaml is present but node_modules/.pnpm/lock.yaml is
33+
// not — a source checkout that was never installed, which is exactly the fresh-worktree
34+
// trap: without its own install, module resolution silently walks up to another
35+
// checkout's node_modules.
3136
// 'stale': both files exist but their contents (and therefore hashes) disagree —
3237
// node_modules was installed from a different pnpm-lock.yaml than the one checked out.
33-
readonly reason: 'lockfile-missing' | 'install-missing' | 'stale';
38+
readonly reason: 'install-missing' | 'stale';
3439
};
3540

3641
/**
3742
* Compares the lockfile a checkout's node_modules was installed from against the
3843
* lockfile currently checked out, using a content hash of each — no subprocess.
44+
*
45+
* Whether this is a source checkout at all is decided by the presence of
46+
* `pnpm-lock.yaml` under `repoRoot`, not by any heuristic about where the code was
47+
* installed from: the lockfile is committed in every worktree and shipped in no
48+
* published package, so its presence is the fact itself rather than a proxy for it.
49+
*
3950
* Works from any worktree: both paths are resolved under the given repoRoot, so a
4051
* worktree's own node_modules is checked against its own pnpm-lock.yaml, never another
4152
* checkout's.
4253
*/
4354
export function checkLockfileInstallSync(repoRoot: string): LockfileInstallSyncResult {
4455
const lockfileHash = hashFileIfExists(path.join(repoRoot, LOCKFILE_BASENAME));
45-
if (!lockfileHash) return { inSync: false, reason: 'lockfile-missing' };
56+
if (!lockfileHash) return { status: 'no-source-checkout' };
4657

4758
const installedSnapshotHash = hashFileIfExists(
4859
path.join(repoRoot, ...INSTALLED_SNAPSHOT_RELATIVE_PATH),
4960
);
50-
if (!installedSnapshotHash) return { inSync: false, reason: 'install-missing' };
61+
if (!installedSnapshotHash) return { status: 'out-of-sync', reason: 'install-missing' };
5162

5263
return lockfileHash === installedSnapshotHash
53-
? { inSync: true }
54-
: { inSync: false, reason: 'stale' };
64+
? { status: 'in-sync' }
65+
: { status: 'out-of-sync', reason: 'stale' };
5566
}
5667

5768
function hashFileIfExists(filePath: string): string | undefined {

0 commit comments

Comments
 (0)