github-router 0.3.117 → 0.3.121

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-router",
-  "version": "0.3.117",
+  "version": "0.3.121",
   "license": "MIT",
   "description": "A reverse proxy that exposes GitHub Copilot as OpenAI and Anthropic compatible API endpoints.",
   "keywords": [

package/dist/lifecycle-DzJicg68.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"lifecycle-DzJicg68.js","names":["path","quoted: string","child: ReturnType<typeof spawn>","chunks: Array<Buffer>","stderrChunks: Array<Buffer>","inactivityTimer: ReturnType<typeof setTimeout> | undefined","_instanceUuid: string | null","_exitHandler: (() => void) | null","_sigintHandler: (() => void) | null","_sigtermHandler: (() => void) | null","names: Array<string>","path","meta: Record<string, unknown>"],"sources":["../src/lib/exec.ts","../src/lib/colbert/lifecycle.ts"],"sourcesContent":["/**\n * Windows-safe, injection-safe command execution helpers.\n *\n * Why this module exists: on Windows, npm-installed CLIs (`claude`,\n * `npm`, `codex`) are `.cmd`/`.bat` shims. Node's `execFile`/`spawn`\n * with `shell:false` cannot launch them (CreateProcess only resolves\n * `.exe`), so callers must go through `cmd.exe` (`shell:true`). That in\n * turn opens two hazards this module closes:\n *\n *   1. **Metacharacter injection** (`& | < > ^ ( ) ! %`). A naive\n *      \"quote only tokens with spaces\" scheme lets `pkg@latest&calc`\n *      run `calc` as a second command. `buildExecInvocation` applies\n *      real cmd.exe quoting (argv-quote + caret-escape) and fails\n *      closed on `%` (which cannot be reliably escaped on the cmd\n *      command line).\n *\n *   2. **CWD shadowing.** `cmd.exe` resolves a bare `npm` from the\n *      current directory before PATH, so an untrusted repo can plant\n *      `npm.cmd`. `resolveExecutable` resolves to an absolute path\n *      against PATH only (honoring PATHEXT), never the cwd, so callers\n *      spawn the real binary by absolute path.\n *\n * All runners are best-effort and timeout-bounded; callers wrap in\n * try/catch and never let an update/probe failure block launch.\n */\n\nimport { spawn } from \"node:child_process\"\nimport { existsSync } from \"node:fs\"\nimport path from \"node:path\"\nimport process from \"node:process\"\n\n/**\n * Parse a boolean-ish env value. Returns `undefined` when unset or\n * unrecognized so callers can apply their own default. Accepts\n * `1|true|yes|on` (true) and `0|false|no|off|<empty>` (false),\n * case-insensitive. The single shared parser for all new `GH_ROUTER_*`\n * flags so on/off semantics don't drift per call site.\n */\nexport function parseBoolEnv(value: string | undefined): boolean | undefined {\n  if (value === undefined) return undefined\n  const v = value.trim().toLowerCase()\n  if (v === \"1\" || v === \"true\" || v === \"yes\" || v === \"on\") return true\n  if (v === \"0\" || v === \"false\" || v === \"no\" || v === \"off\" || v === \"\") {\n    return false\n  }\n  return undefined\n}\n\n/** Read the PATH value from an env object, case-insensitively. */\nfunction pathValueOf(env: NodeJS.ProcessEnv): string {\n  for (const key of Object.keys(env)) {\n    if (key.toLowerCase() === \"path\") return env[key] ?? \"\"\n  }\n  return \"\"\n}\n\nexport interface ResolveExecutableOpts {\n  env?: NodeJS.ProcessEnv\n  platform?: NodeJS.Platform\n  /** Directory to treat as \"current dir\" and exclude from resolution. */\n  cwd?: string\n}\n\n/**\n * Resolve an executable name to an absolute path against PATH, honoring\n * `PATHEXT` on Windows and **excluding the current working directory**.\n *\n * Returns `null` when unresolved — callers treat that as \"tool absent\"\n * and skip (best-effort). Spawning the returned absolute path means\n * `cmd.exe`'s implicit cwd-first lookup never applies, closing the\n * planted-`npm.cmd` vector.\n */\nexport function resolveExecutable(\n  name: string,\n  opts: ResolveExecutableOpts = {},\n): string | null {\n  const platform = opts.platform ?? process.platform\n  const env = opts.env ?? process.env\n  // Defensive: some test harnesses mock `node:process` without `cwd`.\n  // Absent a usable cwd we simply skip the cwd-exclusion guard (the\n  // returned absolute path already bypasses cmd.exe's cwd-first lookup).\n  const cwdRaw =\n    opts.cwd ?? (typeof process.cwd === \"function\" ? process.cwd() : undefined)\n  const resolvedCwd = cwdRaw ? path.resolve(cwdRaw) : null\n\n  const dirs = pathValueOf(env)\n    .split(path.delimiter)\n    // Drop empty entries and a literal \".\" — both denote the cwd on\n    // Windows, which we explicitly refuse to resolve against.\n    .filter((d) => d.length > 0 && d !== \".\")\n\n  const isWin = platform === \"win32\"\n\n  // POSIX: an explicit path component → resolve directly.\n  if (!isWin && name.includes(\"/\")) {\n    return existsSync(name) ? path.resolve(name) : null\n  }\n  // Windows: an explicit path component (with a separator) → direct.\n  if (isWin && (name.includes(\"\\\\\") || name.includes(\"/\"))) {\n    return existsSync(name) ? path.resolve(name) : null\n  }\n\n  const exts =\n    isWin && path.extname(name) === \"\"\n      ? (env.PATHEXT ?? \".COM;.EXE;.BAT;.CMD\")\n          .split(\";\")\n          .map((e) => e.trim())\n          .filter(Boolean)\n      : [\"\"]\n\n  for (const dir of dirs) {\n    // Belt-and-suspenders: never resolve against the cwd even if it is\n    // listed explicitly in PATH.\n    if (resolvedCwd && path.resolve(dir) === resolvedCwd) continue\n    for (const ext of exts) {\n      const candidate = path.join(dir, name + ext)\n      if (existsSync(candidate)) return candidate\n    }\n  }\n  return null\n}\n\n/**\n * Quote one argument for a `cmd.exe /c \"<line>\"` command line so the\n * target program receives it verbatim and no `cmd.exe` metacharacter\n * retains shell meaning.\n *\n * Two phases (the canonical Windows approach — Colascione / Rust std):\n *   1. **argv quoting** so `CommandLineToArgvW` in the target parses\n *      the token as one argument (double-quote, backslash-escape).\n *   2. **caret-escaping** every `cmd.exe` metacharacter — including the\n *      quotes from phase 1 — so `cmd.exe` is never in quote-mode, strips\n *      the carets, and hands the argv-quoted string to the program.\n *\n * `%` is special: it cannot be reliably escaped on the `cmd.exe`\n * *command line* (caret does not stop `%VAR%` expansion there). Rather\n * than mis-escape, we **throw** — our callers never pass `%`, so this\n * fails closed on the one unescapable injection vector.\n */\nexport function quoteWinArg(arg: string): string {\n  if (arg.includes(\"%\")) {\n    throw new Error(\n      \"buildExecInvocation: argument contains '%', which cannot be safely \" +\n        \"escaped on the Windows command line; refusing to build the command.\",\n    )\n  }\n\n  // Phase 1 — argv quoting.\n  let quoted: string\n  if (arg.length > 0 && !/[ \\t\\n\\v\"&|<>()^!]/.test(arg)) {\n    quoted = arg\n  } else {\n    let s = '\"'\n    let backslashes = 0\n    for (const ch of arg) {\n      if (ch === \"\\\\\") {\n        backslashes++\n      } else if (ch === '\"') {\n        s += \"\\\\\".repeat(backslashes * 2 + 1) + '\"'\n        backslashes = 0\n      } else {\n        s += \"\\\\\".repeat(backslashes) + ch\n        backslashes = 0\n      }\n    }\n    s += \"\\\\\".repeat(backslashes * 2) + '\"'\n    quoted = s\n  }\n\n  // Phase 2 — caret-escape all cmd.exe metacharacters (and the carets\n  // themselves). cmd strips these; the program sees the phase-1 string.\n  return quoted.replace(/[()!^\"<>&|]/g, \"^$&\")\n}\n\nexport interface ExecInvocation {\n  command: string\n  args: string[]\n  shell: boolean\n}\n\n/**\n * Build the platform-correct `spawn` invocation for a command given as\n * an argv array. Pure / unit-testable (no spawn).\n *\n *   - win32 → a single caret/argv-quoted command string + `shell:true`\n *     + empty args array (the empty array avoids the DEP0190 warning\n *     that fires when args and `shell:true` are combined). `cmd[0]`\n *     should already be an absolute path from `resolveExecutable`.\n *   - posix → `(cmd[0], cmd.slice(1))` with `shell:false` — no shell,\n *     no injection surface.\n */\nexport function buildExecInvocation(\n  cmd: string[],\n  platform: NodeJS.Platform = process.platform,\n): ExecInvocation {\n  if (cmd.length === 0) throw new Error(\"buildExecInvocation: empty command\")\n  if (platform === \"win32\") {\n    return { command: cmd.map(quoteWinArg).join(\" \"), args: [], shell: true }\n  }\n  return { command: cmd[0], args: cmd.slice(1), shell: false }\n}\n\nexport interface RunOpts {\n  cwd?: string\n  /** Hard timeout in ms; the process tree is killed on expiry. */\n  timeoutMs?: number\n  /** Extra env to merge over the parent env for the child. */\n  env?: NodeJS.ProcessEnv\n}\n\nexport interface RunResult {\n  stdout: string\n  stderr: string\n  /** Exit code; `null` when killed by signal/timeout. */\n  code: number | null\n  timedOut: boolean\n}\n\nfunction runInternal(\n  cmd: string[],\n  stdoutMode: \"pipe\" | \"inherit\" | \"ignore\",\n  opts: RunOpts,\n): Promise<RunResult> {\n  const { command, args, shell } = buildExecInvocation(cmd)\n  return new Promise<RunResult>((resolve, reject) => {\n    let child: ReturnType<typeof spawn>\n    try {\n      child = spawn(command, args, {\n        cwd: opts.cwd,\n        env: opts.env ?? process.env,\n        shell,\n        windowsHide: true,\n        stdio: [\n          \"ignore\",\n          stdoutMode,\n          stdoutMode === \"inherit\" ? \"inherit\" : \"pipe\",\n        ],\n      })\n    } catch (err) {\n      reject(err instanceof Error ? err : new Error(String(err)))\n      return\n    }\n\n    let stdout = \"\"\n    let stderr = \"\"\n    let timedOut = false\n    let settled = false\n\n    const timer = opts.timeoutMs\n      ? setTimeout(() => {\n          timedOut = true\n          killTree(child.pid)\n        }, opts.timeoutMs)\n      : undefined\n    timer?.unref?.()\n\n    child.stdout?.on(\"data\", (c: Buffer) => {\n      stdout += c.toString(\"utf8\")\n    })\n    child.stderr?.on(\"data\", (c: Buffer) => {\n      stderr += c.toString(\"utf8\")\n    })\n    child.stdout?.on(\"error\", () => {})\n    child.stderr?.on(\"error\", () => {})\n\n    const finish = (code: number | null): void => {\n      if (settled) return\n      settled = true\n      if (timer) clearTimeout(timer)\n      resolve({ stdout, stderr, code, timedOut })\n    }\n\n    child.on(\"error\", (err) => {\n      if (settled) return\n      settled = true\n      if (timer) clearTimeout(timer)\n      reject(err)\n    })\n    child.on(\"close\", (code) => finish(code))\n  })\n}\n\n/** Kill a process tree best-effort (taskkill /T on Windows). */\nfunction killTree(pid: number | undefined): void {\n  if (!pid) return\n  try {\n    if (process.platform === \"win32\") {\n      spawn(\"taskkill\", [\"/T\", \"/F\", \"/PID\", String(pid)], {\n        stdio: \"ignore\",\n        windowsHide: true,\n      })\n    } else {\n      process.kill(pid, \"SIGTERM\")\n    }\n  } catch {\n    // already gone\n  }\n}\n\n/** Run a command and capture stdout/stderr. Rejects on spawn error. */\nexport function runCommandCapture(\n  cmd: string[],\n  opts: RunOpts = {},\n): Promise<RunResult> {\n  return runInternal(cmd, \"pipe\", opts)\n}\n\n/** Run a command discarding output (still captures stderr for errors). */\nexport function runCommandVoid(\n  cmd: string[],\n  opts: RunOpts = {},\n): Promise<RunResult> {\n  return runInternal(cmd, \"pipe\", opts)\n}\n\n/** Run a command with the child's stdout/stderr inherited to the user. */\nexport function runCommandInherit(\n  cmd: string[],\n  opts: RunOpts = {},\n): Promise<RunResult> {\n  return runInternal(cmd, \"inherit\", opts)\n}\n\nexport interface ManagedExeOpts extends RunOpts {\n  /**\n   * Hard cap on captured stdout bytes. On overflow the child is\n   * tree-killed and the result carries `stdoutTruncated: true`. Defends\n   * against a full-`CodeUnit` colgrep `--json` payload (source + 5\n   * analysis layers per hit) bloating memory.\n   */\n  maxStdoutBytes?: number\n  /**\n   * When true, exceeding `maxStdoutBytes` does NOT tree-kill the child — it\n   * sets `stdoutTruncated` and stops BUFFERING further stdout while still\n   * draining the pipe (no backpressure). Use for a child whose kill is unsafe\n   * (e.g. colgrep, which writes a non-atomic index — a byte-cap kill during\n   * its result output could interrupt a write). The child runs to completion\n   * (bounded by `timeoutMs` / `inactivityTimeoutMs`). Default false (kill).\n   */\n  truncateInsteadOfKill?: boolean\n  /**\n   * Called synchronously with the spawned child right after spawn\n   * succeeds, BEFORE any output arrives. The colbert lifecycle ledger\n   * uses this to register the child so a session-exit sweep can\n   * tree-kill an orphan. Never throws into the runner.\n   */\n  onSpawn?: (child: ReturnType<typeof spawn>) => void\n  /**\n   * Inactivity (stall) watchdog. When set, a timer is armed for\n   * `inactivityTimeoutMs` and RESET on every stdout/stderr data chunk. On\n   * expiry (no output for the window) it consults `onInactivityCheck`: a\n   * `true` return means \"still making progress via an out-of-band signal\"\n   * (e.g. the colgrep index dir is still growing on disk even though the\n   * process is silent on a non-TTY pipe) and the watchdog re-arms; a\n   * `false`/absent return tree-kills the child and sets `stalled: true`.\n   * This is the progress-based \"stuck\" detector that lets a long-but-\n   * progressing build run to completion while still killing a hung one —\n   * independent of the coarse total `timeoutMs` backstop.\n   */\n  inactivityTimeoutMs?: number\n  /** External progress probe consulted when the inactivity timer fires.\n   * Return `true` to re-arm (still progressing), `false`/throw to kill.\n   * MUST be cheap + synchronous (called on a timer, not awaited). */\n  onInactivityCheck?: () => boolean\n}\n\nexport interface ManagedExeResult extends RunResult {\n  /** True iff stdout was truncated at `maxStdoutBytes` (child was killed). */\n  stdoutTruncated: boolean\n  /** True iff the inactivity watchdog killed the child (no progress). */\n  stalled: boolean\n}\n\n/**\n * Run a **native executable** (a real `.exe`/Mach-O/ELF, NOT a `.cmd`\n * shim) capturing stdout/stderr, with `shell:false` on EVERY platform.\n *\n * Why a separate runner from `runCommandCapture`: that path routes\n * through `buildExecInvocation`, which on Windows builds a\n * `cmd.exe`-quoted command string and **throws on `%`** (`quoteWinArg`).\n * A workspace path can legally contain `%` (and `&`, `(`, `)`, `!`, …),\n * so the managed colgrep binary — which IS a native `.exe`, not a shim —\n * must bypass cmd.exe entirely. `spawn(absExe, args, {shell:false})`\n * resolves the `.exe` via CreateProcess directly: no cmd.exe, no\n * metacharacter hazard, no `%` refusal. POSIX was already `shell:false`.\n * This is what makes \"ANY absolute workspace\" hold on Windows.\n *\n * Lifecycle:\n *   - `timeoutMs` → tree-kill on expiry (`taskkill /T /F` on Windows,\n *     POSIX process-group `kill(-pgid)` so colgrep's rayon worker\n *     children die too). `timedOut: true` in the result.\n *   - `maxStdoutBytes` → tree-kill + `stdoutTruncated: true` once the\n *     captured stdout exceeds the cap.\n *   - `onSpawn(child)` → register the child with the caller's ledger.\n *\n * `command` MUST be an absolute path to the executable (the caller\n * resolves it; we never search PATH here — there is nothing to inject).\n */\nexport function runManagedExeCapture(\n  command: string,\n  args: ReadonlyArray<string>,\n  opts: ManagedExeOpts = {},\n): Promise<ManagedExeResult> {\n  const isWin = process.platform === \"win32\"\n  return new Promise<ManagedExeResult>((resolve, reject) => {\n    let child: ReturnType<typeof spawn>\n    try {\n      child = spawn(command, [...args], {\n        cwd: opts.cwd,\n        env: opts.env ?? process.env,\n        shell: false,\n        windowsHide: true,\n        // POSIX: new process group so we can kill the whole tree\n        // (colgrep + rayon workers) with kill(-pgid). Windows uses\n        // taskkill /T instead; `detached` there has no group semantics.\n        detached: !isWin,\n        stdio: [\"ignore\", \"pipe\", \"pipe\"],\n      })\n    } catch (err) {\n      reject(err instanceof Error ? err : new Error(String(err)))\n      return\n    }\n\n    try {\n      opts.onSpawn?.(child)\n    } catch {\n      // ledger registration must never break the spawn\n    }\n\n    const chunks: Array<Buffer> = []\n    let stdoutBytes = 0\n    const stderrChunks: Array<Buffer> = []\n    let stderrBytes = 0\n    const STDERR_CAP = 64 * 1024\n    let timedOut = false\n    let stdoutTruncated = false\n    let stalled = false\n    let settled = false\n\n    // Exactly one terminator wins: the first to fire records its reason and\n    // tree-kills; later ones no-op. Keeps timedOut / stalled / stdoutTruncated\n    // mutually exclusive and avoids a double tree-kill.\n    let terminated = false\n    const terminate = (reason: \"timeout\" | \"stall\" | \"truncate\"): void => {\n      if (terminated) return\n      terminated = true\n      if (reason === \"timeout\") timedOut = true\n      else if (reason === \"stall\") stalled = true\n      else stdoutTruncated = true\n      if (timer) clearTimeout(timer)\n      if (inactivityTimer) clearTimeout(inactivityTimer)\n      killManagedTree(child, isWin)\n    }\n\n    const timer = opts.timeoutMs\n      ? setTimeout(() => terminate(\"timeout\"), opts.timeoutMs)\n      : undefined\n    timer?.unref?.()\n\n    // Inactivity (stall) watchdog. Re-arms itself: when the window elapses\n    // with no output, consult the external progress probe — re-arm if it\n    // says \"still progressing\" (e.g. the index dir grew), else kill + mark\n    // stalled. Reset on every data chunk (a chatty process never stalls).\n    let inactivityTimer: ReturnType<typeof setTimeout> | undefined\n    const armInactivity = (): void => {\n      if (opts.inactivityTimeoutMs === undefined || settled || terminated) return\n      inactivityTimer = setTimeout(() => {\n        if (settled) return\n        // No probe → pure output-inactivity kill. A probe that THROWS is\n        // inconclusive → don't kill (re-arm); the absolute timeoutMs backstop\n        // still catches a genuinely wedged process.\n        let progressing = false\n        if (opts.onInactivityCheck) {\n          try {\n            progressing = opts.onInactivityCheck() === true\n          } catch {\n            progressing = true\n          }\n        }\n        if (progressing) {\n          armInactivity()\n          return\n        }\n        terminate(\"stall\")\n      }, opts.inactivityTimeoutMs)\n      inactivityTimer?.unref?.()\n    }\n    const resetInactivity = (): void => {\n      if (inactivityTimer) clearTimeout(inactivityTimer)\n      armInactivity()\n    }\n    armInactivity()\n\n    child.stdout?.on(\"data\", (c: Buffer) => {\n      resetInactivity()\n      if (stdoutTruncated) return\n      stdoutBytes += c.length\n      if (\n        opts.maxStdoutBytes !== undefined &&\n        stdoutBytes > opts.maxStdoutBytes\n      ) {\n        stdoutTruncated = true\n        // Default: tree-kill on overflow. Opt-in: keep the child alive and\n        // just stop buffering (the data handler keeps firing + discarding via\n        // the `if (stdoutTruncated) return` guard above, so the pipe drains\n        // and the child never blocks on a full buffer).\n        if (!opts.truncateInsteadOfKill) terminate(\"truncate\")\n        return\n      }\n      chunks.push(c)\n    })\n    child.stderr?.on(\"data\", (c: Buffer) => {\n      resetInactivity()\n      // Hard byte cap on stderr — append only the slice that fits so a\n      // single huge chunk can't overshoot. Never logged raw (it can\n      // embed source code from colgrep).\n      if (stderrBytes >= STDERR_CAP) return\n      const remaining = STDERR_CAP - stderrBytes\n      const slice = c.length > remaining ? c.subarray(0, remaining) : c\n      stderrChunks.push(slice)\n      stderrBytes += slice.length\n    })\n    child.stdout?.on(\"error\", () => {})\n    child.stderr?.on(\"error\", () => {})\n\n    const finish = (code: number | null): void => {\n      if (settled) return\n      settled = true\n      if (timer) clearTimeout(timer)\n      if (inactivityTimer) clearTimeout(inactivityTimer)\n      resolve({\n        stdout: Buffer.concat(chunks).toString(\"utf8\"),\n        stderr: Buffer.concat(stderrChunks).toString(\"utf8\"),\n        code,\n        timedOut,\n        stdoutTruncated,\n        stalled,\n      })\n    }\n\n    child.on(\"error\", (err) => {\n      if (settled) return\n      settled = true\n      if (timer) clearTimeout(timer)\n      if (inactivityTimer) clearTimeout(inactivityTimer)\n      reject(err)\n    })\n    child.on(\"close\", (code) => finish(code))\n  })\n}\n\n/**\n * Tree-kill a managed child. Windows: `taskkill /T /F /PID` (whole\n * tree). POSIX: kill the process GROUP (`-pgid`) so colgrep's rayon\n * worker children die with the parent.\n *\n * `runManagedExeCapture` always spawns POSIX children `detached:true`\n * (their own process group), so the group kill is the correct and\n * sufficient primitive. We deliberately do NOT fall back to a positive-\n * pid `process.kill(pid)` when the group kill fails: by the time a kill\n * fires (timeout / byte-cap race), the child may have already exited and\n * its PID been recycled by an unrelated process — a positive-pid kill\n * would then target the wrong process. `ESRCH` (group already gone) is\n * the success case for our purposes; any other error is swallowed.\n */\nexport function killManagedTree(\n  child: ReturnType<typeof spawn>,\n  isWin: boolean = process.platform === \"win32\",\n): void {\n  const pid = child.pid\n  if (!pid) return\n  try {\n    if (isWin) {\n      spawn(\"taskkill\", [\"/T\", \"/F\", \"/PID\", String(pid)], {\n        stdio: \"ignore\",\n        windowsHide: true,\n      })\n    } else {\n      // Negative pid → the process group (we spawned detached). No\n      // positive-pid fallback (PID-reuse hazard — see doc comment).\n      process.kill(-pid, \"SIGKILL\")\n    }\n  } catch {\n    // ESRCH (already gone) / EPERM — best-effort, nothing more to do.\n  }\n}\n","/**\n * ColBERT sidecar lifecycle: in-memory PID ledger for the short-lived\n * `colgrep` children this proxy spawns, signal-handler tree-kill on\n * exit, and a boot-time metadata reclassification sweep.\n *\n * Because colgrep is CLI-per-invocation (no daemon), the lifecycle\n * problem is **process tracking + cancellation + boot/exit sweep**, NOT\n * keep-alive. Modeled on `worker-agent/lifecycle.ts` (PID ledger + boot\n * sweep + per-proxy-run instance UUID) and `exec.ts`'s tree-kill.\n *\n * Three cooperating layers (none sufficient alone):\n *   1. Per-call cleanup — the runner's `finally` force-kills the child\n *      it spawned (handled in runner.ts).\n *   2. Session-end signal sweep (this file) — SIGINT/SIGTERM/exit kill\n *      every still-tracked child of THIS run.\n *   3. Boot-time sweep (`sweepStaleColbertMetaAtBoot`) — reclassifies\n *      `.gh-router-meta/*.json` entries whose `buildPid` is dead from\n *      `building` → `failed`. It NEVER issues a kill to a PID from a\n *      prior boot (a reused PID may belong to an unrelated process);\n *      only the in-memory ledger (this run's spawns) is ever killed.\n */\n\nimport { spawn } from \"node:child_process\"\nimport { randomUUID } from \"node:crypto\"\nimport fs from \"node:fs/promises\"\nimport path from \"node:path\"\nimport process from \"node:process\"\n\nimport { killManagedTree } from \"../exec\"\nimport { PATHS } from \"../paths\"\n\n// ---------------------------------------------------------------------\n// Per-launch instance UUID (mirrors worker-agent/lifecycle.ts)\n// ---------------------------------------------------------------------\n\nlet _instanceUuid: string | null = null\n\n/**\n * Stable UUID4 generated once per proxy process. Written into the\n * sidecar metadata `ownerInstanceId` so the boot sweep can tell \"this\n * proxy's still-live build\" from \"a stranded `building` entry from a\n * prior proxy whose PID got recycled\" (Docker PID-1 across restarts).\n */\nexport function getColbertInstanceUuid(): string {\n  if (_instanceUuid === null) _instanceUuid = randomUUID()\n  return _instanceUuid\n}\n\n/** Test-only: reset the cached UUID. */\nexport function __resetColbertInstanceUuidForTests(): void {\n  _instanceUuid = null\n}\n\n// ---------------------------------------------------------------------\n// In-memory PID ledger of THIS run's live colgrep children\n// ---------------------------------------------------------------------\n\ntype TrackedChild = ReturnType<typeof spawn>\n\nconst _liveChildren = new Set<TrackedChild>()\n\n/**\n * Register a freshly-spawned colgrep child so the exit sweep can reap\n * it. The runner also removes it on natural close via `untrackChild`.\n */\nexport function trackChild(child: TrackedChild): void {\n  _liveChildren.add(child)\n  child.once(\"close\", () => _liveChildren.delete(child))\n  child.once(\"error\", () => _liveChildren.delete(child))\n}\n\n/** Remove a child from the ledger (e.g. after a clean per-call kill). */\nexport function untrackChild(child: TrackedChild): void {\n  _liveChildren.delete(child)\n}\n\n/** Count of live tracked children (test/diagnostic). */\nexport function liveChildCount(): number {\n  return _liveChildren.size\n}\n\n/**\n * Synchronous best-effort tree-kill of every tracked child. Called from\n * the signal/exit handlers. After killing, the set is cleared so a\n * second call is a no-op.\n */\nexport function sweepLiveChildren(): void {\n  const isWin = process.platform === \"win32\"\n  for (const child of _liveChildren) {\n    try {\n      killManagedTree(child, isWin)\n    } catch {\n      // already gone\n    }\n  }\n  _liveChildren.clear()\n}\n\n// ---------------------------------------------------------------------\n// Signal handlers (mirror worker-agent/lifecycle.ts re-raise pattern)\n// ---------------------------------------------------------------------\n\nlet _registered = false\nlet _exitHandler: (() => void) | null = null\nlet _sigintHandler: (() => void) | null = null\nlet _sigtermHandler: (() => void) | null = null\n\n/**\n * Wire SIGINT/SIGTERM/exit handlers that tree-kill every tracked\n * colgrep child. Idempotent — subsequent calls are a no-op (we never\n * leak listeners). The signal handlers re-raise after sweeping so Node's\n * default terminate-on-signal behavior is restored (otherwise attaching\n * a listener cancels the default and Ctrl-C would clean but not exit).\n */\nexport function registerColbertExitHandlers(): void {\n  if (_registered) return\n  _registered = true\n  _exitHandler = () => sweepLiveChildren()\n  _sigintHandler = () => {\n    sweepLiveChildren()\n    if (_sigintHandler) process.off(\"SIGINT\", _sigintHandler)\n    process.kill(process.pid, \"SIGINT\")\n  }\n  _sigtermHandler = () => {\n    sweepLiveChildren()\n    if (_sigtermHandler) process.off(\"SIGTERM\", _sigtermHandler)\n    process.kill(process.pid, \"SIGTERM\")\n  }\n  process.on(\"SIGINT\", _sigintHandler)\n  process.on(\"SIGTERM\", _sigtermHandler)\n  process.on(\"exit\", _exitHandler)\n}\n\n/** Test-only: unregister handlers + reset module state. */\nexport function __unregisterColbertExitHandlersForTests(): void {\n  if (_sigintHandler) {\n    process.off(\"SIGINT\", _sigintHandler)\n    _sigintHandler = null\n  }\n  if (_sigtermHandler) {\n    process.off(\"SIGTERM\", _sigtermHandler)\n    _sigtermHandler = null\n  }\n  if (_exitHandler) {\n    process.off(\"exit\", _exitHandler)\n    _exitHandler = null\n  }\n  _registered = false\n  _liveChildren.clear()\n}\n\n// ---------------------------------------------------------------------\n// Boot-time metadata reclassification sweep\n// ---------------------------------------------------------------------\n\n/**\n * True iff `pid` names a live process. `process.kill(pid, 0)` probes\n * existence without signalling; `EPERM` means the process exists but is\n * owned by another user (still alive). Exported so the per-query freshness\n * verdict can mirror the boot sweep's liveness check.\n */\nexport function isPidAlive(pid: number): boolean {\n  if (!Number.isInteger(pid) || pid <= 0) return false\n  try {\n    process.kill(pid, 0)\n    return true\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EPERM\") return true\n    return false\n  }\n}\n\n/**\n * Boot-time sweep. Walks `.gh-router-meta/*.json`; any entry stuck in\n * `status:\"building\"` whose `buildPid` is DEAD is a crashed-build\n * escapee → reset to `status:\"failed\"` so the next search re-kicks a\n * build instead of routing to a never-finishing one.\n *\n * It NEVER kills anything: a live PID matching a stale `buildPid` from a\n * prior boot may be a recycled PID belonging to an unrelated process, so\n * the boot sweep only RECLASSIFIES metadata. The in-memory ledger (this\n * run's spawns) is the only thing the SIGINT/SIGTERM handler ever kills.\n *\n * Best-effort; never throws (wrapped by the caller in `ensurePaths`).\n */\nexport async function sweepStaleColbertMetaAtBoot(): Promise<void> {\n  const metaDir = PATHS.COLBERT_META_DIR\n  let names: Array<string>\n  try {\n    names = await fs.readdir(metaDir)\n  } catch {\n    return // no meta dir yet — nothing to sweep\n  }\n  for (const name of names) {\n    if (!name.endsWith(\".json\")) continue\n    const file = path.join(metaDir, name)\n    let meta: Record<string, unknown>\n    try {\n      meta = JSON.parse(await fs.readFile(file, \"utf8\")) as Record<string, unknown>\n    } catch {\n      continue // corrupt — leave it; index-store re-derives on next access\n    }\n    if (meta.status !== \"building\") continue\n    const buildPid = typeof meta.buildPid === \"number\" ? meta.buildPid : 0\n    if (buildPid > 0 && isPidAlive(buildPid)) {\n      // A live PID — could be ours (this run re-kicked) or a recycled\n      // unrelated PID. Either way: never kill from the boot sweep. Leave\n      // the entry; the runner's own ownership check governs.\n      continue\n    }\n    // Dead build PID → reclassify to failed (atomic temp+rename). Stamp the\n    // crash class so the per-query self-heal treats it as transient (re-kick)\n    // rather than operator-actionable.\n    meta.status = \"failed\"\n    meta.failureClass = \"crashed\"\n    const tmp = `${file}.${process.pid}.tmp`\n    try {\n      await fs.writeFile(tmp, JSON.stringify(meta, null, 2))\n      await fs.rename(tmp, file)\n    } catch {\n      await fs.rm(tmp, { force: true }).catch(() => {})\n    }\n  }\n}\n"],"mappings":"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"}