Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { describe, expect, test, vi } from 'vitest';
import { getLogger } from '../logger.ts';
import { withLocalAcquisitionRegistry } from './acquisition-contract.test-helper.ts';
import {
AgentLaunchError,
type ResolvedLaunch,
resetAcquisitionCache,
resolveRegistryLaunch,
} from './launch.ts';
import {
installNodeFixture,
npmNative,
probedDescriptors,
registryPackage,
withAcquisitionHome,
writeExecutable,
writeRecordingNpm,
} from './package-acquisition.test-helper.ts';
const log = getLogger('launch-probe-scope-test');
function acquisitionBin(home: string): { bin: string; probeLog: string } {
const bin = join(home, 'bin');
mkdirSync(bin);
installNodeFixture(bin);
writeExecutable(join(bin, 'npx'), 'process.exit(0);');
return { bin, probeLog: join(home, 'probes.log') };
}
function recordingNpmBin(home: string): { bin: string; probeLog: string } {
const { bin, probeLog } = acquisitionBin(home);
writeRecordingNpm(bin, probeLog);
return { bin, probeLog };
}
function releaseAgeNpmBin(home: string, admitted: string): { bin: string; probeLog: string } {
const { bin, probeLog } = acquisitionBin(home);
writeExecutable(
join(bin, 'npm'),
`require('node:fs').appendFileSync(${JSON.stringify(probeLog)}, JSON.stringify(process.argv.slice(2)) + '\\n');
const spec = process.argv[3];
const at = spec.lastIndexOf('@');
const name = spec.slice(0, at);
const range = spec.slice(at + 1);
if (process.env.npm_config_before && !range.includes(' - ')) {
process.stderr.write('npm error code ETARGET\\nnpm error notarget No matching version found for ' + spec + ' with a date before the release-age cutoff.\\n');
process.exit(1);
}
const version = range.includes(' - ') ? ${JSON.stringify(admitted)} : range;
process.stdout.write(JSON.stringify([{ name, version }]));`,
);
return { bin, probeLog };
}
function gatedNpmBin(
home: string,
gatedOutcome: 'refuse' | 'admit',
): { bin: string; probeLog: string; entered: string; release: string } {
const { bin, probeLog } = acquisitionBin(home);
const entered = join(home, 'entered');
const release = join(home, 'release');
writeExecutable(
join(bin, 'npm'),
`const fs = require('node:fs');
let gated = false;
try {
fs.writeFileSync(${JSON.stringify(entered)}, '', { flag: 'wx' });
gated = true;
} catch {}
fs.appendFileSync(${JSON.stringify(probeLog)}, JSON.stringify(process.argv.slice(2)) + '\\n');
const spec = process.argv[3];
const at = spec.lastIndexOf('@');
const admit = () =>
process.stdout.write(
JSON.stringify([{ name: spec.slice(0, at), version: spec.slice(at + 1) }]),
);
const refuse = () => {
process.stderr.write('npm error code EAGAIN\\nnpm error the fixture registry refused this probe\\n');
process.exit(1);
};
const settle = () => {
if (!fs.existsSync(${JSON.stringify(release)})) setTimeout(settle, 20);
else if (${JSON.stringify(gatedOutcome)} === 'refuse') refuse();
else admit();
};
if (gated) settle();
else admit();`,
);
return { bin, probeLog, entered, release };
}
function retryRefusingNpmBin(home: string): {
bin: string;
probeLog: string;
entered: string;
release: string;
} {
const { bin, probeLog } = acquisitionBin(home);
const admitted = join(home, 'admitted');
const entered = join(home, 'entered');
const release = join(home, 'release');
writeExecutable(
join(bin, 'npm'),
`const fs = require('node:fs');
fs.appendFileSync(${JSON.stringify(probeLog)}, JSON.stringify(process.argv.slice(2)) + '\\n');
const spec = process.argv[3];
const at = spec.lastIndexOf('@');
const claim = (path) => {
try {
fs.writeFileSync(path, '', { flag: 'wx' });
return true;
} catch {
return false;
}
};
const admit = () =>
process.stdout.write(
JSON.stringify([{ name: spec.slice(0, at), version: spec.slice(at + 1) }]),
);
const refuse = () => {
process.stderr.write('npm error code EAGAIN\\nnpm error the fixture registry refused this re-acquisition\\n');
process.exit(1);
};
const settle = () => {
if (fs.existsSync(${JSON.stringify(release)})) refuse();
else setTimeout(settle, 20);
};
if (claim(${JSON.stringify(admitted)}) || !claim(${JSON.stringify(entered)})) admit();
else settle();`,
);
return { bin, probeLog, entered, release };
}
const HOUR_MS = 60 * 60 * 1000;
const awaitGate = (entered: string): Promise<void> =>
vi.waitFor(() => expect(existsSync(entered)).toBe(true), { timeout: 15_000, interval: 20 });
async function awaitGateOffFakeClock(entered: string): Promise<void> {
const deadline = performance.now() + 15_000;
while (!existsSync(entered)) {
if (performance.now() > deadline) throw new Error(`the gated probe never entered: ${entered}`);
await new Promise((settle) => setTimeout(settle, 20));
}
}
function pinnedOpen(
descriptor: string,
env: Record<string, string>,
acquisition?: { reacquire: true },
): Promise<ResolvedLaunch | null> {
return resolveRegistryLaunch(
registryPackage(descriptor, 'npx', env),
null,
log,
undefined,
(candidate) => Promise.resolve(candidate),
acquisition,
);
}
describe('registry launch probe scope', () => {
test('repeated opens of one pinned adapter acquire it once per process', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog } = recordingNpmBin(home);
const env = { PATH: bin };
const first = await resolveRegistryLaunch(
registryPackage('[email protected]', 'npx', env),
null,
log,
);
const second = await resolveRegistryLaunch(
registryPackage('[email protected]', 'npx', env),
null,
log,
);
const third = await resolveRegistryLaunch(
registryPackage('[email protected]', 'npx', env),
null,
log,
);
expect(first.args).toEqual(['-y', '[email protected]', '--version']);
expect(second.args).toEqual(first.args);
expect(third.args).toEqual(first.args);
expect(probedDescriptors(probeLog)).toEqual(['[email protected]']);
});
});
test('a resolved acquisition reports how long its probe took', async () => {
await withAcquisitionHome(async (home) => {
const { bin, entered, release } = gatedNpmBin(home, 'admit');
const env = { PATH: bin };
const resolutions: { source: string; elapsedMs: number }[] = [];
const acquisition = {
onResolved: (resolution: { source: string; elapsedMs: number }) => {
resolutions.push(resolution);
},
};
const open = (): Promise<ResolvedLaunch | null> =>
resolveRegistryLaunch(
registryPackage('[email protected]', 'npx', env),
null,
log,
undefined,
(candidate) => Promise.resolve(candidate),
acquisition,
);
vi.useFakeTimers({ toFake: ['Date'] });
try {
const startedAt = new Date('2026-09-17T00:00:00Z');
vi.setSystemTime(startedAt);
const probing = open();
await awaitGateOffFakeClock(entered);
vi.setSystemTime(new Date(startedAt.getTime() + 5_000));
writeFileSync(release, '');
await probing;
await open();
expect(resolutions.map((entry) => entry.source)).toEqual(['probe', 'memo']);
expect(resolutions[0]?.elapsedMs).toBe(5_000);
expect(resolutions[1]?.elapsedMs).toBe(0);
} finally {
vi.useRealTimers();
}
});
}, 30_000);
test('a distinct pin is acquired on its own rather than served from another pin', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog } = recordingNpmBin(home);
const env = { PATH: bin };
const ceiling = await resolveRegistryLaunch(
registryPackage('[email protected]', 'npx', env),
null,
log,
);
const lower = await resolveRegistryLaunch(
registryPackage('[email protected]', 'npx', env),
null,
log,
);
const other = await resolveRegistryLaunch(
registryPackage('[email protected]', 'npx', env),
null,
log,
);
expect(ceiling.args).toEqual(['-y', '[email protected]', '--version']);
expect(lower.args).toEqual(['-y', '[email protected]', '--version']);
expect(other.args).toEqual(['-y', '[email protected]', '--version']);
expect(probedDescriptors(probeLog)).toEqual([
'[email protected]',
'[email protected]',
'[email protected]',
]);
});
});
test('two adapters sharing a pin but not their npm configuration are acquired apart', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog } = releaseAgeNpmBin(home, '6.0.0');
const descriptor = '[email protected]';
const bounded = await resolveRegistryLaunch(
registryPackage(descriptor, 'npx', {
PATH: bin,
npm_config_before: '2018-04-01T00:00:00Z',
}),
null,
log,
);
const unbounded = await resolveRegistryLaunch(
registryPackage(descriptor, 'npx', { PATH: bin }),
null,
log,
);
expect(bounded.args).toEqual(['-y', '[email protected]', '--version']);
expect(unbounded.args).toEqual(['-y', '[email protected]', '--version']);
expect(probedDescriptors(probeLog)).toEqual([
descriptor,
'[email protected] - 7.0.0',
descriptor,
]);
});
});
test('a release-age-bounded acquisition is re-probed once its freshness window closes', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog } = releaseAgeNpmBin(home, '6.0.0');
const env = { PATH: bin, npm_config_before: '2018-04-01T00:00:00Z' };
const descriptor = '[email protected]';
const boundedProbe = ['[email protected]', '[email protected] - 7.0.0'];
const resolve = () =>
resolveRegistryLaunch(registryPackage(descriptor, 'npx', env), null, log);
vi.useFakeTimers({ toFake: ['Date'] });
try {
vi.setSystemTime(new Date('2026-09-17T00:00:00Z'));
const first = await resolve();
expect(first.args).toEqual(['-y', '[email protected]', '--version']);
expect(probedDescriptors(probeLog)).toEqual(boundedProbe);
vi.setSystemTime(new Date('2026-09-17T00:30:00Z'));
const withinWindow = await resolve();
expect(withinWindow.args).toEqual(first.args);
expect(probedDescriptors(probeLog)).toEqual(boundedProbe);
vi.setSystemTime(new Date(Date.now() + HOUR_MS));
const afterWindow = await resolve();
expect(afterWindow.args).toEqual(first.args);
expect(probedDescriptors(probeLog)).toEqual([...boundedProbe, ...boundedProbe]);
} finally {
vi.useRealTimers();
}
});
});
test('an exact pin stays acquired for the process however long it is held', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog } = recordingNpmBin(home);
const env = { PATH: bin };
const resolve = () =>
resolveRegistryLaunch(registryPackage('[email protected]', 'npx', env), null, log);
vi.useFakeTimers({ toFake: ['Date'] });
try {
vi.setSystemTime(new Date('2026-09-17T00:00:00Z'));
const first = await resolve();
vi.setSystemTime(new Date(Date.now() + 48 * HOUR_MS));
const later = await resolve();
expect(later.args).toEqual(first.args);
expect(probedDescriptors(probeLog)).toEqual(['[email protected]']);
} finally {
vi.useRealTimers();
}
});
});
test('overlapping opens of one pinned adapter share a single probe', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog, entered, release } = gatedNpmBin(home, 'admit');
const env = { PATH: bin };
const descriptor = '[email protected]';
const resolve = () =>
resolveRegistryLaunch(registryPackage(descriptor, 'npx', env), null, log);
const first = resolve();
const second = resolve();
await awaitGate(entered);
writeFileSync(release, '');
const [opened, alsoOpened] = await Promise.all([first, second]);
expect(opened.args).toEqual(['-y', descriptor, '--version']);
expect(alsoOpened.args).toEqual(opened.args);
expect(probedDescriptors(probeLog)).toEqual([descriptor]);
});
}, 30_000);
test('an open that joins a probe already running for its pin is reported as joined', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog, entered, release } = gatedNpmBin(home, 'admit');
const env = { PATH: bin };
const descriptor = '[email protected]';
const sources: string[] = [];
const acquisition = {
onResolved: (resolution: { source: string }) => {
sources.push(resolution.source);
},
};
const open = (): Promise<ResolvedLaunch | null> =>
resolveRegistryLaunch(
registryPackage(descriptor, 'npx', env),
null,
log,
undefined,
(candidate) => Promise.resolve(candidate),
acquisition,
);
const first = open();
await awaitGate(entered);
const second = open();
writeFileSync(release, '');
const [opened, alsoOpened] = await Promise.all([first, second]);
expect(opened?.args).toEqual(['-y', descriptor, '--version']);
expect(alsoOpened?.args).toEqual(opened?.args);
expect(probedDescriptors(probeLog)).toEqual([descriptor]);
expect(
sources,
'a caller that joined an open probe must not be reported as having originated it',
).toEqual(['probe', 'joined']);
});
}, 30_000);
test('a failed acquisition is not remembered, so the next open probes again', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog, release } = gatedNpmBin(home, 'refuse');
writeFileSync(release, '');
const env = { PATH: bin };
const descriptor = '[email protected]';
const resolve = () =>
resolveRegistryLaunch(registryPackage(descriptor, 'npx', env), null, log);
const refused = await resolve().catch((error: unknown) => error);
expect(refused).toBeInstanceOf(AgentLaunchError);
const recovered = await resolve();
expect(recovered.args).toEqual(['-y', descriptor, '--version']);
expect(probedDescriptors(probeLog)).toEqual([descriptor, descriptor]);
});
}, 30_000);
test('an acquisition that found no npm sibling is attempted again on the next open', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog } = acquisitionBin(home);
const env = { PATH: bin };
const descriptor = '[email protected]';
const resolve = () =>
resolveRegistryLaunch(registryPackage(descriptor, 'npx', env), null, log);
const forwarded = await resolve();
expect(forwarded.args).toEqual(['-y', descriptor, '--version']);
expect(probedDescriptors(probeLog)).toEqual([]);
writeRecordingNpm(bin, probeLog);
const probed = await resolve();
expect(probed.args).toEqual(['-y', descriptor, '--version']);
expect(probedDescriptors(probeLog)).toEqual([descriptor]);
});
});
test('a pinned launch that found no npm sibling still installs before it starts', async () => {
await withAcquisitionHome(async (home) => {
const { bin } = acquisitionBin(home);
const npxLog = join(home, 'npx.log');
writeExecutable(
join(bin, 'npx'),
`require('node:fs').appendFileSync(${JSON.stringify(npxLog)}, JSON.stringify(process.argv.slice(2)) + '\\n');`,
);
const descriptor = '[email protected]';
const launch = await resolveRegistryLaunch(
registryPackage(descriptor, 'npx', { PATH: bin }),
null,
log,
undefined,
(candidate) => Promise.resolve(candidate),
{ install: true },
);
expect(launch?.args).toEqual(['--yes=false', '--loglevel=error', descriptor, '--version']);
expect(readFileSync(npxLog, 'utf8')).toBe(
`${JSON.stringify(['--yes', `--package=${descriptor}`, '--call=exit 0'])}\n`,
);
});
});
test('a failing probe that outlives a reset does not evict the entry that replaced it', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog, entered, release } = gatedNpmBin(home, 'refuse');
const env = { PATH: bin };
const descriptor = '[email protected]';
const resolve = () =>
resolveRegistryLaunch(registryPackage(descriptor, 'npx', env), null, log);
const stalled = resolve().catch((error: unknown) => error);
await awaitGate(entered);
resetAcquisitionCache();
const replacement = await resolve();
writeFileSync(release, '');
expect(replacement.args).toEqual(['-y', descriptor, '--version']);
expect(await stalled).toBeInstanceOf(AgentLaunchError);
const reused = await resolve();
expect(reused.args).toEqual(replacement.args);
expect(probedDescriptors(probeLog)).toEqual([descriptor, descriptor]);
});
}, 30_000);
test('a refused re-acquisition still serves the held pin to an open that never asked for one', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog, entered, release } = retryRefusingNpmBin(home);
const env = { PATH: bin };
const descriptor = '[email protected]';
const open = (acquisition?: { reacquire: true }) => pinnedOpen(descriptor, env, acquisition);
const acquired = ['-y', descriptor, '--version'];
const cold = await open();
expect(cold?.args).toEqual(acquired);
const retried = open({ reacquire: true }).catch((error: unknown) => error);
await awaitGate(entered);
const bystander = open().catch((error: unknown) => error);
writeFileSync(release, '');
expect(await retried).toBeInstanceOf(AgentLaunchError);
expect(
await bystander,
'an open that never asked to re-acquire must not inherit the retry failure',
).toMatchObject({ args: acquired });
const afterRefusal = await open();
expect(afterRefusal?.args).toEqual(acquired);
expect(probedDescriptors(probeLog)).toEqual([descriptor, descriptor]);
});
}, 30_000);
test('a re-acquisition joins the probe already open for its pin', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog, entered, release } = gatedNpmBin(home, 'admit');
const env = { PATH: bin };
const descriptor = '[email protected]';
const open = (acquisition?: { reacquire: true }) => pinnedOpen(descriptor, env, acquisition);
const cold = open();
await awaitGate(entered);
const retried = open({ reacquire: true });
writeFileSync(release, '');
const [opened, reacquired] = await Promise.all([cold, retried]);
expect(opened?.args).toEqual(['-y', descriptor, '--version']);
expect(reacquired?.args).toEqual(opened?.args);
expect(probedDescriptors(probeLog)).toEqual([descriptor]);
});
}, 30_000);
test('a re-acquisition joins a refresh already open over the held pin', async () => {
await withAcquisitionHome(async (home) => {
const { bin, probeLog, entered, release } = retryRefusingNpmBin(home);
const env = { PATH: bin };
const descriptor = '[email protected]';
const open = (acquisition?: { reacquire: true }) => pinnedOpen(descriptor, env, acquisition);
const acquired = ['-y', descriptor, '--version'];
const cold = await open();
expect(cold?.args).toEqual(acquired);
const retried = open({ reacquire: true }).catch((error: unknown) => error);
await awaitGate(entered);
const alsoRetried = open({ reacquire: true }).catch((error: unknown) => error);
writeFileSync(release, '');
expect(await retried).toBeInstanceOf(AgentLaunchError);
expect(
await alsoRetried,
'a re-acquisition arriving over a refresh already in flight must share it rather than open a second probe',
).toBeInstanceOf(AgentLaunchError);
expect(probedDescriptors(probeLog)).toEqual([descriptor, descriptor]);
const afterRefusal = await open();
expect(afterRefusal?.args).toEqual(acquired);
expect(probedDescriptors(probeLog)).toEqual([descriptor, descriptor]);
});
}, 30_000);
test('an unreachable registry still launches a pin the local npm cache can answer', async () => {
await withLocalAcquisitionRegistry(async (home, control) => {
const warm = await npmNative([
'pack',
'[email protected]',
'--dry-run',
'--ignore-scripts',
'--json',
]);
expect(warm.code, warm.stderr).toBe(0);
await control.closeRegistry();
const uncached = await npmNative([
'pack',
'@agentclientprotocol/[email protected]',
'--dry-run',
'--ignore-scripts',
'--json',
]);
expect(uncached.code, `${home}: the registry must be unreachable`).not.toBe(0);
expect(uncached.stderr).toContain('ECONNREFUSED');
const offline = await npmNative([
'pack',
'[email protected]',
'--dry-run',
'--ignore-scripts',
'--json',
'--offline',
]);
expect(offline.code, 'the local cache must hold an answer').toBe(0);
const launch = await resolveRegistryLaunch(registryPackage('[email protected]'), null, log);
expect(launch.args).toEqual(['-y', '[email protected]', '--version']);
const refused = await resolveRegistryLaunch(
registryPackage('@agentclientprotocol/[email protected]'),
null,
log,
).catch((error: unknown) => error);
expect(
refused,
'a pin the cache cannot answer must fail acquisition rather than reach npx unvalidated',
).toBeInstanceOf(AgentLaunchError);
expect(refused).toMatchObject({
code: 'install-failed',
machineDetail: expect.stringContaining('ECONNREFUSED'),
});
});
}, 90_000);
});