Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
f09fe48
feat: discover ~/.codex/worktrees and a weekly home folder scan as re…
janicduplessis Nov 15, 2026
5add18c
chore: record the discovered checkout reduceOnly field in the API report
janicduplessis Nov 15, 2026
1153971
fix: the discovery scan trigger reads the tick disk level and a scan …
janicduplessis Nov 15, 2026
9a0630f
feat: the home folder scan enters home dot-folders except named tool …
janicduplessis Nov 15, 2026
0f08652
fix: revalidate cached scan finds, persist the scan schedule, run the…
janicduplessis Nov 15, 2026
e2e8a86
fix: scan finds under home dot-folders are recorded and never acted o…
janicduplessis Nov 15, 2026
b6de5cf
fix: consult PATH launchers only for reduce-only checkouts
janicduplessis Nov 15, 2026
6a9fc02
Merge remote-tracking branch 'origin/main' into feat/5762-discovery-t…
janicduplessis Nov 15, 2026
79ebfb7
fix: every output, dependency and Cargo route keeps a reduce-only che…
janicduplessis Nov 15, 2026
ec0b77a
test: a PATH launcher keeps a reduce-only checkout through the artifa…
janicduplessis Nov 15, 2026
b8df58d
test: use test.skipIf for the unreadable launcher directory case
janicduplessis Nov 15, 2026
60fdb10
fix: read launchers anew before each deletion, check a Cargo target a…
janicduplessis Nov 15, 2026
ee888f6
fix: read launchers with the process evidence at every deletion, trim…
janicduplessis Nov 15, 2026
3b03132
fix: make the reduce-only flag a required argument on every launcher …
janicduplessis Nov 15, 2026
a64b277
fix: prove project detection cannot block before the scan or revalida…
janicduplessis Nov 15, 2026
9b4a97f
fix: check every folder on the way to a checkout structurally, read c…
janicduplessis Nov 15, 2026
6e87062
fix: compare detection names case-insensitively, gate ios and android…
janicduplessis Nov 15, 2026
b8c9206
fix: make the recognition gate fail closed on every listing error and…
janicduplessis Nov 15, 2026
0032b44
fix: check the scan budget before every read of the recognition gate
janicduplessis Nov 15, 2026
3d6edcf
fix: let an abort escape the recognition gate, correct the chain leng…
janicduplessis Nov 15, 2026
9ad3222
fix: record a denied project check as unreadable and keep its finds, …
janicduplessis Nov 15, 2026
1c22881
fix: record any failed scan read that is not absent or a timeout as u…
janicduplessis Nov 15, 2026
f3e3d27
fix: a background worktree sweep inspects no reduce-only checkout lef…
janicduplessis Nov 15, 2026
4b5265a
Revert "fix: a background worktree sweep inspects no reduce-only chec…
janicduplessis Nov 15, 2026
cc647e1
docs: state what the reduce-only window bounds and add a regression t…
janicduplessis Nov 15, 2026
938fee2
fix: remove the reduce-only window and skip the scan when its file ca…
janicduplessis Nov 15, 2026
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
1 change: 1 addition & 0 deletions .oxlintrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -522,6 +522,7 @@
"packages/stim-cli/src/web/chrome.ts",
"packages/stim-cli/src/workspace/config.ts",
"packages/stim-cli/src/workspace/git-read.ts",
"packages/stim-cli/src/workspace/launcher-directories.ts",
"packages/stim-cli/src/workspace/settings.ts",
"packages/stim-cli/src/workspace/workspace-state.ts",
"packages/stim-cli/src/workspace/worktree-refresh.ts"
Expand Down
243 changes: 239 additions & 4 deletions llp/0004-discovered-checkouts.decision.md

Large diffs are not rendered by default.

111 changes: 111 additions & 0 deletions packages/core/state/discovery-scan.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
import { isJsonObject, readStateFile } from './json-file.ts';
import { discoveryScanFile } from './paths.ts';

/** How an attempt ended: finished, cut short by the folder cap or the time budget, or by a read that timed out or a failure. */
export type ScanTruncation = 'none' | 'budget' | 'folders' | 'read' | 'failed';

const isTruncation = (value: unknown): value is ScanTruncation =>
value === 'none' || value === 'budget' || value === 'folders' || value === 'read' || value === 'failed';

