@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/livecli.ts

@@ -0,0 +1,336 @@
+// `qcr live [RUN_ID | DIR] [--lens ID] [--round N] [--follow] [--json]` - read a
+// review's LiveEvent log (src/live/) as a transcript: what the main session
+// said and did, tool by tool, and with `--lens` one lens session's.
+//
+// RUN_ID is a detached run (`qcr review start`), DIR a run directory or a round
+// directory (`.../state/live/<key>/r<n>`); with neither, the newest run. With
+// `--follow` it keeps reading what is appended until the session settles or the
+// run is over. The log is read by byte offset, so a follow never re-reads, and
+// a line a writer is still finishing is left for the next poll.
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  LIVE_MAIN_FILE,
+  lensLogName,
+  readLiveEvents,
+  type LiveEvent,
+} from "@quickchatai/pi-quickreview/src/live/events.js";
+import { latestLiveRound, lensLogIds, listLiveRounds, type LiveRoundRef } from "./live/read.js";
+
+export const LIVE_USAGE =
+  "usage: qcr live [RUN_ID | DIR] [--lens ID] [--round N] [--follow] [--json]";
+
+export interface LiveCliDeps {
+  /** The detached-run registry (`<state home>/review/detached`). */
+  home: string;
+  out: (line: string) => void;
+  sleep: (ms: number) => Promise<void>;
+  /** Whether a pid is alive (to stop following a run that died). */
+  alive: (pid: number) => boolean;
+  /** The review containers that are up, for runs that are one (null: not told). */
+  liveContainers?: () => ReadonlySet<string> | null;
+}
+
+const POLL_MS = 500;
+
+const clock = (at: string): string => at.slice(11, 19);
+
+const oneLine = (s: string, max = 160): string => {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+
+/** Per-render memory: a message whose text already streamed as deltas does not
+ * print again at its end. */
+export interface RenderState {
+  streamed: boolean;
+}
+
+export function newRenderState(): RenderState {
+  return { streamed: false };
+}
+
+/** One event as transcript lines. */
+export function renderLiveEvent(e: LiveEvent, state: RenderState): string[] {
+  const t = clock(e.at);
+  switch (e.type) {
+    case "session_start":
+      return [
+        e.stream === "lens"
+          ? `${t}  lens ${e.agent ?? ""} ${e.lens_id ?? ""} (${e.session}, round ${e.round})`.replace(
+              /\s+/g,
+              " ",
+            )
+          : `${t}  session ${e.session} (${e.key}, round ${e.round})`,
+      ];
+    case "agent_start":
+      return [`${t}  agent started`];
+    case "agent_end":
+      return e.will_retry ? [`${t}  agent turn ended, retrying`] : [];
+    case "agent_settled":
+      return [`${t}  agent settled${e.aborted ? " (aborted)" : ""}`];
+    case "message_start":
+      state.streamed = false;
+      return e.role === "user" && e.text ? [`${t}  > ${oneLine(e.text)}`] : [];
+    case "message_delta":
+      state.streamed = state.streamed || Boolean(e.text);
+      return e.text ? e.text.split("\n").map((l) => `    ${l}`) : [];
+    case "message_end": {
+      const lines: string[] = [];
+      if (!state.streamed && e.text) lines.push(...e.text.split("\n").map((l) => `    ${l}`));
+      const bits = [
+        e.tool_calls?.length ? `calls ${e.tool_calls.join(", ")}` : "",
+        e.stop_reason ?? "",
+        e.usage ? `$${e.usage.cost_usd.toFixed(4)}` : "",
+        e.error ? `error: ${oneLine(e.error, 100)}` : "",
+      ].filter(Boolean);
+      if (bits.length > 0) lines.push(`${t}  assistant ${bits.join(" · ")}`);
+      state.streamed = false;
+      return lines;
+    }
+    case "tool_start": {
+      const what = e.executions?.length
+        ? e.executions.map((x) => x.agent).join(", ")
+        : (e.preview ?? "");
+      return [`${t}  ${e.parent ? "  " : ""}tool ${e.tool}${what ? ` ${what}` : ""}`];
+    }
+    case "tool_update":
+      return e.results.map(
+        (r) =>
+          `${t}    ${r.agent ?? `child ${r.slot}`} ${r.progress?.status ?? "…"}` +
+          ((r.progress?.tool_count ?? r.native?.tool_count)
+            ? ` (${r.progress?.tool_count ?? r.native?.tool_count} tools)`
+            : "") +
+          ((r.progress?.last_message ?? r.native?.last_text)
+            ? ` ${oneLine((r.progress?.last_message ?? r.native?.last_text)!, 80)}`
+            : ""),
+      );
+    case "tool_end": {
+      const bits = [
+        e.is_error ? "failed" : "done",
+        e.duration_ms !== undefined ? `${(e.duration_ms / 1000).toFixed(1)}s` : "",
+        e.cost_usd !== undefined ? `$${e.cost_usd.toFixed(4)}` : "",
+      ].filter(Boolean);
+      return [`${t}  ${e.parent ? "  " : ""}tool ${e.tool} ${bits.join(" · ")}`];
+    }
+    case "queue_update":
+      return e.steering.length + e.follow_up.length > 0
+        ? [`${t}  queued: ${e.steering.length} steer, ${e.follow_up.length} follow-up`]
+        : [];
+    case "compaction_start":
+      return [`${t}  compacting (${e.reason})`];
+    case "compaction_end":
+      return [`${t}  compaction ${e.aborted ? "aborted" : "done"}${e.error ? `: ${e.error}` : ""}`];
+    case "retry":
+      return [
+        e.phase === "start"
+          ? `${t}  retry ${e.attempt}${e.error ? `: ${oneLine(e.error, 100)}` : ""}`
+          : `${t}  retry ${e.success ? "succeeded" : "gave up"}`,
+      ];
+    default:
+      return [];
+  }
+}
+
+// ---- finding the log --------------------------------------------------------------
+
+function isDir(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+interface Target {
+  ref: LiveRoundRef;
+  /** Set when the target is a registry run: where its exit lives. */
+  runDir?: string;
+  pid: number | null;
+  /** The container the run is, when it is one. */
+  container?: string;
+}
+
+function readJson<T>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** The run roots under a detached run directory: `work/<run>/`. */
+function runRoots(runDir: string): string[] {
+  const work = join(runDir, "work");
+  try {
+    return readdirSync(work)
+      .map((d) => join(work, d))
+      .filter(isDir);
+  } catch {
+    return [];
+  }
+}
+
+function newestRun(home: string): string | undefined {
+  const runs = join(home, "runs");
+  try {
+    return readdirSync(runs)
+      .filter((d) => existsSync(join(runs, d, "run.json")))
+      .sort()
+      .at(-1);
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveTarget(
+  arg: string | undefined,
+  round: number | undefined,
+  deps: LiveCliDeps,
+): Target | string {
+  let roots: string[];
+  let runDir: string | undefined;
+  let pid: number | null = null;
+  let container: string | undefined;
+  const id = arg ?? newestRun(deps.home);
+  const run =
+    id !== undefined && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)
+      ? readJson<{ pid: number | null; container?: string }>(
+          join(deps.home, "runs", id, "run.json"),
+        )
+      : null;
+  if (run !== null && id !== undefined) {
+    runDir = join(deps.home, "runs", id);
+    pid = run.pid;
+    container = run.container;
+    roots = runRoots(runDir);
+  } else if (arg !== undefined && existsSync(join(arg, LIVE_MAIN_FILE))) {
+    // a round directory: .../state/live/<key>/r<n>
+    const m = /^(.*)[/\\]([^/\\]+)[/\\]r(\d+)$/.exec(resolve(arg));
+    if (!m) return `${arg} is not a round log directory (state/live/<key>/r<n>)`;
+    if (round !== undefined && round !== Number(m[3]))
+      return `${arg} is round ${m[3]}, not round ${round}`;
+    return { ref: { dir: resolve(arg), key: m[2]!, round: Number(m[3]) }, pid };
+  } else if (arg !== undefined && isDir(arg)) {
+    roots = [resolve(arg)];
+  } else {
+    return arg === undefined ? "no review run to read" : `no review run ${arg}`;
+  }
+  const pick =
+    round !== undefined
+      ? roots
+          .flatMap((r) => listLiveRounds(r))
+          .filter((r) => r.round === round)
+          .at(-1)
+      : roots
+          .map((r) => latestLiveRound(r))
+          .filter((r): r is LiveRoundRef => r !== undefined)
+          .at(-1);
+  if (pick === undefined)
+    return round !== undefined
+      ? `no round ${round} log yet`
+      : "no live log yet: the review has not started its session";
+  return {
+    ref: pick,
+    ...(runDir !== undefined ? { runDir } : {}),
+    pid,
+    ...(container !== undefined ? { container } : {}),
+  };
+}
+
+// ---- the verb -----------------------------------------------------------------------
+
+/** Run `qcr live`; resolves its exit code (0 read, 1 nothing to read, 2 usage). */
+export async function runLive(
+  rest: readonly string[],
+  json: boolean,
+  deps: LiveCliDeps,
+): Promise<number> {
+  let arg: string | undefined;
+  let lens: string | undefined;
+  let round: number | undefined;
+  let follow = false;
+  // a usage error found before a later --json is still reported as JSON
+  const wantsJson = json || rest.includes("--json");
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!;
+    if (a === "--follow" || a === "-f") follow = true;
+    else if (a === "--json") json = true;
+    else if (a === "--lens") {
+      lens = rest[++i];
+      if (lens === undefined) return usage(deps, "--lens needs a lens id", wantsJson);
+    } else if (a === "--round") {
+      const n = Number(rest[++i]);
+      if (!Number.isInteger(n) || n < 1)
+        return usage(deps, "--round needs a round number", wantsJson);
+      round = n;
+    } else if (!a.startsWith("-") && arg === undefined) arg = a;
+    else return usage(deps, `unknown argument ${a}`, wantsJson);
+  }
+  if (lens === "" || (lens !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(lens)))
+    return usage(deps, "--lens needs a lens id", wantsJson);
+
+  const target = resolveTarget(arg, round, deps);
+  if (typeof target === "string") {
+    deps.out(json ? JSON.stringify({ ok: false, errors: [target] }) : `✗ ${target}`);
+    return 1;
+  }
+  const file = join(target.ref.dir, lens !== undefined ? lensLogName(lens) : LIVE_MAIN_FILE);
+  if (lens !== undefined && !existsSync(file)) {
+    const known = lensLogIds(target.ref.dir);
+    deps.out(
+      json
+        ? JSON.stringify({ ok: false, errors: [`no lens log ${lens}`], lenses: known })
+        : `✗ no lens log ${lens}; this round has: ${known.join(", ") || "none"}`,
+    );
+    return 1;
+  }
+
+  const state = newRenderState();
+  let offset = 0;
+  let announced = false;
+  for (;;) {
+    const read = readLiveEvents(file, offset);
+    offset = read.nextOffset;
+    for (const e of read.events) {
+      if (json) deps.out(JSON.stringify(e));
+      else for (const line of renderLiveEvent(e, state)) deps.out(line);
+    }
+    if (!announced && !json) {
+      announced = true;
+      const lenses = lensLogIds(target.ref.dir);
+      if (lens === undefined && lenses.length > 0)
+        deps.out(`(lens logs: ${lenses.join(", ")}; read one with --lens ID)`);
+    }
+    const settled = read.events.some((e) => e.type === "agent_settled");
+    if (!follow || (settled && lens === undefined)) return 0;
+    if (lens !== undefined && settled) return 0;
+    // A run that ended, or whose driver died, writes nothing more.
+    if (target.runDir !== undefined && ended(target.runDir, target, deps)) {
+      const last = readLiveEvents(file, offset);
+      if (last.events.length === 0) return 0;
+      continue;
+    }
+    await deps.sleep(POLL_MS);
+  }
+}
+
+function ended(runDir: string, run: Pick<Target, "pid" | "container">, deps: LiveCliDeps): boolean {
+  if (existsSync(join(runDir, "exit.json")) || existsSync(join(runDir, "stopped.json")))
+    return true;
+  // a container run's liveness is the wrapper's list of the containers that are up
+  if (run.container !== undefined) {
+    const live = deps.liveContainers?.() ?? null;
+    return live !== null && !live.has(run.container);
+  }
+  return run.pid !== null && !deps.alive(run.pid);
+}
+
+function usage(deps: LiveCliDeps, why: string, json: boolean): number {
+  deps.out(
+    json
+      ? JSON.stringify({ ok: false, errors: [why], usage: LIVE_USAGE })
+      : `${LIVE_USAGE}\n(${why})`,
+  );
+  return 2;
+}

package/src/loginhint.ts

@@ -0,0 +1,56 @@
+// Before `qcr review` spends anything: does pi hold a credential for every
+// provider the review's models run on? A login in pi's agent dir counts, and
+// so does the provider's own API key in the environment. An API key for some
+// OTHER provider never does: the review runs on the models its config names,
+// or not at all, and it never switches models to use a key. The refusal names
+// `qcr login`, the way to get the login.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  loginSummary,
+  RUNTIME_KEY_ENVS,
+  type LoginSummary,
+} from "@quickchatai/pi-quickreview/src/engine/auth.js";
+
+/** pi's stored logins in `agentDir`; empty when it holds none. */
+export function readLogins(
+  agentDir: string,
+  read: (path: string) => string = (p) => readFileSync(p, "utf8"),
+): LoginSummary {
+  try {
+    return loginSummary(read(join(agentDir, "auth.json")));
+  } catch {
+    return {};
+  }
+}
+
+/** Why the review cannot run on this machine's credentials, or null when
+ * every provider it needs has one. */
+export function reviewLoginRefusal(o: {
+  providers: readonly string[];
+  agentDir: string;
+  env: Readonly<Record<string, string | undefined>>;
+  logins?: LoginSummary;
+}): string | null {
+  const logins = o.logins ?? readLogins(o.agentDir);
+  const keyOf = (p: string): string | null => {
+    const name = RUNTIME_KEY_ENVS[p];
+    return name !== undefined && (o.env[name] ?? "").trim() !== "" ? name : null;
+  };
+  for (const p of o.providers) {
+    if (logins[p] !== undefined || keyOf(p) !== null) continue;
+    const otherKeys = Object.keys(RUNTIME_KEY_ENVS)
+      .filter((q) => q !== p)
+      .map(keyOf)
+      .filter((k): k is string => k !== null);
+    const keys =
+      otherKeys.length > 0
+        ? ` ${otherKeys.join(" and ")} ${otherKeys.length === 1 ? "is" : "are"} set, and the review does not switch models to use ${otherKeys.length === 1 ? "it" : "them"}: to review on another provider, set the review's models to it in your qcr config.`
+        : "";
+    return (
+      `the review runs on ${p}, and pi has no login for it (pi's agent dir ${o.agentDir}). ` +
+      `Run \`qcr login\` to log in with pi's own /login, then review again.${keys}`
+    );
+  }
+  return null;
+}

package/src/loginrefresh/atomic.ts

@@ -0,0 +1,76 @@
+// The one way the login file is replaced: a tmp file in the SAME directory,
+// fsync, rename over the target. Node builtins only and no runtime TypeScript
+// features, so a test can also run this very file as a separate process
+// (node's type stripping) and race a reader against it.
+//
+// A reader therefore sees the old file or the new one, whole, never a prefix.
+// The target's inode changes on every write, which is why the single-instance
+// lock is NOT on the target (lock.ts).
+import {
+  chmodSync,
+  chownSync,
+  closeSync,
+  fsyncSync,
+  openSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs";
+import { dirname, join, basename } from "node:path";
+
+/** The mode every file in the login volume gets (entrypoint.sh share_login). */
+export const LOGIN_FILE_MODE = 0o660;
+
+export interface AtomicWriteOptions {
+  /** The group to give the new file; default: the target's current group. */
+  gid?: number | undefined;
+}
+
+/**
+ * Replace `target` with `text`: 0660, the login group. The chown is best
+ * effort (a uid outside the group cannot give a file to it); the mode is not.
+ */
+export function writeFileAtomic(target: string, text: string, o: AtomicWriteOptions = {}): void {
+  let gid = o.gid;
+  if (gid === undefined) {
+    try {
+      gid = statSync(target).gid;
+    } catch {
+      /* first write: the directory's group applies */
+    }
+  }
+  const tmp = join(dirname(target), `.${basename(target)}.${process.pid}.tmp`);
+  const fd = openSync(tmp, "w", LOGIN_FILE_MODE);
+  try {
+    writeSync(fd, text);
+    fsyncSync(fd);
+  } catch (err) {
+    closeSync(fd);
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* nothing to remove */
+    }
+    throw err;
+  }
+  closeSync(fd);
+  try {
+    chmodSync(tmp, LOGIN_FILE_MODE);
+    if (gid !== undefined) {
+      try {
+        chownSync(tmp, -1, gid);
+      } catch {
+        /* not in that group: keep the creator's */
+      }
+    }
+    renameSync(tmp, target);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* already gone */
+    }
+    throw err;
+  }
+}

