@pome-sh/cli 0.4.0 → 0.7.0

package/README.md

@@ -29,7 +29,7 @@ Gmail is first-party too:
 ```bash
 npx @pome-sh/cli twin start gmail --port 3336
 # prints POME_GMAIL_REST_URL, POME_GMAIL_MCP_URL, and POME_GMAIL_TOKEN
-pome scenarios gmail --copy
+pome tasks gmail --copy
 ```
 
 `POME_GMAIL_TOKEN` is the same Pome session JWT as `POME_AUTH_TOKEN`; it is not
@@ -40,21 +40,46 @@ local/OSS package release.
 
 ```bash
 pome login                       # one-time; opens the dashboard to sign in
-pome init                        # scaffolds scenarios/, examples/agents/, runs/, pome.config.json
+pome init                        # scaffolds tasks/, examples/agents/, runs/, pome.config.json
 pome register agent my-agent     # scopes runs to this project
-pome run scenarios/01-bug-happy-path.md --agent "npx tsx examples/agents/scripted-triage-agent.ts"
+pome run tasks/01-bug-happy-path.md --agent "npx tsx examples/agents/scripted-triage-agent.ts"
 pome inspect latest              # trace/audit view of the last run
 ```
 
 To capture a trace without the cloud (self-host), then get a verdict later:
 
 ```bash
-pome run --local scenarios/01-bug-happy-path.md   # captures a raw trace only — no verdict
+pome run --local tasks/01-bug-happy-path.md   # captures a raw trace only — no verdict
 pome eval runs/01-bug-happy-path/<run-id>         # uploads it for a cloud verdict
 ```
 
-See [docs.pome.sh](https://docs.pome.sh) for the task library, exit-code
-contract, authentication, the Stripe/Slack twins, and everything else.
+See [docs.pome.sh](https://docs.pome.sh) for the task library, authentication,
+the Stripe/Slack twins, and everything else.
+
+## CI one-shot — the exit-code contract
+
+`pome run <task>` is the CI one-shot: one hosted, scored run, and its **exit
+code is the verdict**. Gate CI on it directly.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | pass (hosted/scored run), or trace captured (`--local`, not scored) |
+| `1` | ran and scored **below** the pass threshold |
+| `2` | twin / orchestration error (network, 5xx, twin spawn failed) |
+| `3` | auth error (401/403) — `pome login` again, or set `POME_API_KEY` in CI |
+| `4` | quota exceeded (402/429) |
+| `5` | usage error (bad flags, missing task file) |
+
+Two rules CI must honor:
+
+- **`--local` is not a verdict.** A `--local` run captures a raw trace and never
+  scores, so its exit `0` means "trace captured," not "passed." Never gate CI on
+  a `--local` exit code — score it later with `pome eval <run-dir>`.
+- **Trial groups map as a whole.** `pome run -n k` (k>1) collapses the whole
+  group to one code: `0` = at least one trial completed and every completed
+  trial passed; `1` = at least one completed trial failed its threshold; `2` =
+  no trial completed. Errored trials are excluded from the verdict fraction and
+  never drag a passing group below `0` on their own.
 
 ## Development
 

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "package": "pome-sh",
-  "version": "0.4.0",
-  "git_sha": "724f504bafc5a7fa59b2b6a295f1529f03e3ece0",
-  "build_time": "2026-07-22T19:44:48.942Z"
+  "version": "0.7.0",
+  "git_sha": "c07382656e095899efa7d46c96a12830869e9cbb",
+  "build_time": "2026-07-24T16:38:09.759Z"
 }

package/dist/examples/agents/llm-refund-agent.js

@@ -93,7 +93,7 @@ async function callStripeTool(name, input) {
     }
     throw new Error(`Unknown tool ${name}`);
 }
-// Hero bug surfaced by scenarios/14-stripe-refund-retry.md: this agent intentionally
+// Hero bug surfaced by tasks/14-stripe-refund-retry.md: this agent intentionally
 // never sends an `Idempotency-Key` header on POST /v1/refunds. When the twin's
 // failure-injection middleware drops the first response, the LLM-driven retry
 // creates a second refund row — exactly the double-charge bug Pome is built to catch.

package/dist/src/cli/compile-seeds.js

@@ -13,15 +13,15 @@ import { existsSync } from "node:fs";
 import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { extname, join, resolve } from "node:path";
 import { z } from "zod";
