exponential-cli 1.18.1 → 1.20.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/program.ts
-import { Command as Command25 } from "commander";
+import { Command as Command26 } from "commander";
 
 // src/commands/auth.ts
 import { Command } from "commander";
@@ -1187,6 +1187,41 @@ Tickets (${tickets.length} total)`));
   }
   console.log();
 }
+function transformTicketSearchHit(hit) {
+  return {
+    id: hit.id,
+    number: hit.number,
+    shortId: hit.shortId,
+    title: hit.title,
+    status: hit.status,
+    priority: hit.priority,
+    assignee: hit.assignee ?? null
+  };
+}
+function outputTicketSearchJson(hits, query) {
+  console.log(JSON.stringify({
+    query,
+    tickets: hits.map(transformTicketSearchHit),
+    total: hits.length
+  }, null, 2));
+}
+function outputTicketSearchPretty(hits, query) {
+  if (hits.length === 0) {
+    console.log(chalk3.gray(`No tickets match "${query}".`));
+    return;
+  }
+  console.log(chalk3.bold(`
+Tickets matching "${query}" (${hits.length})`));
+  console.log(chalk3.gray("\u2500".repeat(50)));
+  for (const t of hits) {
+    const id = t.shortId ?? (t.number != null ? `#${t.number}` : "?");
+    const statusBadge2 = chalk3[getTicketStatusColor(t.status)](`[${t.status}]`);
+    const assignee = t.assignee ? chalk3.gray(` \u2014 ${t.assignee.name ?? t.assignee.id}`) : "";
+    console.log(`  ${statusBadge2} ${chalk3.bold(id)} ${t.title}${assignee}`);
+    console.log(chalk3.gray(`    ID: ${t.id}`));
+  }
+  console.log();
+}
 function transformTicket(ticket) {
   const detail = ticket;
   return {
@@ -3959,6 +3994,23 @@ function createEpicsCommand() {
       }
     }
   );
+  epics.command("delete").description(
+    "Delete an epic. Its tickets and actions are unlinked from it (epicId is cleared), not deleted. Only workspace owners/admins and the epic owner can delete."
+  ).requiredOption("--id <id>", "Epic CUID").action(async (options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+    try {
+      const client = getClient();
+      await client.epics.delete(options.id);
+      if (useJson) {
+        console.log(JSON.stringify({ deleted: true, id: options.id }, null, 2));
+      } else {
+        console.log("\n\u2713 Epic deleted");
+      }
+    } catch (error) {
+      handleError(error, useJson);
+    }
+  });
   return epics;
 }
 
@@ -4069,6 +4121,42 @@ function createStoriesCommand() {
       }
     }
   );
+  stories.command("update").description("Update a user story. Only the fields you pass are written.").requiredOption("--id <id>", "User story CUID").option("--as-a <text>", '"As a ..." actor').option("--i-want <text>", '"I want ..." capability').option("--so-that <text>", '"So that ..." outcome').option("--acceptance <text>", "Acceptance criteria").option("--scope <id>", 'Feature scope CUID to group the story under (or "null" to ungroup)').action(
+    async (options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+      try {
+        const client = getClient();
+        const story = await client.userStories.update({
+          id: options.id,
+          asA: options.asA,
+          iWant: options.iWant,
+          soThat: options.soThat,
+          acceptanceCriteria: options.acceptance,
+          scopeId: options.scope === "null" ? null : options.scope
+        });
+        if (useJson) outputUserStoryJson(story);
+        else {
+          console.log("\n\u2713 User story updated");
+          outputUserStoryPretty(story);
+        }
+      } catch (error) {
+        handleError(error, useJson);
+      }
+    }
+  );
+  stories.command("rm").description("Delete a user story").requiredOption("--id <id>", "User story CUID").action(async (options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+    try {
+      const client = getClient();
+      const result = await client.userStories.delete(options.id);
+      if (useJson) console.log(JSON.stringify(result, null, 2));
+      else console.log("\n\u2713 User story deleted");
+    } catch (error) {
+      handleError(error, useJson);
+    }
+  });
   return stories;
 }
 
@@ -5635,6 +5723,84 @@ function createProductsCommand() {
       }
     }
   );
