@impulselab/hepha 0.1.0 → 0.2.44

package/dist/index.js

@@ -12,12 +12,50 @@ import { homedir } from "os";
 import { dirname, join } from "path";
 
 // src/lib/errors.ts
+var CLI_ERROR_CODES = {
+  BAD_USAGE: "BAD_USAGE",
+  /** The session needs a person — the exit-3 family. */
+  NEEDS_HUMAN: "NEEDS_HUMAN",
+  NOT_AUTHENTICATED: "NOT_AUTHENTICATED",
+  NETWORK: "NETWORK",
+  TIMEOUT: "TIMEOUT",
+  /** Ctrl-C: a cancellation, not a failure of ours. */
+  INTERRUPTED: "INTERRUPTED",
+  /** A 2xx whose shape this CLI version does not understand. */
+  API_SCHEMA_MISMATCH: "API_SCHEMA_MISMATCH",
+  /** Not JSON at all — wrong host, proxy, error page. */
+  NON_JSON_RESPONSE: "NON_JSON_RESPONSE",
+  ERROR: "ERROR"
+};
 var CliError = class extends Error {
   exitCode;
-  constructor(message, exitCode = 1) {
+  details;
+  /**
+   * A followed session parking on a question is a non-zero outcome AND a result
+   * worth reading. Carried here so stdout stays ONE JSON document.
+   */
+  result;
+  constructor(message, exitCode = 1, details = {}, result) {
     super(message);
     this.name = "CliError";
     this.exitCode = exitCode;
+    this.details = details;
+    if (result !== void 0) {
+      this.result = result;
+    }
+  }
+  /** The code to report, defaulting to whatever the exit code implies. */
+  get code() {
+    if (this.details.code) {
+      return this.details.code;
+    }
+    if (this.exitCode === 2) {
+      return CLI_ERROR_CODES.BAD_USAGE;
+    }
+    if (this.exitCode === 3) {
+      return CLI_ERROR_CODES.NEEDS_HUMAN;
+    }
+    return CLI_ERROR_CODES.ERROR;
   }
 };
 
@@ -105,7 +143,144 @@ var config = {
   }
 };
 
