@pome-sh/cli 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # Pome CLI
 
-The `pome` command runs AI-agent scenarios against resettable digital twins of
+The `pome` command runs AI-agent tasks against resettable digital twins of
 real SaaS APIs (GitHub, Stripe, …), captures the trace, and gets a verdict from
 Pome cloud.
 
@@ -24,6 +24,18 @@ Or run it without installing: `npx @pome-sh/cli <command>` — e.g.
 `npx @pome-sh/cli twin start github` boots a local GitHub twin with nothing
 but Node ≥ 24.
 
+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_GMAIL_TOKEN` is the same Pome session JWT as `POME_AUTH_TOKEN`; it is not
+a Google OAuth token. Hosted Gmail availability is gated separately from the
+local/OSS package release.
+
 ## Quickstart
 
 ```bash
@@ -41,8 +53,33 @@ pome run --local scenarios/01-bug-happy-path.md   # captures a raw trace only
 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 scenario 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.3.0",
-  "git_sha": "a6d896782cc39f3d7c93a0f713d77594aef7441c",
-  "build_time": "2026-07-16T22:11:55.839Z"
+  "version": "0.5.0",
+  "git_sha": "1a21867bd939b741c17449e7edc519b721f16950",
+  "build_time": "2026-07-24T12:29:18.845Z"
 }

package/dist/src/cli/agent-identity.d.ts

@@ -0,0 +1,20 @@
+export interface RunAgentIdentity {
+    /** The resolved agent id to send at session create; absent = unattributed. */
+    agentId?: string;
+    /** `--agent-version` override, else the manifest's `agent.version`. */
+    agentVersion?: string;
+    /** The manifest's `agent.framework` — the run's "SDK badge" on the dashboard. */
+    framework?: string;
+    /** The manifest's `agent.slug`, when a manifest is present. */
+    agentSlug?: string;
+}
+export interface ResolveRunAgentIdentityInput {
+    /** Directory to discover the manifest + link cache from (walks up). */
+    startDir: string;
+    apiBaseUrl: string;
+    /** `--agent-version` flag value; wins over the manifest's version. */
+    agentVersionOverride?: string;
+    /** Test seam — forwarded to resolveCredentials. */
+    credentialsPath?: string;
+}
+export declare function resolveRunAgentIdentity(input: ResolveRunAgentIdentityInput): Promise<RunAgentIdentity>;

package/dist/src/cli/agent-identity.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Run-path agent identity (F-819). Resolves the `agt_` id + version to stamp on
+// a hosted session from the committed manifest + gitignored `.pome/link.json`.
+//
+// The cached id is trusted only when its `team_id` matches the caller's team: a
+// re-clone under the same team short-circuits with no network (Champion TTHW);
+// a fork or team switch silently re-resolves the slug via `POST /v1/agents` so
+// a run never sends a foreign `agt_` id and self-onboards with zero extra
+// commands. A resolver hiccup degrades to "unattributed" rather than blocking a
+// local twin run.
+import { dirname } from "node:path";
+import { postAgentResolver, resolveSeams, } from "./agent-resolver.js";
+import { resolveCredentials } from "./credentials.js";
+import { ensurePomeGitignored, readLinkCache, resolveCachedAgentId, writeLinkCache, } from "./link-cache.js";
+import { readManifest } from "./project-config.js";
+export 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 };
+        }
+        // Silent re-resolution — a run never prompts for a near-miss.
+        const resolved = await postAgentResolver(creds, {
+            name: agent.name ?? agent.slug,
+            slug: agent.slug,
+            description: agent.description,
+            version: agent.version,
+            framework: agent.framework,
+        }, 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;
+    }
+}

package/dist/src/cli/agent-resolver.d.ts