package/src/loginrefresh/lock.ts

@@ -0,0 +1,104 @@
+// The single-instance lock: an exclusive flock on a SEPARATE lock file
+// (`pihome/agent/auth.json.lock`), held for the refresher's whole life.
+//
+// Why not a lock on auth.json: every refresh replaces auth.json by rename
+// (atomic.ts), so a lock on it stays on the old inode, a second refresher could
+// then lock the new file and run beside the first, and the two would rotate the
+// refresh token under each other. The lock file is created once and never
+// renamed or replaced, so its lock survives every refresh.
+//
+// Node has no flock. The lock is held by a helper process: `flock -n <file> sh
+// -c 'echo locked; exec cat'`. `cat` blocks on a pipe from this process, so the
+// lock lasts exactly as long as the pipe's write end does: release() closes it,
+// and a refresher that is killed in any way closes it too (the kernel closes its
+// descriptors), so a crash can never leave the lock held by an orphan.
+import { spawn } from "node:child_process";
+import { chmodSync, chownSync, closeSync, mkdirSync, openSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** flock's exit status when the lock is held by someone else (-E). */
+export const LOCK_HELD_EXIT = 75;
+
+/** Another refresher holds the lock. */
+export class LoginLockHeld extends Error {
+  // A plain field, not a parameter property: tests also run this file as a
+  // separate process under node's type stripping, which has no such syntax.
+  readonly path: string;
+  constructor(path: string) {
+    super(`another login refresher holds ${path}`);
+    this.name = "LoginLockHeld";
+    this.path = path;
+  }
+}
+
+export interface LoginLock {
+  readonly path: string;
+  /** Resolves with a reason if the holder ends without a release() (the lock is then gone). */
+  readonly lost: Promise<string | undefined>;
+  /** Drop the lock (and nothing else). Idempotent. */
+  release(): Promise<void>;
+}
+
+/** Create the lock file if it is missing, never replacing an existing one. */
+function ensureLockFile(path: string, gid: number | undefined): void {
+  mkdirSync(dirname(path), { recursive: true });
+  // "a": create, never truncate; an existing file keeps its inode.
+  closeSync(openSync(path, "a", 0o660));
+  try {
+    chmodSync(path, 0o660);
+    if (gid !== undefined) chownSync(path, -1, gid);
+  } catch {
+    /* not ours to change: the lock does not need it */
+  }
+}
+
+/**
+ * Take the exclusive lock, without waiting. Throws `LoginLockHeld` when
+ * another process holds it.
+ */
+export function acquireLoginLock(
+  path: string,
+  o: { flockBin?: string; gid?: number | undefined } = {},
+): Promise<LoginLock> {
+  ensureLockFile(path, o.gid);
+  return new Promise<LoginLock>((resolve, reject) => {
+    const child = spawn(
+      o.flockBin ?? "flock",
+      ["-n", "-E", String(LOCK_HELD_EXIT), path, "sh", "-c", "echo locked; exec cat"],
+      { stdio: ["pipe", "pipe", "pipe"] },
+    );
+    let settled = false;
+    let stderr = "";
+    const done = new Promise<void>((r) => child.once("exit", () => r()));
+    child.stderr.on("data", (c: unknown) => {
+      stderr += String(c);
+    });
+    child.stdout.once("data", () => {
+      if (settled) return;
+      settled = true;
+      let released = false;
+      resolve({
+        path,
+        lost: done.then(() => (released ? undefined : "the lock holder exited")),
+        release: async () => {
+          if (!released) {
+            released = true;
+            child.stdin.end();
+          }
+          await done;
+        },
+      });
+    });
+    child.once("error", (err) => {
+      if (settled) return;
+      settled = true;
+      reject(new Error(`could not run flock: ${err.message}`));
+    });
+    child.once("exit", (code) => {
+      if (settled) return;
+      settled = true;
+      if (code === LOCK_HELD_EXIT) reject(new LoginLockHeld(path));
+      else reject(new Error(`flock exited ${code}: ${stderr.trim() || "no output"}`));
+    });
+  });
+}

package/src/loginrefresh/main.ts

@@ -0,0 +1,59 @@
+// Entry point of the login refresher: `node dist/src/loginrefresh/main.js`,
+// spawned and supervised by the daemon (supervisor.ts) by path. Configured by
+// env, so this process reads no config.toml:
+//
+//   QCR_LOGIN_AGENT_DIR   pi's agent dir (default $PI_CODING_AGENT_DIR, else ~/.pi/agent)
+//   QCR_LOGIN_MARGIN_MIN  the refresh margin beyond pi's window, in minutes
+//   QCR_LOGIN_GID         the login group a new file is given (default: auth.json's)
+//
+// Exit 75: another refresher holds the lock (the supervisor backs off).
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { LOCK_HELD_EXIT, LoginLockHeld } from "./lock.js";
+import { piOAuthRefresh } from "./pirefresh.js";
+import { LoginRefresher } from "./refresher.js";
+
+const log = (msg: string, extra?: unknown): void => {
+  const tail =
+    extra === undefined ? "" : ` ${extra instanceof Error ? extra.message : JSON.stringify(extra)}`;
+  console.log(`${msg}${tail}`);
+};
+
+const agentDir =
+  process.env["QCR_LOGIN_AGENT_DIR"]?.trim() ||
+  process.env["PI_CODING_AGENT_DIR"]?.trim() ||
+  join(process.env["HOME"]?.trim() || homedir(), ".pi", "agent");
+const marginMin = Number(process.env["QCR_LOGIN_MARGIN_MIN"] ?? "90");
+const gid = Number(process.env["QCR_LOGIN_GID"] ?? "");
+
+try {
+  const refresher = await LoginRefresher.start({
+    agentDir,
+    refresh: piOAuthRefresh,
+    marginMs: (Number.isFinite(marginMin) && marginMin > 0 ? marginMin : 90) * 60_000,
+    gid: Number.isInteger(gid) && gid > 0 ? gid : undefined,
+    log,
+  });
+  log(`login refresh: up — owns ${join(agentDir, "auth.json")}`);
+  let stopping = false;
+  const shutdown = (signal: string): void => {
+    if (stopping) return;
+    stopping = true;
+    log(`login refresh: ${signal} — stopping`);
+    void refresher.stop().finally(() => process.exit(0));
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  void refresher.lost.then((why) => {
+    if (stopping || !why) return;
+    log(`login refresh: ${why} — exiting so the supervisor starts a clean one`);
+    process.exit(1);
+  });
+} catch (err) {
+  if (err instanceof LoginLockHeld) {
+    log(`login refresh: ${err.message} — refusing to start`);
+    process.exit(LOCK_HELD_EXIT);
+  }
+  log("login refresh: could not start", err);
+  process.exit(1);
+}

package/src/loginrefresh/pirefresh.ts

@@ -0,0 +1,57 @@
+// pi-ai's own OAuth refresh for a provider: the one file in the refresher that
+// touches pi. Deep-imported by file path (the package's export map publishes no
+// OAuth flow), like the SDK host's dispatcher (packages/pi-plugin/src/engine/pisdk.ts), so the
+// refresh is exactly what pi itself would do. The daemon never imports this
+// module: it spawns main.js, which does.
+//
+// VERIFY-ON-PIN (pi-ai 1.3.0, re-read at 1.4.0): `dist/auth/oauth/load.js` exports the loaders
+// below, each resolving to an `OAuthAuth` whose `refresh(credential, signal)`
+// returns the new credential. A bump that moves or renames them makes the
+// refresh fail loudly (a `login_refresh_failed` anomaly), never silently.
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { RefreshFn } from "./refresher.js";
+
+const PI_AI = "@earendil-works/pi-ai";
+
+/** A provider id (its key in auth.json) to the pi-ai loader of its OAuth flow. */
+export const OAUTH_LOADERS: Readonly<Record<string, string>> = {
+  anthropic: "loadAnthropicOAuth",
+  "openai-codex": "loadOpenAICodexOAuth",
+  "github-copilot": "loadGitHubCopilotOAuth",
+  openrouter: "loadOpenRouterOAuth",
+  "kimi-coding": "loadKimiCodingOAuth",
+  meta: "loadMetaOAuth",
+  xai: "loadXaiOAuth",
+};
+
+/** The installed pi-ai package directory, found on the module search path. */
+export function piAiDir(): string {
+  const req = createRequire(import.meta.url);
+  for (const base of req.resolve.paths(PI_AI) ?? []) {
+    const dir = join(base, PI_AI);
+    if (existsSync(join(dir, "package.json"))) return dir;
+  }
+  throw new Error(`${PI_AI} not found on the module search path`);
+}
+
+interface OAuthFlow {
+  refresh(credential: unknown, signal: AbortSignal): Promise<Record<string, unknown>>;
+}
+
+export const piOAuthRefresh: RefreshFn = async (provider, credential, signal) => {
+  const loaderName = OAUTH_LOADERS[provider];
+  if (!loaderName) throw new Error(`no pi-ai OAuth flow is known for provider ${provider}`);
+  const file = join(piAiDir(), "dist", "auth", "oauth", "load.js");
+  const mod = (await import(pathToFileURL(file).href)) as Record<string, unknown>;
+  const loader = mod[loaderName];
+  if (typeof loader !== "function")
+    throw new Error(
+      `pi-ai's ${loaderName} is gone from ${file}: the pinned pi drifted (VERIFY-ON-PIN)`,
+    );
+  const flow = await (loader as () => Promise<OAuthFlow>)();
+  const fresh = await flow.refresh(credential, signal);
+  return fresh;
+};