Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Bound Windows shell startup by liveness, not the round-trip budget (#4799)
Nick Gomezce91867799ff
diff --git a/packages/desktop/tests/support/pty-readiness.test-helper.ts b/packages/desktop/tests/support/pty-readiness.test-helper.tsindex bc1c7ef93..272db1a87 100644--- a/packages/desktop/tests/support/pty-readiness.test-helper.ts+++ b/packages/desktop/tests/support/pty-readiness.test-helper.ts@@ -86,15 +86,58 @@ const DEFAULT_TIMEOUT_MS = 8_000;const DEFAULT_READY_INTERVAL_MS = 50;const DEFAULT_QUIET_SAMPLES = 20;const DEFAULT_READY_TIMEOUT_MS = 12_000;-const RECEIVED_TAIL_CHARS = 400;+const RECEIVED_EXCERPT_CHARS = 400;const DEFAULT_INPUT_READY_TIMEOUT_MS = 16_000;+/*+ * UPSTREAM([email protected]): the console host, not the shell, writes these on attach, and+ * the two halves rest on different evidence. VtIo::StartIfNeeded's device-attributes and mode trio+ * is a contiguous literal in the conpty 1.25.260303002 OpenConsole.exe this package bundles, found+ * by byte search on both win10-x64 and win10-arm64. XtermEngine's first-paint frame of _HideCursor,+ * _ClearScreen, _SetGraphicsDefault, _CursorHome, _ChangeTitle (the child's own path, BEL- or+ * ST-terminated) and _ShowCursor is composed at runtime, so it is zero literals in that same+ * binary; it rests on the renderer source and on what Windows CI captures on attach. Absence of a+ * literal there is not evidence the host does not emit it.+ */+const CONPTY_ATTACH_SEQUENCES = [+ '\u001b[c',+ '\u001b[?9001h',+ '\u001b[?1004h',+ '\u001b[?25l',+ '\u001b[?25h',+ '\u001b[2J',+ '\u001b[m',+ '\u001b[H',+] as const;+const CONPTY_TITLE_INTRODUCER = '\u001b]0;';+const CONPTY_TITLE_TERMINATORS = ['\u0007', '\u001b\\'] as const;++const HARNESS_BUDGET_MS_BY_TIER = { win32: 85_000, default: 30_000 } as const;+const HARNESS_VERDICT_GRACE_MS_BY_TIER = { win32: 5_000, default: 15_000 } as const;+const HARNESS_TEARDOWN_GRACE_MS = 15_000;+export const HARNESS_VERDICT_POLL_INTERVAL_MS = 25;+export const HARNESS_CHILD_KILL_WAIT_MS = 2_000;const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));+function requireDuration(value: number, what: string, label: string): number {+ if (!Number.isFinite(value) || value <= 0) {+ throw new Error(+ `${what} for ${label} must be a positive finite duration in milliseconds, got ${String(value)}`,+ );+ }+ return value;+}+function describeReceived(text: string): string {if (text.length === 0) return 'nothing';- const tail = text.length > RECEIVED_TAIL_CHARS ? text.slice(-RECEIVED_TAIL_CHARS) : text;- return `${text.length > RECEIVED_TAIL_CHARS ? '...' : ''}${JSON.stringify(tail)}`;+ const tail = text.length > RECEIVED_EXCERPT_CHARS ? text.slice(-RECEIVED_EXCERPT_CHARS) : text;+ return `${text.length > RECEIVED_EXCERPT_CHARS ? '...' : ''}${JSON.stringify(tail)}`;+}++function describeLeading(text: string): string {+ if (text.length === 0) return 'nothing';+ if (text.length <= RECEIVED_EXCERPT_CHARS) return JSON.stringify(text);+ return `${JSON.stringify(text.slice(0, RECEIVED_EXCERPT_CHARS))}...`;}export async function waitForCondition(@@ -104,7 +147,8 @@ export async function waitForCondition(options: WaitOptions = {},): Promise<void> {const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;- const deadline = performance.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);+ const timeoutMs = requireDuration(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 'timeout', label);+ const deadline = performance.now() + timeoutMs;for (;;) {if (predicate()) return;const failure = stream.failure();@@ -113,7 +157,7 @@ export async function waitForCondition(}if (performance.now() >= deadline) {throw new Error(- `timeout waiting for: ${label} (received ${describeReceived(stream.read())})`,+ `timeout waiting for: ${label} after ${Math.round(timeoutMs)}ms (received ${describeReceived(stream.read())})`,);}await sleep(intervalMs);@@ -149,23 +193,171 @@ export interface EvaluatedInputProbe {marker: string;}+export interface EvaluatedInputOptions extends Omit<WaitOptions, 'timeoutMs'> {+ budgetMs: number;+ roundTripTimeoutMs?: number;+}++export interface EvaluatedInputTiming {+ firstOutputMs: number;+ firstOutput: string;+ roundTripMs: number;+}++export interface HarnessTimeouts {+ budgetMs: number;+ verdictDeadlineMs: number;+ testTimeoutMs: number;+}++export function harnessTimeouts(platform: NodeJS.Platform): HarnessTimeouts {+ const tier = platform === 'win32' ? 'win32' : 'default';+ const budgetMs = HARNESS_BUDGET_MS_BY_TIER[tier];+ const verdictDeadlineMs = budgetMs + HARNESS_VERDICT_GRACE_MS_BY_TIER[tier];+ return {+ budgetMs,+ verdictDeadlineMs,+ testTimeoutMs: verdictDeadlineMs + HARNESS_TEARDOWN_GRACE_MS,+ };+}++export interface HarnessBudget {+ grantMs(before: string): number;+}++export function createHarnessBudget(+ budgetMs: number,+ reserveMs: number,+ now: () => number = () => performance.now(),+): HarnessBudget {+ requireDuration(budgetMs, 'the budget', 'the harness');+ requireDuration(reserveMs, 'the report reserve', 'the harness');+ const startedAt = now();+ const remainingMs = (): number => budgetMs - (now() - startedAt);+ return {+ grantMs: (before) => {+ const granted = remainingMs() - reserveMs;+ if (granted <= 0) {+ throw new Error(`the ${budgetMs}ms harness budget was spent before ${before}`);+ }+ return granted;+ },+ };+}++export function resolveHarnessBudgetMs(raw: string | undefined, defaultMs: number): number {+ if (raw === undefined || raw === '') return defaultMs;+ const override = requireDuration(+ Number(raw),+ 'the OK_PTY_HARNESS_BUDGET_MS override',+ 'the harness budget',+ );+ return Math.min(override, defaultMs);+}++type AttachMatch =+ | { kind: 'attach'; length: number }+ | { kind: 'cut-mid-attach' }+ | { kind: 'shell' };++function conptyTitleMatch(text: string): AttachMatch {+ if (CONPTY_TITLE_INTRODUCER.startsWith(text)) return { kind: 'cut-mid-attach' };+ if (!text.startsWith(CONPTY_TITLE_INTRODUCER)) return { kind: 'shell' };+ for (let at = CONPTY_TITLE_INTRODUCER.length; at < text.length; at += 1) {+ const terminator = CONPTY_TITLE_TERMINATORS.find((candidate) => text.startsWith(candidate, at));+ if (terminator !== undefined) return { kind: 'attach', length: at + terminator.length };+ const char = text[at] as string;+ if (char < '\u0020' && char !== '\u001b') return { kind: 'attach', length: at };+ }+ return { kind: 'cut-mid-attach' };+}++function attachMatch(text: string): AttachMatch {+ const sequence = CONPTY_ATTACH_SEQUENCES.find((candidate) => text.startsWith(candidate));+ if (sequence !== undefined) return { kind: 'attach', length: sequence.length };+ if (CONPTY_ATTACH_SEQUENCES.some((candidate) => candidate.startsWith(text)) && text.length > 0) {+ return { kind: 'cut-mid-attach' };+ }+ return conptyTitleMatch(text);+}++export function shellOutputBeyondAttach(text: string): string {+ let rest = text;+ for (;;) {+ const match = attachMatch(rest);+ if (match.kind === 'attach') {+ rest = rest.slice(match.length);+ continue;+ }+ return match.kind === 'cut-mid-attach' ? '' : rest;+ }+}++async function waitForShellFirstOutput(+ stream: PtyStream,+ label: string,+ options: { timeoutMs: number; intervalMs?: number },+): Promise<{ firstOutputMs: number; firstOutput: string }> {+ const startedAt = performance.now();+ const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;+ const deadline = startedAt + options.timeoutMs;+ for (;;) {+ const beyondAttach = shellOutputBeyondAttach(stream.read());+ if (beyondAttach.length > 0) {+ return {+ firstOutputMs: performance.now() - startedAt,+ firstOutput: describeLeading(beyondAttach),+ };+ }+ const failure = stream.failure();+ if (failure !== null) {+ throw new Error(+ `shell died before producing output for ${label}, probe unwritten: ${failure}`,+ );+ }+ if (performance.now() >= deadline) {+ throw new Error(+ `shell never produced output before ${label} within ${Math.round(options.timeoutMs)}ms (received ${describeReceived(stream.read())})`,+ );+ }+ await sleep(intervalMs);+ }+}+export async function waitForEvaluatedInput(stream: PtyStream,send: (data: string) => void,probe: EvaluatedInputProbe,label: string,- options: WaitOptions = {},-): Promise<number> {+ options: EvaluatedInputOptions,+): Promise<EvaluatedInputTiming> {if (probe.input.includes(probe.marker)) {throw new Error(`readiness probe input must not contain its marker: ${probe.marker}`);}+ const budgetMs = requireDuration(options.budgetMs, 'budget', label);+ const ceilingMs = requireDuration(+ options.roundTripTimeoutMs ?? DEFAULT_INPUT_READY_TIMEOUT_MS,+ 'round-trip timeout',+ label,+ );+ const interval = options.intervalMs === undefined ? {} : { intervalMs: options.intervalMs };+ const { firstOutputMs, firstOutput } = await waitForShellFirstOutput(stream, label, {+ timeoutMs: budgetMs,+ ...interval,+ });+ const remainingMs = budgetMs - firstOutputMs;+ if (remainingMs <= 0) {+ throw new Error(+ `shell startup spent the ${Math.round(budgetMs)}ms budget for ${label}: first output after ${Math.round(firstOutputMs)}ms left nothing for the round trip`,+ );+ }const startedAt = performance.now();send(probe.input);await waitForCondition(stream, () => stream.read().includes(probe.marker), label, {- timeoutMs: options.timeoutMs ?? DEFAULT_INPUT_READY_TIMEOUT_MS,- ...(options.intervalMs === undefined ? {} : { intervalMs: options.intervalMs }),+ timeoutMs: Math.min(ceilingMs, remainingMs),+ ...interval,});- return performance.now() - startedAt;+ return { firstOutputMs, firstOutput, roundTripMs: performance.now() - startedAt };}export function buildCwdFileProofCommand(platform: NodeJS.Platform, fileName: string): string {diff --git a/packages/desktop/tests/utility/pty-host-real-io.test.ts b/packages/desktop/tests/utility/pty-host-real-io.test.tsindex 944b45f68..cbe8798a3 100644--- a/packages/desktop/tests/utility/pty-host-real-io.test.ts+++ b/packages/desktop/tests/utility/pty-host-real-io.test.ts@@ -5,16 +5,25 @@ import { join } from 'node:path';import { fileURLToPath } from 'node:url';import { describe, expect, test } from 'vitest';import { isTerminalPlatform } from '../../src/shared/terminal-platform.ts';+import {+ HARNESS_CHILD_KILL_WAIT_MS,+ HARNESS_VERDICT_POLL_INTERVAL_MS,+ harnessTimeouts,+} from '../support/pty-readiness.test-helper.ts';import { removeTempDirBestEffort } from '../support/temp-dir-cleanup.test-helper.ts';const HARNESS = fileURLToPath(new URL('./pty-host.real-io-harness.ts', import.meta.url));+const HARNESS_TIMEOUTS = harnessTimeouts(process.platform);const TERMINAL_PLATFORM = isTerminalPlatform(process.platform);const SUCCESS_RESULT = `HARNESS_RESULT ok=${process.platform === 'win32' ? 5 : 4} fail=0`;const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));-async function runHarness(outputDir: string): Promise<string> {+async function runHarness(+ outputDir: string,+ extraEnv: Record<string, string> = {},+): Promise<string> {const outputPath = join(outputDir, 'output.log');const outputFd = openSync(outputPath, 'w');const child = (() => {@@ -25,6 +34,7 @@ async function runHarness(outputDir: string): Promise<string> {TEMP: outputDir,TMP: outputDir,TMPDIR: outputDir,+ ...extraEnv,},stdio: ['ignore', outputFd, outputFd],windowsHide: true,@@ -51,13 +61,13 @@ async function runHarness(outputDir: string): Promise<string> {async function terminateChild(): Promise<void> {if (exitResult === null) {child.kill();- await Promise.race([exitPromise, sleep(2_000)]);+ await Promise.race([exitPromise, sleep(HARNESS_CHILD_KILL_WAIT_MS)]);}child.unref();}try {- const deadline = Date.now() + (process.platform === 'win32' ? 90_000 : 45_000);+ const deadline = Date.now() + HARNESS_TIMEOUTS.verdictDeadlineMs;while (Date.now() < deadline) {const output = readFileSync(outputPath, 'utf8');if (spawnError !== null) {@@ -84,7 +94,7 @@ async function runHarness(outputDir: string): Promise<string> {`real-PTY harness exited ${exitResult.code ?? exitResult.signal} without a verdict:\n${output}`,);}- await sleep(25);+ await sleep(HARNESS_VERDICT_POLL_INTERVAL_MS);}const output = readFileSync(outputPath, 'utf8');@@ -109,6 +119,25 @@ describe('PTY host — real shell I/O (Node runtime)', () => {removeTempDirBestEffort(outputDir);}},- process.platform === 'win32' ? 105_000 : 60_000,+ HARNESS_TIMEOUTS.testTimeoutMs,+ );++ test.skipIf(!TERMINAL_PLATFORM)(+ 'refuses every scenario a spent budget cannot cover, rather than running into the hard timeout',+ async () => {+ const outputDir = mkdtempSync(join(tmpdir(), 'ok-real-pty-budget-'));+ try {+ const failure = await runHarness(outputDir, { OK_PTY_HARNESS_BUDGET_MS: '1' }).then(+ () => null,+ (error: unknown) => (error as Error).message,+ );+ expect(failure).toContain('the 1ms harness budget was spent before this scenario started');+ expect(failure).toContain('HARNESS_RESULT ok=0');+ expect(failure).not.toContain('hard timeout');+ } finally {+ removeTempDirBestEffort(outputDir);+ }+ },+ HARNESS_TIMEOUTS.testTimeoutMs,);});diff --git a/packages/desktop/tests/utility/pty-host.real-io-harness.ts b/packages/desktop/tests/utility/pty-host.real-io-harness.tsindex acdab1087..fec67ff15 100644--- a/packages/desktop/tests/utility/pty-host.real-io-harness.ts+++ b/packages/desktop/tests/utility/pty-host.real-io-harness.ts@@ -10,7 +10,10 @@ import {} from '../smoke/_helpers/terminal-smoke-shell.ts';import {buildCwdFileProofCommand,+ createHarnessBudget,createPtyHostProbe,+ harnessTimeouts,+ resolveHarnessBudgetMs,waitForCondition,waitForEvaluatedInput,waitForShellReady,@@ -36,6 +39,7 @@ let inFlight: string | null = null;async function scenario(name: string, fn: () => Promise<void>): Promise<void> {inFlight = name;try {+ harnessBudget.grantMs('this scenario started');await fn();results.push({ name, ok: true });console.log(`PASS ${name}`);@@ -51,6 +55,12 @@ const BASE_ENV = { ...process.env };const shellCommands = terminalSmokeShellCommands();const CWD_PROOF_FILE = '.ok-pty-cwd-proof';const WINDOWS_LAUNCH_WAIT = { timeoutMs: 20_000 } as const;+const HARNESS_BUDGET_MS = resolveHarnessBudgetMs(+ process.env.OK_PTY_HARNESS_BUDGET_MS,+ harnessTimeouts(process.platform).budgetMs,+);+const HARNESS_REPORT_RESERVE_MS = 1_000;+const harnessBudget = createHarnessBudget(HARNESS_BUDGET_MS, HARNESS_REPORT_RESERVE_MS);async function waitForWindowsInputReady(host: ReturnType<typeof createHost>,@@ -58,13 +68,16 @@ async function waitForWindowsInputReady(label: string,): Promise<void> {const probe = buildInputReadyProbe();- const readyMs = await waitForEvaluatedInput(+ const timing = await waitForEvaluatedInput(host.streamOf(ptyId),(data) => host.send({ type: 'input', ptyId, data }),{ input: `${probe.command}\r`, marker: probe.marker },label,+ { budgetMs: harnessBudget.grantMs(label) },+ );+ console.log(+ `INPUT_READY ${label} firstOutputMs=${timing.firstOutputMs} firstOutput=${timing.firstOutput} readyMs=${timing.roundTripMs}`,);- console.log(`INPUT_READY ${label} readyMs=${readyMs}`);}async function waitForInteractiveShellReady(@@ -255,17 +268,14 @@ async function main(): Promise<void> {process.exit(failed === 0 ? 0 : 1);}-const hardTimeout = setTimeout(- () => {- const passed = results.filter((result) => result.ok).length;- const failed = results.length - passed + 1;- console.log(- `HARNESS_RESULT ok=${passed} fail=${failed} :: hard timeout during ${inFlight ?? 'startup'}`,- );- process.exit(1);- },- process.platform === 'win32' ? 85_000 : 30_000,-);+const hardTimeout = setTimeout(() => {+ const passed = results.filter((result) => result.ok).length;+ const failed = results.length - passed + 1;+ console.log(+ `HARNESS_RESULT ok=${passed} fail=${failed} :: hard timeout during ${inFlight ?? 'startup'}`,+ );+ process.exit(1);+}, HARNESS_BUDGET_MS);hardTimeout.unref();void main().catch((err) => {diff --git a/packages/desktop/tests/utility/pty-readiness.test.ts b/packages/desktop/tests/utility/pty-readiness.test.tsindex c3ec7f4ce..6978e4b24 100644--- a/packages/desktop/tests/utility/pty-readiness.test.ts+++ b/packages/desktop/tests/utility/pty-readiness.test.ts@@ -2,8 +2,16 @@ import { afterEach, describe, expect, test, vi } from 'vitest';import type { PtyProcessLike, PtySpawnOptions, SpawnPty } from '../../src/utility/pty-host.ts';import {buildCwdFileProofCommand,+ createHarnessBudget,createPtyHostProbe,+ type EvaluatedInputOptions,+ type EvaluatedInputTiming,+ HARNESS_CHILD_KILL_WAIT_MS,+ HARNESS_VERDICT_POLL_INTERVAL_MS,+ harnessTimeouts,type PtyStream,+ resolveHarnessBudgetMs,+ shellOutputBeyondAttach,waitForCondition,waitForEvaluatedInput,waitForShellReady,@@ -81,6 +89,114 @@ describe('shell readiness gate', () => {});});+describe('attach classifier direction', () => {+ const INTRODUCER = '\u001b]0;';++ test('a title the classifier cannot terminate stops withholding once a control byte follows', () => {+ const wedge = `${INTRODUCER}C:\\no\\terminator\r\nPowerShell 7.6.5`;+ expect(shellOutputBeyondAttach(wedge)).toBe('\r\nPowerShell 7.6.5');+ });++ test('a read cut inside a title is still attach, so the gate keeps waiting', () => {+ expect(shellOutputBeyondAttach(`${INTRODUCER}C:\\partial`)).toBe('');+ expect(shellOutputBeyondAttach('\u001b]')).toBe('');+ expect(shellOutputBeyondAttach('\u001b[?100')).toBe('');+ });++ test('a generic frame member as the shell own first output is consumed, not treated as speech', () => {+ expect(shellOutputBeyondAttach('\u001b[2Jcleared by a profile')).toBe('cleared by a profile');+ expect(shellOutputBeyondAttach('\u001b[2J')).toBe('');+ });+});++describe('harness budget override', () => {+ test('an override may narrow the declared budget but never widen it', () => {+ expect(resolveHarnessBudgetMs('1', 85_000)).toBe(1);+ expect(resolveHarnessBudgetMs('84999', 85_000)).toBe(84_999);+ expect(resolveHarnessBudgetMs('85001', 85_000)).toBe(85_000);+ expect(resolveHarnessBudgetMs('999999999', 85_000)).toBe(85_000);+ });++ test('an absent or empty override reads as unset and falls back to the declared budget', () => {+ for (const raw of [undefined, '']) {+ expect(resolveHarnessBudgetMs(raw, 85_000)).toBe(85_000);+ }+ });++ test('an override that is present but cannot bound the run is named instead of ignored', () => {+ for (const raw of ['soon', '0', '-1', 'NaN', 'Infinity']) {+ expect(() => resolveHarnessBudgetMs(raw, 85_000)).toThrow(+ /the OK_PTY_HARNESS_BUDGET_MS override for the harness budget must be a positive finite duration/u,+ );+ }+ });+});++describe('harness budget clock', () => {+ const FAKE_BUDGET_MS = 1_000;+ const FAKE_RESERVE_MS = 100;++ test('every later grant is strictly smaller than the one before it', () => {+ let nowMs = 0;+ const budget = createHarnessBudget(FAKE_BUDGET_MS, FAKE_RESERVE_MS, () => nowMs);+ const atStart = budget.grantMs('this scenario started');+ nowMs = FAKE_BUDGET_MS / 4;+ expect(budget.grantMs('this scenario started')).toBeLessThan(atStart);+ });++ test('a grant the reserve or the deadline has eaten is named in the harness wording, not as a bad argument', () => {+ let nowMs = 0;+ const budget = createHarnessBudget(FAKE_BUDGET_MS, FAKE_RESERVE_MS, () => nowMs);+ expect(budget.grantMs('this scenario started')).toBeGreaterThan(0);+ nowMs = FAKE_BUDGET_MS - FAKE_RESERVE_MS;+ expect(() => budget.grantMs('this scenario started')).toThrow(+ `the ${FAKE_BUDGET_MS}ms harness budget was spent before this scenario started`,+ );+ nowMs = FAKE_BUDGET_MS * 2;+ expect(() => budget.grantMs('this scenario started')).toThrow(+ `the ${FAKE_BUDGET_MS}ms harness budget was spent before this scenario started`,+ );+ });++ test('the default clock is the monotonic one the harness runs on', async () => {+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });+ const budget = createHarnessBudget(FAKE_BUDGET_MS, FAKE_RESERVE_MS);+ const atStart = budget.grantMs('this scenario started');+ await vi.advanceTimersByTimeAsync(FAKE_BUDGET_MS / 4);+ expect(budget.grantMs('this scenario started')).toBe(atStart - FAKE_BUDGET_MS / 4);+ });++ test('a budget or reserve that is not a positive finite duration is refused at construction', () => {+ expect(() => createHarnessBudget(Number.NaN, FAKE_RESERVE_MS)).toThrow(+ 'the budget for the harness must be a positive finite duration in milliseconds, got NaN',+ );+ expect(() => createHarnessBudget(FAKE_BUDGET_MS, Number.POSITIVE_INFINITY)).toThrow(+ 'the report reserve for the harness must be a positive finite duration in milliseconds, got Infinity',+ );+ });+});++describe('harness timeout ladder', () => {+ test('each rung leaves the one below it room to report its own verdict', () => {+ for (const platform of ['win32', 'darwin', 'linux'] as const) {+ const ladder = harnessTimeouts(platform);+ expect(ladder.budgetMs).toBeGreaterThan(0);+ expect(ladder.verdictDeadlineMs).toBeGreaterThan(ladder.budgetMs);+ expect(ladder.testTimeoutMs).toBeGreaterThan(ladder.verdictDeadlineMs);+ expect(ladder.verdictDeadlineMs - ladder.budgetMs).toBeGreaterThan(+ HARNESS_VERDICT_POLL_INTERVAL_MS,+ );+ expect(ladder.testTimeoutMs - ladder.verdictDeadlineMs).toBeGreaterThan(+ HARNESS_CHILD_KILL_WAIT_MS,+ );+ }+ });++ test('windows gets the wider ladder its slower shell startup needs', () => {+ expect(harnessTimeouts('win32').budgetMs).toBeGreaterThan(harnessTimeouts('linux').budgetMs);+ });+});+describe('cwd file proof command', () => {test('reads a relative sentinel without embedding its random contents', () => {expect(buildCwdFileProofCommand('win32', '.ok-cwd-proof')).toBe(@@ -170,6 +286,18 @@ describe('condition waits', () => {).resolves.toBeUndefined();});+ test('a timeout that cannot bound the wait is named instead of polled against', async () => {+ const stream = createFakeStream();+ for (const timeoutMs of [Number.NaN, 0, -1]) {+ await expect(+ waitForCondition(stream, () => false, 'evaluated command output', {+ timeoutMs,+ intervalMs: 5,+ }),+ ).rejects.toThrow(/timeout for evaluated command output must be a positive finite duration/u);+ }+ });+test('names what did arrive when a condition times out', async () => {const stream = createFakeStream();stream.emit('PS C:\\project> Write-Output "HARNESS_$((6*7))_DONE"');@@ -308,7 +436,8 @@ const INPUT_READY_PROBE = {input: 'Write-Output "OK_INPUT_READY_deadbeef_$((6*7))_READY"\r',marker: INPUT_READY_MARKER,} as const;-const INPUT_READY_FAST = { timeoutMs: 200, intervalMs: 5 } as const;+const INPUT_READY_FAST = { roundTripTimeoutMs: 200, intervalMs: 5 } as const;+const BOOTED_PROMPT = 'PS C:\\project> ';const SLOW_EVALUATION_MS = 120;const READINESS_CEILING_MS = 16_000;@@ -341,55 +470,55 @@ describe('evaluated-input readiness', () => {vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });vi.spyOn(Date, 'now').mockReturnValue(1_000);const stream = createFakeStream();+ stream.emit(BOOTED_PROMPT);const shell = driveEvaluatingShell(stream, { evaluatesAfterMs: SLOW_EVALUATION_MS });try {const pending = waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {- timeoutMs: 5_000,+ roundTripTimeoutMs: 5_000,intervalMs: 5,+ budgetMs: 5_000,});await vi.advanceTimersByTimeAsync(SLOW_EVALUATION_MS);- expect(await pending).toBe(SLOW_EVALUATION_MS);+ expect((await pending).roundTripMs).toBe(SLOW_EVALUATION_MS);expect(shell.sent).toEqual([INPUT_READY_PROBE.input]);} finally {shell.dispose();}});- test('defaults to the 16 second ceiling the four four-second attempts used to spend', async () => {+ test('the round trip, measured from a booted shell, keeps the 16 second ceiling', async () => {vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });const stream = createFakeStream();+ stream.emit(BOOTED_PROMPT);const shell = driveEvaluatingShell(stream, { evaluates: false });- let outcome: 'pending' | 'resolved' | 'rejected' = 'pending';- const pending = waitForEvaluatedInput(- stream,- shell.send,- INPUT_READY_PROBE,- 'input ready',- ).then(+ let outcome: string = 'pending';+ const pending = waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: READINESS_CEILING_MS * 4,+ }).then(() => {outcome = 'resolved';},- () => {- outcome = 'rejected';+ (error: unknown) => {+ outcome = error instanceof Error ? error.message : String(error);},);await vi.advanceTimersByTimeAsync(READINESS_CEILING_MS - 1_000);expect(outcome).toBe('pending');await vi.advanceTimersByTimeAsync(1_100);- expect(outcome).toBe('rejected');+ expect(outcome).toMatch(+ new RegExp(`^timeout waiting for: input ready after ${READINESS_CEILING_MS}ms`, 'u'),+ );await pending;});test('a shell that only echoes the probe never reports ready', async () => {const stream = createFakeStream();+ stream.emit(BOOTED_PROMPT);await expect(- waitForEvaluatedInput(- stream,- (data) => stream.emit(data),- INPUT_READY_PROBE,- 'input ready',- INPUT_READY_FAST,- ),+ waitForEvaluatedInput(stream, (data) => stream.emit(data), INPUT_READY_PROBE, 'input ready', {+ ...INPUT_READY_FAST,+ budgetMs: 5_000,+ }),).rejects.toThrow(/timeout waiting for: input ready/u);expect(stream.read()).toContain('Write-Output');expect(stream.read()).not.toContain(INPUT_READY_MARKER);@@ -397,9 +526,13 @@ describe('evaluated-input readiness', () => {test('a shell that never evaluates times out having written the probe once', async () => {const stream = createFakeStream();+ stream.emit(BOOTED_PROMPT);const shell = driveEvaluatingShell(stream, { evaluates: false });await expect(- waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', INPUT_READY_FAST),+ waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ ...INPUT_READY_FAST,+ budgetMs: 5_000,+ }),).rejects.toThrow(/timeout waiting for: input ready/u);expect(shell.sent).toEqual([INPUT_READY_PROBE.input]);});@@ -413,7 +546,7 @@ describe('evaluated-input readiness', () => {shell.send,{ ...INPUT_READY_PROBE, input: `echo ${INPUT_READY_MARKER}` },'input ready',- INPUT_READY_FAST,+ { ...INPUT_READY_FAST, budgetMs: 5_000 },),).rejects.toThrow(/must not contain its marker/u);expect(shell.sent).toEqual([]);@@ -426,11 +559,361 @@ describe('evaluated-input readiness', () => {const startedAt = Date.now();await expect(waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {- timeoutMs: 5_000,+ roundTripTimeoutMs: 5_000,intervalMs: 5,+ budgetMs: 5_000,}),- ).rejects.toThrow(/shell failed before input ready/u);+ ).rejects.toThrow(/shell died before producing output for input ready, probe unwritten/u);expect(Date.now() - startedAt).toBeLessThan(1_000);- expect(shell.sent).toEqual([INPUT_READY_PROBE.input]);+ expect(shell.sent).toEqual([]);+ });+});++const ATTACH_PROLOGUE = '\u001b[?9001h\u001b[?1004h';+const SHIPPED_ATTACH_PROLOGUE = '\u001b[c\u001b[?1004h\u001b[?9001h';+const BOOT_PAST_ROUND_TRIP_MS = READINESS_CEILING_MS + 500;+const CONPTY_REPAINT = '\u001b[?25l\u001b[2J\u001b[m\u001b[H';+const CONPTY_SHOW_CURSOR = '\u001b[?25h';+const WINDOWS_POWERSHELL_TITLE_BEL =+ '\u001b]0;Administrator: C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe\u0007';+const WINDOWS_POWERSHELL_TITLE_ST =+ '\u001b]0;Administrator: C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe\u001b\\';+const CONPTY_INIT_FRAME = `${CONPTY_REPAINT}${WINDOWS_POWERSHELL_TITLE_BEL}${CONPTY_SHOW_CURSOR}`;+const CONPTY_INIT_FRAME_ST_TITLE = `${CONPTY_REPAINT}${WINDOWS_POWERSHELL_TITLE_ST}${CONPTY_SHOW_CURSOR}`;+const CONPTY_INIT_FRAME_CUT_MID_TITLE = `${CONPTY_REPAINT}\u001b]0;C:\\Prog`;+const WINDOWS_POWERSHELL_GUID_ECHO = '7768de99-595e-40d4-9a3d-a4760b05683b\r\n';+const PWSH_BANNER = 'PowerShell 7.6.5\r\n';+const PWSH_TITLE = '\u001b]0;C:\\Program Files\\PowerShell\\7\\pwsh.exe\u0007';+const PWSH_ADMIN_TITLE = '\u001b]0;Administrator: C:\\Program Files\\PowerShell\\7\\pwsh.exe\u0007';+const CI_CAPTURE_CONTENT_FREE_FRAME = `${CONPTY_INIT_FRAME}${WINDOWS_POWERSHELL_GUID_ECHO}`;+const CI_CAPTURE_BANNER_INSIDE_FRAME = `${CONPTY_REPAINT}${PWSH_BANNER}${PWSH_TITLE}${CONPTY_SHOW_CURSOR}`;+const CI_CAPTURE_BANNER_THEN_RETITLE = `${CI_CAPTURE_BANNER_INSIDE_FRAME}${PWSH_ADMIN_TITLE}`;++describe('shell startup is a liveness wait, not a round-trip budget', () => {+ test('a shell whose first output arrives after the round-trip ceiling still reports ready', async () => {+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });+ const stream = createFakeStream();+ stream.emit(ATTACH_PROLOGUE);+ const shell = driveEvaluatingShell(stream);+ const boot = setTimeout(() => stream.emit(BOOTED_PROMPT), BOOT_PAST_ROUND_TRIP_MS);+ let outcome: string = 'pending';+ const pending = waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: BOOT_PAST_ROUND_TRIP_MS * 4,+ }).then(+ (result): EvaluatedInputTiming | null => {+ outcome = 'resolved';+ return result;+ },+ (error: unknown): EvaluatedInputTiming | null => {+ outcome = error instanceof Error ? error.message : String(error);+ return null;+ },+ );+ try {+ await vi.advanceTimersByTimeAsync(READINESS_CEILING_MS);+ expect(outcome).toBe('pending');+ await vi.advanceTimersByTimeAsync(BOOT_PAST_ROUND_TRIP_MS - READINESS_CEILING_MS + 100);+ expect(outcome).toBe('resolved');+ const timing = await pending;+ if (timing === null) throw new Error('the wait resolved without reporting any timing');+ expect(timing.firstOutputMs).toBeGreaterThanOrEqual(BOOT_PAST_ROUND_TRIP_MS);+ expect(timing.firstOutput).toContain('PS C:');+ expect(shell.sent).toEqual([INPUT_READY_PROBE.input]);+ } finally {+ clearTimeout(boot);+ shell.dispose();+ await pending;+ }+ });++ test('a shell that never writes is named as never having produced output', async () => {+ const stream = createFakeStream();+ stream.emit(ATTACH_PROLOGUE);+ const shell = driveEvaluatingShell(stream);+ try {+ await expect(+ waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: 150,+ intervalMs: 5,+ }),+ ).rejects.toThrow(/shell never produced output before input ready/u);+ expect(shell.sent).toEqual([]);+ } finally {+ shell.dispose();+ }+ });++ test('a shell that boots but never answers is named at the round trip, not at startup', async () => {+ const stream = createFakeStream();+ stream.emit(`${ATTACH_PROLOGUE}${BOOTED_PROMPT}`);+ const shell = driveEvaluatingShell(stream, { evaluates: false });+ try {+ await expect(+ waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: 5_000,+ roundTripTimeoutMs: 200,+ intervalMs: 5,+ }),+ ).rejects.toThrow(/timeout waiting for: input ready/u);+ expect(shell.sent).toEqual([INPUT_READY_PROBE.input]);+ } finally {+ shell.dispose();+ }+ });++ test('the attach handshake alone is not the shell speaking, and one byte past it is', () => {+ expect(shellOutputBeyondAttach(ATTACH_PROLOGUE)).toBe('');+ expect(shellOutputBeyondAttach(`${ATTACH_PROLOGUE}${BOOTED_PROMPT}`)).toBe(BOOTED_PROMPT);+ expect(shellOutputBeyondAttach(ATTACH_PROLOGUE.slice(0, -2))).toBe('');+ expect(shellOutputBeyondAttach('')).toBe('');+ });++ test('the order the bundled ConPTY ships is not the shell speaking either', () => {+ expect(shellOutputBeyondAttach(SHIPPED_ATTACH_PROLOGUE)).toBe('');+ expect(shellOutputBeyondAttach(`${SHIPPED_ATTACH_PROLOGUE}${BOOTED_PROMPT}`)).toBe(+ BOOTED_PROMPT,+ );+ expect(shellOutputBeyondAttach(SHIPPED_ATTACH_PROLOGUE.slice(0, -2))).toBe('');+ });++ test("the host's screen-init frame on attach is not the shell speaking", () => {+ expect(shellOutputBeyondAttach(CONPTY_INIT_FRAME)).toBe('');+ expect(shellOutputBeyondAttach(`${ATTACH_PROLOGUE}${CONPTY_INIT_FRAME}`)).toBe('');+ expect(shellOutputBeyondAttach(`${SHIPPED_ATTACH_PROLOGUE}${CONPTY_INIT_FRAME}`)).toBe('');+ expect(shellOutputBeyondAttach(`${ATTACH_PROLOGUE}${CONPTY_INIT_FRAME_ST_TITLE}`)).toBe('');+ expect(shellOutputBeyondAttach(`${ATTACH_PROLOGUE}${CONPTY_INIT_FRAME_CUT_MID_TITLE}`)).toBe(+ '',+ );+ });++ test('a Windows capture reduces to the bytes the shell itself wrote', () => {+ expect(+ shellOutputBeyondAttach(`${SHIPPED_ATTACH_PROLOGUE}${CI_CAPTURE_CONTENT_FREE_FRAME}`),+ ).toBe(WINDOWS_POWERSHELL_GUID_ECHO);+ expect(+ shellOutputBeyondAttach(`${SHIPPED_ATTACH_PROLOGUE}${CI_CAPTURE_BANNER_INSIDE_FRAME}`),+ ).toBe(`${PWSH_BANNER}${PWSH_TITLE}${CONPTY_SHOW_CURSOR}`);+ expect(shellOutputBeyondAttach(`${ATTACH_PROLOGUE}${CI_CAPTURE_BANNER_THEN_RETITLE}`)).toBe(+ `${PWSH_BANNER}${PWSH_TITLE}${CONPTY_SHOW_CURSOR}${PWSH_ADMIN_TITLE}`,+ );+ expect(+ shellOutputBeyondAttach(`${ATTACH_PROLOGUE}${CONPTY_INIT_FRAME_ST_TITLE}${BOOTED_PROMPT}`),+ ).toBe(BOOTED_PROMPT);+ });++ test('shell output behind the init frame is never stripped with it', () => {+ expect(+ shellOutputBeyondAttach(`${ATTACH_PROLOGUE}${CONPTY_INIT_FRAME}${BOOTED_PROMPT}`),+ ).toContain(BOOTED_PROMPT);+ expect(shellOutputBeyondAttach(CI_CAPTURE_BANNER_INSIDE_FRAME)).toContain('PowerShell 7.6.5');+ expect(shellOutputBeyondAttach(CI_CAPTURE_CONTENT_FREE_FRAME)).toContain(+ WINDOWS_POWERSHELL_GUID_ECHO,+ );+ expect(+ shellOutputBeyondAttach(`${ATTACH_PROLOGUE}${CONPTY_INIT_FRAME_ST_TITLE}${BOOTED_PROMPT}`),+ ).toContain(BOOTED_PROMPT);+ });++ test('the first output the gate reports leads with the bytes that opened it', async () => {+ const stream = createFakeStream();+ const head = 'OK_GATE_OPENED_HERE';+ stream.emit(+ `${SHIPPED_ATTACH_PROLOGUE}${CONPTY_INIT_FRAME}${head}${'x'.repeat(600)}${BOOTED_PROMPT}`,+ );+ const shell = driveEvaluatingShell(stream);+ try {+ const timing = await waitForEvaluatedInput(+ stream,+ shell.send,+ INPUT_READY_PROBE,+ 'input ready',+ { budgetMs: 5_000, roundTripTimeoutMs: 2_000, intervalMs: 5 },+ );+ expect(timing.firstOutput).toContain(head);+ expect(timing.firstOutput.startsWith('...')).toBe(false);+ } finally {+ shell.dispose();+ }+ });++ test('the shipped attach burst leaves the gate shut, and a prompt behind it opens it', async () => {+ const attaching = createFakeStream();+ attaching.emit(SHIPPED_ATTACH_PROLOGUE);+ const attachingShell = driveEvaluatingShell(attaching);+ const booted = createFakeStream();+ booted.emit(`${SHIPPED_ATTACH_PROLOGUE}${BOOTED_PROMPT}`);+ const bootedShell = driveEvaluatingShell(booted);+ try {+ await expect(+ waitForEvaluatedInput(attaching, attachingShell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: 150,+ intervalMs: 5,+ }),+ ).rejects.toThrow(/shell never produced output before input ready/u);+ expect(attachingShell.sent).toEqual([]);++ const timing = await waitForEvaluatedInput(+ booted,+ bootedShell.send,+ INPUT_READY_PROBE,+ 'input ready',+ { budgetMs: 5_000, roundTripTimeoutMs: 2_000, intervalMs: 5 },+ );+ expect(timing.firstOutput).toContain('PS C:');+ expect(bootedShell.sent).toEqual([INPUT_READY_PROBE.input]);+ } finally {+ attachingShell.dispose();+ bootedShell.dispose();+ }+ });++ test('a handshake cut by a read boundary does not open the gate', async () => {+ const stream = createFakeStream();+ stream.emit(ATTACH_PROLOGUE.slice(0, -2));+ const shell = driveEvaluatingShell(stream);+ try {+ await expect(+ waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: 150,+ intervalMs: 5,+ }),+ ).rejects.toThrow(/shell never produced output before input ready/u);+ expect(shell.sent).toEqual([]);+ } finally {+ shell.dispose();+ }+ });++ test('a budget that cannot bound the wait is named instead of polled against', async () => {+ const stream = createFakeStream();+ const shell = driveEvaluatingShell(stream);+ try {+ await expect(+ waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ intervalMs: 5,+ } as unknown as EvaluatedInputOptions),+ ).rejects.toThrow(/budget for input ready must be a positive finite duration/u);+ for (const budgetMs of [Number.NaN, 0, -1]) {+ await expect(+ waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs,+ intervalMs: 5,+ }),+ ).rejects.toThrow(/budget for input ready must be a positive finite duration/u);+ }+ await expect(+ waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: 5_000,+ roundTripTimeoutMs: Number.NaN,+ intervalMs: 5,+ }),+ ).rejects.toThrow(/round-trip timeout for input ready must be a positive finite duration/u);+ expect(shell.sent).toEqual([]);+ } finally {+ shell.dispose();+ }+ });++ test('a late-booting shell leaves the round trip only what the budget has left', async () => {+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });+ const stream = createFakeStream();+ stream.emit(ATTACH_PROLOGUE);+ const shell = driveEvaluatingShell(stream, { evaluates: false });+ const boot = setTimeout(() => stream.emit(BOOTED_PROMPT), BOOT_PAST_ROUND_TRIP_MS);+ let outcome: string = 'pending';+ const pending = waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: BOOT_PAST_ROUND_TRIP_MS + 1_000,+ }).then(+ () => {+ outcome = 'resolved';+ },+ (error: unknown) => {+ outcome = error instanceof Error ? error.message : String(error);+ },+ );+ try {+ await vi.advanceTimersByTimeAsync(BOOT_PAST_ROUND_TRIP_MS);+ expect(outcome).toBe('pending');+ await vi.advanceTimersByTimeAsync(1_100);+ expect(outcome).toMatch(/^timeout waiting for: input ready after 1000ms/u);+ await pending;+ } finally {+ clearTimeout(boot);+ shell.dispose();+ }+ });++ test('startup that outruns its grant is named as such, with the probe unsent', async () => {+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });+ const stream = createFakeStream();+ stream.emit(ATTACH_PROLOGUE);+ const shell = driveEvaluatingShell(stream);+ const boot = setTimeout(() => stream.emit(BOOTED_PROMPT), 25);+ let outcome: string = 'pending';+ const pending = waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: 20,+ intervalMs: 15,+ }).then(+ () => {+ outcome = 'resolved';+ },+ (error: unknown) => {+ outcome = error instanceof Error ? error.message : String(error);+ },+ );+ try {+ await vi.advanceTimersByTimeAsync(40);+ expect(outcome).toMatch(/^shell startup spent the 20ms budget for input ready/u);+ expect(shell.sent).toEqual([]);+ await pending;+ } finally {+ clearTimeout(boot);+ shell.dispose();+ }+ });++ test('the startup timeout tells a silent PTY apart from one that only handshook', async () => {+ const silent = createFakeStream();+ const handshaken = createFakeStream();+ handshaken.emit(ATTACH_PROLOGUE);+ const budget = { budgetMs: 60, intervalMs: 5 } as const;+ const cases = [+ { stream: silent, tail: 'received nothing' },+ { stream: handshaken, tail: `received ${JSON.stringify(ATTACH_PROLOGUE)}` },+ ];+ for (const { stream, tail } of cases) {+ const failure = await waitForEvaluatedInput(+ stream,+ () => undefined,+ INPUT_READY_PROBE,+ 'input ready',+ budget,+ ).then(+ () => null,+ (error: unknown) => (error as Error).message,+ );+ expect(failure).toContain('shell never produced output before input ready');+ expect(failure).toContain(tail);+ }+ });++ test('a shell that dies during startup is surfaced without writing the probe into it', async () => {+ const stream = createFakeStream();+ stream.emit(ATTACH_PROLOGUE);+ const shell = driveEvaluatingShell(stream);+ stream.fail('exited (code -1, signal none)');+ try {+ await expect(+ waitForEvaluatedInput(stream, shell.send, INPUT_READY_PROBE, 'input ready', {+ budgetMs: 5_000,+ intervalMs: 5,+ }),+ ).rejects.toThrow(+ /shell died before producing output for input ready, probe unwritten: exited \(code -1/u,+ );+ expect(shell.sent).toEqual([]);+ } finally {+ shell.dispose();+ }});});