+// src/lib/output.ts
+var COLORS = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  bold: "\x1B[1m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m"
+};
+var STATUS_COLORS = {
+  running: "blue",
+  provisioning: "blue",
+  queued: "dim",
+  created: "dim",
+  delivering: "blue",
+  verifying: "blue",
+  waiting_human: "yellow",
+  awaiting_approval: "yellow",
+  completed: "green",
+  failed: "red",
+  killed: "red",
+  abstained: "yellow"
+};
+function supportsColor() {
+  return process.stdout.isTTY === true && process.env.NO_COLOR === void 0 && !jsonMode;
+}
+var jsonMode = false;
+var out = {
+  /** Declared once per run, before anything can fail. */
+  setJson(enabled) {
+    jsonMode = enabled;
+  },
+  isJson() {
+    return jsonMode;
+  },
+  json(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+  },
+  line(text = "") {
+    process.stdout.write(`${text}
+`);
+  },
+  error(text) {
+    process.stderr.write(`${out.paint(`error: ${out.safe(text)}`, "red")}
+`);
+  },
+  /**
+   * The one place a failure is reported. Under `--json` stdout must be
+   * parseable, and it was not: failures went to stderr as prose. Success keeps
+   * its bare shape, so nothing that already parses stdout has to change.
+   */
+  failure(error) {
+    if (!jsonMode) {
+      out.error(error.message);
+      return;
+    }
+    out.json({
+      ok: false,
+      error: {
+        ...error.details.status === void 0 ? {} : { status: error.details.status },
+        code: error.code,
+        message: out.safe(error.message),
+        ...error.details.issues ? { issues: error.details.issues } : {},
+        ...error.details.retryAfterSeconds === void 0 ? {} : { retryAfterSeconds: error.details.retryAfterSeconds }
+      },
+      // Inside the envelope, so stdout stays one parseable document.
+      ...error.result === void 0 ? {} : { result: error.result }
+    });
+  },
+  paint(text, color) {
+    if (!supportsColor()) {
+      return text;
+    }
+    return `${COLORS[color] ?? ""}${text}${COLORS.reset}`;
+  },
+  /**
+   * Neutralise terminal control sequences in text the platform gives us.
+   *
+   * Transcript content, PR titles and question bodies carry model output, tool
+   * output and repository contents — none of it trusted. Printed raw, an ESC
+   * sequence could repaint or erase what the user already read, or emit an OSC
+   * 8 hyperlink pointing somewhere else entirely. Newlines and tabs survive;
+   * every other C0/C1 control does not. (`--json` is unaffected: JSON.stringify
+   * already escapes control characters.)
+   */
+  safe(text) {
+    return text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+  },
+  /** `safe`, flattened to one line — anything going into a table cell. */
+  cell(text) {
+    return out.safe(text).replace(/\s+/g, " ").trim();
+  },
+  status(status) {
+    return out.paint(status, STATUS_COLORS[status] ?? "reset");
+  },
+  /** Left-aligned two-column block — the shape used by every list command. */
+  table(rows) {
+    if (rows.length === 0) {
+      return;
+    }
+    const widths = rows[0].map(
+      (_, column) => Math.max(...rows.map((row) => stripAnsi(row[column] ?? "").length))
+    );
+    for (const row of rows) {
+      const line = row.map((cell, column) => {
+        const padding = widths[column] - stripAnsi(cell).length;
+        return column === row.length - 1 ? cell : cell + " ".repeat(padding);
+      }).join("  ");
+      out.line(line.trimEnd());
+    }
+  }
+};
+function stripAnsi(text) {
+  return text.replace(/\u001b\[\d+m/g, "");
+}
+
 // src/lib/api.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+function resolveTimeout(override) {
+  if (override !== void 0) {
+    return override;
+  }
+  const raw = process.env.HEPHA_TIMEOUT_MS?.trim();
+  if (!raw) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new CliError(
+      `HEPHA_TIMEOUT_MS expects a positive number of milliseconds, got "${raw}".`,
+      2
+    );
+  }
+  return parsed;
+}
 function authHeaders(as) {
   if (as) {
     return { authorization: `Bearer ${as.token}` };
@@ -119,24 +294,54 @@ function authHeaders(as) {
     return { authorization: `Bearer ${token}` };
   }
   throw new CliError(
-    "Not signed in. Run `hepha login`, or set HEPHA_API_KEY to act as an agent."
+    "Not signed in. Run `hepha login`, or set HEPHA_API_KEY to act as an agent.",
+    1,
+    { code: CLI_ERROR_CODES.NOT_AUTHENTICATED }
   );
 }
+function readIssues(payload) {
+  if (!payload || typeof payload !== "object") {
+    return void 0;
+  }
+  const data = payload.data;
+  if (!data || typeof data !== "object") {
+    return void 0;
+  }
+  const issues = data.issues;
+  return Array.isArray(issues) ? issues : void 0;
+}
+function readString2(payload, key) {
+  if (!payload || typeof payload !== "object") {
+    return void 0;
+  }
+  const value = payload[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function retryAfterSeconds(response) {
+  const raw = response.headers.get("retry-after") ?? response.headers.get("x-retry-after");
+  if (!raw) {
+    return void 0;
+  }
+  const seconds = Number(raw.trim());
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : void 0;
+}
 function messageFrom(status, payload) {
-  if (payload && typeof payload === "object" && "message" in payload) {
-    const message = payload.message;
-    if (typeof message === "string" && message.length > 0) {
-      return message;
-    }
+  const message = readString2(payload, "message");
+  if (message) {
+    return status === 403 && process.env.HEPHA_API_KEY ? `${message} (HEPHA_API_KEY is set and takes precedence over your \`hepha login\` session \u2014 unset it to act as yourself.)` : message;
   }
   if (status === 401) {
     return "Unauthorized \u2014 your credential is missing, expired or revoked.";
   }
   return `Request failed with status ${status}.`;
 }
-async function api(path, options = {}) {
+function excerpt(text) {
+  const flattened = out.cell(text);
+  return flattened.length > 200 ? `${flattened.slice(0, 200)}\u2026` : flattened;
+}
+async function api(requestPath, options = {}) {
   const baseUrl = options.as?.baseUrl ?? config.load().baseUrl;
-  const url = new URL(`${baseUrl.replace(/\/$/, "")}/api/v1${path}`);
+  const url = new URL(`${baseUrl.replace(/\/$/, "")}/api/v1${requestPath}`);
   for (const [key, value] of Object.entries(options.query ?? {})) {
     if (value !== void 0) {
       url.searchParams.set(key, String(value));
@@ -146,37 +351,103 @@ async function api(path, options = {}) {
     ...authHeaders(options.as),
     ...options.body === void 0 ? {} : { "content-type": "application/json" }
   };
+  const method = options.method ?? "GET";
+  const deadline = resolveTimeout(options.timeoutMs);
+  const controller = new AbortController();
+  let abortedBy = null;
+  const timer = setTimeout(() => {
+    abortedBy ??= "timeout";
+    controller.abort();
+  }, deadline);
+  const onInterrupt = () => {
+    abortedBy ??= "interrupt";
+    controller.abort();
+  };
+  process.once("SIGINT", onInterrupt);
   let response;
+  let text;
   try {
     response = await fetch(url, {
-      method: options.method ?? "GET",
+      method,
       headers,
+      signal: controller.signal,
       ...options.body === void 0 ? {} : { body: JSON.stringify(options.body) }
     });
+    text = await response.text();
   } catch (cause) {
+    if (abortedBy === "interrupt") {
+      throw new CliError(`${method} ${url.pathname} interrupted.`, 130, {
+        code: CLI_ERROR_CODES.INTERRUPTED
+      });
+    }
+    if (abortedBy === "timeout") {
+      throw new CliError(
+        `${method} ${url.pathname} timed out after ${deadline}ms. Raise HEPHA_TIMEOUT_MS if the platform is simply slow.`,
+        1,
+        { code: CLI_ERROR_CODES.TIMEOUT }
+      );
+    }
     throw new CliError(
-      `Cannot reach ${baseUrl}. Set HEPHA_URL if the platform lives elsewhere. (${String(cause)})`
+      `Cannot reach ${baseUrl}. Set HEPHA_URL if the platform lives elsewhere. (${String(cause)})`,
+      1,
+      { code: CLI_ERROR_CODES.NETWORK }
     );
+  } finally {
+    clearTimeout(timer);
+    process.removeListener("SIGINT", onInterrupt);
   }
-  const text = await response.text();
+  const retryAfter = retryAfterSeconds(response);
   let payload = null;
   if (text) {
     try {
       payload = JSON.parse(text);
     } catch {
+      const body = excerpt(text);
+      const contentType = response.headers.get("content-type") ?? "unknown";
       throw new CliError(
-        `${url.origin} answered ${response.status} with a non-JSON body. Is HEPHA_URL pointing at a Hephaistos deployment?`
+        response.ok ? `${method} ${url.pathname} answered ${response.status} with a non-JSON body (${contentType}). Is HEPHA_URL pointing at a Hephaistos deployment?${body ? ` Body: ${body}` : ""}` : `${method} ${url.pathname} failed with ${response.status} and a non-JSON body (${contentType}).${body ? ` Body: ${body}` : ""}`,
+        1,
+        {
+          status: response.status,
+          code: CLI_ERROR_CODES.NON_JSON_RESPONSE,
+          ...retryAfter === void 0 ? {} : { retryAfterSeconds: retryAfter }
+        }
       );
     }
   }
   if (!response.ok) {
-    throw new CliError(messageFrom(response.status, payload));
+    const code = readString2(payload, "code") ?? readString2(payload, "error");
+    const issues = readIssues(payload);
+    throw new CliError(
+      messageFrom(response.status, payload) + (response.status === 429 && retryAfter !== void 0 ? ` Retry in ${retryAfter}s.` : ""),
+      1,
+      {
+        status: response.status,
+        ...code ? { code } : {},
+        ...issues ? { issues } : {},
+        ...retryAfter === void 0 ? {} : { retryAfterSeconds: retryAfter }
+      }
+    );
   }
   return payload;
 }
 
+// src/lib/api-path.ts
+function path(strings, ...values) {
+  return strings.reduce(
+    (accumulator, literal, index) => accumulator + (index === 0 ? "" : encodeURIComponent(values[index - 1] ?? "")) + literal,
+    ""
+  );
+}
+
 // src/lib/args.ts
-var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json", "follow", "help", "all", "quiet"]);
+var GLOBAL_BOOLEANS = ["json", "help", "quiet"];
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  ...GLOBAL_BOOLEANS,
+  "follow",
+  "all",
+  "version"
+]);
 var args = {
   parse(argv) {
     const parsed = {
@@ -203,6 +474,12 @@ var args = {
       if (equalsAt >= 0) {
         name = withoutDashes.slice(0, equalsAt);
         value = withoutDashes.slice(equalsAt + 1);
+        if (BOOLEAN_FLAGS.has(name)) {
+          throw new CliError(
+            `--${name} is a boolean flag: pass --${name} to enable it, or omit it. "--${name}=${value}" is not a value.`,
+            2
+          );
+        }
       } else {
         name = withoutDashes;
         const next = argv[index + 1];
@@ -211,7 +488,7 @@ var args = {
           index += 1;
         }
       }
-      if (value === void 0) {
+      if (value === void 0 || value.trim() === "") {
         if (!BOOLEAN_FLAGS.has(name)) {
           throw new CliError(`--${name} expects a value.`, 2);
         }
@@ -223,6 +500,41 @@ var args = {
     }
     return parsed;
   },
+  /**
+   * Refuse anything this action does not understand. Called once the action is
+   * known, because `sessions list` and `sessions logs` accept different flags.
+   */
+  expect(parsed, spec) {
+    const allowed = /* @__PURE__ */ new Set([
+      ...GLOBAL_BOOLEANS,
+      ...spec.flags ?? [],
+      ...spec.booleans ?? []
+    ]);
+    for (const name of [...Object.keys(parsed.flags), ...parsed.booleans]) {
+      if (!allowed.has(name)) {
+        throw new CliError(`Unknown flag --${name}.`, 2);
+      }
+    }
+    const max = spec.positional ?? 0;
+    if (parsed.positional.length > max) {
+      const surplus = parsed.positional.slice(max).map((value) => `"${value}"`).join(", ");
+      throw new CliError(
+        `Unexpected argument${parsed.positional.length - max > 1 ? "s" : ""} ${surplus}.`,
+        2
+      );
+    }
+  },
+  /** The action name, validated against what the group actually implements. */
+  action(parsed, group, allowed, fallback) {
+    const action = parsed.positional[0] ?? fallback;
+    if (!allowed.includes(action)) {
+      throw new CliError(
+        `Unknown ${group} command "${action}". Expected one of: ${allowed.join(", ")}.`,
+        2
+      );
+    }
+    return action;
+  },
   required(parsed, index, name) {
     const value = parsed.positional[index];
     if (!value) {
@@ -230,7 +542,11 @@ var args = {
     }
     return value;
   },
-  number(parsed, name) {
+  /**
+   * A whole number inside a range, refused locally: `--page -1` used to come
+   * back from the API as a bare "Input validation failed".
+   */
+  integer(parsed, name, bounds = {}) {
     const raw = parsed.flags[name];
     if (raw === void 0) {
       return void 0;
@@ -238,116 +554,115 @@ var args = {
     const trimmed = raw.trim();
     const value = Number(trimmed);
     if (trimmed === "" || !Number.isFinite(value)) {
-      throw new CliError(`--${name} expects a number.`, 2);
+      throw new CliError(`--${name} expects a number, got "${raw}".`, 2);
+    }
+    if (!Number.isInteger(value)) {
+      throw new CliError(`--${name} expects a whole number, got "${raw}".`, 2);
+    }
+    if (bounds.min !== void 0 && value < bounds.min) {
+      throw new CliError(`--${name} must be at least ${bounds.min}.`, 2);
+    }
+    if (bounds.max !== void 0 && value > bounds.max) {
+      throw new CliError(`--${name} must be at most ${bounds.max}.`, 2);
     }
     return value;
+  },
+  /** One of a fixed set, named in the error so the fix is obvious. */
+  choice(parsed, name, allowed) {
+    const raw = parsed.flags[name];
+    if (raw === void 0) {
+      return void 0;
+    }
+    if (!allowed.includes(raw)) {
+      throw new CliError(
+        `--${name} expects one of: ${allowed.join(", ")}. Got "${raw}".`,
+        2
+      );
+    }
+    return raw;
   }
 };
 
-// src/lib/output.ts
-var COLORS = {
-  reset: "\x1B[0m",
-  dim: "\x1B[2m",
-  bold: "\x1B[1m",
-  red: "\x1B[31m",
-  green: "\x1B[32m",
-  yellow: "\x1B[33m",
-  blue: "\x1B[34m",
-  magenta: "\x1B[35m"
-};
-var STATUS_COLORS = {
-  running: "blue",
-  provisioning: "blue",
-  queued: "dim",
-  created: "dim",
-  delivering: "blue",
-  verifying: "blue",
-  waiting_human: "yellow",
-  awaiting_approval: "yellow",
-  completed: "green",
-  failed: "red",
-  killed: "red",
-  abstained: "yellow"
-};
-function supportsColor() {
-  return process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
-}
-var out = {
-  json(value) {
-    process.stdout.write(`${JSON.stringify(value, null, 2)}
-`);
-  },
-  line(text = "") {
-    process.stdout.write(`${text}
-`);
-  },
-  error(text) {
-    process.stderr.write(`${out.paint(`error: ${out.safe(text)}`, "red")}
-`);
-  },
-  paint(text, color) {
-    if (!supportsColor()) {
-      return text;
+// src/lib/version.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+import { fileURLToPath } from "url";
+function readVersion() {
+  let directory = dirname2(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 5; depth += 1) {
+    try {
+      const manifest = JSON.parse(
+        readFileSync2(join2(directory, "package.json"), "utf8")
+      );
+      const version = manifest.version;
+      if (typeof version === "string" && version.length > 0) {
+        return version;
+      }
+    } catch {
     }
-    return `${COLORS[color] ?? ""}${text}${COLORS.reset}`;
-  },
-  /**
-   * Neutralise terminal control sequences in text the platform gives us.
-   *
-   * Transcript content, PR titles and question bodies carry model output, tool
-   * output and repository contents — none of it trusted. Printed raw, an ESC
-   * sequence could repaint or erase what the user already read, or emit an OSC
-   * 8 hyperlink pointing somewhere else entirely. Newlines and tabs survive;
-   * every other C0/C1 control does not. (`--json` is unaffected: JSON.stringify
-   * already escapes control characters.)
-   */
-  safe(text) {
-    return text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
-  },
-  /** `safe`, flattened to one line — anything going into a table cell. */
-  cell(text) {
-    return out.safe(text).replace(/\s+/g, " ").trim();
-  },
-  status(status) {
-    return out.paint(status, STATUS_COLORS[status] ?? "reset");
-  },
-  /** Left-aligned two-column block — the shape used by every list command. */
-  table(rows) {
-    if (rows.length === 0) {
-      return;
+    const parent = dirname2(directory);
+    if (parent === directory) {
+      break;
     }
-    const widths = rows[0].map(
-      (_, column) => Math.max(...rows.map((row) => stripAnsi(row[column] ?? "").length))
-    );
-    for (const row of rows) {
-      const line = row.map((cell, column) => {
-        const padding = widths[column] - stripAnsi(cell).length;
-        return column === row.length - 1 ? cell : cell + " ".repeat(padding);
-      }).join("  ");
-      out.line(line.trimEnd());
+    directory = parent;
+  }
+  return "unknown";
+}
+var VERSION = readVersion();
+
+// src/lib/expect-shape.ts
+function read(payload, dotted) {
+  return dotted.split(".").reduce((current, key) => {
+    if (!current || typeof current !== "object") {
+      return void 0;
+    }
+    return current[key];
+  }, payload);
+}
+function expectShape(payload, endpoint, requirements) {
+  for (const [field, predicate] of Object.entries(requirements)) {
+    if (!predicate(read(payload, field))) {
+      throw new CliError(
+        `${endpoint} returned a payload this CLI does not understand: "${field}" is missing or has the wrong type. hepha ${VERSION} may be out of step with the platform \u2014 try \`npm install -g @impulselab/hepha\`.`,
+        1,
+        { code: CLI_ERROR_CODES.API_SCHEMA_MISMATCH }
+      );
     }
   }
-};
-function stripAnsi(text) {
-  return text.replace(/\u001b\[\d+m/g, "");
+  return payload;
 }
 
+// src/lib/is.ts
+var is = {
+  string: (value) => typeof value === "string",
+  number: (value) => typeof value === "number",
+  array: (value) => Array.isArray(value),
+  object: (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value)
+};
+
 // src/commands/approvals.ts
+var ACTIONS = ["list", "show", "approve", "reject"];
+var REJECT_MODES = ["rework", "terminate"];
 async function approvalsCommand(parsed) {
-  const action = parsed.positional[0] ?? "list";
+  const action = args.action(parsed, "approvals", ACTIONS, "list");
   const asJson = parsed.booleans.has("json");
   if (action === "list") {
-    const result = await api("/approvals");
+    args.expect(parsed, { positional: 1 });
+    const result2 = expectShape(
+      await api("/approvals"),
+      "GET /approvals",
+      { items: is.array }
+    );
     if (asJson) {
-      out.json(result);
+      out.json(result2);
       return;
     }
-    if (result.items.length === 0) {
+    if (result2.items.length === 0) {
       out.line("No guardrail waiting on you.");
       return;
     }
     out.table(
-      result.items.map((item) => [
+      result2.items.map((item) => [
         out.cell(item.id),
         out.cell(item.guardrailKind),
         out.cell(item.repoName ?? "\u2014"),
@@ -356,73 +671,77 @@ async function approvalsCommand(parsed) {
     );
     return;
   }
+  args.expect(parsed, {
+    positional: 2,
+    ...action === "reject" ? { flags: ["mode", "feedback"] } : {}
+  });
   const guardrailId = args.required(parsed, 1, "guardrailRequestId");
   if (action === "show") {
-    const detail = await api(
-      `/approvals/${guardrailId}`
+    const detail2 = expectShape(
+      await api(path`/approvals/${guardrailId}`),
+      "GET /approvals/{id}",
+      { guardrailKind: is.string, status: is.string, summary: is.string }
     );
     if (asJson) {
-      out.json(detail);
+      out.json(detail2);
       return;
     }
     out.line(
-      `${out.paint(out.cell(detail.guardrailKind), "bold")}  ${detail.status}`
+      `${out.paint(out.cell(detail2.guardrailKind), "bold")}  ${detail2.status}`
     );
-    out.line(out.safe(detail.summary));
+    out.line(out.safe(detail2.summary));
     out.line();
-    out.json(detail.payload);
+    out.json(detail2.payload);
     return;
   }
   if (action === "approve") {
-    const result = await api(
-      `/approvals/${guardrailId}/approve`,
+    const result2 = await api(
+      path`/approvals/${guardrailId}/approve`,
       { method: "POST", body: {} }
     );
     if (asJson) {
-      out.json(result);
+      out.json(result2);
       return;
     }
     out.line(`${out.paint("\u2713", "green")} Approved ${out.cell(guardrailId)}`);
     return;
   }
-  if (action === "reject") {
-    const mode = parsed.flags.mode ?? "rework";
-    if (mode !== "rework" && mode !== "terminate") {
-      throw new CliError("--mode expects rework or terminate.", 2);
-    }
-    if (mode === "rework" && !parsed.flags.feedback) {
-      throw new CliError(
-        "--feedback is required with --mode rework: the agent needs to know what to change.",
-        2
-      );
-    }
-    const result = await api(
-      `/approvals/${guardrailId}/reject`,
-      {
-        method: "POST",
-        body: {
-          mode,
-          ...parsed.flags.feedback ? { feedback: parsed.flags.feedback } : {}
-        }
-      }
-    );
-    if (asJson) {
-      out.json(result);
-      return;
-    }
-    out.line(
-      `${out.paint("\u2713", "green")} Rejected ${out.cell(guardrailId)} (${mode})`
+  const mode = args.choice(parsed, "mode", REJECT_MODES) ?? "rework";
+  if (mode === "rework" && !parsed.flags.feedback) {
+    throw new CliError(
+      "--feedback is required with --mode rework: the agent needs to know what to change.",
+      2
     );
+  }
+  const result = await api(
+    path`/approvals/${guardrailId}/reject`,
+    {
+      method: "POST",
+      body: {
+        mode,
+        ...parsed.flags.feedback ? { feedback: parsed.flags.feedback } : {}
+      }
+    }
+  );
+  if (asJson) {
+    out.json(result);
     return;
   }
-  throw new CliError(`Unknown approvals command "${action}".`, 2);
+  out.line(
+    `${out.paint("\u2713", "green")} Rejected ${out.cell(guardrailId)} (${mode})`
+  );
 }
 
 // src/commands/catalog.ts
 async function catalogCommand(topic, parsed) {
   const asJson = parsed.booleans.has("json");
   if (topic === "repos") {
-    const result = await api("/repos");
+    args.expect(parsed, {});
+    const result = expectShape(
+      await api("/repos"),
+      "GET /repos",
+      { repos: is.array }
+    );
     if (asJson) {
       out.json(result);
       return;
@@ -433,6 +752,7 @@ async function catalogCommand(topic, parsed) {
     return;
   }
   if (topic === "branches") {
+    args.expect(parsed, { positional: 1 });
     const repoFullName = args.required(parsed, 0, "owner/repo");
     const segments = repoFullName.split("/");
     const [owner, repo] = segments;
@@ -443,15 +763,15 @@ async function catalogCommand(topic, parsed) {
       );
     }
     const result = await api(
-      `/repos/${owner}/${repo}/branches`
+      path`/repos/${owner}/${repo}/branches`
     );
+    if (!result.result) {
+      throw new CliError(`No GitHub installation covers ${repoFullName}.`);
+    }
     if (asJson) {
       out.json(result);
       return;
     }
-    if (!result.result) {
-      throw new CliError(`No GitHub installation covers ${repoFullName}.`);
-    }
     for (const branch of result.result.branches) {
       out.line(
         branch === result.result.defaultBranch ? `${out.cell(branch)} ${out.paint("(default)", "dim")}` : out.cell(branch)
@@ -460,7 +780,12 @@ async function catalogCommand(topic, parsed) {
     return;
   }
   if (topic === "models") {
-    const result = await api("/models");
+    args.expect(parsed, {});
+    const result = expectShape(
+      await api("/models"),
+      "GET /models",
+      { harnesses: is.array, gatewayModels: is.array }
+    );
     if (asJson) {
       out.json(result);
       return;
@@ -477,7 +802,12 @@ async function catalogCommand(topic, parsed) {
     return;
   }
   if (topic === "skills") {
-    const result = await api("/skills");
+    args.expect(parsed, {});
+    const result = expectShape(
+      await api("/skills"),
+      "GET /skills",
+      { skills: is.array }
+    );
     if (asJson) {
       out.json(result);
       return;
@@ -504,17 +834,24 @@ THE LOOP
   hepha run "<prompt>" --repo owner/repo --follow
       Start a session and follow it until it finishes or asks you something.
       Exit 0 completed \xB7 3 waiting on a human \xB7 1 failed.
+      [--title "\u2026"] [--task-type implement|new-project|question|draft]
+      [--model <slug>] [--harness claude-code|codex] [--branch <name>]
+      [--skill <id>]\u2026
   hepha questions list [--session <id>]
+  hepha questions show <batchId>
   hepha questions answer <batchId> --option <questionId>=1,2 --text <questionId>="\u2026"
+                                   [--answers '<json array>']
+  hepha questions cancel <batchId>
   hepha approvals list | show <id> | approve <id> | reject <id> --mode rework --feedback "\u2026"
 
 SESSIONS
   hepha sessions list [--status active|waiting|done] [--repo owner/repo]
-                      [--page N] [--limit N] [--all]
+                      [--search "\u2026"] [--page N] [--limit N] [--all]
   hepha sessions get <id>
-  hepha sessions logs <id> [--after <sequence>] [--follow]
+  hepha sessions logs <id> [--after <sequence>] [--limit N] [--follow]
   hepha sessions send <id> "<message>"
-  hepha sessions pause|resume|kill|archive <id> [--reason "\u2026"]
+  hepha sessions pause|resume|archive <id>
+  hepha sessions kill <id> [--reason "\u2026"]
   hepha sessions checks|pr|verify <id>
 
 CATALOG
@@ -532,31 +869,47 @@ AUTH
   hepha keys revoke <keyId>
 
 ENVIRONMENT
-  HEPHA_API_KEY   Act as an agent. Takes precedence over a stored login.
-  HEPHA_TOKEN     A device-flow session token, instead of ~/.hepha/config.json.
-  HEPHA_URL       Platform base URL.
+  HEPHA_API_KEY     Act as an agent. Takes precedence over a stored login, so
+                    the human-only commands (approvals approve/reject, keys)
+                    answer 403 while it is set \u2014 unset it to act as yourself.
+  HEPHA_TOKEN       A device-flow session token, instead of ~/.hepha/config.json.
+  HEPHA_URL         Platform base URL.
+  HEPHA_TIMEOUT_MS  Per-request timeout in milliseconds (default 30000).
 
 GLOBAL FLAGS
   --json          Machine-readable output on stdout. Every command that
                   returns data honours it; login is interactive and does not.
+                  Failures print {"ok":false,"error":{\u2026}} and keep their exit code.
+  --quiet         Suppress the streamed transcript while following a session.
+  --version       Print the version and exit.
+  --help          Print this.
+
+Unknown flags and surplus arguments are refused: for an agent, a typo must
+fail rather than run with default options.
 
 `;
 function helpCommand() {
   const baseUrl = config.load().baseUrl.replace(/\/$/, "");
-  out.line(`${HELP}Full reference: ${baseUrl}/api/v1/docs`);
+  out.line(`${HELP}hepha ${VERSION} \xB7 full reference: ${baseUrl}/api/v1/docs`);
 }
 
 // src/commands/keys.ts
+var ACTIONS2 = ["list", "create", "revoke"];
 async function keysCommand(parsed) {
-  const action = parsed.positional[0] ?? "list";
+  const action = args.action(parsed, "keys", ACTIONS2, "list");
   const asJson = parsed.booleans.has("json");
   if (action === "list") {
-    const result = await api("/keys");
+    args.expect(parsed, { positional: 1 });
+    const result2 = expectShape(
+      await api("/keys"),
+      "GET /keys",
+      { keys: is.array }
+    );
     if (asJson) {
-      out.json(result);
+      out.json(result2);
       return;
     }
-    if (result.keys.length === 0) {
+    if (result2.keys.length === 0) {
       out.line("No keys. Create one with `hepha keys create <name>`.");
       return;
     }
@@ -567,7 +920,7 @@ async function keysCommand(parsed) {
         out.paint("PREFIX", "dim"),
         out.paint("SCOPES", "dim")
       ],
-      ...result.keys.map((key) => [
+      ...result2.keys.map((key) => [
         out.cell(key.id),
         out.cell(key.name ?? "\u2014"),
         out.cell(key.start ?? "\u2014"),
@@ -577,17 +930,28 @@ async function keysCommand(parsed) {
     return;
   }
   if (action === "create") {
+    args.expect(parsed, {
+      flags: ["scope", "expires-in-days"],
+      positional: 2
+    });
     const name = args.required(parsed, 1, "name");
     const scopes = parsed.repeated.scope;
-    const expiresInDays = args.number(parsed, "expires-in-days");
-    const created = await api("/keys", {
-      method: "POST",
-      body: {
-        name,
-        ...scopes && scopes.length > 0 ? { scopes } : {},
-        ...expiresInDays !== void 0 ? { expiresInDays } : {}
-      }
+    const expiresInDays = args.integer(parsed, "expires-in-days", {
+      min: 1,
+      max: 365
     });
+    const created = expectShape(
+      await api("/keys", {
+        method: "POST",
+        body: {
+          name,
+          ...scopes && scopes.length > 0 ? { scopes } : {},
+          ...expiresInDays !== void 0 ? { expiresInDays } : {}
+        }
+      }),
+      "POST /keys",
+      { key: is.string, scopes: is.array }
+    );
     if (asJson) {
       out.json(created);
       return;
@@ -607,19 +971,16 @@ async function keysCommand(parsed) {
     out.line(out.paint(`  Scopes: ${created.scopes.join(" ")}`, "dim"));
     return;
   }
-  if (action === "revoke") {
-    const keyId = args.required(parsed, 1, "keyId");
-    const result = await api(`/keys/${keyId}`, {
-      method: "DELETE"
-    });
-    if (asJson) {
-      out.json(result);
-      return;
-    }
-    out.line(`${out.paint("\u2713", "green")} Revoked ${out.cell(keyId)}`);
+  args.expect(parsed, { positional: 2 });
+  const keyId = args.required(parsed, 1, "keyId");
+  const result = await api(path`/keys/${keyId}`, {
+    method: "DELETE"
+  });
+  if (asJson) {
+    out.json(result);
     return;
   }
-  throw new CliError(`Unknown keys command "${action}".`, 2);
+  out.line(`${out.paint("\u2713", "green")} Revoked ${out.cell(keyId)}`);
 }
 
 // src/commands/login.ts
@@ -644,6 +1005,12 @@ var API_SCOPES = [
 var DEFAULT_API_SCOPES = API_SCOPES.filter(
   (scope) => scope.endsWith(":read")
 );
+var SESSION = {
+  /** Cookie + session row lifetime: 30 days. */
+  EXPIRES_IN: 60 * 60 * 24 * 30,
+  /** Refresh the expiry at most once a day, to avoid a write per request. */
+  UPDATE_AGE: 60 * 60 * 24
+};
 var DEVICE_AUTHORIZATION = {
   /** Only these clients may open a device flow. */
   CLIENT_IDS: ["hepha-cli"],
@@ -652,9 +1019,52 @@ var DEVICE_AUTHORIZATION = {
   /** Minimum delay the CLI must wait between two token polls. */
   INTERVAL: "5s",
   /** Page a human visits to approve a pending device. */
-  VERIFICATION_PATH: "/device"
+  VERIFICATION_PATH: "/device",
+  /**
+   * Per-IP ceiling on `/device/token`. The window is deliberately SHORTER than
+   * INTERVAL: Better Auth only resets its counter when two requests are further
+   * apart than the window, so a 5s poll under the default 60s window never reset
+   * it and every login 429'd partway through the code's lifetime.
+   */
+  POLL_RATE_LIMIT: { WINDOW_SECONDS: 4, MAX_REQUESTS: 10 }
+};
+
+// src/lib/device-token-error.ts
+var deviceTokenError = {
+  /** What the server said, when it said anything at all. */
+  message(error) {
+    if (!error || typeof error !== "object") {
+      return void 0;
+    }
+    const message = error.message;
+    return typeof message === "string" && message.length > 0 ? message : void 0;
+  },
+  /** Better Auth answers `X-Retry-After`, the platform the standard header. */
+  retryAfter(error) {
+    if (!error || typeof error !== "object") {
+      return void 0;
+    }
+    const headers = error.headers;
+    if (!(headers instanceof Headers)) {
+      return void 0;
+    }
+    const raw = headers.get("x-retry-after") ?? headers.get("retry-after") ?? void 0;
+    if (!raw) {
+      return void 0;
+    }
+    const seconds = Number(raw.trim());
+    return Number.isFinite(seconds) && seconds > 0 ? seconds : void 0;
+  }
 };
 
+// src/commands/login-backoff.ts
+function nextPollDelay(interval, remainingSeconds) {
+  if (remainingSeconds <= 0) {
+    return null;
+  }
+  return Math.min(interval, remainingSeconds);
+}
+
 // src/lib/open-browser.ts
 import { spawn } from "child_process";
 function openBrowser(url) {
@@ -674,12 +1084,14 @@ function openBrowser(url) {
 
 // src/commands/login.ts
 var CLIENT_ID = DEVICE_AUTHORIZATION.CLIENT_IDS[0];
+var MIN_BACKOFF = 10;
 function sleep(seconds) {
   return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
 }
 async function loginCommand(parsed) {
+  args.expect(parsed, { flags: ["url"] });
   const requested = parsed.flags.url?.trim();
-  if (requested && !isHttpUrl(requested)) {
+  if (requested !== void 0 && !isHttpUrl(requested)) {
     throw new CliError(`--url is not a valid http(s) URL: "${requested}".`, 2);
   }
   const baseUrl = (requested ?? config.load().baseUrl).replace(/\/$/, "");
@@ -706,12 +1118,23 @@ async function loginCommand(parsed) {
   let interval = device.interval ?? 5;
   const deadline = Date.now() + (device.expires_in ?? 900) * 1e3;
   while (Date.now() < deadline) {
-    await sleep(interval);
+    const delay = nextPollDelay(interval, (deadline - Date.now()) / 1e3);
+    if (delay === null) {
+      break;
+    }
+    await sleep(delay);
     const { data: token, error } = await authClient.device.token({
       grant_type: "urn:ietf:params:oauth:grant-type:device_code",
       device_code: device.device_code,
       client_id: CLIENT_ID
     });
+    if (error?.status === 429) {
+      interval = Math.max(
+        deviceTokenError.retryAfter(error) ?? interval * 2,
+        MIN_BACKOFF
+      );
+      continue;
+    }
     if (token?.access_token) {
       const identity = await api("/me", {
         as: { baseUrl, token: token.access_token }
@@ -745,7 +1168,7 @@ async function loginCommand(parsed) {
         throw new CliError("Access denied \u2014 the request was rejected.");
       default:
         throw new CliError(
-          error.error_description || "Device authorization failed."
+          error.error_description || deviceTokenError.message(error) || `Device authorization failed (HTTP ${error.status}).`
         );
     }
   }
@@ -754,6 +1177,7 @@ async function loginCommand(parsed) {
 
 // src/commands/logout.ts
 function logoutCommand(parsed) {
+  args.expect(parsed, {});
   config.clear();
   if (parsed.booleans.has("json")) {
     out.json({ signedOut: true });
@@ -762,47 +1186,107 @@ function logoutCommand(parsed) {
   out.line("Signed out.");
 }
 
-// src/commands/questions.ts
-function printBatch(batch) {
-  out.line(
-    `${out.paint(out.cell(batch.sessionTitle), "bold")}  ${out.paint(`round ${batch.round}`, "dim")}`
-  );
-  out.line(
-    out.paint(
-      `batch ${out.cell(batch.id)} \xB7 session ${out.cell(batch.sessionId)}`,
-      "dim"
-    )
-  );
-  for (const question of batch.questions) {
-    out.line();
-    if (question.header) {
-      out.line(out.paint(out.cell(question.header), "dim"));
+// src/commands/collect-answers.ts
+var LIMITS = {
+  QUESTION_ID: 40,
+  OPTION_ID: 40,
+  OPTIONS_PER_ANSWER: 50,
+  FREE_TEXT: 1e4,
+  ANSWERS: 50
+};
+function validateAnswer(answer, label) {
+  if (answer.questionId.trim().length === 0) {
+    throw new CliError(`${label} needs a non-empty "questionId".`, 2);
+  }
+  if (answer.questionId.length > LIMITS.QUESTION_ID) {
+    throw new CliError(
+      `${label} has a "questionId" longer than ${LIMITS.QUESTION_ID} characters.`,
+      2
+    );
+  }
+  const options = answer.selectedOptionIds;
+  if (options !== void 0) {
+    if (options.length > LIMITS.OPTIONS_PER_ANSWER) {
+      throw new CliError(
+        `${label} selects more than ${LIMITS.OPTIONS_PER_ANSWER} options.`,
+        2
+      );
     }
-    out.line(
-      `${out.paint(out.cell(question.id), "dim")} ${out.safe(question.body)}`
+    for (const id of options) {
+      if (id.trim().length === 0) {
+        throw new CliError(`${label} has an empty option id.`, 2);
+      }
+      if (id.trim().length > LIMITS.OPTION_ID) {
+        throw new CliError(
+          `${label} has an option id longer than ${LIMITS.OPTION_ID} characters.`,
+          2
+        );
+      }
+    }
+  }
+  if (answer.freeText !== void 0) {
+    const freeText = answer.freeText.trim();
+    if (freeText.length === 0) {
+      throw new CliError(`${label} has empty free text.`, 2);
+    }
+    if (freeText.length > LIMITS.FREE_TEXT) {
+      throw new CliError(
+        `${label} has free text longer than ${LIMITS.FREE_TEXT} characters.`,
+        2
+      );
+    }
+  }
+  if ((options === void 0 || options.length === 0) && answer.freeText === void 0) {
+    throw new CliError(
+      `${label} answers nothing. Give it at least one option id or some free text.`,
+      2
     );
-    if (question.image) {
-      out.line(out.paint(`    (image) ${out.cell(question.image)}`, "dim"));
+  }
+}
+function parseAnswersFlag(raw) {
+  let decoded;
+  try {
+    decoded = JSON.parse(raw);
+  } catch {
+    throw new CliError("--answers expects a JSON array.", 2);
+  }
+  if (!Array.isArray(decoded) || decoded.length === 0) {
+    throw new CliError(
+      `--answers expects a non-empty JSON array, e.g. '[{"questionId":"q1","selectedOptionIds":["1"]}]'.`,
+      2
+    );
+  }
+  if (decoded.length > LIMITS.ANSWERS) {
+    throw new CliError(
+      `--answers carries more than ${LIMITS.ANSWERS} entries.`,
+      2
+    );
+  }
+  for (const [index, entry] of decoded.entries()) {
+    const label = `--answers[${index}]`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new CliError(`${label} must be an object.`, 2);
     }
-    for (const option of question.options) {
-      const recommended = option.id === question.recommendedOptionId;
-      const label = option.label ? out.cell(option.label) : option.image ? out.paint(`(image) ${out.cell(option.image)}`, "dim") : out.paint("(no label)", "dim");
-      out.line(
-        `    ${out.cell(option.id)}) ${label}${recommended ? out.paint("  \u2190 recommended", "green") : ""}`
+    const answer = entry;
+    if (typeof answer.questionId !== "string") {
+      throw new CliError(`${label} needs a non-empty "questionId".`, 2);
+    }
+    if (answer.selectedOptionIds !== void 0 && (!Array.isArray(answer.selectedOptionIds) || answer.selectedOptionIds.some((id) => typeof id !== "string"))) {
+      throw new CliError(
+        `${label}.selectedOptionIds must be an array of strings.`,
+        2
       );
     }
-    if (question.allowFreeText) {
-      out.line(out.paint("    free text accepted", "dim"));
+    if (answer.freeText !== void 0 && typeof answer.freeText !== "string") {
+      throw new CliError(`${label}.freeText must be a string.`, 2);
     }
+    validateAnswer(entry, label);
   }
+  return decoded;
 }
 function collectAnswers(parsed) {
   if (parsed.flags.answers) {
-    try {
-      return JSON.parse(parsed.flags.answers);
-    } catch {
-      throw new CliError("--answers expects a JSON array.", 2);
-    }
+    return parseAnswersFlag(parsed.flags.answers);
   }
   const byQuestion = /* @__PURE__ */ new Map();
   const put = (pair, apply) => {
@@ -832,24 +1316,74 @@ function collectAnswers(parsed) {
       2
     );
   }
+  if (answers.length > LIMITS.ANSWERS) {
+    throw new CliError(
+      `More than ${LIMITS.ANSWERS} answers in one submission.`,
+      2
+    );
+  }
+  for (const answer of answers) {
+    validateAnswer(answer, `--option/--text ${answer.questionId}`);
+  }
   return answers;
 }
+
+// src/commands/questions.ts
+var ACTIONS3 = ["list", "show", "answer", "cancel"];
+function printBatch(batch) {
+  out.line(
+    `${out.paint(out.cell(batch.sessionTitle), "bold")}  ${out.paint(`round ${batch.round}`, "dim")}`
+  );
+  out.line(
+    out.paint(
+      `batch ${out.cell(batch.id)} \xB7 session ${out.cell(batch.sessionId)}`,
+      "dim"
+    )
+  );
+  for (const question of batch.questions) {
+    out.line();
+    if (question.header) {
+      out.line(out.paint(out.cell(question.header), "dim"));
+    }
+    out.line(
+      `${out.paint(out.cell(question.id), "dim")} ${out.safe(question.body)}`
+    );
+    if (question.image) {
+      out.line(out.paint(`    (image) ${out.cell(question.image)}`, "dim"));
+    }
+    for (const option of question.options) {
+      const recommended = option.id === question.recommendedOptionId;
+      const label = option.label ? out.cell(option.label) : option.image ? out.paint(`(image) ${out.cell(option.image)}`, "dim") : out.paint("(no label)", "dim");
+      out.line(
+        `    ${out.cell(option.id)}) ${label}${recommended ? out.paint("  \u2190 recommended", "green") : ""}`
+      );
+    }
+    if (question.allowFreeText) {
+      out.line(out.paint("    free text accepted", "dim"));
+    }
+  }
+}
 async function questionsCommand(parsed) {
-  const action = parsed.positional[0] ?? "list";
+  const action = args.action(parsed, "questions", ACTIONS3, "list");
   const asJson = parsed.booleans.has("json");
   if (action === "list") {
-    const path = parsed.flags.session ? `/sessions/${parsed.flags.session}/questions` : "/questions";
-    const result = await api(path);
+    args.expect(parsed, { flags: ["session"], positional: 1 });
+    const session = parsed.flags.session;
+    const result2 = expectShape(
+      await api(session ? path`/sessions/${session}/questions` : "/questions"),
+      "GET /questions",
+      { items: is.array }
+    );
     if (asJson) {
-      out.json(result);
+      out.json(result2);
       return;
     }
-    if (result.items.length === 0) {
+    if (result2.items.length === 0) {
       out.line("Nothing waiting on you.");
       return;
     }
     out.table(
-      result.items.map((batch) => [
+      result2.items.map((batch) => [
         out.cell(batch.id),
         out.cell(batch.sessionId),
         `${batch.questions.length} question(s)`,
@@ -858,9 +1392,17 @@ async function questionsCommand(parsed) {
     );
     return;
   }
+  args.expect(parsed, {
+    positional: 2,
+    ...action === "answer" ? { flags: ["option", "text", "answers"] } : {}
+  });
   const batchId = args.required(parsed, 1, "batchId");
   if (action === "show") {
-    const batch = await api(`/questions/${batchId}`);
+    const batch = expectShape(
+      await api(path`/questions/${batchId}`),
+      "GET /questions/{id}",
+      { id: is.string, questions: is.array, sessionTitle: is.string }
+    );
     if (asJson) {
       out.json(batch);
       return;
@@ -869,34 +1411,34 @@ async function questionsCommand(parsed) {
     return;
   }
   if (action === "answer") {
-    const result = await api(
-      `/questions/${batchId}/submit`,
-      { method: "POST", body: { answers: collectAnswers(parsed) } }
+    const result2 = expectShape(
+      await api(path`/questions/${batchId}/submit`, {
+        method: "POST",
+        body: { answers: collectAnswers(parsed) }
+      }),
+      "POST /questions/{id}/submit",
+      { answeredCount: is.number }
     );
     if (asJson) {
-      out.json(result);
+      out.json(result2);
       return;
     }
     out.line(
-      `${out.paint("\u2713", "green")} Answered ${result.answeredCount} question(s); the session resumes.`
+      `${out.paint("\u2713", "green")} Answered ${result2.answeredCount} question(s); the session resumes.`
     );
     return;
   }
-  if (action === "cancel") {
-    const result = await api(
-      `/questions/${batchId}/cancel`,
-      { method: "POST", body: {} }
-    );
-    if (asJson) {
-      out.json(result);
-      return;
-    }
-    out.line(
-      'Round cancelled. The session stays parked \u2014 send a message to steer it: `hepha sessions send <id> "\u2026"`'
-    );
+  const result = await api(
+    path`/questions/${batchId}/cancel`,
+    { method: "POST", body: {} }
+  );
+  if (asJson) {
+    out.json(result);
     return;
   }
-  throw new CliError(`Unknown questions command "${action}".`, 2);
+  out.line(
+    'Round cancelled. The session stays parked \u2014 send a message to steer it: `hepha sessions send <id> "\u2026"`'
+  );
 }
 
 // src/lib/format-event.ts
@@ -951,15 +1493,19 @@ function formatEvent(event) {
 var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "killed", "abstained"]);
 var BLOCKED = /* @__PURE__ */ new Set(["waiting_human", "awaiting_approval"]);
 var POLL_SECONDS = 3;
+var PAGE_SIZE = 200;
 function sleep2(seconds) {
   return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
 }
 async function followSession(sessionId, options = {}) {
   let cursor = options.after ?? 0;
   for (; ; ) {
-    const page = await api(
-      `/sessions/${sessionId}/events`,
-      { query: { after: cursor || void 0, limit: 200 } }
+    const page = expectShape(
+      await api(path`/sessions/${sessionId}/events`, {
+        query: { after: cursor || void 0, limit: PAGE_SIZE }
+      }),
+      "GET /sessions/{id}/events",
+      { items: is.array }
     );
     for (const event of page.items) {
       cursor = Math.max(cursor, event.sequence);
@@ -977,7 +1523,7 @@ async function followSession(sessionId, options = {}) {
     if (page.hasMore) {
       continue;
     }
-    const session = await api(`/sessions/${sessionId}`);
+    const session = await api(path`/sessions/${sessionId}`);
     if (TERMINAL.has(session.status) || BLOCKED.has(session.status)) {
       return session;
     }
@@ -1044,38 +1590,71 @@ function sessionOutcome(session) {
     case "waiting_human":
       return new CliError(
         `Waiting on an answer \u2014 \`hepha questions list --session ${session.id}\``,
-        3
+        3,
+        {},
+        session
       );
     case "awaiting_approval":
       return new CliError(
         "Waiting on a guardrail approval \u2014 `hepha approvals list`",
-        3
+        3,
+        {},
+        session
       );
     default:
       return new CliError(
-        `Session ended ${session.status}${session.statusReason ? `: ${session.statusReason}` : "."}`
+        `Session ended ${session.status}${session.statusReason ? `: ${session.statusReason}` : "."}`,
+        1,
+        {},
+        session
       );
   }
 }
 
 // src/commands/run.ts
+var TASK_TYPES = [
+  "implement",
+  "new-project",
+  "question",
+  "draft"
+];
+var HARNESSES = [
+  "claude-code",
+  "codex"
+];
 async function runCommand(parsed) {
+  args.expect(parsed, {
+    flags: [
+      "title",
+      "task-type",
+      "model",
+      "harness",
+      "repo",
+      "branch",
+      "skill"
+    ],
+    booleans: ["follow"],
+    positional: 1
+  });
   const prompt = args.required(parsed, 0, "prompt");
   const asJson = parsed.booleans.has("json");
+  const taskType = args.choice(parsed, "task-type", TASK_TYPES);
+  const harness = args.choice(parsed, "harness", HARNESSES);
   const body = {
     prompt,
     ...parsed.flags.title ? { title: parsed.flags.title } : {},
-    ...parsed.flags["task-type"] ? { taskType: parsed.flags["task-type"] } : {},
+    ...taskType ? { taskType } : {},
     ...parsed.flags.model ? { modelSelection: parsed.flags.model } : {},
-    ...parsed.flags.harness ? { harnessPin: parsed.flags.harness } : {},
+    ...harness ? { harnessPin: harness } : {},
     ...parsed.flags.repo ? { repoFullName: parsed.flags.repo } : {},
     ...parsed.flags.branch ? { branch: parsed.flags.branch } : {},
     ...parsed.repeated.skill ? { pinnedSkillIds: parsed.repeated.skill } : {}
   };
-  const session = await api("/sessions", {
-    method: "POST",
-    body
-  });
+  const session = expectShape(
+    await api("/sessions", { method: "POST", body }),
+    "POST /sessions",
+    { id: is.string, title: is.string, status: is.string }
+  );
   if (!parsed.booleans.has("follow")) {
     if (asJson) {
       out.json(session);
@@ -1086,41 +1665,78 @@ async function runCommand(parsed) {
     out.line(out.paint(`  hepha sessions logs ${session.id} --follow`, "dim"));
     return;
   }
-  if (!asJson) {
+  const quiet = asJson || parsed.booleans.has("quiet");
+  if (!quiet) {
     out.line(out.paint(`session ${session.id}`, "dim"));
     out.line();
   }
-  const final = await followSession(session.id, { quiet: asJson });
+  const final = await followSession(session.id, { quiet });
+  const outcome = sessionOutcome(final);
   if (asJson) {
-    out.json(final);
+    if (!outcome) {
+      out.json(final);
+    }
   } else {
     out.line();
     printSession(final);
   }
-  const outcome = sessionOutcome(final);
   if (outcome) {
     throw outcome;
   }
 }
 
 // src/commands/sessions.ts
+var ACTIONS4 = [
+  "list",
+  "get",
+  "logs",
+  "send",
+  "pause",
+  "resume",
+  "kill",
+  "archive",
+  "checks",
+  "pr",
+  "verify"
+];
 var CONTROL_PATHS = {
   pause: "pause",
   resume: "resume",
   kill: "kill",
   archive: "archive"
 };
+var STATUS_GROUPS = ["active", "waiting", "done"];
+var SESSION_FIELDS = {
+  id: is.string,
+  title: is.string,
+  status: is.string,
+  taskType: is.string,
+  repos: is.array,
+  deliverables: is.array
+};
+function detail(payload, endpoint) {
+  return expectShape(payload, endpoint, SESSION_FIELDS);
+}
 async function listSessions(parsed) {
-  const result = await api("/sessions", {
-    query: {
-      statusGroup: parsed.flags.status,
-      repoFullName: parsed.flags.repo,
-      search: parsed.flags.search,
-      page: args.number(parsed, "page"),
-      limit: args.number(parsed, "limit") ?? 20,
-      scope: parsed.booleans.has("all") ? "all" : void 0
-    }
+  args.expect(parsed, {
+    flags: ["status", "repo", "search", "page", "limit"],
+    booleans: ["all"],
+    positional: 1
   });
+  const result = expectShape(
+    await api("/sessions", {
+      query: {
+        statusGroup: args.choice(parsed, "status", STATUS_GROUPS),
+        repoFullName: parsed.flags.repo,
+        search: parsed.flags.search,
+        page: args.integer(parsed, "page", { min: 1 }),
+        limit: args.integer(parsed, "limit", { min: 1, max: 100 }),
+        scope: parsed.booleans.has("all") ? "all" : void 0
+      }
+    }),
+    "GET /sessions",
+    { data: is.array, "pagination.page": is.number }
+  );
   if (parsed.booleans.has("json")) {
     out.json(result);
     return;
@@ -1148,34 +1764,42 @@ async function listSessions(parsed) {
   );
 }
 async function showLogs(parsed) {
+  args.expect(parsed, {
+    flags: ["after", "limit"],
+    booleans: ["follow"],
+    positional: 2
+  });
   const sessionId = args.required(parsed, 1, "sessionId");
   const asJson = parsed.booleans.has("json");
-  const after = args.number(parsed, "after");
+  const after = args.integer(parsed, "after", { min: 0 });
   if (parsed.booleans.has("follow")) {
     const session = await followSession(sessionId, {
-      quiet: asJson,
+      quiet: asJson || parsed.booleans.has("quiet"),
       ...after !== void 0 ? { after } : {}
     });
+    const outcome = sessionOutcome(session);
     if (asJson) {
-      out.json(session);
+      if (!outcome) {
+        out.json(session);
+      }
     } else {
       out.line();
       printSession(session);
     }
-    const outcome = sessionOutcome(session);
     if (outcome) {
       throw outcome;
     }
     return;
   }
-  const page = await api(
-    `/sessions/${sessionId}/events`,
-    {
+  const page = expectShape(
+    await api(path`/sessions/${sessionId}/events`, {
       query: {
         after,
-        limit: args.number(parsed, "limit") ?? 100
+        limit: args.integer(parsed, "limit", { min: 1, max: 200 })
       }
-    }
+    }),
+    "GET /sessions/{id}/events",
+    { items: is.array }
   );
   if (asJson) {
     out.json(page);
@@ -1198,7 +1822,7 @@ async function showLogs(parsed) {
   }
 }
 async function sessionsCommand(parsed) {
-  const action = parsed.positional[0] ?? "list";
+  const action = args.action(parsed, "sessions", ACTIONS4, "list");
   const asJson = parsed.booleans.has("json");
   if (action === "list") {
     return await listSessions(parsed);
@@ -1206,21 +1830,17 @@ async function sessionsCommand(parsed) {
   if (action === "logs") {
     return await showLogs(parsed);
   }
-  const sessionId = args.required(parsed, 1, "sessionId");
-  if (action === "get") {
-    const session = await api(`/sessions/${sessionId}`);
-    if (asJson) {
-      out.json(session);
-      return;
-    }
-    printSession(session);
-    return;
-  }
   if (action === "send") {
+    args.expect(parsed, { positional: 3 });
+    const sessionId2 = args.required(parsed, 1, "sessionId");
     const message = args.required(parsed, 2, "message");
-    const result = await api(
-      `/sessions/${sessionId}/messages`,
-      { method: "POST", body: { message } }
+    const result = expectShape(
+      await api(path`/sessions/${sessionId2}/messages`, {
+        method: "POST",
+        body: { message }
+      }),
+      "POST /sessions/{id}/messages",
+      { delivery: is.string }
     );
     if (asJson) {
       out.json(result);
@@ -1231,13 +1851,31 @@ async function sessionsCommand(parsed) {
     );
     return;
   }
+  args.expect(parsed, {
+    positional: 2,
+    ...action === "kill" ? { flags: ["reason"] } : {}
+  });
+  const sessionId = args.required(parsed, 1, "sessionId");
+  if (action === "get") {
+    const session = detail(
+      await api(path`/sessions/${sessionId}`),
+      "GET /sessions/{id}"
+    );
+    if (asJson) {
+      out.json(session);
+      return;
+    }
+    printSession(session);
+    return;
+  }
   if (Object.hasOwn(CONTROL_PATHS, action)) {
-    const session = await api(
-      `/sessions/${sessionId}/${CONTROL_PATHS[action]}`,
-      {
+    const controlPath = CONTROL_PATHS[action];
+    const session = detail(
+      await api(path`/sessions/${sessionId}/${controlPath}`, {
         method: "POST",
         body: action === "kill" && parsed.flags.reason ? { reason: parsed.flags.reason } : {}
-      }
+      }),
+      `POST /sessions/{id}/${controlPath}`
     );
     if (asJson) {
       out.json(session);
@@ -1247,35 +1885,42 @@ async function sessionsCommand(parsed) {
     return;
   }
   if (action === "checks") {
-    const result = await api(
-      `/sessions/${sessionId}/checks`,
-      { method: "POST", body: {} }
-    );
-    out.json(result);
-    return;
-  }
-  if (action === "pr") {
     out.json(
       await api(
-        `/sessions/${sessionId}/pr-checks`
+        path`/sessions/${sessionId}/checks`,
+        { method: "POST", body: {} }
       )
     );
     return;
   }
-  if (action === "verify") {
+  if (action === "pr") {
     out.json(
       await api(
-        `/sessions/${sessionId}/verification`
+        path`/sessions/${sessionId}/pr-checks`
       )
     );
     return;
   }
-  throw new CliError(`Unknown sessions command "${action}".`, 2);
+  out.json(
+    await api(
+      path`/sessions/${sessionId}/verification`
+    )
+  );
 }
 
 // src/commands/whoami.ts
 async function whoamiCommand(parsed) {
-  const identity = await api("/me");
+  args.expect(parsed, {});
+  const identity = expectShape(
+    await api("/me"),
+    "GET /me",
+    {
+      "user.name": is.string,
+      "user.email": is.string,
+      "auth.method": is.string,
+      "auth.scopes": is.array
+    }
+  );
   if (parsed.booleans.has("json")) {
     out.json(identity);
     return;
@@ -1297,6 +1942,19 @@ async function whoamiCommand(parsed) {
   ]);
 }
 
+// src/lib/wants-json.ts
+function wantsJson(argv) {
+  for (const token of argv) {
+    if (token === "--") {
+      return false;
+    }
+    if (token === "--json") {
+      return true;
+    }
+  }
+  return false;
+}
+
 // src/index.ts
 var CATALOG_TOPICS = /* @__PURE__ */ new Set(["repos", "branches", "models", "skills"]);
 async function dispatch(command, argv) {
@@ -1331,19 +1989,27 @@ async function dispatch(command, argv) {
   }
 }
 async function main() {
-  const [command, ...argv] = process.argv.slice(2);
+  const argv = process.argv.slice(2);
+  out.setJson(wantsJson(argv));
+  const [command, ...rest] = argv;
   if (!command || command === "help" || command === "--help") {
     helpCommand();
     return;
   }
-  await dispatch(command, argv);
+  if (command === "--version" || command === "-v" || command === "version") {
+    args.expect(args.parse(rest), {});
+    if (out.isJson()) {
+      out.json({ version: VERSION });
+    } else {
+      out.line(VERSION);
+    }
+    return;
+  }
+  await dispatch(command, rest);
 }
 main().catch((error) => {
-  if (error instanceof CliError) {
-    out.error(error.message);
-    process.exit(error.exitCode);
-  }
-  out.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
+  const failure = error instanceof CliError ? error : new CliError(error instanceof Error ? error.message : String(error));
+  out.failure(failure);
+  process.exit(failure.exitCode);
 });
 //# sourceMappingURL=index.js.map