@shogo-ai/worker 1.0.10

package/src/commands/agent.ts

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * `shogo` / `shogo chat` — launch the interactive coding agent.
+ *
+ * License boundary: this file (MIT) does NOT import `@shogo/agent-runtime`.
+ * It resolves the AGPL agent-runtime binary on disk and spawns it in
+ * interactive mode as a separate OS process (stdio inherited), passing the
+ * working directory and proxy-billing credentials via env. The agent loop
+ * runs in-process inside that AGPL binary — there is no HTTP runtime hop.
+ *
+ * Billing: the spawned runtime is pointed at the Shogo AI proxy
+ * (`AI_PROXY_URL` = `<cloud>/api/ai/v1`) authenticated with the logged-in
+ * workspace key (`AI_PROXY_TOKEN` = `shogo_sk_…`). The proxy accepts the key
+ * directly, so all LLM usage bills to the account with no token minting.
+ */
+import { spawn } from 'node:child_process';
+import { resolve as resolvePath } from 'node:path';
+import pc from 'picocolors';
+import { resolveConfig } from '../lib/config.ts';
+import { resolveRuntime, formatMissingRuntimeError, type ResolvedRuntime } from '../lib/runtime-resolver.ts';
+
+export interface AgentFlags {
+  /** Headless one-shot prompt (`-p` / `--print`). `''` = read, but no value. */
+  print?: string;
+  /** Model id for new turns (`--model`). */
+  model?: string;
+  /** Working directory to operate in (`--cwd`). Defaults to $PWD. */
+  cwd?: string;
+  /** Override the agent-runtime binary path (`--runtime-bin`). */
+  runtimeBin?: string;
+  /** Disable the Ink TUI, use the plain readline renderer (`--no-tui`). */
+  noTui?: boolean;
+  /** API key override (else config/env). */
+  apiKey?: string;
+  /** Cloud URL override (else config/env). */
+  cloudUrl?: string;
+}
+
+export interface AgentSpawnPlan {
+  bin: string;
+  args: string[];
+  env: NodeJS.ProcessEnv;
+  cwd: string;
+}
+
+/**
+ * Build the spawn argv + env for the interactive runtime. Pure — no IO — so
+ * it is unit-testable.
+ */
+export function buildAgentSpawn(input: {
+  flags: AgentFlags;
+  config: { apiKey: string; cloudUrl: string };
+  runtime: ResolvedRuntime;
+  baseEnv?: NodeJS.ProcessEnv;
+}): AgentSpawnPlan {
+  const { flags, config, runtime } = input;
+  const cwd = flags.cwd ? resolvePath(flags.cwd) : process.cwd();
+
+  const args: string[] = ['interactive'];
+  if (flags.print !== undefined) args.push('-p', flags.print);
+  if (flags.noTui) args.push('--no-tui');
+
+  const cloudUrl = config.cloudUrl.replace(/\/$/, '');
+
+  const env: NodeJS.ProcessEnv = {
+    ...(input.baseEnv ?? process.env),
+    SHOGO_INTERACTIVE: '1',
+    SHOGO_INTERACTIVE_CWD: cwd,
+    // The runtime derives WORKSPACE_DIR from these — point them at the CWD so
+    // the agent reads/writes the user's actual directory.
+    PROJECT_DIR: cwd,
+    WORKSPACE_DIR: cwd,
+    SHOGO_API_URL: cloudUrl,
+    SHOGO_CLOUD_URL: cloudUrl,
+    SHOGO_API_KEY: config.apiKey,
+    // Proxy billing: route all LLM traffic through the Shogo proxy using the
+    // workspace key (accepted directly by the proxy).
+    AI_PROXY_URL: `${cloudUrl}/api/ai/v1`,
+    AI_PROXY_TOKEN: config.apiKey,
+    NODE_ENV: 'production',
+  };
+  if (flags.model) env.SHOGO_MODEL = flags.model;
+  if (flags.print !== undefined) env.SHOGO_PRINT_PROMPT = flags.print;
+
+  return { bin: runtime.path, args, env, cwd };
+}
+
+/**
+ * Resolve config + runtime binary and exec the interactive agent. Resolves
+ * with the child's exit code.
+ */
+export async function runAgent(flags: AgentFlags = {}): Promise<void> {
+  // Gate on login — resolveConfig throws a `shogo login` hint when no key.
+  const cfg = resolveConfig({ apiKey: flags.apiKey, cloudUrl: flags.cloudUrl });
+
+  const runtime = resolveRuntime({ flag: flags.runtimeBin });
+  if (!runtime) {
+    console.error(pc.red(formatMissingRuntimeError({ flag: flags.runtimeBin })));
+    process.exit(1);
+  }
+
+  const plan = buildAgentSpawn({
+    flags,
+    config: { apiKey: cfg.apiKey, cloudUrl: cfg.cloudUrl },
+    runtime,
+  });
+
+  const code = await new Promise<number>((resolveExit) => {
+    const child = spawn(plan.bin, plan.args, {
+      cwd: plan.cwd,
+      env: plan.env,
+      stdio: 'inherit',
+    });
+    child.on('error', (err) => {
+      console.error(pc.red(`✗ Failed to launch agent-runtime: ${err.message}`));
+      resolveExit(1);
+    });
+    child.on('exit', (exitCode) => resolveExit(exitCode ?? 0));
+  });
+
+  process.exit(code);
+}