+  products.command("update <slugOrId>").description("Update a product. Only the fields you pass are written.").option("-n, --name <name>", "New name").option("-d, --description <text>", "New description").option("--icon <icon>", "Icon shortcode").option("--color <color>", "Color").option("--fun-ticket-ids", "Use fun ticket ids (e.g. prime.toucan) for new tickets").option("--no-fun-ticket-ids", "Use numbered ticket ids for new tickets").option("--workspace <slug|id>", "Workspace (required when using a slug)").action(
+    async (slugOrId, options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+      try {
+        const client = getClient();
+        const workspaceId = await resolveWorkspaceId(client, options.workspace);
+        const existing = await client.products.resolve(workspaceId, slugOrId);
+        const product = await client.products.update({
+          id: existing.id,
+          name: options.name,
+          description: options.description,
+          icon: options.icon,
+          color: options.color,
+          funTicketIds: options.funTicketIds
+        });
+        if (useJson) outputProductJson(product);
+        else {
+          console.log("\n\u2713 Product updated");
+          outputProductPretty(product);
+        }
+      } catch (error) {
+        handleError(error, useJson);
+      }
+    }
+  );
+  products.command("delete <slugOrId>").description(
+    "Delete a product. Deleting a product deletes everything under it \u2014 its features, tickets, epics, research and retrospectives cascade \u2014 so this refuses while it still has any of them, unless --force."
+  ).option("--force", "Delete anyway, taking everything under it with it (destructive)").option("--workspace <slug|id>", "Workspace (required when using a slug)").action(
+    async (slugOrId, options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+      try {
+        const client = getClient();
+        const workspaceId = await resolveWorkspaceId(client, options.workspace);
+        const product = await client.products.resolve(workspaceId, slugOrId);
+        const counts = product._count ?? {};
+        const blockers = [
+          counts.features ? `${counts.features} feature(s)` : null,
+          counts.tickets ? `${counts.tickets} ticket(s)` : null,
+          counts.researches ? `${counts.researches} research item(s)` : null,
+          counts.retrospectives ? `${counts.retrospectives} retrospective(s)` : null
+        ].filter(Boolean);
+        if (blockers.length > 0 && !options.force) {
+          const payload2 = {
+            deleted: false,
+            id: product.id,
+            slug: product.slug,
+            reason: `has ${blockers.join(", ")}`,
+            counts
+          };
+          if (useJson) console.log(JSON.stringify(payload2, null, 2));
+          else {
+            console.error(
+              `Product "${product.name}" has ${blockers.join(", ")}. Deleting it deletes them too.
+Re-run with --force to delete it anyway.`
+            );
+          }
+          process.exitCode = 1;
+          return;
+        }
+        await client.products.delete(product.id);
+        const payload = {
+          deleted: true,
+          id: product.id,
+          slug: product.slug,
+          counts
+        };
+        if (useJson) console.log(JSON.stringify(payload, null, 2));
+        else {
+          console.log("\n\u2713 Product deleted");
+          if (blockers.length) console.log(`  ${blockers.join(", ")} went with it`);
+        }
+      } catch (error) {
+        handleError(error, useJson);
+      }
+    }
+  );
   return products;
 }
 