@@ -0,0 +1,26 @@
+import { type AgentResponse } from "@pome-sh/shared-types";
+import type { ResolvedCredentials } from "./credentials.js";
+/** Test seams — default to a live TTY [y/N] prompt (mirrors install.ts). */
+export interface InteractiveSeams {
+    stdinIsTTY?: boolean;
+    confirm?: (question: string) => Promise<boolean>;
+}
+/** The manifest identity fields POSTed to the resolver. */
+export interface AgentPostBody {
+    name: string;
+    slug?: string;
+    description?: string;
+    version?: string;
+    framework?: string;
+    twins?: string[];
+    confirm?: boolean;
+}
+export declare function resolveSeams(opts: InteractiveSeams): Required<InteractiveSeams>;
+/** Extract the near-miss suggested slug from a 409 conflict envelope. F-820
+ *  returns it under `error.details.suggestion`; we also tolerate `suggestions[]`
+ *  and `slug` as forward-compatible fallbacks. */
+export declare function nearMissSuggestion(json: unknown): string | undefined;
+/** POST the manifest identity, resolving a 409 near-miss per the confirmation
+ *  UX: interactive → "did you mean X?" (yes re-resolves X, no force-creates the
+ *  typed slug); non-TTY/CI → warn + force-create (`confirm: true`). */
+export declare function postAgentResolver(creds: ResolvedCredentials, body: AgentPostBody, seams: Required<InteractiveSeams>): Promise<AgentResponse>;