-import { compileSeed, COMPILER_MODEL } from "../scenario/seed-compiler.js";
-import { compileSeedHosted } from "../scenario/seed-compiler-hosted.js";
-import { verifySeedWithTwin } from "../scenario/seed-verifier.js";
+import { compileSeed, COMPILER_MODEL } from "../task/seed-compiler.js";
+import { compileSeedHosted } from "../task/seed-compiler-hosted.js";
+import { verifySeedWithTwin } from "../task/seed-verifier.js";
 import { exitCodeFor } from "../hosted/errors.js";
 const SIDECAR_META_VERSION = 1;
 export async function runCompileSeeds(target, opts) {
-    const files = await resolveScenarioFiles(target ?? "scenarios");
+    const files = await resolveTaskFiles(target ?? "tasks");
     if (files.length === 0) {
-        console.error(`No task .md files found at ${target ?? "scenarios"}.`);
+        console.error(`No task .md files found at ${target ?? "tasks"}.`);
         return 2;
     }
     const results = [];
@@ -44,17 +44,17 @@ export async function runCompileSeeds(target, opts) {
     }
     return 0;
 }
-async function compileOne(scenarioPath, opts) {
+async function compileOne(taskPath, opts) {
     let markdown;
     try {
-        markdown = await readFile(scenarioPath, "utf8");
+        markdown = await readFile(taskPath, "utf8");
     }
     catch (err) {
-        return { path: scenarioPath, status: "error", message: `read failed: ${err.message}` };
+        return { path: taskPath, status: "error", message: `read failed: ${err.message}` };
     }
     const seedText = extractSeedSection(markdown).trim();
     if (seedText.length === 0) {
-        return { path: scenarioPath, status: "skipped-no-seed", message: "no ## Seed State section" };
+        return { path: taskPath, status: "skipped-no-seed", message: "no ## Seed State section" };
     }
     // Stripe scenarios use a different schema; v1 only supports github. Check
     // twin first so Stripe scenarios are silently skipped without surfacing
@@ -62,7 +62,7 @@ async function compileOne(scenarioPath, opts) {
     const twins = readTwinsFromConfig(markdown);
     if (twins.length > 0 && !twins.includes("github")) {
         return {
-            path: scenarioPath,
+            path: taskPath,
             status: "skipped-unsupported-twin",
             message: `twins=${twins.join(",")} not supported yet`
         };
@@ -72,12 +72,12 @@ async function compileOne(scenarioPath, opts) {
     // before compile-seeds can take over.
     if (looksLikeJsonBlock(seedText)) {
         return {
-            path: scenarioPath,
+            path: taskPath,
             status: "skipped-inline-json",
             message: "still on inline JSON — replace the fenced JSON with prose"
         };
     }
-    const sidecarPath = sidecarPathFor(scenarioPath);
+    const sidecarPath = sidecarPathFor(taskPath);
     const proseHash = hashProse(seedText);
     // Cache check only applies to local compile — hosted callers may have
     // different model versions than the locally-pinned COMPILER_MODEL, and the
@@ -85,18 +85,18 @@ async function compileOne(scenarioPath, opts) {
     if (!opts.force && !opts.hosted && existsSync(sidecarPath)) {
         const cached = await readSidecarMeta(sidecarPath);
         if (cached && cached.source_hash === proseHash && cached.model === COMPILER_MODEL) {
-            return { path: scenarioPath, status: "skipped-cached", message: `up-to-date (${sidecarPath})` };
+            return { path: taskPath, status: "skipped-cached", message: `up-to-date (${sidecarPath})` };
         }
     }
     let result;
     try {
         result = opts.hosted
-            ? await compileSeedHosted(seedText, { apiBaseUrl: opts.apiBaseUrl, scenarioPath })
+            ? await compileSeedHosted(seedText, { apiBaseUrl: opts.apiBaseUrl, taskPath })
             : await compileSeed(seedText);
     }
     catch (err) {
         return {
-            path: scenarioPath,
+            path: taskPath,
             status: "error",
             message: `compile failed: ${err.message}`,
             exitCode: opts.hosted ? exitCodeFor(err) : undefined
@@ -106,7 +106,7 @@ async function compileOne(scenarioPath, opts) {
         verifySeedWithTwin(result.seed);
     }
     catch (err) {
-        return { path: scenarioPath, status: "error", message: err.message };
+        return { path: taskPath, status: "error", message: err.message };
     }
     const payload = {
         _meta: {
@@ -119,7 +119,7 @@ async function compileOne(scenarioPath, opts) {
     };
     await writeFile(sidecarPath, JSON.stringify(payload, null, 2) + "\n");
     return {
-        path: scenarioPath,
+        path: taskPath,
         status: "compiled",
         message: `→ ${sidecarPath}`,
         inputTokens: result.inputTokens,
@@ -128,7 +128,7 @@ async function compileOne(scenarioPath, opts) {
     };
 }
 function extractSeedSection(markdown) {
-    // Mirrors the H2-section logic in parseScenario.ts: find the "## Seed State"
+    // Mirrors the H2-section logic in parseTask.ts: find the "## Seed State"
     // heading and return everything until the next H2.
     const headingRegex = /^##\s+seed state\s*$/im;
     const m = markdown.match(headingRegex);
@@ -159,9 +159,9 @@ function readTwinsFromConfig(markdown) {
 function looksLikeJsonBlock(input) {
     return /^```(?:json)?\s*\{/m.test(input.trim());
 }
-function sidecarPathFor(scenarioPath) {
-    const ext = extname(scenarioPath);
-    return scenarioPath.slice(0, -ext.length) + ".seed.json";
+function sidecarPathFor(taskPath) {
+    const ext = extname(taskPath);
+    return taskPath.slice(0, -ext.length) + ".seed.json";
 }
 function hashProse(input) {
     return "sha256:" + createHash("sha256").update(input.replace(/\s+$/g, "")).digest("hex");
@@ -186,7 +186,7 @@ async function readSidecarMeta(path) {
         return null;
     }
 }
-async function resolveScenarioFiles(target) {
+async function resolveTaskFiles(target) {
     const abs = resolve(target);
     if (!existsSync(abs))
         throw new Error(`Path not found: ${target}`);

package/dist/src/cli/default-task.d.ts

@@ -1,6 +1,6 @@
 /** Design default k for "run yours" (moment 05: "Their agent · k=5"). */
 export declare const DEFAULT_TASK_TRIALS = 5;
-export declare const DEFAULT_TASK_DIR = "scenarios";
+export declare const DEFAULT_TASK_DIR = "tasks";
 export declare const DEFAULT_TASK_FILENAME = "first-run-demo.md";
 export interface DefaultTaskResolution {
     /** Absolute path of the task markdown to run. */
@@ -25,7 +25,7 @@ export declare function withDefaultTrials(source: string, runs?: number): {
 export declare function withUserCopyComment(source: string): string;
 /**
  * Resolve the bare-`pome run` default task, dropping the user copy on first
- * use. Never clobbers an existing scenarios/first-run-demo.md — that file is
+ * use. Never clobbers an existing tasks/first-run-demo.md — that file is
  * the user's (possibly edited) task from a prior bare run.
  */
 export declare function ensureDefaultTask(cwd?: string): Promise<DefaultTaskResolution>;

package/dist/src/cli/default-task.js

@@ -3,7 +3,7 @@
 // task, closing the demo → run-yours seam (north-star moment 05: their
 // agent, k=5, the same task they just watched the demo agent attempt).
 //
-// The default is a USER-VISIBLE COPY at scenarios/first-run-demo.md, dropped
+// The default is a USER-VISIBLE COPY at tasks/first-run-demo.md, dropped
 // on first use from the packaged demo task (src/demo/first-run-demo.md plus
 // its compiled seed sidecar — the client parser requires the sidecar when a
 // prose ## Seed State section is present). The copy — never the canonical
@@ -22,7 +22,7 @@ import { DEMO_TASK_NAME, demoTaskPath } from "../demo/task.js";
 import { HostedUsageError } from "../hosted/errors.js";
 /** Design default k for "run yours" (moment 05: "Their agent · k=5"). */
 export const DEFAULT_TASK_TRIALS = 5;
-export const DEFAULT_TASK_DIR = "scenarios";
+export const DEFAULT_TASK_DIR = "tasks";
 export const DEFAULT_TASK_FILENAME = `${DEMO_TASK_NAME}.md`;
 const USER_COPY_COMMENT = `<!--
 Copied into your project by \`pome run\` — the "run yours" default: the same
@@ -73,7 +73,7 @@ export function withUserCopyComment(source) {
 }
 /**
  * Resolve the bare-`pome run` default task, dropping the user copy on first
- * use. Never clobbers an existing scenarios/first-run-demo.md — that file is
+ * use. Never clobbers an existing tasks/first-run-demo.md — that file is
  * the user's (possibly edited) task from a prior bare run.
  */
 export async function ensureDefaultTask(cwd = process.cwd()) {
@@ -101,7 +101,7 @@ export async function ensureDefaultTask(cwd = process.cwd()) {
     // Seed first, md last: the md's presence is the commit point (the parser
     // hard-requires the sidecar once the md's prose ## Seed State is seen), so
     // a crash between the two writes never strands a half-usable default.
-    // COPYFILE_EXCL: NO file under scenarios/ is ever overwritten — a user who
+    // COPYFILE_EXCL: NO file under tasks/ is ever overwritten — a user who
     // deleted only the md but kept an edited seed keeps their seed.
     try {
         await copyFile(packagedSeed, target.replace(/\.md$/, ".seed.json"), constants.COPYFILE_EXCL);

package/dist/src/cli/docs-topics.js

@@ -11,24 +11,38 @@ export const DOCS_TOPICS = [
         path: "/getting-started",
         keywords: ["install", "quickstart", "setup", "begin"],
     },
+    {
+        id: "existing-agent",
+        title: "Bring your own agent",
+        path: "/existing-agent",
+        keywords: [
+            "existing agent",
+            "own agent",
+            "already have an agent",
+            "bring your own",
+            "register",
+            "pome.json",
+            "connect",
+            // Migrated from the retired skills-setup topic (F-893): wiring your own
+            // agent is now the "bring your own agent" path. ("pome-setup" / "setup"
+            // already resolve to getting-started via its "setup" keyword.)
+            "wire",
+        ],
+    },
     {
         id: "how-pome-works",
         title: "How Pome works",
         path: "/docs/how-pome-works",
         keywords: ["twins", "scenarios", "runs", "scoring", "artifacts", "loop"],
     },
-    {
-        id: "skills-setup",
-        title: "/setup",
-        path: "/docs/skills/setup",
-        keywords: ["pome-setup", "setup", "/setup", "register", "wire"],
-    },
-    {
-        id: "skills-test",
-        title: "/test-with-pome",
-        path: "/docs/skills/test-with-pome",
-        keywords: ["pome-test", "test-with-pome", "/test-with-pome", "run scenarios", "eval"],
-    },
+    // F-889 dropped the Gen-1 /setup and /test-with-pome skill pages from the
+    // docs nav; F-893 retired the CLI commands that pointed at them. The two
+    // topic entries are gone, but their still-live keywords are MIGRATED onto the
+    // surviving replacement topics so `pome docs <kw>` keeps routing:
+    //   wire → existing-agent;  test-with-pome / pome-test → cli-run;
+    //   eval → cli (the CLI reference index — no dedicated eval page exists).
+    //   (setup / pome-setup / register / run scenarios / /setup all already
+    //   resolve via existing substrings — see the tests.)
     {
         id: "dashboard",
         title: "Pome Dashboard",
@@ -69,13 +83,30 @@ export const DOCS_TOPICS = [
         id: "cli",
         title: "Command Line Interface",
         path: "/docs/cli",
-        keywords: ["commands", "flags", "pome run", "reference"],
+        // "eval" migrated from the retired skills-test topic (F-893): there is no
+        // dedicated `pome eval` docs page, and it is a distinct workflow from
+        // `pome inspect`, so it routes to the CLI reference index that documents
+        // every command rather than to a sibling command's page.
+        keywords: ["commands", "flags", "pome run", "reference", "eval"],
     },
     {
         id: "cli-run",
         title: "pome run",
         path: "/docs/cli/run",
-        keywords: ["run", "scenario", "agent", "flags", "artifacts", "default", "demo task", "run yours"],
+        keywords: [
+            "run",
+            "scenario",
+            "agent",
+            "flags",
+            "artifacts",
+            "default",
+            "demo task",
+            "run yours",
+            // Migrated from the retired skills-test topic (F-893): running tasks is
+            // how you test an agent with pome.
+            "test-with-pome",
+            "pome-test",
+        ],
     },
     {
         id: "cli-session",
@@ -84,8 +115,10 @@ export const DOCS_TOPICS = [
         keywords: ["session", "hosted", "sandbox", "twin"],
     },
     {
-        id: "cli-scenarios",
-        title: "pome scenarios",
+        id: "cli-tasks",
+        title: "pome tasks",
+        // F-892 — `path` still points at /docs/cli/scenarios: the docs.pome.sh page
+        // is renamed by the M4 docs door, not here. Repoint once that lands.
         path: "/docs/cli/scenarios",
         keywords: ["tasks", "scenarios", "catalog", "copy", "library", "twin"],
     },

package/dist/src/cli/eval.d.ts

@@ -6,7 +6,7 @@ import { type Score } from "../hosted/evalResultView.js";
  *  `deriveEvalIdentity` so the error can name the flag that fixes it. */
 export interface RunMeta {
     runId: string | null;
-    /** Scenario slug (`meta.json` key: `scenario`) — the default task name. */
+    /** Task slug (`meta.json` key: `scenario`) — the default task name. */
     scenario: string | null;
     title: string | null;
     startedAt: string | null;

package/dist/src/cli/eval.js

@@ -307,9 +307,9 @@ export async function runEval(options) {
             // owns them (FDRS-655). Cloud's finalize schema defaults all scenario
             // fields, so empty strings are accepted.
             criteria: [],
-            scenarioName: taskName,
-            scenarioHash: "",
-            scenarioPrompt: "",
+            taskName: taskName,
+            taskHash: "",
+            taskPrompt: "",
             expectedBehavior: "",
             traceStorageKey: keys.eventsKey ?? undefined,
             stateInitialStorageKey: keys.stateInitialKey ?? undefined,

package/dist/src/cli/init-sdk.js

@@ -123,7 +123,7 @@ async function writeClaudeSdkScaffold() {
             "  1. npm install @pome-sh/adapter-claude-sdk @anthropic-ai/claude-agent-sdk zod\n" +
             "  2. pome login\n" +
             "  3. pome register agent <name>\n" +
-            "  4. pome run scenarios/01-bug-happy-path.md\n" +
+            "  4. pome run tasks/01-bug-happy-path.md\n" +
             "\n" +
             "See `pome docs getting-started` for a narrative walkthrough.",
     };

package/dist/src/cli/install.d.ts

@@ -1,41 +1,4 @@
-import { type AgentSdkModule } from "./agent-sdk.js";
-import { type LoginOptions } from "./login.js";
-/** First message of the interactive session. The skill carries the wiring
- *  knowledge; this only names it, sets adapter-first, and fixes the exit
- *  contract (pome verifies with doctor after the session ends). */
-export declare const KICKOFF_PROMPT: string;
-/** Self-contained fallback prompt for users without a detected coding agent
- *  (their agent won't have the pome-setup skill installed). */
-export declare const PASTE_PROMPT: string;
-export interface InstallOptions {
-    apiUrl: string;
-    dashboardUrl: string;
-    /** Force the interactive agent-session handoff (skip the headless
-     *  staged-diff flow). */
-    interactive?: boolean;
-    /** Repo root the session wires. Defaults to process.cwd(). */
-    cwd?: string;
-    /** Test seam — forwarded to resolveCredentials. */
-    credentialsPath?: string;
-    /** Test seam — defaults to process.stdin.isTTY. */
-    stdinIsTTY?: boolean;
-    /** Test seam — defaults to a readline [y/N] prompt on stderr. */
-    confirm?: (question: string) => Promise<boolean>;
-    /** Test seam — defaults to loginWithClerk (opens a browser). */
-    login?: (options: LoginOptions) => Promise<void>;
-    /** Test seam — defaults to detectClaudeLogin (keychain/credentials/env). */
-    hasClaudeLogin?: () => boolean;
-    /** Test seam — defaults to the consent-gated provision + import of the
-     *  Claude Agent SDK driver. */
-    acquireSdk?: (confirm: (question: string) => Promise<boolean>) => Promise<AgentSdkModule | null>;
-}
-export declare function runInstall(options: InstallOptions): Promise<void>;
-export interface DetectedAgent {
-    bin: string;
-    label: string;
-    path: string;
-}
-/** First known coding agent found on PATH, or null. Exported for tests. */
-export declare function detectAgent(env?: Record<string, string | undefined>): DetectedAgent | null;
-/** The package manager a lockfile in `dir` names, or null. Exported for tests. */
-export declare function lockfilePackageManager(dir: string): "bun" | "pnpm" | "yarn" | "npm" | null;
+/** Print the Gen-2 wiring path. Exported for the `pome install` command and its
+ *  unit test. Never errors — a retired command should land the user on the
+ *  right path, not exit non-zero. */
+export declare function runInstall(): void;