{"record":{"id":"c9750da71bb4d3ea","repo":"stablyai/orca","slug":"timed-out-waiting-for-description","errorCode":null,"errorMessage":"Timed out waiting for ${description}","messagePattern":"Timed out waiting for (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"config/scripts/wsl-hook-relay-reattach-benchmark.mjs","lineNumber":102,"sourceCode":"}\n\nasync function readGuestFile(distro, path) {\n  const result = await run('wsl.exe', wslArgs(distro, ['/bin/cat', path]), {\n    allowFailure: true\n  })\n  return result.status === 0 ? result.stdout : null\n}\n\nasync function waitFor(description, probe, timeoutMs = 30_000) {\n  const deadline = Date.now() + timeoutMs\n  while (Date.now() < deadline) {\n    const value = await probe()\n    if (value) {\n      return value\n    }\n    await new Promise((resolve) => setTimeout(resolve, 100))\n  }\n  throw new Error(`Timed out waiting for ${description}`)\n}\n\nfunction parseEndpoint(contents) {\n  const port = Number(/ORCA_AGENT_HOOK_PORT=['\"]?(\\d+)/.exec(contents)?.[1])\n  const token = /ORCA_AGENT_HOOK_TOKEN=['\"]?([^'\"\\r\\n]+)/.exec(contents)?.[1]\n  return Number.isInteger(port) && port > 0 && token ? { port, token } : null\n}\n\nasync function freeGuestPort(distro) {\n  const result = await run(\n    'wsl.exe',\n    wslArgs(distro, [\n      '/usr/bin/python3',\n      '-c',\n      'import socket; s=socket.socket(); s.bind((\"127.0.0.1\",0)); print(s.getsockname()[1]); s.close()'\n    ])\n  )\n  const port = Number(result.stdout.trim())","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/config/scripts/wsl-hook-relay-reattach-benchmark.mjs#L84-L120","documentation":"Thrown by the WSL hook-relay reattach benchmark's generic `waitFor` helper when a probe function does not return a truthy value within timeoutMs (default 30s, polled every 100ms). It is benchmark scaffolding, not production code — it signals that some expected observable condition (relay registered, endpoint file written, hook delivered) never appeared in time.","triggerScenarios":"Calling `waitFor(description, probe, timeoutMs)` where probe() keeps returning a falsy value (null/undefined/0/'') past the deadline. Used in the benchmark to wait for the WSL guest relay to boot, register its hook endpoint, or deliver a hook event back to the host.","commonSituations":"WSL distro is slow to start Node, the relay bundle failed to build (out/relay/wsl missing), the endpoint.env file path is wrong, the guest relay crashed silently, or the host's PTY refresh integration never fires because pty.ts was refactored and no longer routes through the production singleton.","solutions":["Increase the timeout via the caller (pass a larger timeoutMs) or run the benchmark on faster hardware / a warmer WSL cache.","Check that out/relay/wsl/wsl-agent-hook-relay.js and its .version exist (the script builds them via build-relay.mjs if missing — confirm that build succeeded).","Manually run the relay inside the WSL distro to see the real startup error the probe is masking.","Verify the endpoint.env path the probe parses matches where the guest relay actually writes it ($HOME/.orca-wsl/agent-hooks/instance-<key>/endpoint.env)."],"exampleFix":"// before\nawait new Promise((resolve) => setTimeout(resolve, 100))\n\n// after — log probe output on timeout for diagnosis\nthrow new Error(`Timed out waiting for ${description} (last probe: ${JSON.stringify(lastProbe)})`)","handlingStrategy":"retry","validationCode":"// Pre-flight: confirm the relay binary exists before waiting on the probe\nimport { existsSync } from 'node:fs'\nif (!existsSync(bundlePath)) {\n  throw new Error(`relay bundle missing: ${bundlePath}`)\n}","typeGuard":null,"tryCatchPattern":"try {\n  await waitFor('relay endpoint', probe, 30_000)\n} catch (err) {\n  console.error((err as Error).message)\n  // surface guest relay logs collected during the run for diagnosis\n  throw err\n}","preventionTips":["Keep the relay build step deterministic — assert out/relay/wsl/.version before benchmarking.","Run the guest relay manually once to capture its real startup error.","Log the last probe value on timeout instead of a bare message."],"tags":["wsl","benchmark","polling","timeout","relay"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}