package/dist/src/cli/agent-resolver.js

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// The `POST /v1/agents` resolver round-trip (F-820), shared by `pome register`
+// (interactive near-miss) and the run paths (silent re-resolution of a
+// committed slug under the caller's team). Kept import-neutral — no register/
+// session dependency — so both sides can consume it without a cycle.
+import { createInterface } from "node:readline";
+import { agentResponseSchema } from "@pome-sh/shared-types";
+import { HostedAuthError, HostedOrchError } from "../hosted/errors.js";
+export function resolveSeams(opts) {
+    return {
+        stdinIsTTY: opts.stdinIsTTY ?? Boolean(process.stdin.isTTY),
+        confirm: opts.confirm ?? promptYesNo,
+    };
+}
+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 };
+}
+/** Drop undefined keys so the wire body stays byte-clean (older cloud, tests). */
+function prunePostBody(body) {
+    const out = { name: body.name };
+    if (body.slug !== undefined)
+        out.slug = body.slug;
+    if (body.description !== undefined)
+        out.description = body.description;
+    if (body.version !== undefined)
+        out.version = body.version;
+    if (body.framework !== undefined)
+        out.framework = body.framework;
+    if (body.twins && body.twins.length > 0)
+        out.twins = body.twins;
+    if (body.confirm !== undefined)
+        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 → HTTP ${status}`);
+}
+/** Extract the near-miss suggested slug from a 409 conflict envelope. F-820
+ *  returns it under `error.details.suggestion`; we also tolerate `suggestions[]`
+ *  and `slug` as forward-compatible fallbacks. */
+export function nearMissSuggestion(json) {
+    const error = json.error;
+    if (error?.type !== "conflict")
+        return undefined;
+    const details = error.details;
+    if (!details)
+        return undefined;
+    const candidate = details.suggestion ??
+        details.slug ??
+        (Array.isArray(details.suggestions) ? details.suggestions[0] : undefined);
+    return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
+}
+/** POST the manifest identity, resolving a 409 near-miss per the confirmation
+ *  UX: interactive → "did you mean X?" (yes re-resolves X, no force-creates the
+ *  typed slug); non-TTY/CI → warn + force-create (`confirm: true`). */
+export 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();
+    }
+}

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

@@ -21,7 +21,7 @@ const SIDECAR_META_VERSION = 1;
 export async function runCompileSeeds(target, opts) {
     const files = await resolveScenarioFiles(target ?? "scenarios");
     if (files.length === 0) {
-        console.error(`No scenario .md files found at ${target ?? "scenarios"}.`);
+        console.error(`No task .md files found at ${target ?? "scenarios"}.`);
         return 2;
     }
     const results = [];

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

@@ -9,6 +9,10 @@ export interface ResolveCredentialsInput {
 export interface ResolvedCredentials {
     apiKey: string;
     apiBaseUrl: string;
+    /** The team the api key belongs to, when known (stored at login). Powers the
+     *  `.pome/link.json` team gate (F-819). Undefined for a bare `POME_API_KEY`
+     *  env key, whose team is known only server-side. */
+    teamId?: string;
 }
 export interface CredentialsFile {
     api_key?: string;

package/dist/src/cli/credentials.js

@@ -50,6 +50,7 @@ export async function resolveCredentials(input) {
         return {
             apiKey: keychain.api_key.trim(),
             apiBaseUrl: resolveApiBaseUrl(input.apiBaseUrl, keychain.api_url),
+            teamId: normalizeTeamId(keychain.team_id),
         };
     }
     const path = input.credentialsPath ?? DEFAULT_PATH();
@@ -84,8 +85,15 @@ export async function resolveCredentials(input) {
     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 undefined;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
 function resolveApiBaseUrl(callerInput, storedApiUrl) {
     const candidate = callerInput ?? storedApiUrl;
     if (typeof candidate !== "string" || candidate.trim().length === 0) {

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",
@@ -59,17 +73,40 @@ export const DOCS_TOPICS = [
         path: "/docs/twins/slack",
         keywords: ["messaging", "channels", "workspace", "slack", "exfiltration"],
     },
+    {
+        id: "gmail",
+        title: "Gmail twin",
+        path: "/docs/twins/gmail",
+        keywords: ["email", "inbox", "drafts", "labels", "gmail", "mcp"],
+    },
     {
         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",
@@ -81,7 +118,7 @@ export const DOCS_TOPICS = [
         id: "cli-scenarios",
         title: "pome scenarios",
         path: "/docs/cli/scenarios",
-        keywords: ["scenarios", "catalog", "copy", "library", "twin"],
+        keywords: ["tasks", "scenarios", "catalog", "copy", "library", "twin"],
     },
     {
         id: "cli-compile-seeds",
@@ -99,7 +136,7 @@ export const DOCS_TOPICS = [
         id: "cli-init",
         title: "pome init",
         path: "/docs/cli/init",
-        keywords: ["init", "scaffold", "pome.config.json", "project"],
+        keywords: ["init", "scaffold", "pome.json", "manifest", "project"],
     },
     {
         id: "troubleshooting",

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

@@ -1,7 +1,6 @@
 import { type HostedClient } from "../hosted/client.js";
 import { type UploadClient } from "../hosted/uploadAndFinalize.js";
 import { type Score } from "../hosted/evalResultView.js";
-import { type ProjectConfig } from "./project-config.js";
 /** The fields `writeRunArtifactsCore` persists to meta.json that `pome eval`
  *  relies on. Everything is optional-by-parse — validation happens in
  *  `deriveEvalIdentity` so the error can name the flag that fixes it. */
@@ -35,13 +34,18 @@ export interface EvalIdentity {
     agent: string;
     taskName: string;
 }
+/** The manifest fields `pome eval` reads: the agent slug (identity) and the
+ *  framework (the finalize "SDK badge"). */
+export interface EvalProjectIdentity {
+    agentSlug?: string;
+    framework?: string;
+}
 /** Precedence: explicit flags → meta.json (`scenario`, then `title`) for the
- *  task; explicit flag → pome.config.json (`agentSlug`, then `agentId`) for
- *  the agent. */
+ *  task; explicit flag → manifest `agent.slug` for the agent. */
 export declare function deriveEvalIdentity(meta: RunMeta, flags: {
     agent?: string;
     task?: string;
-}, config: ProjectConfig | null): EvalIdentity;
+}, identity: EvalProjectIdentity | null): EvalIdentity;
 /** The narrow client surface `runEval` needs; tests mock exactly this. */
 export type EvalClient = UploadClient & Pick<HostedClient, "createEvalSession" | "finalize">;
 export interface RunEvalOptions {
@@ -54,8 +58,8 @@ export interface RunEvalOptions {
     };
     /** For tests: inject a client. Otherwise constructed from `hosted`. */
     client?: EvalClient;
-    /** For tests: bypass pome.config.json discovery (pass null for "none"). */
-    projectConfig?: ProjectConfig | null;
+    /** For tests: bypass manifest discovery (pass null for "none"). */
+    projectConfig?: EvalProjectIdentity | null;
 }
 export interface RunEvalResult {
     taskName: string;

package/dist/src/cli/eval.js

@@ -28,7 +28,7 @@ import { readLatestRun, toTwinHttpEvent } from "../recorder/artifacts.js";
 import { redactEvent, redactSecrets } from "../recorder/redaction.js";
 import { criterionMarkerLabel, markerFor, outcomeOf, runScoreLine, scoreCountsSummary, scoreStatus, twinSkipSuffix, } from "../hosted/evalResultView.js";
 import { resolveCredentials } from "./credentials.js";
-import { normalizeConfigAgentSdk, readProjectConfig, } from "./project-config.js";
+import { readManifest } from "./project-config.js";
 import { isLegacyEventRow } from "../types/shared.js";
 const EVAL_SESSION_FILE = "eval-session.json";
 // The eval command has no scenario file (and therefore no per-scenario
@@ -68,7 +68,7 @@ async function readRequiredFile(runDir, name) {
     }
     catch (err) {
         if (err.code === "ENOENT") {
-            throw new HostedUsageError(`pome eval: ${name} not found in ${runDir} — expected a pome run directory (runs/<scenario>/<run-id>).`);
+            throw new HostedUsageError(`pome eval: ${name} not found in ${runDir} — expected a pome run directory (runs/<task>/<run-id>).`);
         }
         throw new HostedUsageError(`pome eval: ${name} could not be read: ${err instanceof Error ? err.message : String(err)}`);
     }
@@ -138,47 +138,39 @@ export async function readRunDirArtifacts(runDir) {
     };
 }
 /** Precedence: explicit flags → meta.json (`scenario`, then `title`) for the
- *  task; explicit flag → pome.config.json (`agentSlug`, then `agentId`) for
- *  the agent. */
-export function deriveEvalIdentity(meta, flags, config) {
+ *  task; explicit flag → manifest `agent.slug` for the agent. */
+export function deriveEvalIdentity(meta, flags, identity) {
     const taskName = flags.task?.trim() || meta.scenario || meta.title;
     if (!taskName) {
         throw new HostedUsageError("pome eval: could not derive a task name — meta.json has no `scenario` or `title` field. Pass --task <name>.");
     }
-    const agent = flags.agent?.trim() || configAgent(config);
+    const agent = flags.agent?.trim() || identity?.agentSlug?.trim() || "";
     if (!agent) {
-        throw new HostedUsageError("pome eval: no agent identity found. Pass --agent <slug>, or run `pome register agent <name>` so pome.config.json carries agentSlug.");
+        throw new HostedUsageError("pome eval: no agent identity found. Pass --agent <slug>, or run `pome register agent <name>` so pome.json carries agent.slug.");
     }
     return { agent, taskName };
 }
-function configAgent(config) {
-    if (!config)
-        return null;
-    const slug = typeof config.agentSlug === "string" ? config.agentSlug.trim() : "";
-    if (slug.length > 0)
-        return slug;
-    const id = typeof config.agentId === "string" ? config.agentId.trim() : "";
-    if (id.length > 0)
-        return id;
-    return null;
-}
 /** Walk up from the run dir first (in-project runs), then from the CWD
  *  (external run dirs like `pome eval /tmp/some-run` invoked from a
- *  configured project). Corrupt configs surface as named usage errors
- *  instead of raw JSON.parse throws (exit 2). */
+ *  configured project). Corrupt manifests surface as named usage errors
+ *  instead of raw parse throws (exit 2). */
 async function discoverProjectConfig(runDir) {
-    const fromRunDir = await readConfigNamed(runDir);
+    const fromRunDir = await readIdentityNamed(runDir);
     if (fromRunDir)
         return fromRunDir;
-    return readConfigNamed(process.cwd());
+    return readIdentityNamed(process.cwd());
 }
-async function readConfigNamed(startDir) {
+async function readIdentityNamed(startDir) {
+    let read;
     try {
-        return (await readProjectConfig(startDir))?.config ?? null;
+        read = await readManifest(startDir);
     }
     catch (err) {
-        throw new HostedUsageError(`pome eval: pome.config.json is corrupt — ${err instanceof Error ? err.message : String(err)}`);
+        throw new HostedUsageError(`pome eval: pome manifest is corrupt — ${err instanceof Error ? err.message : String(err)}`);
     }
+    if (!read)
+        return null;
+    return { agentSlug: read.manifest.agent.slug, framework: read.manifest.agent.framework };
 }
 // ---------------------------------------------------------------------------
 // eval-session persistence (idempotent re-runs)
@@ -237,10 +229,10 @@ function isSessionGoneError(err) {
 export async function runEval(options) {
     const runDir = options.runDir;
     const artifacts = await readRunDirArtifacts(runDir);
-    const config = options.projectConfig !== undefined
+    const projectIdentity = options.projectConfig !== undefined
         ? options.projectConfig
         : await discoverProjectConfig(runDir);
-    const identity = deriveEvalIdentity(artifacts.meta, { agent: options.agent, task: options.task }, config);
+    const identity = deriveEvalIdentity(artifacts.meta, { agent: options.agent, task: options.task }, projectIdentity);
     const { agent, taskName } = identity;
     const client = options.client ??
         createHostedClient({
@@ -310,7 +302,7 @@ export async function runEval(options) {
             exitCode: artifacts.meta.exitCode ?? -1,
             durationMs: durationMsFrom(artifacts.meta),
             agentModel: "unknown",
-            agentSdk: config ? normalizeConfigAgentSdk(config) : null,
+            agentSdk: projectIdentity?.framework ?? null,
             // Eval sessions carry no client-side criteria — the cloud eval judge
             // owns them (FDRS-655). Cloud's finalize schema defaults all scenario
             // fields, so empty strings are accepted.
@@ -391,7 +383,7 @@ export async function runEvalCommand(runDirArg, opts) {
                 throw new HostedUsageError(`pome eval: ${latestPath} is corrupt — not valid JSON (${err instanceof Error ? err.message : String(err)}).`);
             }
             if (!latest || typeof latest.run_dir !== "string" || latest.run_dir.length === 0) {
-                throw new HostedUsageError(`pome eval: no run directory given and ${latestPath} ${latest ? "has no run_dir field" : "not found"}. Pass a run directory (runs/<scenario>/<run-id>).`);
+                throw new HostedUsageError(`pome eval: no run directory given and ${latestPath} ${latest ? "has no run_dir field" : "not found"}. Pass a run directory (runs/<task>/<run-id>).`);
             }
             runDir = resolve(latest.run_dir);
         }

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

@@ -0,0 +1,12 @@
+/** Known agent frameworks. Open enum by design — this list drives the warning
+ *  suggestion only, never a hard rejection. */
+export declare const KNOWN_FRAMEWORKS: readonly ["langgraph", "claude-agent-sdk", "openai-agents", "crewai", "autogen", "llamaindex", "google-adk", "mastra", "pydantic-ai", "semantic-kernel"];
+export interface FrameworkSuggestion {
+    known: boolean;
+    /** Present only when unknown AND a known framework is within edit distance. */
+    suggestion?: string;
+}
+/** Classify a framework value. Known → `{ known: true }`. Unknown → `{ known:
+ *  false }`, with `suggestion` set to the nearest known value within edit
+ *  distance 2 (else omitted). Comparison is case-insensitive. */
+export declare function suggestFramework(input: string): FrameworkSuggestion;