package/src/commands/config.ts

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+import pc from 'picocolors';
+import { loadConfig, saveConfig } from '../lib/config.ts';
+import { CONFIG_FILE } from '../lib/paths.ts';
+
+export async function runConfigShow(): Promise<void> {
+  const cfg = loadConfig();
+  if (Object.keys(cfg).length === 0) {
+    console.log(pc.dim('(no config — run `shogo login` or `shogo config set`)'));
+    return;
+  }
+  const masked = { ...cfg, apiKey: cfg.apiKey ? `***${cfg.apiKey.slice(-4)}` : undefined };
+  console.log(pc.dim(`file: ${CONFIG_FILE}`));
+  console.log(JSON.stringify(masked, null, 2));
+}
+
+export async function runConfigSet(key: string, value: string): Promise<void> {
+  const allowed = ['apiKey', 'cloudUrl', 'name', 'workerDir', 'port'] as const;
+  if (!allowed.includes(key as any)) {
+    console.error(pc.red(`Unknown key: ${key}`));
+    console.error(pc.dim(`Allowed: ${allowed.join(', ')}`));
+    process.exit(1);
+  }
+  const cfg = loadConfig();
+  (cfg as any)[key] = key === 'port' ? parseInt(value, 10) : value;
+  saveConfig(cfg);
+  console.log(pc.green(`✓ ${key} set`));
+}