@@ -5784,8 +5950,571 @@ Re-run with --force to delete it anyway.`
   return projects;
 }
 
-// src/commands/search.ts
+// src/commands/runner.ts
 import { Command as Command20 } from "commander";
+import { hostname, homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { execFileSync } from "child_process";
+import { mkdirSync as mkdirSync3 } from "fs";
+import { fileURLToPath } from "url";
+import { resolve } from "path";
+
+// src/runner/config.ts
+import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { dirname, join } from "path";
+function runnerConfigPath() {
+  return join(dirname(getConfigPath()), "runner.json");
+}
+function loadRunnerConfig(path = runnerConfigPath()) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync2(path, "utf-8"));
+  } catch {
+    throw new Error(`Could not parse ${path}; fix or delete it`);
+  }
+}
+function saveRunnerConfig(values, path = runnerConfigPath()) {
+  const next = { ...loadRunnerConfig(path), ...values };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(next, null, 2) + "\n");
+  return next;
+}
+
+// src/runner/stream.ts
+var MAX_PAYLOAD_TEXT = 2e3;
+function clip(value, max = MAX_PAYLOAD_TEXT) {
+  const text = typeof value === "string" ? value : JSON.stringify(value ?? null);
+  return text.length > max ? `${text.slice(0, max)}\u2026` : text;
+}
+var StreamParser = class {
+  nextSeq;
+  events = [];
+  resultText = null;
+  isError = false;
+  errorMessage = null;
+  usage = null;
+  sessionId = null;
+  /** The session called ask_owner: the run is parked by the app; the runner must not finish it. */
+  askedOwner = false;
+  /** The session called finish_run itself: the runner's final finish is a no-op. */
+  finishedViaTool = false;
+  constructor(firstSeq = 1) {
+    this.nextSeq = firstSeq;
+  }
+  push(kind, payload) {
+    const event = { seq: this.nextSeq++, kind, payload };
+    this.events.push(event);
+    return event;
+  }
+  /** Feed one line; returns the events it produced (possibly none). */
+  feed(line) {
+    const trimmed = line.trim();
+    if (!trimmed) return [];
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      return [];
+    }
+    const before = this.events.length;
+    switch (parsed.type) {
+      case "system":
+        if (parsed.subtype === "init" && typeof parsed.session_id === "string") this.sessionId = parsed.session_id;
+        break;
+      case "assistant": {
+        const content = parsed.message?.content;
+        if (typeof content === "string") {
+          if (content.trim()) this.push("text", { text: clip(content) });
+        } else if (Array.isArray(content)) {
+          for (const block of content) {
+            if (block.type === "tool_use") {
+              const name = block.name ?? "tool";
+              const input = block.input ?? {};
+              if (name.endsWith("__report_progress") && typeof input.text === "string") {
+                this.push("text", { text: clip(input.text, 500) });
+              } else if (name.endsWith("__ask_owner")) {
+                this.askedOwner = true;
+                this.push("tool_call", { tool: "ask-owner", snippet: clip(input.question, 200) });
+              } else if (name.endsWith("__finish_run")) {
+                this.finishedViaTool = true;
+                this.push("tool_call", { tool: "finish-run", readyToClose: input.readyToClose === true });
+              } else {
+                this.push("tool_call", { tool: name, input: clip(block.input, 500) });
+              }
+            } else if (block.type === "text" && typeof block.text === "string" && block.text.trim()) {
+              this.push("text", { text: clip(block.text) });
+            }
+          }
+        }
+        break;
+      }
+      case "user": {
+        const content = parsed.message?.content;
+        if (Array.isArray(content)) {
+          for (const block of content) {
+            if (block.type === "tool_result") {
+              this.push(block.is_error ? "error" : "tool_result", {
+                toolUseId: block.tool_use_id ?? null,
+                output: clip(block.content, 500)
+              });
+            }
+          }
+        }
+        break;
+      }
+      case "result":
+        this.resultText = typeof parsed.result === "string" ? parsed.result : null;
+        this.isError = parsed.is_error === true || (parsed.subtype ?? "").startsWith("error");
+        this.errorMessage = this.isError ? parsed.error ?? parsed.result ?? parsed.subtype ?? "error" : null;
+        this.usage = parsed.usage ?? null;
+        if (typeof parsed.total_cost_usd === "number") {
+          this.usage = { ...this.usage ?? {}, totalCostUsd: parsed.total_cost_usd };
+        }
+        break;
+      default:
+        break;
+    }
+    return this.events.slice(before);
+  }
+  /** Events not yet handed out by a previous `drain`. */
+  drained = 0;
+  drain() {
+    const batch = this.events.slice(this.drained);
+    this.drained = this.events.length;
+    return batch;
+  }
+  snapshot() {
+    return {
+      events: [...this.events],
+      resultText: this.resultText,
+      isError: this.isError,
+      errorMessage: this.errorMessage,
+      usage: this.usage,
+      sessionId: this.sessionId,
+      askedOwner: this.askedOwner,
+      finishedViaTool: this.finishedViaTool
+    };
+  }
+};
+
+// src/runner/mcp.ts
+import { mkdtempSync, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { tmpdir } from "os";
+import { join as join2 } from "path";
+var MCP_SERVER_NAME = "exponential";
+var RUN_TOOL_NAMES = ["report_progress", "ask_owner", "finish_run"];
+function buildMcpConfig(input) {
+  const [command, ...args] = input.command ?? ["npx", "-y", "exponential-mcp"];
+  return {
+    mcpServers: {
+      [MCP_SERVER_NAME]: {
+        command,
+        args,
+        env: {
+          EXPONENTIAL_API_KEY: input.token,
+          EXPONENTIAL_API_URL: input.apiUrl,
+          EXPONENTIAL_RUN_ID: input.runId,
+          EXPONENTIAL_RUNNER_ID: input.runnerId
+        }
+      }
+    }
+  };
+}
+function allowedRunTools(extra = []) {
+  return [...RUN_TOOL_NAMES.map((t) => `mcp__${MCP_SERVER_NAME}__${t}`), ...extra];
+}
+function writeMcpSession(input, extraAllowed = []) {
+  const dir = mkdtempSync(join2(tmpdir(), "exponential-runner-"));
+  const file = join2(dir, "mcp.json");
+  writeFileSync2(file, JSON.stringify(buildMcpConfig(input), null, 2), { mode: 384 });
+  return {
+    args: ["--mcp-config", file, "--allowedTools", allowedRunTools(extraAllowed).join(",")],
+    cleanup: () => rmSync(dir, { recursive: true, force: true })
+  };
+}
+
+// src/runner/retry.ts
+var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+function isRetryableError(error) {
+  const code = error?.data?.code;
+  if (!code) return true;
+  return !["FORBIDDEN", "UNAUTHORIZED", "NOT_FOUND", "PRECONDITION_FAILED", "BAD_REQUEST"].includes(code);
+}
+async function withRetry(fn, options = {}) {
+  const attempts = options.attempts ?? 5;
+  const baseMs = options.baseMs ?? 1e3;
+  const maxMs = options.maxMs ?? 3e4;
+  const retryable = options.retryable ?? isRetryableError;
+  const sleep = options.sleep ?? defaultSleep;
+  const jitter = options.jitter ?? (() => 0.5 + Math.random());
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt === attempts || !retryable(error)) throw error;
+      const delay = Math.min(maxMs, baseMs * 2 ** (attempt - 1)) * jitter();
+      options.log?.(`retry ${attempt}/${attempts - 1} in ${Math.round(delay)}ms: ${error instanceof Error ? error.message : String(error)}`);
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+var Backoff = class {
+  constructor(baseMs, maxMs = 5 * 6e4) {
+    this.baseMs = baseMs;
+    this.maxMs = maxMs;
+  }
+  failures = 0;
+  /** Current wait, before recording an outcome. */
+  get delayMs() {
+    return Math.min(this.maxMs, this.baseMs * 2 ** this.failures);
+  }
+  success() {
+    this.failures = 0;
+  }
+  failure() {
+    this.failures = Math.min(this.failures + 1, 16);
+  }
+};
+
+// src/runner/loop.ts
+var DEFAULT_HEARTBEAT_MS = 6e4;
+var DEFAULT_FLUSH_MS = 5e3;
+var MAX_BATCH = 200;
+function promptsFor(run) {
+  const system = run.messages.filter((m) => m.role === "system").map((m) => m.content).join("\n\n");
+  const user = run.messages.filter((m) => m.role === "user").map((m) => m.content).join("\n\n");
+  return { systemPrompt: system, prompt: user || `You have been assigned the action "${run.action.name}".` };
+}
+async function runOnce(options) {
+  const { client, runnerId, cwd, spawn: spawn2 } = options;
+  const log = options.log ?? (() => void 0);
+  const run = await client.agentRuns.claim(runnerId);
+  if (!run) return null;
+  log(`claimed run ${run.id} for action "${run.action.name}"`);
+  const parser = new StreamParser(1);
+  let eventsSent = 0;
+  let cancelled = false;
+  const retry = { log, sleep: options.sleep, attempts: options.retryAttempts };
+  let pending = [];
+  const flush = async () => {
+    pending.push(...parser.drain());
+    while (pending.length > 0) {
+      const slice = pending.slice(0, MAX_BATCH);
+      await withRetry(() => client.agentRuns.appendEvents(run.id, slice, runnerId), retry);
+      pending = pending.slice(slice.length);
+      eventsSent += slice.length;
+    }
+  };
+  const { systemPrompt, prompt } = promptsFor(run);
+  let mcp = null;
+  if (options.mcp) {
+    mcp = writeMcpSession(
+      { token: options.mcp.token, apiUrl: options.mcp.apiUrl, runId: run.id, runnerId, command: options.mcp.command },
+      options.mcp.allowedTools
+    );
+  }
+  const session = spawn2({ prompt, systemPrompt, cwd, extraArgs: [...options.extraArgs ?? [], ...mcp?.args ?? []] });
+  const heartbeat = setInterval(() => {
+    void client.agentRuns.heartbeat(run.id, runnerId).then((h) => {
+      if (!h.ok) {
+        cancelled = true;
+        log(`run ${run.id} left RUNNING (cancelled) \u2014 stopping the session`);
+        session.kill();
+      }
+    }).catch((err) => log(`heartbeat failed: ${err instanceof Error ? err.message : String(err)}`));
+  }, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
+  const flusher = setInterval(() => {
+    void flush().catch((err) => log(`append failed: ${err instanceof Error ? err.message : String(err)}`));
+  }, options.flushMs ?? DEFAULT_FLUSH_MS);
+  let exitCode = 1;
+  let spawnError = null;
+  try {
+    for await (const line of session.lines) {
+      parser.feed(line);
+    }
+    exitCode = await session.exit;
+  } catch (err) {
+    spawnError = err instanceof Error ? err.message : String(err);
+  } finally {
+    clearInterval(heartbeat);
+    clearInterval(flusher);
+    mcp?.cleanup();
+  }
+  await flush().catch((err) => log(`final append failed: ${err instanceof Error ? err.message : String(err)}`));
+  if (cancelled) return { runId: run.id, status: "FAILED", eventsSent };
+  const snap = parser.snapshot();
+  if (snap.askedOwner) {
+    log(`run ${run.id} is waiting on the owner (${eventsSent} events)`);
+    return { runId: run.id, status: "WAITING_ON_OWNER", eventsSent };
+  }
+  if (snap.finishedViaTool) {
+    log(`run ${run.id} finished by the session (${eventsSent} events)`);
+    return { runId: run.id, status: "SUCCEEDED", eventsSent };
+  }
+  let outcome;
+  if (spawnError) {
+    outcome = { status: "FAILED", error: spawnError };
+  } else if (snap.isError || exitCode !== 0) {
+    outcome = {
+      status: "FAILED",
+      error: snap.errorMessage ?? `claude exited with code ${exitCode}`,
+      summary: snap.resultText ?? void 0,
+      usage: snap.usage ?? void 0
+    };
+  } else {
+    outcome = {
+      status: "SUCCEEDED",
+      summary: snap.resultText ?? void 0,
+      usage: snap.usage ?? void 0
+    };
+  }
+  await withRetry(() => client.agentRuns.finish(run.id, outcome, runnerId), retry);
+  log(`run ${run.id} ${outcome.status.toLowerCase()} (${eventsSent} events)`);
+  return { runId: run.id, status: outcome.status, eventsSent };
+}
+async function runForever(options) {
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+  const log = options.log ?? (() => void 0);
+  const backoff = new Backoff(options.intervalMs);
+  while (!options.shouldStop()) {
+    let outcome = null;
+    let failed = false;
+    try {
+      outcome = await runOnce(options);
+      backoff.success();
+    } catch (err) {
+      failed = true;
+      backoff.failure();
+      log(`runner error: ${err instanceof Error ? err.message : String(err)} \u2014 next poll in ${Math.round(backoff.delayMs / 1e3)}s`);
+    }
+    if ((!outcome || failed) && !options.shouldStop()) await sleep(backoff.delayMs);
+  }
+}
+
+// src/runner/spawn.ts
+import { spawn } from "child_process";
+import { createInterface } from "readline";
+var spawnClaude = ({ prompt, systemPrompt, cwd, extraArgs = [] }) => {
+  const child = spawn(
+    "claude",
+    ["-p", prompt, "--output-format", "stream-json", "--verbose", "--append-system-prompt", systemPrompt, ...extraArgs],
+    { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env }
+  );
+  const stderr = [];
+  child.stderr?.on("data", (chunk) => stderr.push(chunk.toString()));
+  const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+  const exit = new Promise((resolve2, reject) => {
+    child.on("error", (err) => reject(new Error(`could not start claude: ${err.message}`)));
+    child.on("close", (code) => {
+      if (code !== 0 && stderr.length) {
+        process.stderr.write(stderr.join("").slice(-2e3));
+      }
+      resolve2(code ?? 1);
+    });
+  });
+  return { lines, exit, kill: () => child.kill("SIGTERM") };
+};
+
+// src/runner/install.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3, existsSync as existsSync2, rmSync as rmSync2 } from "fs";
+import { homedir, platform } from "os";
+import { join as join3 } from "path";
+var SERVICE_LABEL = "im.exponential.runner";
+function xmlEscape(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function launchdPlist(input) {
+  const args = [input.nodeBin, input.exponentialBin, "runner", "start", "--runner-id", input.runnerId, "--cwd", input.cwd];
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args.map((a) => `    <string>${xmlEscape(a)}</string>`).join("\n")}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${xmlEscape(input.path)}</string>
+    <key>HOME</key><string>${xmlEscape(input.home)}</string>
+  </dict>
+  <key>WorkingDirectory</key><string>${xmlEscape(input.cwd)}</string>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${xmlEscape(join3(input.logDir, "runner.log"))}</string>
+  <key>StandardErrorPath</key><string>${xmlEscape(join3(input.logDir, "runner.log"))}</string>
+</dict>
+</plist>
+`;
+}
+function systemdUnit(input) {
+  const q = (s) => `"${s.replace(/"/g, '\\"')}"`;
+  return `[Unit]
+Description=Exponential Assistant runner
+After=network-online.target
+
+[Service]
+ExecStart=${q(input.nodeBin)} ${q(input.exponentialBin)} runner start --runner-id ${q(input.runnerId)} --cwd ${q(input.cwd)}
+WorkingDirectory=${input.cwd}
+Environment=PATH=${input.path}
+Environment=HOME=${input.home}
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+}
+function planService(input, os = platform(), home = homedir()) {
+  if (os === "darwin") {
+    const file = join3(home, "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+    return {
+      kind: "launchd",
+      file,
+      contents: launchdPlist(input),
+      load: ["launchctl", "bootstrap", `gui/${process.getuid?.() ?? 501}`, file],
+      unload: ["launchctl", "bootout", `gui/${process.getuid?.() ?? 501}/${SERVICE_LABEL}`]
+    };
+  }
+  if (os === "linux") {
+    const file = join3(home, ".config", "systemd", "user", "exponential-runner.service");
+    return {
+      kind: "systemd",
+      file,
+      contents: systemdUnit(input),
+      load: ["systemctl", "--user", "enable", "--now", "exponential-runner.service"],
+      unload: ["systemctl", "--user", "disable", "--now", "exponential-runner.service"]
+    };
+  }
+  throw new Error(`runner install is not supported on ${os}; run "exponential runner start" in a terminal instead`);
+}
+function writeServiceFile(plan) {
+  mkdirSync2(join3(plan.file, ".."), { recursive: true });
+  writeFileSync3(plan.file, plan.contents, { mode: 420 });
+}
+function removeServiceFile(plan) {
+  if (!existsSync2(plan.file)) return false;
+  rmSync2(plan.file);
+  return true;
+}
+
+// src/commands/runner.ts
+function createRunnerCommand() {
+  const cmd = new Command20("runner").description(
+    "Run your Assistant locally: claim its queued runs and work them with Claude Code on this machine"
+  );
+  cmd.command("start").description("Poll for queued runs and work them until stopped (Ctrl-C)").option("--runner-id <id>", "Name of this runner, recorded on each run", hostname()).option("--cwd <dir>", "Working directory for the spawned CLI (overrides runner config; never from the server)").option("--interval <seconds>", "Seconds between polls when nothing is queued", "15").option("--once", "Claim at most one run, work it, and exit").option("--no-mcp", "Spawn without the Exponential MCP run tools (progress still streams; the session cannot ask the owner)").action(async (opts) => {
+    try {
+      const client = getClient();
+      const settings = loadRunnerConfig();
+      const cwd = resolve(opts.cwd ?? settings.cwd ?? process.cwd());
+      const auth = getConfig();
+      const log = (line) => console.error(`[runner ${opts.runnerId}] ${line}`);
+      const base = {
+        client,
+        runnerId: opts.runnerId,
+        cwd,
+        spawn: spawnClaude,
+        log,
+        mcp: opts.mcp ? { token: auth.token, apiUrl: auth.apiUrl, command: settings.mcpCommand, allowedTools: settings.allowedTools } : void 0
+      };
+      if (opts.once) {
+        const outcome = await runOnce(base);
+        console.log(JSON.stringify(outcome ?? { runId: null, status: "IDLE", eventsSent: 0 }));
+        return;
+      }
+      let stop = false;
+      const onSignal = () => {
+        stop = true;
+        log("stopping after the current run");
+      };
+      process.on("SIGINT", onSignal);
+      process.on("SIGTERM", onSignal);
+      log(`polling every ${opts.interval}s in ${cwd}`);
+      await runForever({ ...base, intervalMs: Number(opts.interval) * 1e3, shouldStop: () => stop });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  cmd.command("install").description("Keep the runner running as a user service (launchd on macOS, systemd --user on Linux)").option("--runner-id <id>", "Name of this runner", hostname()).option("--cwd <dir>", "Working directory for the spawned CLI (defaults to runner config, then the current directory)").option("--dry-run", "Print the service file and commands without installing").action((opts) => {
+    try {
+      getClient();
+      const settings = loadRunnerConfig();
+      const cwd = resolve(opts.cwd ?? settings.cwd ?? process.cwd());
+      const logDir = resolve(homedir2(), "Library", "Logs", "exponential-runner");
+      const plan = planService({
+        exponentialBin: resolve(fileURLToPath(import.meta.url), "..", "..", "bin", "exponential.js"),
+        nodeBin: process.execPath,
+        runnerId: opts.runnerId,
+        cwd,
+        logDir: process.platform === "darwin" ? logDir : resolve(tmpdir2(), "exponential-runner"),
+        path: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+        home: homedir2()
+      });
+      if (opts.dryRun) {
+        console.log(`# ${plan.file}
+${plan.contents}
+# load: ${plan.load.join(" ")}
+# unload: ${plan.unload.join(" ")}`);
+        return;
+      }
+      if (plan.kind === "launchd") mkdirSync3(logDir, { recursive: true });
+      saveRunnerConfig({ cwd });
+      writeServiceFile(plan);
+      try {
+        execFileSync(plan.unload[0], plan.unload.slice(1), { stdio: "ignore" });
+      } catch {
+      }
+      execFileSync(plan.load[0], plan.load.slice(1), { stdio: "inherit" });
+      console.error(`Installed ${plan.kind} service ${plan.file}; the runner works in ${cwd}.`);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  cmd.command("uninstall").description("Stop and remove the runner user service").action(() => {
+    try {
+      const plan = planService({
+        exponentialBin: "",
+        nodeBin: "",
+        runnerId: "",
+        cwd: "",
+        logDir: "",
+        path: "",
+        home: homedir2()
+      });
+      try {
+        execFileSync(plan.unload[0], plan.unload.slice(1), { stdio: "ignore" });
+      } catch {
+      }
+      console.error(removeServiceFile(plan) ? `Removed ${plan.file}` : `No service file at ${plan.file}`);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  const config = cmd.command("config").description(`Runner settings on this machine (${runnerConfigPath()})`);
+  config.command("show").description("Print the runner settings").action(() => {
+    console.log(JSON.stringify({ path: runnerConfigPath(), ...loadRunnerConfig() }, null, 2));
+  });
+  config.command("set").description("Set a runner setting: cwd <dir> | allowed-tools <a,b,c> | mcp-command <cmd ...>").argument("<key>", "cwd | allowed-tools | mcp-command").argument("<value...>", "The value").action((key, value) => {
+    try {
+      let next;
+      if (key === "cwd") next = saveRunnerConfig({ cwd: resolve(value.join(" ")) });
+      else if (key === "allowed-tools") next = saveRunnerConfig({ allowedTools: value.join(" ").split(",").map((t) => t.trim()).filter(Boolean) });
+      else if (key === "mcp-command") next = saveRunnerConfig({ mcpCommand: value });
+      else throw new Error(`Unknown setting "${key}". Use cwd, allowed-tools or mcp-command.`);
+      console.log(JSON.stringify(next, null, 2));
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/search.ts
+import { Command as Command21 } from "commander";
 import chalk8 from "chalk";
 var TYPE_LABELS = {
   workspace: "Workspaces",
@@ -5804,7 +6533,7 @@ var TYPE_LABELS = {
   product: "Products"
 };
 function createSearchCommand() {
-  const search = new Command20("search").description(
+  const search = new Command21("search").description(
     "Global search across projects, actions, goals, workspaces and more \u2014 same coverage as the app's Cmd+K palette"
   ).argument("<query>", "Text to search for").option("-w, --workspace <slug>", "Restrict results to one workspace (slug or ID)").option("-l, --limit <n>", "Max results per entity type (1-25, default 10)").action(async (query, options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
@@ -5863,7 +6592,7 @@ ${TYPE_LABELS[type] ?? type}`));
 }
 
 // src/commands/tickets.ts
-import { Command as Command21 } from "commander";
+import { Command as Command22 } from "commander";
 function collectRepeatable(value, previous) {
   return [...previous, value];
 }
@@ -5906,7 +6635,7 @@ function validateTicketType(value) {
   return value;
 }
 function createTicketsCommand() {
-  const tickets = new Command21("tickets").description(
+  const tickets = new Command22("tickets").description(
     "Manage product backlog tickets. Tickets live under a product, link to features/epics, depend on each other, and can be implemented via actions."
   );
   tickets.command("list").description(
@@ -5995,6 +6724,49 @@ function createTicketsCommand() {
       }
     }
   );
+  tickets.command("search <query>").description(
+    [
+      "Find tickets in a product by free text \u2014 the same picker search the app uses",
+      "when you link a dependency. Matches title (case-insensitive substring), shortId",
+      '(word-order-insensitive, so "toucan.prime" finds prime.toucan) or an exact',
+      "ticket number. Most recently updated first. Returns slim rows (id, number,",
+      "shortId, title, status, priority, assignee); use `tickets get` for the rest."
+    ].join("\n")
+  ).requiredOption("--product <slug|id>", "Product slug or CUID").option("--workspace <slug|id>", "Workspace (required when --product is a slug)").option("--limit <n>", "Max results, 1-50 (default 20)").option("--exclude <id>", "Ticket CUID to leave out of the results").action(
+    async (query, options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+      try {
+        const trimmed = query.trim();
+        if (!trimmed) {
+          throw new Error("Search query is empty. Use `tickets list` to list a product's tickets.");
+        }
+        if (trimmed.length > 200) {
+          throw new Error("Search query is too long (max 200 characters).");
+        }
+        let limit;
+        if (options.limit !== void 0) {
+          limit = Number(options.limit);
+          if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+            throw new Error(`Invalid --limit "${options.limit}". Use a whole number from 1 to 50.`);
+          }
+        }
+        const client = getClient();
+        const workspaceId = await resolveWorkspaceId(client, options.workspace);
+        const productId = await resolveProductId(client, workspaceId, options.product);
+        const hits = await client.tickets.search({
+          productId,
+          query: trimmed,
+          excludeTicketId: options.exclude,
+          limit
+        });
+        if (useJson) outputTicketSearchJson(hits, trimmed);
+        else outputTicketSearchPretty(hits, trimmed);
+      } catch (error) {
+        handleError(error, useJson);
+      }
+    }
+  );
   tickets.command("get <id>").description("Show a ticket with dependencies, actions, and comments").action(async (id, _options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
@@ -6232,7 +7004,7 @@ function createTicketsCommand() {
       handleError(error, useJson);
     }
   });
-  const comment = new Command21("comment").description("Manage comments on a ticket");
+  const comment = new Command22("comment").description("Manage comments on a ticket");
   comment.command("list").description("List comments on a ticket").requiredOption("--id <id>", "Ticket CUID").action(async (options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
@@ -6324,7 +7096,7 @@ function createTicketsCommand() {
 }
 
 // src/commands/time.ts
-import { Command as Command22 } from "commander";
+import { Command as Command23 } from "commander";
 import { segmentConversation } from "exponential-sdk";
 var SOURCES2 = ["manual", "claude-desktop", "agent-run"];
 var STATUSES2 = ["PROPOSED", "CONFIRMED"];
@@ -6414,7 +7186,7 @@ function batchItemToInput(item, index, defaults) {
   };
 }
 function createTimeCommand() {
-  const time = new Command22("time").description(
+  const time = new Command23("time").description(
     `Time entries \u2014 log the day's work and list it. ${OWNERSHIP_NOTE}`
   );
   time.command("log").description(
@@ -6584,10 +7356,10 @@ function parseMessagesFile(raw) {
 }
 
 // src/commands/workspaces.ts
-import { Command as Command23 } from "commander";
+import { Command as Command24 } from "commander";
 import chalk9 from "chalk";
 function createWorkspacesCommand() {
-  const workspaces = new Command23("workspaces").description("Manage workspaces");
+  const workspaces = new Command24("workspaces").description("Manage workspaces");
   workspaces.command("list").description("List all workspaces").action(async (_options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
@@ -6677,7 +7449,7 @@ Members (${members.length})
 }
 
 // src/commands/goals.ts
-import { Command as Command24 } from "commander";
+import { Command as Command25 } from "commander";
 var GOAL_STATUSES = [
   "planned",
   "active",
@@ -6789,7 +7561,7 @@ function validateKeyResultUnit(value) {
   return value;
 }
 function createKeyResultsCommand() {
-  const kr = new Command24("kr").description(
+  const kr = new Command25("kr").description(
     "Key results on an objective. Ids are CUIDs; --goal takes the objective's integer id."
   );
   kr.command("list").description("List key results").option("--goal <id>", "Objective ID (a number)").option("-w, --workspace <slug|id>", "Workspace (workspace-wide: every member's KRs)").option("--period <period>", "Period, e.g. Q3-2026").option("--status <status>", `Filter by status: ${KEY_RESULT_STATUSES.join(", ")}`).option("--mine", "Narrow a workspace list to key results you own").action(
@@ -6992,7 +7764,7 @@ function createKeyResultsCommand() {
   return kr;
 }
 function createGoalCommentsCommand() {
-  const comment = new Command24("comment").description(
+  const comment = new Command25("comment").description(
     "Read and post comments on a goal. Mention teammates with --mention."
   );
   comment.command("list").description("List comments on a goal").requiredOption("--goal <id>", "Goal ID (a number)").action(async (options, cmd) => {
@@ -7087,18 +7859,39 @@ function createGoalCommentsCommand() {
   return comment;
 }
 function createGoalsCommand() {
-  const goals = new Command24("goals").description(
+  const goals = new Command25("goals").description(
     "Manage goals (objectives) and their key results. Objectives have integer ids; key results are CUIDs."
   );
   goals.command("list").description(
     "List objectives, each with the projects linked to it \u2014 the join that ties an action (which carries a projectId) back to a goal."
-  ).option("-w, --workspace <slug|id>", "Workspace slug or ID (defaults to your default workspace)").option("--all-workspaces", "List across every workspace you belong to").option("--period <period>", "Filter by period, e.g. Q3-2026").option("--status <status>", `Filter by status: ${GOAL_STATUSES.join(", ")}`).option("--tree", "Render the parent/child cascade instead of a flat list").action(
+  ).option("-w, --workspace <slug|id>", "Workspace slug or ID (defaults to your default workspace)").option("--all-workspaces", "List across every workspace you belong to").option("--period <period>", "Filter by period, e.g. Q3-2026").option("--status <status>", `Filter by status: ${GOAL_STATUSES.join(", ")}`).option("--tree", "Render the parent/child cascade instead of a flat list").option(
+    "--project <cuid>",
+    "Only objectives linked to this project (yours only \u2014 the server scopes this lookup to objectives you created). Not combinable with --workspace, --all-workspaces or --tree."
+  ).action(
     async (options, cmd) => {
       const globalOpts = cmd.optsWithGlobals();
       const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
       try {
         const status = validateGoalStatus(options.status);
         const client = getClient();
+        if (options.project) {
+          const conflicting = [
+            options.workspace ? "--workspace" : null,
+            options.allWorkspaces ? "--all-workspaces" : null,
+            options.tree ? "--tree" : null
+          ].filter(Boolean);
+          if (conflicting.length > 0) {
+            throw new Error(
+              `--project can't be combined with ${conflicting.join(", ")}.`
+            );
+          }
+          const list2 = (await client.goals.listByProject(options.project)).filter(
+            (g) => (!options.period || g.period === options.period) && (!status || g.status === status)
+          );
+          if (useJson) outputGoalsJson(list2);
+          else outputGoalsPretty(list2);
+          return;
+        }
         const workspaces = await targetWorkspaces(client, options);
         if (options.tree) {
           const trees = await fanOutByWorkspace(
@@ -7353,7 +8146,7 @@ Re-run with --with-key-results to go ahead, or move them with \`goals kr update
   return goals;
 }
 function createOkrsCommand() {
-  const okrs = new Command24("okrs").description(
+  const okrs = new Command25("okrs").description(
     "OKRs \u2014 objectives with their key results nested. Manage the parts with `goals` and `goals kr`."
   );
   okrs.command("list").description(
@@ -7431,18 +8224,18 @@ function createOkrsCommand() {
 }
 
 // src/program.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname2, join as join4 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 var PKG_VERSION = JSON.parse(
-  readFileSync2(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")
+  readFileSync3(join4(dirname2(fileURLToPath2(import.meta.url)), "..", "package.json"), "utf-8")
 ).version;
 var CLI_VERSION_FLAGS = "-V, --cli-version";
 function isBareVersionRequest(args) {
   return args.includes("--version") && args.every((arg) => arg.startsWith("-"));
 }
 function buildProgram() {
-  const program = new Command25();
+  const program = new Command26();
   program.name("exponential").description(
     [
       "CLI to interact with Exponential productivity app.",
@@ -7465,6 +8258,7 @@ function buildProgram() {
   program.addCommand(createPagesCommand());
   program.addCommand(createProductsCommand());
   program.addCommand(createProjectsCommand());
+  program.addCommand(createRunnerCommand());
   program.addCommand(createSearchCommand());
   program.addCommand(createTicketsCommand());
   program.addCommand(createTimeCommand());