@pome-sh/cli 0.19.0 → 0.21.0

package/dist/chunk-PPJUFV6S.js

@@ -0,0 +1,1179 @@
+import { readManifest, normalizeManifestTwins } from './chunk-BSKITCXD.js';
+import { createHostedClient, perTwinReturnedByCloud, parseTaskFile, runAgentCommand, writeRunArtifactsCore, toTwinHttpEvent, redactJsonl, uploadRunBlobs, scoreFromFinalizeResponse, scoreStatus } from './chunk-D3GRORLQ.js';
+import { MOUNTED_TWINS, HostedAuthError, HostedDiscardRefusedError, HostedQuotaError, HostedOrchError, HostedTrialError, agentResponseSchema } from './chunk-2Q7AYEUA.js';
+import { redactSecrets, redactEvent } from './chunk-SG6ZTIMT.js';
+import { existsSync } from 'node:fs';
+import { readFile, rm, stat, mkdir, writeFile, chmod, mkdtemp, readdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { tmpdir, homedir } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createInterface } from 'node:readline';
+import { randomUUID, createHash } from 'node:crypto';
+
+var VERDICT_ARTIFACT_VERSION = 1;
+var VERDICT_FILENAME = "verdict.json";
+async function writeVerdictArtifact(runDir, verdict) {
+  await writeFile(
+    join(runDir, VERDICT_FILENAME),
+    `${JSON.stringify(verdict, null, 2)}
+`,
+    "utf8"
+  );
+}
+function isVerdictArtifact(parsed) {
+  if (typeof parsed !== "object" || parsed === null) return false;
+  const v = parsed;
+  if (v.source !== "cloud-finalize") return false;
+  if (typeof v.session_id !== "string") return false;
+  if (typeof v.task_name !== "string") return false;
+  if (typeof v.task_path !== "string" && typeof v.scenario_path !== "string") return false;
+  if (v.group_id !== null && typeof v.group_id !== "string") return false;
+  if (typeof v.finalized_at !== "string") return false;
+  if (typeof v.passed !== "boolean") return false;
+  if (typeof v.score !== "number") return false;
+  if (!Array.isArray(v.criteria_results)) return false;
+  return v.criteria_results.every((r) => {
+    if (typeof r !== "object" || r === null) return false;
+    const result = r;
+    const criterion = result.criterion;
+    return typeof criterion === "object" && criterion !== null && typeof criterion.text === "string" && typeof result.reason === "string" && typeof result.passed === "boolean" && typeof result.skipped === "boolean";
+  });
+}
+function normalizeVerdictArtifact(parsed) {
+  const { scenario_path: legacyPath, task_path: taskPath, ...rest } = parsed;
+  return { ...rest, task_path: taskPath ?? legacyPath };
+}
+async function readVerdictArtifact(runDir) {
+  const path = join(runDir, VERDICT_FILENAME);
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isVerdictArtifact(parsed)) return null;
+    return { runDir, verdict: normalizeVerdictArtifact(parsed) };
+  } catch {
+    return null;
+  }
+}
+async function scanVerdictArtifacts(artifactsRoot) {
+  const found = [];
+  let slugs;
+  try {
+    slugs = await readdir(artifactsRoot);
+  } catch {
+    return found;
+  }
+  for (const slug of slugs) {
+    const slugDir = join(artifactsRoot, slug);
+    let runIds;
+    try {
+      runIds = await readdir(slugDir);
+    } catch {
+      continue;
+    }
+    for (const runId of runIds) {
+      const trial = await readVerdictArtifact(join(slugDir, runId));
+      if (trial) found.push(trial);
+    }
+  }
+  return found;
+}
+function groupRunSets(trials) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const trial of trials) {
+    const key = trial.verdict.group_id ?? `solo:${trial.verdict.session_id}`;
+    const bucket = byKey.get(key);
+    if (bucket) bucket.push(trial);
+    else byKey.set(key, [trial]);
+  }
+  const sets = [];
+  for (const bucket of byKey.values()) {
+    bucket.sort(
+      (a, b) => a.verdict.finalized_at.localeCompare(b.verdict.finalized_at)
+    );
+    const last = bucket[bucket.length - 1];
+    sets.push({
+      groupId: bucket[0].verdict.group_id,
+      taskName: bucket[0].verdict.task_name,
+      taskPath: bucket[0].verdict.task_path,
+      trials: bucket,
+      latestFinalizedAt: last.verdict.finalized_at,
+      anyFailed: bucket.some((t) => !t.verdict.passed)
+    });
+  }
+  sets.sort((a, b) => a.latestFinalizedAt.localeCompare(b.latestFinalizedAt));
+  return sets;
+}
+function latestFailedRunSet(sets) {
+  for (let i = sets.length - 1; i >= 0; i -= 1) {
+    if (sets[i].anyFailed) return sets[i];
+  }
+  return null;
+}
+async function discoverRunSet(target) {
+  const anchor = await readVerdictArtifact(target);
+  if (anchor) {
+    const root = join(target, "..", "..");
+    const sets2 = groupRunSets(await scanVerdictArtifacts(root));
+    const own = sets2.find(
+      (s) => anchor.verdict.group_id !== null && s.groupId === anchor.verdict.group_id || anchor.verdict.group_id === null && s.trials.length === 1 && s.trials[0].verdict.session_id === anchor.verdict.session_id
+    ) ?? groupRunSets([anchor])[0];
+    return { kind: "trial-dir", set: own, totalSets: Math.max(sets2.length, 1) };
+  }
+  if (!existsSync(target)) return { kind: "root", set: null, totalSets: 0 };
+  const sets = groupRunSets(await scanVerdictArtifacts(target));
+  return {
+    kind: "root",
+    set: latestFailedRunSet(sets),
+    totalSets: sets.length
+  };
+}
+async function loadTrialEvents(runDir) {
+  let raw;
+  try {
+    raw = await readFile(join(runDir, "events.jsonl"), "utf8");
+  } catch {
+    return [];
+  }
+  const events = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed === "object" && parsed !== null) events.push(parsed);
+    } catch {
+    }
+  }
+  return events;
+}
+var execFileAsync = promisify(execFile);
+var SERVICE = "sh.pome.cli";
+var ACCOUNT = "hosted";
+function keychainSupported() {
+  if (process.env.POME_CLI_DISABLE_KEYCHAIN === "1") return false;
+  return process.platform === "darwin";
+}
+async function writeKeychainCredentials(creds) {
+  if (!keychainSupported()) return;
+  const payload = JSON.stringify({
+    api_key: creds.api_key,
+    api_url: creds.api_url,
+    dashboard_url: creds.dashboard_url,
+    team_id: creds.team_id,
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  await execFileAsync("security", [
+    "add-generic-password",
+    "-U",
+    "-s",
+    SERVICE,
+    "-a",
+    ACCOUNT,
+    "-w",
+    payload
+  ]);
+}
+async function readKeychainCredentials() {
+  if (!keychainSupported()) return null;
+  try {
+    const { stdout } = await execFileAsync("security", [
+      "find-generic-password",
+      "-s",
+      SERVICE,
+      "-a",
+      ACCOUNT,
+      "-w"
+    ]);
+    const text = stdout.trim();
+    if (!text) return null;
+    const parsed = JSON.parse(text);
+    if (typeof parsed.api_key !== "string" || !parsed.api_key.trim()) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function deleteKeychainCredentials() {
+  if (!keychainSupported()) return false;
+  try {
+    await execFileAsync("security", [
+      "delete-generic-password",
+      "-s",
+      SERVICE,
+      "-a",
+      ACCOUNT
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/cli/credentials.ts
+var DEFAULT_PATH = () => join(homedir(), ".pome", "credentials.json");
+async function persistCredentialsAfterLogin(credentials, path = DEFAULT_PATH()) {
+  if (keychainSupported()) {
+    try {
+      await writeKeychainCredentials(credentials);
+      try {
+        await rm(path, { force: true });
+      } catch {
+      }
+      return { stored: "keychain" };
+    } catch {
+    }
+  }
+  await writeCredentialsFile(credentials, path);
+  return { stored: "file", path };
+}
+async function clearLocalCredentials(path = DEFAULT_PATH()) {
+  await deleteKeychainCredentials();
+  try {
+    await rm(path, { force: true });
+  } catch {
+  }
+}
+async function resolveCredentials(input) {
+  const envKey = process.env.POME_API_KEY;
+  if (envKey && envKey.trim().length > 0) {
+    const apiBaseUrl = resolveApiBaseUrl(input.apiBaseUrl, void 0);
+    return { apiKey: envKey.trim(), apiBaseUrl };
+  }
+  const keychain = await readKeychainCredentials();
+  if (keychain && typeof keychain.api_key === "string" && keychain.api_key.trim().length > 0) {
+    return {
+      apiKey: keychain.api_key.trim(),
+      apiBaseUrl: resolveApiBaseUrl(input.apiBaseUrl, keychain.api_url),
+      teamId: normalizeTeamId(keychain.team_id)
+    };
+  }
+  const path = input.credentialsPath ?? DEFAULT_PATH();
+  let raw;
+  try {
+    await assertSafeCredentialFileMode(path);
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    if (err instanceof Error && err.code === "ENOENT") {
+      throw new HostedAuthError(
+        `Hosted mode requires authentication. Run \`pome login\`, set POME_API_KEY in your environment, or sign in on macOS to store credentials in Keychain. Expected file: ${path}.`
+      );
+    }
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${path} is not valid JSON.`);
+  }
+  if (typeof parsed.api_key !== "string" || parsed.api_key.trim().length === 0) {
+    throw new Error(`${path} is missing "api_key".`);
+  }
+  return {
+    apiKey: parsed.api_key.trim(),
+    apiBaseUrl: resolveApiBaseUrl(input.apiBaseUrl, parsed.api_url),
+    teamId: normalizeTeamId(parsed.team_id)
+  };
+}
+function normalizeTeamId(raw) {
+  if (typeof raw !== "string") return void 0;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function resolveApiBaseUrl(callerInput, storedApiUrl) {
+  const candidate = callerInput ?? storedApiUrl;
+  if (typeof candidate !== "string" || candidate.trim().length === 0) {
+    throw new Error(
+      "Refusing to resolve hosted credentials: no apiBaseUrl supplied and no stored api_url found."
+    );
+  }
+  return normalizeBaseUrl(candidate);
+}
+async function assertSafeCredentialFileMode(path) {
+  const st = await stat(path);
+  const perm = st.mode & 511;
+  if ((perm & 63) !== 0) {
+    throw new Error(
+      `Refusing to read credentials at ${path}: mode 0${perm.toString(8)} is too permissive (group/other bits must be 0). Run: chmod 600 ${path}`
+    );
+  }
+}
+async function writeCredentialsFile(credentials, path = DEFAULT_PATH()) {
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await writeFile(
+    path,
+    `${JSON.stringify(
+      {
+        ...credentials,
+        created_at: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      null,
+      2
+    )}
+`,
+    { mode: 384 }
+  );
+  await chmod(path, 384);
+}
+function normalizeBaseUrl(raw) {
+  return new URL(raw).toString().replace(/\/$/, "");
+}
+function resolveSeams(opts) {
+  return {
+    stdinIsTTY: opts.stdinIsTTY ?? Boolean(process.stdin.isTTY),
+    confirm: opts.confirm ?? promptYesNo,
+    ask: opts.ask ?? promptLine
+  };
+}
+async function requestAgent(creds, body) {
+  const res = await fetch(`${creds.apiBaseUrl}/v1/agents`, {
+    method: "POST",
+    headers: { "x-api-key": creds.apiKey, "content-type": "application/json" },
+    body: JSON.stringify(prunePostBody(body))
+  }).catch((err) => {
+    throw new HostedOrchError(err instanceof Error ? err.message : "network error");
+  });
+  const text = await res.text();
+  let json = {};
+  try {
+    json = text.length ? JSON.parse(text) : {};
+  } catch {
+    throw new HostedOrchError(`non-JSON response (status ${res.status})`);
+  }
+  return { ok: res.ok, status: res.status, json };
+}
+function prunePostBody(body) {
+  const out = { name: body.name };
+  if (body.slug !== void 0) out.slug = body.slug;
+  if (body.description !== void 0) out.description = body.description;
+  if (body.version !== void 0) out.version = body.version;
+  if (body.framework !== void 0) out.framework = body.framework;
+  if (body.twins && body.twins.length > 0) out.twins = body.twins;
+  if (body.confirm !== void 0) out.confirm = body.confirm;
+  return out;
+}
+function parseOkAgent(json) {
+  const parsed = agentResponseSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new HostedOrchError("POST /v1/agents returned an unexpected shape");
+  }
+  return parsed.data;
+}
+function mapHttpError(status, json) {
+  const err = json.error;
+  if (status === 401 || status === 403) {
+    return new HostedAuthError(err?.message ?? `HTTP ${status}`);
+  }
+  if (status === 404) {
+    return new HostedOrchError(
+      err?.message ?? "POST /v1/agents is not available at this API URL. Upgrade pome-cloud or check that --api-url/POME_API_URL points at a version that supports agent registration."
+    );
+  }
+  return new HostedOrchError(err?.message ?? `POST /v1/agents \u2192 HTTP ${status}`);
+}
+function nearMissSuggestion(json) {
+  const error = json.error;
+  if (error?.type !== "conflict") return void 0;
+  const details = error.details;
+  if (!details) return void 0;
+  const candidate = details.suggestion ?? details.slug ?? (Array.isArray(details.suggestions) ? details.suggestions[0] : void 0);
+  return typeof candidate === "string" && candidate.length > 0 ? candidate : void 0;
+}
+async function postAgentResolver(creds, body, seams) {
+  const first = await requestAgent(creds, body);
+  if (first.ok) return parseOkAgent(first.json);
+  if (first.status === 409) {
+    const suggestion = nearMissSuggestion(first.json);
+    if (suggestion) {
+      const interactive = seams.stdinIsTTY && !process.env.CI;
+      let retry;
+      if (interactive) {
+        const yes = await seams.confirm(
+          `An agent named "${suggestion}" already exists on your team. Did you mean "${suggestion}"? [y/N] `
+        );
+        retry = yes ? { ...body, slug: suggestion } : { ...body, confirm: true };
+      } else {
+        console.error(
+          `Near-miss: this slug is close to your team's existing "${suggestion}". Registering the new agent anyway (run interactively to link the existing one instead).`
+        );
+        retry = { ...body, confirm: true };
+      }
+      const second = await requestAgent(creds, retry);
+      if (second.ok) return parseOkAgent(second.json);
+      throw mapHttpError(second.status, second.json);
+    }
+  }
+  throw mapHttpError(first.status, first.json);
+}
+async function promptYesNo(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await new Promise((resolve) => rl.question(question, resolve));
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+async function promptLine(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return (await new Promise((resolve) => rl.question(question, resolve))).trim();
+  } finally {
+    rl.close();
+  }
+}
+var POME_DIR = ".pome";
+var LINK_FILE = "link.json";
+var GITIGNORE_ENTRY = `${POME_DIR}/`;
+function linkPath(projectDir) {
+  return join(projectDir, POME_DIR, LINK_FILE);
+}
+async function readLinkCache(projectDir) {
+  let text;
+  try {
+    text = await readFile(linkPath(projectDir), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || typeof parsed.agent_id !== "string" || typeof parsed.team_id !== "string") {
+    return null;
+  }
+  const { agent_id, team_id } = parsed;
+  const resolved_at = typeof parsed.resolved_at === "string" ? parsed.resolved_at : "";
+  return { agent_id, team_id, resolved_at };
+}
+async function writeLinkCache(projectDir, entry) {
+  await mkdir(join(projectDir, POME_DIR), { recursive: true });
+  const body = {
+    agent_id: entry.agent_id,
+    team_id: entry.team_id,
+    resolved_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeFile(linkPath(projectDir), `${JSON.stringify(body, null, 2)}
+`);
+}
+function resolveCachedAgentId(cache, callerTeamId) {
+  if (!cache || !callerTeamId) return void 0;
+  return cache.team_id === callerTeamId ? cache.agent_id : void 0;
+}
+async function ensurePomeGitignored(projectDir) {
+  const path = join(projectDir, ".gitignore");
+  let existing;
+  try {
+    existing = await readFile(path, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    existing = null;
+  }
+  if (existing === null) {
+    await writeFile(path, `${GITIGNORE_ENTRY}
+`);
+    return;
+  }
+  const alreadyIgnored = existing.split(/\r?\n/).some((line) => line.trim() === GITIGNORE_ENTRY || line.trim() === POME_DIR);
+  if (alreadyIgnored) return;
+  const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+  await writeFile(path, `${existing}${separator}${GITIGNORE_ENTRY}
+`);
+}
+
+// src/cli/agent-identity.ts
+async function resolveRunAgentIdentity(input) {
+  const manifestRead = await readManifest(input.startDir);
+  if (!manifestRead) {
+    return input.agentVersionOverride ? { agentVersion: input.agentVersionOverride } : {};
+  }
+  const { agent } = manifestRead.manifest;
+  const agentVersion = input.agentVersionOverride ?? agent.version;
+  const base = {
+    agentVersion,
+    framework: agent.framework,
+    agentSlug: agent.slug
+  };
+  const projectDir = dirname(manifestRead.path);
+  try {
+    const creds = await resolveCredentials({
+      apiBaseUrl: input.apiBaseUrl,
+      credentialsPath: input.credentialsPath
+    });
+    const cachedId = resolveCachedAgentId(await readLinkCache(projectDir), creds.teamId);
+    if (cachedId) {
+      return { ...base, agentId: cachedId };
+    }
+    const resolved = await postAgentResolver(
+      creds,
+      {
+        name: agent.name ?? agent.slug,
+        slug: agent.slug,
+        description: agent.description,
+        version: agent.version,
+        framework: agent.framework,
+        twins: normalizeManifestTwins(manifestRead.manifest.twins)
+      },
+      resolveSeams({ stdinIsTTY: false })
+    );
+    if (creds.teamId) {
+      await writeLinkCache(projectDir, { agent_id: resolved.id, team_id: creds.teamId });
+      await ensurePomeGitignored(projectDir);
+    }
+    return { ...base, agentId: resolved.id };
+  } catch (err) {
+    console.error(
+      `pome: could not resolve agent identity (${err instanceof Error ? err.message : String(err)}); running unattributed.`
+    );
+    return base;
+  }
+}
+
+// src/cli/defaults.ts
+var DEFAULT_CONTROL_PLANE_URL = "https://api.pome.sh";
+var DEFAULT_DASHBOARD_URL = "https://app.pome.sh";
+var DEFAULT_DOCS_SITE_ORIGIN = "https://docs.pome.sh";
+function ensureMcpSuffix(url) {
+  return /\/mcp\/?$/.test(url) ? url : `${url.replace(/\/$/, "")}/mcp`;
+}
+var ALLOWED_TWINS = /* @__PURE__ */ new Set([...MOUNTED_TWINS, "gmail", "linear"]);
+function redactSession(res) {
+  const pcIn = res.provider_credentials;
+  const pcOut = {};
+  if (pcIn.github) {
+    pcOut.github = { ...pcIn.github, token: "***redacted***" };
+  }
+  if (pcIn.stripe) {
+    pcOut.stripe = { ...pcIn.stripe, api_key: "***redacted***" };
+  }
+  if (pcIn.slack) {
+    pcOut.slack = { ...pcIn.slack, token: "***redacted***" };
+  }
+  return {
+    session_id: res.session_id,
+    session_token: res.session_token ? "***redacted***" : res.session_id,
+    twin_url: res.twin_url,
+    expires_at: res.expires_at,
+    openapi_url: res.openapi_url,
+    per_twin: res.per_twin,
+    provider_credentials: pcOut,
+    agent_token: "***redacted***"
+  };
+}
+function formatEnvExport(res, twins) {
+  const lines = [
+    `# Pome hosted session \u2014 treat as secret. Twins: ${twins.join(", ")}`,
+    `export POME_AUTH_TOKEN=${JSON.stringify(res.agent_token)}`,
+    `export POME_SESSION_ID=${JSON.stringify(res.session_id)}`,
+    // Legacy single-endpoint URL (= the primary twin's api_url). Kept for
+    // agents written against the pre-multi-twin contract.
+    `export POME_TWIN_URL=${JSON.stringify(res.twin_url)}`,
+    `export POME_TWIN_NAMES=${JSON.stringify(twins.join(","))}`
+  ];
+  const fromCloud = perTwinReturnedByCloud(res);
+  for (const twin of twins) {
+    const upper = twin.toUpperCase();
+    const pt = res.per_twin?.[twin];
+    if (pt?.api_url) {
+      const mcpUrl = fromCloud ? ensureMcpSuffix(pt.mcp_url) : ensureMcpSuffix(pt.api_url);
+      lines.push(`export POME_${upper}_REST_URL=${JSON.stringify(pt.api_url)}`);
+      lines.push(
+        `export POME_${upper}_MCP_URL=${JSON.stringify(mcpUrl)}`
+      );
+    }
+    if (twin === "github") {
+      const gh = res.provider_credentials.github;
+      if (gh) {
+        lines.push(`export POME_GITHUB_TOKEN=${JSON.stringify(gh.token)}`);
+      }
+    } else if (twin === "stripe") {
+      const st = res.provider_credentials.stripe;
+      if (st) {
+        lines.push(`export POME_STRIPE_API_KEY=${JSON.stringify(st.api_key)}`);
+      }
+      if (pt?.api_url) {
+        lines.push(`export POME_STRIPE_API_BASE=${JSON.stringify(pt.api_url)}`);
+      }
+    } else if (twin === "slack") {
+      lines.push(`export POME_SLACK_TOKEN=${JSON.stringify(res.agent_token)}`);
+    } else if (twin === "gmail") {
+      lines.push(`export POME_GMAIL_TOKEN=${JSON.stringify(res.agent_token)}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function normalizeSessionTwins(raw) {
+  const twins = raw.map((t) => t.trim().toLowerCase()).filter((t) => t.length > 0);
+  for (const twin of twins) {
+    if (!ALLOWED_TWINS.has(twin)) {
+      throw new Error(
+        `Unknown twin "${twin}". Supported: ${[...ALLOWED_TWINS].join(", ")}.`
+      );
+    }
+  }
+  const deduped = [...new Set(twins)];
+  if (deduped.length === 0) {
+    throw new Error(
+      `No twin specified. Pass --twin <name> (repeat for multi-twin). Supported: ${[...ALLOWED_TWINS].join(", ")}.`
+    );
+  }
+  return deduped;
+}
+async function runSessionCreate(opts) {
+  const twins = normalizeSessionTwins(opts.twins);
+  const creds = await resolveCredentials({ apiBaseUrl: opts.apiBaseUrl });
+  const client = createHostedClient({
+    baseUrl: creds.apiBaseUrl,
+    apiKey: creds.apiKey
+  });
+  const identity = await resolveRunAgentIdentity({
+    startDir: process.cwd(),
+    apiBaseUrl: creds.apiBaseUrl
+  });
+  const session = await client.createSession({
+    twins,
+    taskSource: "# ..\n",
+    idempotencyKey: randomUUID(),
+    agentId: identity.agentId,
+    agentVersion: identity.agentVersion
+  });
+  if (opts.secretsFile) {
+    await writeSecretsFile(opts.secretsFile, formatEnvExport(session, twins));
+    console.error(`Wrote session secrets to ${opts.secretsFile} (mode 0600).`);
+  }
+  if (opts.format === "json") {
+    const payload = redactSession(session);
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (opts.format === "env") {
+    if (opts.secretsFile) {
+      return;
+    }
+    console.error(
+      "Refusing to print environment exports. Use --secrets-file <path> to write them to a 0600 file."
+    );
+    process.exitCode = 2;
+    return;
+  }
+  console.error(`Session: ${session.session_id}`);
+  console.error(`Expires: ${session.expires_at}`);
+  let printedAny = false;
+  const mcpFromCloud = perTwinReturnedByCloud(session);
+  for (const twin of twins) {
+    const pt = session.per_twin?.[twin];
+    if (pt) {
+      const label = twins.length > 1 ? `${twin} ` : "";
+      const mcpUrl = mcpFromCloud ? ensureMcpSuffix(pt.mcp_url) : ensureMcpSuffix(pt.api_url);
+      console.error(`${label}API: ${pt.api_url}`);
+      console.error(`${label}MCP: ${mcpUrl}`);
+      printedAny = true;
+    }
+  }
+  if (!printedAny) {
+    console.error(`Twin URL: ${session.twin_url}`);
+  }
+  if (opts.showSecrets) {
+    console.error("--show-secrets no longer prints secrets. Use --secrets-file <path>.");
+  }
+  console.error("Secrets redacted.");
+  console.error(`Dashboard: ${DEFAULT_DASHBOARD_URL}/twins/${session.session_id}`);
+}
+async function writeSecretsFile(path, contents) {
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await writeFile(path, contents, { mode: 384 });
+  await chmod(path, 384);
+}
+function displayState(serverState) {
+  if (serverState === "ready") return "running";
+  return serverState;
+}
+function matchesStateFilter(serverState, filter) {
+  if (filter === "all") return true;
+  if (filter === "running") return serverState === "ready" || serverState === "running";
+  return serverState === filter;
+}
+async function runSessionList(opts) {
+  const creds = await resolveCredentials({ apiBaseUrl: opts.apiBaseUrl });
+  const client = createHostedClient({
+    baseUrl: creds.apiBaseUrl,
+    apiKey: creds.apiKey
+  });
+  const fetchLimit = opts.state === "all" ? opts.limit : Math.min(opts.limit * 4, 200);
+  const all = await client.listSessions({ limit: fetchLimit });
+  const filtered = all.filter((r) => matchesStateFilter(r.state, opts.state));
+  const rows = filtered.slice(0, opts.limit);
+  if (opts.format === "json") {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  if (rows.length === 0) {
+    const scope = opts.state === "all" ? "any" : `state=${opts.state}`;
+    console.error(`No sessions returned (${scope}).`);
+    return;
+  }
+  for (const r of rows) {
+    console.error(
+      `${r.id}	${displayState(r.state)}	${r.twins.join(",")}	expires ${r.expires_at}`
+    );
+  }
+}
+async function runSessionStop(opts) {
+  const creds = await resolveCredentials({ apiBaseUrl: opts.apiBaseUrl });
+  const client = createHostedClient({
+    baseUrl: creds.apiBaseUrl,
+    apiKey: creds.apiKey
+  });
+  try {
+    await client.deleteSession(opts.sessionId, false, {
+      discard: opts.discard === true
+    });
+  } catch (err) {
+    if (err instanceof HostedDiscardRefusedError) {
+      console.error(
+        `Refused to stop ${err.sessionId}: it is still open (${err.state}), so its run has not been graded \u2014 Pome creates the run row at finalize, and stopping now discards it.`
+      );
+      if (err.taskName) console.error(`  Task: ${err.taskName}`);
+      console.error(`  Open for ${err.openSeconds}s.`);
+      console.error(
+        `  To keep the run, finalize it instead. To discard it anyway: pome session stop ${err.sessionId} --discard`
+      );
+    }
+    throw err;
+  }
+  console.error(`Stopped session ${opts.sessionId}.`);
+}
+function friendlyHostedError(err) {
+  if (err instanceof HostedDiscardRefusedError) {
+    return "";
+  }
+  if (err instanceof HostedAuthError) {
+    return `${err.message} \xB7 Run \`pome login\` or set a valid POME_API_KEY.`;
+  }
+  if (err instanceof HostedQuotaError) {
+    return `${err.message} \xB7 Quota or billing limit \u2014 check your team plan in the dashboard.`;
+  }
+  if (err instanceof HostedOrchError) {
+    const m = err.message;
+    if (/422|validation/i.test(m)) {
+      return `${m} \xB7 Check twin name and request body.`;
+    }
+    if (/503|spawn/i.test(m)) {
+      return `${m} \xB7 Control plane could not start the sandbox \u2014 retry later.`;
+    }
+    return m;
+  }
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+function buildAgentEnv(params) {
+  const {
+    session,
+    twins,
+    perTwinFromCloud,
+    prompt,
+    otlpEndpoint,
+    apiKey,
+    agentId,
+    runId,
+    artifactsDir,
+    slug,
+    signalsPath
+  } = params;
+  const env = {
+    POME_TASK: prompt,
+    POME_TWIN_NAMES: twins.join(","),
+    POME_OTEL_EXPORTER_OTLP_ENDPOINT: otlpEndpoint,
+    POME_OTEL_EXPORTER_OTLP_HEADERS: `x-api-key=${apiKey}`,
+    OTEL_SERVICE_NAME: agentId ?? "pome-agent",
+    OTEL_RESOURCE_ATTRIBUTES: `pome.session_id=${session.session_id},pome.run_id=${runId}${agentId ? `,pome.agent_id=${agentId}` : ""}`,
+    // The twin base URL, same value the self-host docs teach agents to fall
+    // back on. Agent code written against the standalone docker twin
+    // reads POME_TWIN_BASE_URL with a 127.0.0.1:3333 fallback; without this
+    // injection that fallback fires on hosted runs and the agent probes a
+    // loopback port nothing listens on. Legacy = the primary twin's bare url.
+    POME_TWIN_BASE_URL: session.twin_url,
+    // Legacy unconditional block (origin/main parity). Injected on EVERY hosted
+    // run regardless of twin; the per-twin overlay below overwrites these in
+    // place for github/stripe when those twins are in the session.
+    POME_GITHUB_REST_URL: session.twin_url,
+    POME_GITHUB_MCP_URL: `${session.twin_url}/mcp`,
+    POME_GITHUB_TOKEN: session.provider_credentials.github?.token ?? session.agent_token,
+    POME_STRIPE_API_BASE: session.twin_url,
+    // Always use the JWT agent_token as the Stripe SDK's Bearer in hosted mode.
+    // The cloud also returns `provider_credentials.stripe.api_key` (an
+    // HMAC-signed `sk_test_pome_*`), but the pome-cloud proxy only accepts
+    // JWTs — it routes by verifying the bearer against `agent_token`. A
+    // stripe-style key short-circuits to the proxy's opaque 404 before the
+    // request reaches the twin pod. The Stripe SDK sends any opaque string as
+    // `Authorization: Bearer …`, and twin-stripe's dual-auth accepts JWTs
+    // natively, so the JWT round-trips cleanly end-to-end.
+    POME_STRIPE_API_KEY: session.agent_token,
+    POME_AUTH_TOKEN: session.agent_token,
+    POME_RUN_ID: runId,
+    POME_ARTIFACTS_DIR: join(artifactsDir, slug, runId),
+    POME_ADAPTER_SIGNALS_PATH: signalsPath
+  };
+  for (const twin of twins) {
+    const upper = twin.toUpperCase();
+    const pt = session.per_twin?.[twin];
+    const apiUrl = pt?.api_url ?? session.twin_url;
+    const mcpUrl = perTwinFromCloud && pt?.mcp_url ? ensureMcpSuffix(pt.mcp_url) : `${apiUrl.replace(/\/$/, "")}/mcp`;
+    env[`POME_${upper}_REST_URL`] = apiUrl;
+    env[`POME_${upper}_MCP_URL`] = mcpUrl;
+    if (twin === "github") {
+      env.POME_GITHUB_TOKEN = session.provider_credentials.github?.token ?? session.agent_token;
+    } else if (twin === "stripe") {
+      env.POME_STRIPE_API_BASE = apiUrl;
+      env.POME_STRIPE_API_KEY = session.agent_token;
+    } else if (twin === "slack") {
+      env.POME_SLACK_TOKEN = session.agent_token;
+    } else if (twin === "gmail") {
+      env.POME_GMAIL_TOKEN = session.agent_token;
+    }
+  }
+  return env;
+}
+async function runTaskHosted(options) {
+  const scenario = await parseTaskFile(options.taskPath);
+  const taskSource = await readFile(options.taskPath, "utf8");
+  const taskHash = createHash("sha256").update(taskSource).digest("hex");
+  const artifactsDir = options.artifactsDir ?? "runs";
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const client = options.client ?? createHostedClient({ baseUrl: options.hosted.baseUrl, apiKey: options.hosted.apiKey });
+  const identity = await resolveRunAgentIdentity({
+    startDir: dirname(options.taskPath),
+    apiBaseUrl: options.hosted.baseUrl,
+    agentVersionOverride: options.agentVersion
+  });
+  const agentId = identity.agentId;
+  const agentVersion = identity.agentVersion;
+  const agentSdk = identity.framework ?? null;
+  const signalsDir = await mkdtemp(join(tmpdir(), "pome-signals-"));
+  const signalsPath = join(signalsDir, `${randomUUID()}.jsonl`);
+  await writeFile(signalsPath, "");
+  const session = await createSessionOrExplain(
+    client,
+    options.premintedSession,
+    {
+      taskSource,
+      twins: scenario.config.twins,
+      agentId,
+      agentVersion,
+      seed: scenario.seedState
+    }
+  );
+  const twins = scenario.config.twins;
+  const primaryTwin = twins[0];
+  const isMultiTwin = twins.length > 1;
+  const twinApiUrl = (twin) => session.per_twin?.[twin]?.api_url ?? session.twin_url;
+  const runId = session.session_id;
+  try {
+    const stateInitialByTwin = await fetchStateForTwins(
+      client,
+      twins,
+      twinApiUrl,
+      session.agent_token
+    );
+    const stateInitial = stateInitialByTwin[primaryTwin];
+    const otlpEndpoint = process.env.POME_OTEL_COLLECTOR_URL?.trim() || new URL(
+      `/v1/sessions/${session.session_id}/traces`,
+      options.hosted.baseUrl
+    ).toString();
+    const env = buildAgentEnv({
+      session,
+      twins,
+      perTwinFromCloud: perTwinReturnedByCloud(session),
+      prompt: scenario.prompt,
+      otlpEndpoint,
+      apiKey: options.hosted.apiKey,
+      agentId,
+      runId,
+      artifactsDir,
+      slug: scenario.slug,
+      signalsPath
+    });
+    const preflightTimeoutSeconds = Math.min(10, scenario.config.timeout);
+    const preflight = await runAgentCommand({
+      command: options.agentCommand,
+      env,
+      timeoutSeconds: preflightTimeoutSeconds,
+      preflight: true
+    });
+    let agentResult = preflight;
+    if (preflight.exitCode === 0) {
+      await writeFile(signalsPath, "");
+      agentResult = await runAgentCommand({
+        command: options.agentCommand,
+        env,
+        timeoutSeconds: scenario.config.timeout
+      });
+    }
+    if (options.abandonOnFailure && (agentResult.timedOut || agentResult.exitCode !== 0)) {
+      const failed = preflight.exitCode !== 0 ? preflight : agentResult;
+      const cause = stderrTail(failed.stderr);
+      const failure = preflight.exitCode !== 0 ? {
+        errorCode: "preflight_failed",
+        reason: preflight.timedOut ? `agent preflight timed out after ${preflightTimeoutSeconds}s` : `agent preflight failed${cause ? ` \u2014 ${cause}` : ""}`
+      } : agentResult.timedOut ? {
+        errorCode: "agent_timeout",
+        reason: `agent timed out after ${scenario.config.timeout}s`
+      } : {
+        errorCode: "agent_exit_nonzero",
+        reason: `agent exited non-zero (exit ${agentResult.exitCode})${cause ? ` \u2014 ${cause}` : ""}`
+      };
+      try {
+        const runDir = join(artifactsDir, scenario.slug, runId);
+        await mkdir(runDir, { recursive: true });
+        await writeFile(join(runDir, "stdout.txt"), redactSecrets(failed.stdout));
+        await writeFile(join(runDir, "stderr.log"), redactSecrets(failed.stderr));
+      } catch {
+      }
+      await abandonBestEffort(client, session.session_id, failure.errorCode);
+      throw new HostedTrialError(failure.reason, failure.errorCode);
+    }
+    const stateFinalByTwin = {};
+    const eventsByTwin = {};
+    await Promise.all(
+      twins.map(async (twin) => {
+        const [sf, ev] = await Promise.all([
+          client.fetchState({ twinUrl: twinApiUrl(twin), agentToken: session.agent_token }),
+          client.fetchEvents({ twinUrl: twinApiUrl(twin), agentToken: session.agent_token })
+        ]);
+        stateFinalByTwin[twin] = sf;
+        eventsByTwin[twin] = isMultiTwin ? ev.map((e) => tagEventTwin(e, twin)) : ev;
+      })
+    );
+    const stateFinal = stateFinalByTwin[primaryTwin];
+    const events = isMultiTwin ? mergeEventsByTimestamp(twins.flatMap((t) => eventsByTwin[t] ?? [])) : eventsByTwin[primaryTwin] ?? [];
+    const legacyEvents = events;
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const durationMs = Date.parse(completedAt) - Date.parse(startedAt);
+    const artifacts = await writeRunArtifactsCore({
+      artifactsDir,
+      runId,
+      scenario,
+      startedAt,
+      completedAt,
+      stdout: agentResult.stdout,
+      stderr: agentResult.stderr,
+      exitCode: agentResult.exitCode,
+      events: legacyEvents,
+      stateInitial,
+      stateFinal
+    });
+    if (isMultiTwin) {
+      for (const twin of twins) {
+        if (twin === primaryTwin) continue;
+        try {
+          await writeFile(
+            join(artifacts.runDir, `state_final.${twin}.json`),
+            `${JSON.stringify(redactSecrets(stateFinalByTwin[twin]), null, 2)}
+`
+          );
+        } catch (err) {
+          console.warn(
+            `[pome] state_final.${twin}.json not written (${err instanceof Error ? err.message : String(err)})`
+          );
+        }
+      }
+    }
+    const eventsJsonl = legacyEvents.map((e) => JSON.stringify(redactEvent(toTwinHttpEvent(e)))).join("\n") + "\n";
+    const stateInitialJson = JSON.stringify(redactSecrets(stateInitial));
+    const stateFinalJson = JSON.stringify(redactSecrets(stateFinal));
+    let signalsJsonl = "";
+    try {
+      signalsJsonl = redactJsonl(
+        await readFile(signalsPath, "utf8").catch(() => "")
+      );
+    } catch (err) {
+      console.warn(
+        `[pome] signals.jsonl upload skipped (${err instanceof Error ? err.message : String(err)}); continuing with signals_storage_key=null`
+      );
+    }
+    const metaJson = await readFile(join(artifacts.runDir, "meta.json"), "utf8").catch(
+      () => "{}"
+    );
+    const perTwinState = isMultiTwin ? Object.fromEntries(
+      twins.map((twin) => [
+        twin,
+        {
+          initialJson: JSON.stringify(redactSecrets(stateInitialByTwin[twin])),
+          finalJson: JSON.stringify(redactSecrets(stateFinalByTwin[twin]))
+        }
+      ])
+    ) : void 0;
+    const uploaded = await uploadRunBlobs(client, session.session_id, {
+      eventsJsonl,
+      stateInitialJson,
+      stateFinalJson,
+      signalsJsonl,
+      metaJson,
+      twins: isMultiTwin ? twins : void 0,
+      perTwinState
+    });
+    const eventsJsonlUrl = uploaded.eventsKey;
+    const stateKeys = {
+      initialKey: uploaded.stateInitialKey,
+      finalKey: uploaded.stateFinalKey
+    };
+    const signalsKey = uploaded.signalsKey;
+    const criteriaDefs = scenario.criteria.map((c, idx) => ({
+      id: `crit_${idx}`,
+      text: c.text,
+      kind: c.type,
+      ...c.twin ? { twin: c.twin } : {}
+    }));
+    const stopReason = agentResult.timedOut ? "agent_timeout" : agentResult.exitCode === 0 ? "agent_exit_0" : "agent_exit_nonzero";
+    const finalized = await client.finalize(session.session_id, {
+      stopReason,
+      exitCode: agentResult.exitCode ?? 0,
+      durationMs,
+      agentModel: options.agentModel ?? "unknown",
+      agentSdk,
+      criteria: criteriaDefs,
+      taskName: scenario.slug,
+      taskHash,
+      taskPrompt: scenario.prompt,
+      expectedBehavior: scenario.expectedBehavior,
+      // Explicit overrides when uploads succeeded; otherwise let cloud fall
+      // back. For events.jsonl the conventional `team-<>/session-<>/events.jsonl`
+      // path matches what /result-upload-url signs, so omitting traceStorageKey
+      // still resolves correctly. For state blobs there is no conventional
+      // fallback today (FDRS-395) — omitting them means cloud's judge sees
+      // "{}", which we accept as best-effort degradation.
+      traceStorageKey: eventsJsonlUrl ?? void 0,
+      stateInitialStorageKey: stateKeys.initialKey ?? void 0,
+      stateFinalStorageKey: stateKeys.finalKey ?? void 0,
+      signalsStorageKey: signalsKey ?? void 0,
+      // Multi-twin (M3): per-twin state storage keys (>=1 key per entry).
+      // Undefined for single-twin / an older cloud that returned no per_twin
+      // upload block — the cloud then scores the primary twin from the flat keys.
+      perTwinStateKeys: uploaded.perTwinStateKeys
+    });
+    const score = scoreFromFinalizeResponse(finalized);
+    const verdict = scoreStatus(score, scenario.config.passThreshold);
+    const exitCode = verdict === "pass" ? 0 : 1;
+    try {
+      await writeVerdictArtifact(artifacts.runDir, {
+        version: VERDICT_ARTIFACT_VERSION,
+        source: "cloud-finalize",
+        task_name: scenario.slug,
+        task_path: options.taskPath,
+        group_id: options.groupId ?? null,
+        session_id: session.session_id,
+        cloud_run_id: finalized.run_id,
+        cloud_dashboard_url: finalized.dashboard_url,
+        judge_model: score.judge_model,
+        score: finalized.score,
+        pass_threshold: scenario.config.passThreshold,
+        passed: exitCode === 0,
+        criteria_results: score.results,
+        duration_ms: durationMs,
+        finalized_at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch (err) {
+      console.warn(
+        `[pome] verdict.json not written (${err instanceof Error ? err.message : String(err)}); pome fix-prompt won't see this trial`
+      );
+    }
+    return {
+      scenario,
+      runId,
+      cloudRunId: finalized.run_id,
+      cloudDashboardUrl: finalized.dashboard_url,
+      artifacts,
+      score,
+      verdict,
+      exitCode,
+      durationMs
+    };
+  } catch (err) {
+    if (options.abandonOnFailure && !(err instanceof HostedTrialError)) {
+      await abandonBestEffort(client, session.session_id, "trial_crashed");
+    }
+    throw err;
+  } finally {
+    await client.deleteSession(session.session_id, true, { discard: true }).catch(() => void 0);
+    await rm(signalsDir, { recursive: true, force: true }).catch(() => void 0);
+  }
+}
+async function createSessionOrExplain(client, preminted, input) {
+  if (preminted) return preminted;
+  try {
+    return await client.createSession(input);
+  } catch (err) {
+    if (err instanceof HostedOrchError && err.status === 422 && (err.type === "multi_twin_unsupported" || /multi_twin_unsupported/i.test(err.message))) {
+      throw new HostedOrchError(
+        "this pome cloud does not support multi-twin sessions yet",
+        err.requestId,
+        err.status,
+        err.type
+      );
+    }
+    throw err;
+  }
+}
+async function fetchStateForTwins(client, twins, twinApiUrl, agentToken) {
+  const byTwin = {};
+  await Promise.all(
+    twins.map(async (twin) => {
+      byTwin[twin] = await client.fetchState({
+        twinUrl: twinApiUrl(twin),
+        agentToken
+      });
+    })
+  );
+  return byTwin;
+}
+function tagEventTwin(event, twin) {
+  if (event && typeof event === "object") {
+    const existing = event.twin;
+    if (existing === void 0 || existing === null || existing === "") {
+      return { ...event, twin };
+    }
+  }
+  return event;
+}
+function mergeEventsByTimestamp(events) {
+  const tsOf = (e) => {
+    const ts = e.ts;
+    return typeof ts === "string" ? ts : "";
+  };
+  return events.map((event, index) => ({ event, index })).sort((a, b) => {
+    const ta = tsOf(a.event);
+    const tb = tsOf(b.event);
+    if (ta < tb) return -1;
+    if (ta > tb) return 1;
+    return a.index - b.index;
+  }).map(({ event }) => event);
+}
+function stderrTail(stderr) {
+  const last = stderr.split("\n").map((line) => line.trim()).filter(Boolean).at(-1);
+  if (!last) return null;
+  const flat = redactSecrets(last.replace(/\s+/g, " ")).trim();
+  return flat.length > 160 ? `${flat.slice(0, 157)}\u2026` : flat;
+}
+async function abandonBestEffort(client, sessionId, errorCode) {
+  try {
+    await client.abandonSession(sessionId, { errorCode });
+  } catch (err) {
+    console.warn(
+      `[pome] session abandon skipped (${err instanceof Error ? err.message : String(err)}); the expiry sweeper will close ${sessionId}`
+    );
+  }
+}
+
+export { DEFAULT_CONTROL_PLANE_URL, DEFAULT_DASHBOARD_URL, DEFAULT_DOCS_SITE_ORIGIN, clearLocalCredentials, discoverRunSet, ensurePomeGitignored, friendlyHostedError, loadTrialEvents, persistCredentialsAfterLogin, postAgentResolver, readLinkCache, resolveCachedAgentId, resolveCredentials, resolveRunAgentIdentity, resolveSeams, runSessionCreate, runSessionList, runSessionStop, runTaskHosted, writeLinkCache };