package/src/commands/doctor.ts

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * `shogo doctor` — diagnose and repair a wedged local Shogo database.
+ *
+ *   shogo doctor                 — detect + (with confirmation) repair
+ *   shogo doctor --check         — detect only, never mutate
+ *   shogo doctor --yes           — repair without the confirmation prompt
+ *   shogo doctor --db <path>     — target a specific shogo.db
+ *   shogo doctor --bun <path>    — use a specific bun binary
+ *   shogo doctor --no-backup     — skip the pre-repair backup (discouraged)
+ *
+ * Clears `_prisma_migrations` rows left in a failed (P3009) state so the
+ * desktop app can re-apply migrations on its next launch. Always backs up
+ * the database first unless `--no-backup` is passed.
+ */
+import { createInterface } from 'node:readline';
+import pc from 'picocolors';
+import {
+  detectFailedMigrations,
+  runDatabaseDoctor,
+  resolveDesktopDbPath,
+  resolveBunBinary,
+  type FailedMigration,
+} from '../lib/db-doctor.ts';
+
+export interface DoctorFlags {
+  check?: boolean;
+  yes?: boolean;
+  db?: string;
+  bun?: string;
+  backup?: boolean; // commander sets `backup: false` for --no-backup
+}
+
+function printFailures(failures: FailedMigration[]): void {
+  for (const f of failures) {
+    const when = Number.isFinite(f.startedAt) ? new Date(f.startedAt).toISOString() : 'unknown time';
+    const firstLine = (f.errorExcerpt ?? '').split('\n')[0]?.trim();
+    console.log(`  ${pc.yellow('•')} ${pc.bold(f.name)} ${pc.dim(`(attempted ${when})`)}`);
+    if (firstLine) console.log(`    ${pc.dim(firstLine)}`);
+  }
+}
+
+async function confirm(question: string): Promise<boolean> {
+  // Non-interactive (CI, piped) stdin: refuse rather than hang.
+  if (!process.stdin.isTTY) {
+    console.log(pc.dim('(stdin is not a TTY — re-run with --yes to repair non-interactively)'));
+    return false;
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise<string>((resolve) => rl.question(question, resolve));
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runDoctor(flags: DoctorFlags = {}): Promise<void> {
+  const dbPath = flags.db ?? resolveDesktopDbPath();
+  const bunPath = resolveBunBinary(flags.bun);
+
+  if (!bunPath) {
+    throw new Error(
+      'Could not find a usable `bun` binary (needed to inspect the SQLite database).\n' +
+        '  • Install Bun (https://bun.sh) so `bun` is on your PATH, or\n' +
+        '  • pass --bun <path> pointing at the bun shipped inside the Shogo app\n' +
+        "    (e.g. /Applications/Shogo.app/Contents/Resources/bun/bun on macOS).",
+    );
+  }
+
+  console.log(pc.dim(`Database: ${dbPath}`));
+  console.log(pc.dim(`Bun:      ${bunPath}`));
+  console.log();
+
+  const failures = detectFailedMigrations(bunPath, dbPath);
+
+  if (failures.length === 0) {
+    console.log(pc.green('✓ No failed migrations detected — your local database looks healthy.'));
+    return;
+  }
+
+  console.log(pc.red(`✗ Found ${failures.length} failed migration(s):`));
+  printFailures(failures);
+  console.log();
+
+  if (flags.check) {
+    console.log(
+      pc.dim('Run `shogo doctor` (without --check) to back up the database and clear these records.'),
+    );
+    // Signal "needs repair" to scripts/CI without throwing a stack trace.
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!flags.yes) {
+    const backupNote =
+      flags.backup === false
+        ? pc.red('This will NOT create a backup (--no-backup).')
+        : 'Your database will be backed up to a .bak-<timestamp> file first.';
+    console.log(backupNote);
+    const ok = await confirm(pc.bold('Clear these failed migration records and repair? [y/N] '));
+    if (!ok) {
+      console.log(pc.dim('Aborted — no changes made.'));
+      process.exitCode = 1;
+      return;
+    }
+    console.log();
+  }
+
+  const result = runDatabaseDoctor({
+    bunPath,
+    dbPath,
+    skipBackup: flags.backup === false,
+    log: (line) => console.log(pc.dim(`  ${line}`)),
+  });
+
+  console.log();
+  if (result.status === 'repaired') {
+    console.log(pc.green(`✓ ${result.message}`));
+    if (result.backupPath) console.log(pc.dim(`  Backup: ${result.backupPath}`));
+    console.log(pc.bold('\n  → Relaunch the Shogo app to finish applying migrations.'));
+  } else {
+    console.log(pc.red(`✗ ${result.message}`));
+    if (result.backupPath) console.log(pc.dim(`  Backup: ${result.backupPath}`));
+    process.exitCode = 1;
+  }
+}

package/src/commands/login.ts

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * `shogo login` — pair this machine with Shogo Cloud.
+ *
+ * Two modes, in priority order:
+ *
+ *   1. `--api-key <key>` flag, or `SHOGO_API_KEY` env var
+ *      → CI / headless mode. Validate against cloud, save, done.
+ *
+ *   2. Interactive (default)
+ *      → Poll-based device flow (see lib/cloud-login.ts):
+ *          POST /api/cli/login/start  → state + authUrl
+ *          open authUrl in browser    → user approves on cloud
+ *          GET  /api/cli/login/poll   → key once approved
+ *
+ * The minted key is written to ~/.shogo/config.json with mode 0600 so
+ * other local users can't read it. The same file is what
+ * `shogo worker start` reads on boot.
+ *
+ * The legacy "paste a shogo_sk_ key at the prompt" flow is still
+ * supported via `--api-key`; it just isn't the default any more.
+ */
+import pc from 'picocolors';
+import { loadConfig, saveConfig } from '../lib/config.ts';
+import { runCloudLogin, CloudLoginError } from '../lib/cloud-login.ts';
+import { getOrCreateDeviceId } from '../lib/device-id.ts';
+
+export interface LoginFlags {
+  apiKey?: string;
+  cloudUrl?: string;
+  name?: string;
+  workspace?: string;
+  noBrowser?: boolean;
+}
+
+const DEFAULT_CLOUD_URL = 'https://studio.shogo.ai';
+
+export async function runLogin(flags: LoginFlags): Promise<void> {
+  const cfg = loadConfig();
+  const cloudUrl = (flags.cloudUrl || cfg.cloudUrl || DEFAULT_CLOUD_URL).replace(/\/$/, '');
+
+  const escapeKey = flags.apiKey || process.env.SHOGO_API_KEY;
+  if (escapeKey) {
+    await loginWithApiKey({ key: escapeKey, cloudUrl, cfg, name: flags.name });
+    return;
+  }
+
+  const deviceId = getOrCreateDeviceId();
+  let result;
+  try {
+    result = await runCloudLogin({
+      cloudUrl,
+      deviceId,
+      deviceName: flags.name,
+      workspaceId: flags.workspace,
+      openBrowser: !flags.noBrowser,
+    });
+  } catch (err: any) {
+    if (err instanceof CloudLoginError) {
+      console.error(pc.red(`✗ ${err.message}`));
+      if (err.kind === 'transport') {
+        console.error(pc.dim(`  If your network blocks browsers, run with --api-key <key> instead.`));
+      }
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  cfg.apiKey = result.key;
+  cfg.cloudUrl = cloudUrl;
+  if (flags.name) cfg.name = flags.name;
+  saveConfig(cfg);
+
+  console.log('');
+  console.log(pc.green('✓ Signed in to Shogo Cloud'));
+  if (result.workspace) console.log(pc.dim('  workspace: ') + result.workspace);
+  if (result.email) console.log(pc.dim('  email:     ') + result.email);
+  console.log(pc.dim('  saved to:  ') + '~/.shogo/config.json');
+  console.log('');
+  console.log(pc.dim('  next: ') + 'shogo worker start');
+}
+
+interface ApiKeyOpts {
+  key: string;
+  cloudUrl: string;
+  cfg: ReturnType<typeof loadConfig>;
+  name?: string;
+}
+
+async function loginWithApiKey({ key, cloudUrl, cfg, name }: ApiKeyOpts): Promise<void> {
+  if (!/^shogo_sk_/.test(key)) {
+    console.error(pc.red('✗ API key should start with "shogo_sk_". Copy it verbatim from the API Keys page.'));
+    process.exit(1);
+  }
+
+  // Mirror apps/api/src/routes/local-auth.ts: re-validate against cloud
+  // before persisting so the user gets immediate feedback on a bad key.
+  let validation: { valid?: boolean; error?: string; workspace?: { name?: string } | null; user?: { email?: string } | null };
+  try {
+    const res = await fetch(`${cloudUrl}/api/api-keys/validate`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    validation = await res.json().catch(() => ({} as any)) as typeof validation;
+    if (!res.ok || !validation?.valid) {
+      console.error(pc.red(`✗ ${validation?.error || `Cloud rejected the key (HTTP ${res.status}).`}`));
+      process.exit(1);
+    }
+  } catch (err: any) {
+    console.error(pc.red(`✗ Cannot reach Shogo Cloud at ${cloudUrl}: ${err?.message ?? err}`));
+    process.exit(1);
+  }
+
+  cfg.apiKey = key;
+  cfg.cloudUrl = cloudUrl;
+  if (name) cfg.name = name;
+  saveConfig(cfg);
+
+  console.log(pc.green('✓ API key saved to ~/.shogo/config.json'));
+  if (validation.workspace?.name) console.log(pc.dim('  workspace: ') + validation.workspace.name);
+  if (validation.user?.email) console.log(pc.dim('  email:     ') + validation.user.email);
+  console.log(pc.dim('  next: ') + 'shogo worker start');
+}

package/src/commands/logs.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+import { spawn } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import pc from 'picocolors';
+import { WORKER_LOG, WORKER_ERR } from '../lib/paths.ts';
+
+export interface LogsFlags { follow?: boolean; err?: boolean }
+
+export async function runLogs(flags: LogsFlags): Promise<void> {
+  const file = flags.err ? WORKER_ERR : WORKER_LOG;
+  if (!existsSync(file)) {
+    console.log(pc.dim('No logs yet.'));
+    return;
+  }
+  const args = flags.follow ? ['-F', '-n', '200', file] : ['-n', '200', file];
+  const child = spawn('tail', args, { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code ?? 0));
+
+  if (!flags.follow) {
+    const size = statSync(file).size;
+    if (size === 0) console.log(pc.dim('(log file is empty)'));
+  }
+}

package/src/commands/project-checkout.ts

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * `shogo project checkout <projectId> [--at <sha|name>] [--unshallow]`
+ *
+ * Rolls the worker's local copy of a project back (or forward) to a
+ * specific git checkpoint. By default this targets the project's
+ * current cloud HEAD — i.e. it's the worker-side equivalent of
+ * `git pull --rebase`.
+ *
+ * `--at` accepts:
+ *   - A full or short SHA (anything `git rev-parse` can resolve).
+ *   - A checkpoint name (resolved against
+ *     `GET /api/projects/:projectId/checkpoints?limit=…`).
+ *
+ * `--unshallow` first converts the local repo from a shallow clone to
+ * a full clone — necessary when checking out a historical SHA that
+ * lives beyond the original `--depth=1` window.
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import pc from 'picocolors';
+import { resolveConfig } from '../lib/config.ts';
+import { projectDirFor } from '../lib/paths.ts';
+import {
+  gitFetchAndReset,
+  gitFetchUnshallow,
+  isGitRepo,
+  runGit,
+} from '../lib/git-cloner.ts';
+
+export interface ProjectCheckoutFlags {
+  /** SHA or checkpoint name. Defaults to remote HEAD. */
+  at?: string;
+  /** Convert a shallow clone to a full one before checking out. */
+  unshallow?: boolean;
+  /** Local dir override. */
+  into?: string;
+  /** API key override. */
+  apiKey?: string;
+  /** Cloud URL override. */
+  cloudUrl?: string;
+}
+
+export async function runProjectCheckout(projectId: string, flags: ProjectCheckoutFlags): Promise<void> {
+  if (!projectId) throw new Error('projectId is required');
+
+  const cfg = resolveConfig({
+    apiKey: flags.apiKey,
+    cloudUrl: flags.cloudUrl,
+  });
+
+  const localDir = resolve(flags.into ?? projectDirFor(projectId, cfg.projectsDir));
+  if (!existsSync(localDir)) {
+    throw new Error(`Local project dir does not exist: ${localDir} — run \`shogo project pull\` first`);
+  }
+  if (!isGitRepo(localDir)) {
+    throw new Error(
+      `${localDir} is not a git repo. \`shogo project checkout\` requires the git sync path; ` +
+        `run \`shogo project pull\` after installing git, or use \`shogo project pull --include\` for file-only restore.`,
+    );
+  }
+
+  console.log(pc.bold(`\nshogo project checkout ${pc.cyan(projectId)}`));
+  console.log(pc.dim('  cloud  ') + cfg.cloudUrl);
+  console.log(pc.dim('  local  ') + localDir);
+  if (flags.at) console.log(pc.dim('  at     ') + flags.at);
+  console.log('');
+
+  if (flags.unshallow) {
+    console.log(pc.dim('Unshallowing repo (this may take a moment)...'));
+    await gitFetchUnshallow({
+      apiUrl: cfg.cloudUrl,
+      apiKey: cfg.apiKey,
+      projectId,
+      localDir,
+    });
+  }
+
+  if (!flags.at) {
+    // Default: fast-forward to remote HEAD.
+    const res = await gitFetchAndReset({
+      apiUrl: cfg.cloudUrl,
+      apiKey: cfg.apiKey,
+      projectId,
+      localDir,
+    });
+    console.log(pc.green(`✓ Reset to ${res.commitSha.slice(0, 8)} (remote HEAD)`));
+    return;
+  }
+
+  // Resolve --at: try as SHA first (cheapest), fall back to checkpoint
+  // name lookup against the cloud listing.
+  let targetSha: string;
+  try {
+    const head = await runGit(['rev-parse', '--verify', `${flags.at}^{commit}`], { cwd: localDir });
+    targetSha = head.stdout.trim();
+  } catch {
+    targetSha = await resolveCheckpointByName(cfg.cloudUrl, cfg.apiKey, projectId, flags.at);
+    console.log(pc.dim(`  resolved checkpoint "${flags.at}" → ${targetSha.slice(0, 8)}`));
+  }
+
+  // Fetch up to that SHA (covers the shallow-window case for users who
+  // didn't pass --unshallow but are reaching for a slightly older sha).
+  try {
+    await gitFetchAndReset({
+      apiUrl: cfg.cloudUrl,
+      apiKey: cfg.apiKey,
+      projectId,
+      localDir,
+      branch: targetSha,
+    });
+  } catch {
+    // If we can't fetch directly to that sha (it's outside the shallow
+    // window), do a full unshallow and retry.
+    if (!flags.unshallow) {
+      console.log(pc.yellow('  fetch failed; unshallowing and retrying...'));
+      await gitFetchUnshallow({
+        apiUrl: cfg.cloudUrl,
+        apiKey: cfg.apiKey,
+        projectId,
+        localDir,
+      });
+      await gitFetchAndReset({
+        apiUrl: cfg.cloudUrl,
+        apiKey: cfg.apiKey,
+        projectId,
+        localDir,
+        branch: targetSha,
+      });
+    } else {
+      throw new Error(`Cannot reach commit ${targetSha} in local clone`);
+    }
+  }
+
+  // Final reset to the requested sha (FETCH_HEAD may differ if we
+  // fetched a branch and the user asked for a specific commit).
+  await runGit(['reset', '--hard', targetSha], { cwd: localDir });
+  console.log(pc.green(`✓ Checked out ${targetSha.slice(0, 8)}`));
+}
+
+interface CheckpointListResponse {
+  ok: true;
+  checkpoints: Array<{ id: string; commitSha: string; name: string | null; commitMessage: string | null; createdAt: string }>;
+  hasMore: boolean;
+}
+
+/**
+ * Resolve a checkpoint by user-facing name (case-insensitive).
+ * Strategy: ask the cloud for the most recent N checkpoints, pick the
+ * one whose `name` or first 8 chars of `commitMessage` matches.
+ */
+async function resolveCheckpointByName(
+  cloudUrl: string,
+  apiKey: string,
+  projectId: string,
+  needle: string,
+): Promise<string> {
+  const url = `${cloudUrl.replace(/\/+$/, '')}/api/projects/${encodeURIComponent(projectId)}/checkpoints?limit=100`;
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to list checkpoints: HTTP ${res.status}`);
+  }
+  const body = (await res.json()) as CheckpointListResponse;
+  const norm = needle.toLowerCase();
+  const match = body.checkpoints.find((cp) => {
+    if (cp.name && cp.name.toLowerCase() === norm) return true;
+    if (cp.commitSha.startsWith(needle)) return true;
+    if (cp.commitMessage && cp.commitMessage.toLowerCase().includes(norm)) return true;
+    return false;
+  });
+  if (!match) {
+    throw new Error(`No checkpoint matches "${needle}" (searched ${body.checkpoints.length} most recent)`);
+  }
+  return match.commitSha;
+}