/**
* What the last full scan of the home folder found: the checkouts Stim's project detection recognises that
* `maintenance.discoverRoots`, registered projects and the common tool folders do not reach, and what it could not read.
*/
export interface DiscoveryScan {
version: 2;
/** When the last attempt started, epoch ms. A failed or truncated attempt is stamped too. */
ranAt: number;
/** When the last attempt that finished, neither failed nor truncated, started; 0 when none did. The weekly schedule counts from it. */
completedAt: number;
/** When the last attempt that ran while a volume's level was above normal started; 0 when none did. */
lowScanAt: number;
durationMs: number;
trigger: 'weekly' | 'low-disk';
/** Folders the scan read. */
visited: number;
/**
* Canonical paths of the recognised checkouts. A failed or truncated scan keeps the previous scan's finds that it did
* not reach, and a scan keeps those under a folder it could not read; discovery revalidates each before using it.
*/
found: string[];
/**
* Canonical paths of recognised checkouts under a dot-folder of the home folder, recorded for the doctor listing and
* never used by discovery: Stim cannot tell an installed tool from a checkout there.
*/
dotFolderFound: string[];
/** Folders the system refused or that did not answer, skipped without error. */
unreadable: string[];
/** The scan stopped at its time or folder limit, or on a read or failure, before it finished. */
truncated: boolean;
/** How the attempt ended. `read` and `failed` are retried after an hour; the others follow the weekly schedule. */
truncation: ScanTruncation;
}

const strings = (value: unknown): value is string[] =>
Array.isArray(value) && value.every((entry) => typeof entry === 'string');
const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);

/** Rejects missing, corrupt or unsupported payloads without throwing. */
export function parseDiscoveryScan(value: unknown): DiscoveryScan | null {
if (
!isJsonObject(value) ||
value.version !== 2 ||
!finite(value.ranAt) ||
!finite(value.completedAt) ||
!finite(value.lowScanAt) ||
!finite(value.durationMs) ||
(value.trigger !== 'weekly' && value.trigger !== 'low-disk') ||
!finite(value.visited) ||
!strings(value.found) ||
!strings(value.dotFolderFound) ||
!strings(value.unreadable) ||
typeof value.truncated !== 'boolean' ||
!isTruncation(value.truncation)
)
return null;
return {
version: 2,
ranAt: value.ranAt,
completedAt: value.completedAt,
lowScanAt: value.lowScanAt,
durationMs: value.durationMs,
trigger: value.trigger,
visited: value.visited,
found: value.found,
dotFolderFound: value.dotFolderFound,
unreadable: value.unreadable,
truncated: value.truncated,
truncation: value.truncation,
};
}

/**
* The scan file as the scheduler needs it: `absent` (no previous result), `unreadable` (it exists and could not be
* read, so nothing is known and no scan may run on top of it), or `read` with the result, which is null when the
* contents do not parse or are another version, since they are unusable either way.
*/
export type DiscoveryScanFile =
| { status: 'absent' }
| { status: 'unreadable' }
| { status: 'read'; scan: DiscoveryScan | null };

export function readDiscoveryScanFile(): DiscoveryScanFile {
let text: string;
try {
text = readStateFile(discoveryScanFile());
} catch (error) {
return error instanceof Error && 'code' in error && error.code === 'ENOENT'
? { status: 'absent' }
: { status: 'unreadable' };
}
try {
return { status: 'read', scan: parseDiscoveryScan(JSON.parse(text)) };
} catch {
return { status: 'read', scan: null };
}
}

export function readDiscoveryScan(): DiscoveryScan | null {
const file = readDiscoveryScanFile();
return file.status === 'read' ? file.scan : null;
}
1 change: 1 addition & 0 deletions packages/core/state/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ export * from './tailnet.ts';
export * from './server-service.ts';
export * from './hosted-logs.ts';
export * from './maintenance.ts';
export * from './discovery-scan.ts';
export * from './gc-log.ts';
export * from './build-ledger.ts';
export * from './agent-device.ts';
Expand Down
4 changes: 4 additions & 0 deletions packages/core/state/paths.ts
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,10 @@ export function maintenanceStateFile(): string {
return join(maintenanceDir(), 'state.json');
}

export function discoveryScanFile(): string {
return join(maintenanceDir(), 'discovery-scan.json');
}

