Function runInProcess

engine/src/cli.ts:375–427

(prompt: string)

  if (!Number.isFinite(timeout) || timeout <= 0) {
    throw new Error(`--timeout must be a positive number of seconds (got ${values.timeout})`);
  }

  // Default to the log's current end, so a watcher started now waits for what happens NEXT
  // rather than firing immediately on the conversation it was started in the middle of.
  //
  // This first call needs the same unreachable handling as the poll loop. Left bare it threw
  // to the top-level catch and exited 1 — a *usage* code — so a harness starting a watcher
  // against a dead engine could not tell "the engine is gone" from "you typed it wrong". That
  // is the distinction the exit codes exist for, defeated at the one moment it matters most.
  // Narrowing does not survive into a closure, so pin it once the guard above has run.
  const kildId = id;
  // Wake latency, and the gap between tolerated retries. Tunable because a harness that
  // wants a snappier wake should not have to fork the CLI to get one.
  const interval = values.interval === undefined ? WATCH_POLL_MS : Number(values.interval) * 1000;
  if (!Number.isFinite(interval) || interval <= 0) {
    throw new Error(`--interval must be a positive number of seconds (got ${values.interval})`);
  }
  const started = Date.now();
  const deadline = started + timeout * 1000;
  function sleep(): Promise<unknown> {
    return new Promise((resolve) => setTimeout(resolve, interval));
  }
  let failures = 0;
  /** Whether the engine has answered even once. "Quiet" is a claim ABOUT the engine — that it
   *  responded and had nothing — so it cannot be reported by a watcher that never heard from
   *  it. Without this, a window that closed after nothing but failures exited 2, asserting the
   *  opposite of what was observed. */
  let answered = false;

  /**
   * Ask once. Returns the batch, or null when the failure was tolerated and the caller should
   * wait and try again; exits `unreachable` once tolerance runs out.
   *
   * ONE place that knows how much transient failure is acceptable, used by both the bootstrap
   * fetch and the poll loop. They had separate copies of this decision and immediately drifted:
   * the loop retried with no delay at all, so three "tolerated" failures burned in about eight
   * milliseconds and a merely-restarting engine was declared dead — the exact opposite of what
   * the tolerance exists for — while the bootstrap fetch tolerated nothing whatsoever.
   */
  async function poll(
    since: number | undefined,
  ): Promise<Awaited<ReturnType<typeof kildMessages>> | null> {
    try {
      // The bound and the deadline are one question, asked once: never wait past the window.
      const batch = await kildMessages(
        kildId,
        since,
        watchRequestTimeout(interval, deadline - Date.now()),
      );
      failures = 0;
      answered = true;
      return batch;
    } catch (err) {
      if (++failures < WATCH_TOLERATED_FAILURES) return null;
      console.error(`kild: engine unreachable after ${failures} attempts: ${errText(err)}`);
      process.exit(WATCH_EXIT.unreachable);