export function gcLogDir(): string {
return join(configDir(), 'gc');
}
Expand Down
3 changes: 2 additions & 1 deletion packages/stim-cli/api.api.txt
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,7 @@
[*] interface DiscoveredCheckout { @@1 from: string;
[*] interface DiscoveredCheckout { @@1 origin: DiscoveryOrigin;
[*] interface DiscoveredCheckout { @@1 path: string;
[*] interface DiscoveredCheckout { @@1 reduceOnly?: boolean;
[*] interface DoctorReport {
[*] interface DoctorReport { @@1 @internal daemon: DaemonStatus & {
[*] interface DoctorReport { @@1 @internal maintenance: ReturnType<typeof maintenanceStatus> & {
Expand Down Expand Up @@ -1499,7 +1500,7 @@
[*] type DeviceToolRequest = { @branch4 @@1 platform: "android";
[*] type DeviceToolRequest = { @branch4 @@1 state: "on" | "off";
[*] type DeviceToolRequest = { @branch4 @@1 tool: "network";
[*] type DiscoveryOrigin = "worktree" | "sibling" | "root";
[*] type DiscoveryOrigin = "worktree" | "sibling" | "root" | "scan";
[*] type DiskPressureLevel = 0 | 1 | 2 | 3;
[*] type DoctorPlatform = "ios" | "android";
[*] type EngineOptions = Omit<StimOptions, "buildCacheDir"> & {
Expand Down
2 changes: 2 additions & 0 deletions packages/stim-cli/src/__tests__/cargo-target-cap.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ const candidate = (
dir,
identity,
discovered,
reduceOnly: false,
checkout: dir.replace(/\/target$/, ''),
measuredAt,
});

Expand Down
54 changes: 47 additions & 7 deletions packages/stim-cli/src/__tests__/cargo-target.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ test('trimming removes the stale profiles, keeps the rest and leaves nothing asi
makeProfile('aarch64-linux-android/host-dev', 3 * DAY);
makeProfile('release', 0);

const result = await trimCargoTarget(target, { needBytes: 0 });
const result = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0 });

expect(result.removed.toSorted()).toEqual(['aarch64-linux-android', 'debug']);
expect(existsSync(join(target, 'debug'))).toBe(false);
Expand Down Expand Up @@ -139,7 +139,7 @@ test('a profile a process works in or runs a binary from stays, and an unreadabl
ps: () => `${real}/release/deps/mytest-0123456789abcdef --nocapture\n/bin/zsh -l\n`,
});

const result = await trimCargoTarget(target, { needBytes: 0 });
const result = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0 });

expect(result.removed).toEqual(['host-dev']);
expect(result.kept).toEqual(['debug: a process uses it', 'release: a process uses it']);
Expand All @@ -150,7 +150,7 @@ test('a profile a process works in or runs a binary from stays, and an unreadabl
},
});
makeProfile('profile-b', 3 * DAY);
const unreadable = await trimCargoTarget(target, { needBytes: 0 });
const unreadable = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0 });
expect(unreadable.removed).toEqual([]);
expect(existsSync(join(target, 'profile-b', 'deps', 'libx.rlib'))).toBe(true);
} finally {
Expand All @@ -175,7 +175,7 @@ test('a directory that cannot be put back after a build took its lock is never d
return '4242\n';
},
});
const result = await trimCargoTarget(target, { needBytes: 0 });
const result = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0 });

expect(result.removed).toEqual([]);
expect(result.kept.join(' ')).toContain('could not be put back');
Expand All @@ -198,7 +198,7 @@ test('a profile whose Cargo 1.97 build lock is held stays, whichever of the lock
lsof: (args) => (args.includes('-t') && args.some((arg) => arg.endsWith('.cargo-build-lock')) ? '4242\n' : ''),
});

const result = await trimCargoTarget(target, { needBytes: 0 });
const result = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0 });

expect(result.removed).toEqual([]);
expect(result.kept).toEqual(['debug: a build holds its .cargo-build-lock']);
Expand Down Expand Up @@ -229,13 +229,13 @@ test('a second trim of a target, from another Stim home, keeps what the first mo
return file === 'lsof' || file === 'ps' ? '' : real.runFileAsync(file, args, options);
},
});
const first = trimCargoTarget(target, { needBytes: 0 });
const first = trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0 });
await reachedPause;
const staged = join(realpathSync.native(target), '.stim-trimmed', '0', '.fingerprint');
expect(existsSync(staged)).toBe(true);

vi.stubEnv('STIM_HOME', otherHome);
const second = await trimCargoTarget(target, { needBytes: 0 });
const second = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0 });

expect(second.removed).toEqual([]);
expect(second.kept.join(' ')).toContain('another trim of it holds');
Expand Down Expand Up @@ -268,6 +268,7 @@ test('a trim stopped at a deadline keeps every unit it has not moved, finishes t
});

const result = await trimCargoTarget(target, {
launching: { reduceOnly: false },
needBytes: 0,
incremental: 'all',
measure: false,
Expand All @@ -288,3 +289,42 @@ test('a trim stopped at a deadline keeps every unit it has not moved, finishes t
resetExecutor();
}
});

test('a launcher on PATH that appears after the first reading keeps what it points into at the later reading, and an incomplete reading keeps everything', async () => {
try {
makeProfile('release', 0);
mkdirSync(join(target, 'release', 'incremental', 'x'), { recursive: true });
const real = realpathSync.native(target);
stubProcesses({});
let readings = 0;
const launchers = async () => ({
targets: readings++ === 0 ? [] : [`${real}/release/incremental/x/tool`],
incomplete: [],
});

const result = await trimCargoTarget(target, {
needBytes: 1,
incremental: 'all',
launching: { reduceOnly: true, launchers, checkout: target },
});

expect(readings).toBe(2);
expect(result.removed).toEqual([]);
expect(result.kept).toEqual(['release/incremental: a process uses it']);
expect(existsSync(join(target, 'release', 'incremental', 'x'))).toBe(true);

makeProfile('debug', 3 * DAY);
const unreadable = await trimCargoTarget(target, {
needBytes: 0,
launching: {
reduceOnly: true,
launchers: async () => ({ targets: [], incomplete: ['/locked'] }),
checkout: target,
},
});
expect(unreadable.removed).toEqual([]);
expect(existsSync(join(target, 'debug', 'deps', 'libx.rlib'))).toBe(true);
} finally {
resetExecutor();
}
});
31 changes: 23 additions & 8 deletions packages/stim-cli/src/__tests__/cargo-units.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,12 @@ describe('a profile on disk with Exact ledger', () => {
writeLedger();
stub({});

const result = await trimCargoTarget(target, { needBytes: 0, incremental: 'all', units: 'all' });
const result = await trimCargoTarget(target, {
launching: { reduceOnly: false },
needBytes: 0,
incremental: 'all',
units: 'all',
});

expect(result.removed).toContain('debug: 1 idle units');
expect(readdirSync(join(profile(), '.fingerprint')).filter((name) => name.startsWith('foo-'))).toHaveLength(8);
Expand All @@ -132,7 +137,12 @@ describe('a profile on disk with Exact ledger', () => {
stub({});

expect(idleCargoUnitPaths(target, Date.now())).toEqual([]);
const result = await trimCargoTarget(target, { needBytes: 0, incremental: 'all', units: 'all' });
const result = await trimCargoTarget(target, {
launching: { reduceOnly: false },
needBytes: 0,
incremental: 'all',
units: 'all',
});

expect(result.removed).not.toContain('debug: 1 idle units');
expect(existsSync(join(profile(), 'deps', `libserde-${h(1)}.rlib`))).toBe(true);
Expand All @@ -146,7 +156,12 @@ describe('a profile on disk with Exact ledger', () => {
stub({});
expect(idleCargoUnitPaths(target, Date.now())).toEqual([]);

const result = await trimCargoTarget(target, { needBytes: 0, incremental: 'all', units: 'all' });
const result = await trimCargoTarget(target, {
launching: { reduceOnly: false },
needBytes: 0,
incremental: 'all',
units: 'all',
});

expect(result.removed).not.toContain('debug: 1 idle units');
expect(existsSync(join(profile(), 'deps', `libserde-${h(1)}.rlib`))).toBe(true);
Expand All @@ -160,7 +175,7 @@ describe('a profile on disk with Exact ledger', () => {
writeLedger();
stub({ ps: () => `${join(profile(), 'deps', `tokio-${h(3)}.d`)} --nocapture\n` });

const result = await trimCargoTarget(target, { needBytes: 0, units: 'all' });
const result = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0, units: 'all' });

expect(result.removed).toEqual(['debug: 1 idle units']);
expect(existsSync(join(profile(), 'deps', `libtokio-${h(3)}.rlib`))).toBe(true);
Expand All @@ -178,7 +193,7 @@ describe('a profile on disk with Exact ledger', () => {
writeLedger();
stub({});

const sweep = () => trimCargoTarget(target, { needBytes: 0, units: 'all' });
const sweep = () => trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0, units: 'all' });
const locked = await withCargoLocks([join(target, dir, lock)], sweep);

expect(locked).toMatchObject({ value: { removed: [], kept: [expect.stringContaining(`holds ${lock}`)] } });
Expand All @@ -193,7 +208,7 @@ describe('a profile on disk with Exact ledger', () => {
mkdirSync(join(profile(), '.cargo-build-lock'));
stub({});

const result = await trimCargoTarget(target, { needBytes: 0, units: 'all' });
const result = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0, units: 'all' });

expect(result.removed).toEqual([]);
expect(result.kept.join(' ')).toContain('.cargo-build-lock could not be locked');
Expand All @@ -213,7 +228,7 @@ describe('a profile on disk with Exact ledger', () => {
},
});

const result = await trimCargoTarget(target, { needBytes: 0, units: 'all' });
const result = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0, units: 'all' });

expect(result.removed).toEqual([]);
expect(existsSync(fp)).toBe(true);
Expand All @@ -234,7 +249,7 @@ describe('a profile on disk with Exact ledger', () => {
},
});

const result = await trimCargoTarget(target, { needBytes: 0, units: 'all' });
const result = await trimCargoTarget(target, { launching: { reduceOnly: false }, needBytes: 0, units: 'all' });

expect(result.removed).toEqual(['debug: 25 idle units']);
expect(result.kept.join(' ')).toContain('Exact updated its ledger');
Expand Down
Loading
Loading