@pome-sh/cli 0.43.0 → 0.44.0

package/README.md

@@ -1,168 +1,288 @@
 # Pome CLI
 
-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.
+The `pome` CLI runs AI-agent tasks against resettable digital twins of real SaaS APIs.
+It records each run and sends hosted runs to Pome for evaluation.
 
-The CLI is **capture-only**: it records raw traces and never scores, judges, or
-correlates locally. A verdict comes only from the cloud — a hosted `pome run`
-prints it to the terminal and records it to the dashboard, and
-`pome eval <run-dir>` uploads a captured trace for a cloud verdict.
+The CLI does not score locally.
 
-**📚 Full documentation lives at [docs.pome.sh](https://docs.pome.sh).**
-Run `pome --help` (or `pome help <command>`) for the CLI reference, and
-`pome docs getting-started` to print the quickstart's URL.
+- `pome run` uses the hosted workflow by default. It records the run and prints the hosted verdict.
+- `pome run --local` uses local twins. It records one trace and does not request a verdict.
+- `pome eval` uploads existing local artifacts and prints the hosted verdict.
+
+See [docs.pome.sh](https://docs.pome.sh) for the full documentation.
+Use `pome --help` or `pome help <command>` for command details.
+
+## Requirements
+
+- Node.js 24 or later
+- A Pome account and API key for hosted runs and evaluations
+- A supported model-provider credential when the agent calls a model provider
+
+Local twin commands do not require a Pome account.
 
 ## Install
 
+Install the CLI globally:
+
 ```bash
 npm install -g @pome-sh/cli
-pome --help
 ```
 
-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.
+You can also run one command without a global installation:
+
+```bash
+npx @pome-sh/cli twin start github
+```
+
+## Set Up A Project
 
-Gmail is first-party too:
+Create the starter project in an empty directory:
 
 ```bash
-npx @pome-sh/cli twin start gmail --port 3336
-# prints POME_GMAIL_REST_URL, POME_GMAIL_MCP_URL, and POME_GMAIL_TOKEN
-pome tasks gmail --copy
+mkdir pome-example
+cd pome-example
+pome init
+pome login
+pome register agent my-agent
+pome run tasks/01-bug-happy-path.md
 ```
 
-`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.
+`pome init` writes `pome.json`, starter tasks, and an example agent in an empty directory.
+In an existing project, it writes only the manifest unless you use `--starter`.
+
+Set `command` in `pome.json`, or pass `--agent <command>` to `pome run`.
+
+## Hosted Workflow
+
+Hosted execution is the default for `pome run`.
+The command creates hosted sandboxes, runs the agent, uploads the artifacts, and prints the verdict.
 
-## Quickstart
+Use `POME_API_KEY` instead of `pome login` in CI.
+Use `-n <count>` to run a hosted trial group of 1 to 20 trials.
+The task `runs` field supplies the count when you omit `-n`.
+
+## Local Capture And Hosted Evaluation
+
+Use `--local` to run one task against in-process twins.
+This command records artifacts but never scores them.
 
 ```bash
-pome login                       # one-time; opens the dashboard to sign in
-pome init                        # scaffolds tasks/, examples/agents/, runs/, pome.json
-pome register agent my-agent     # scopes runs to this project
-pome run tasks/01-bug-happy-path.md --agent "node examples/agents/scripted-triage-agent.ts"
-pome inspect latest              # trace/audit view of the last run
+pome run --local tasks/01-bug-happy-path.md
+pome inspect latest
+pome eval
 ```
 
-To capture a trace without the cloud (self-host), then get a verdict later:
+`pome eval` uses `<artifacts-dir>/latest.json` when you omit the run directory.
+You can also give the directory explicitly:
 
 ```bash
-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
+pome eval runs/01-bug-happy-path/<run-id>
 ```
 
-## Start from an example
+`pome eval` uploads the trace to Pome and prints the hosted verdict.
+It does not add a local score.
+
+Do not combine `--local` with `-n`.
+Local capture always runs one trial.
+
+## Standalone Twins
 
-`pome init --example <id>` fetches a complete, runnable example — its agent,
-its tasks, its `pome.json` and its lockfile — into `./<id>`:
+Start a long-running local twin:
 
 ```bash
-pome init --example minimal-viktor   # a merge bot on the GitHub + Slack twins
-cd minimal-viktor && npm install
-pome run tasks/01-clean-merge.md
+pome twin start gmail --port 3336
 ```
 
-An example is named by **id**, never by path — that is the whole point. The ids
-are derived from the example directories rather than restated anywhere, so an
-example that is renamed or deleted stops answering to the old id on the next
-command, with the valid ids printed underneath, instead of going quietly 404 in
-a link someone typed months ago. An unknown id lists every available one:
+The command prints the REST URL, MCP URL, and bearer token.
+For Gmail, `POME_GMAIL_TOKEN` is the same Pome session JWT as `POME_AUTH_TOKEN`.
+It is not a Google OAuth token.
+
+Create a seed file, then use it to start a twin:
 
 ```bash
-pome init --example nope    # → the full list, each with what it teaches
+pome twin new-seed github --out seed.json
+pome twin start github --seed seed.json
 ```
 
-Two kinds are on that list: **agents for Pome to grade**, which you run with
-`pome run`, and **integration harnesses** (Braintrust, LangSmith) that drive Pome
-from their own eval runner and are started by it, not by `pome run`. The output
-tells you which one you scaffolded.
+A supplied seed replaces the default seed.
+It does not merge with the default seed.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `pome init` | Write `pome.json` and, when applicable, starter files. |
+| `pome login` | Sign in and store a hosted API key. |
+| `pome logout` | Remove locally stored hosted credentials. |
+| `pome docs [topic]` | Print or select a documentation URL. |
+| `pome tasks [twin]` | List or copy bundled tasks. |
+| `pome checks [twin]` | List the checks that can grade `[code]` criteria. |
+| `pome checks add <file>` | Add one declared `[code]` criterion to a task. |
+| `pome checks lint <file...>` | Report `[code]` criteria that do not bind to declared checks. |
+| `pome compile-seeds [target]` | Compile prose seed state to `.seed.json` files with Claude. |
+| `pome register agent <name>` | Register an agent and write its slug to `pome.json`. |
+| `pome sandbox create` | Create a hosted sandbox. |
+| `pome sandbox list` | List hosted sandboxes. |
+| `pome sandbox stop <session-id>` | Stop a hosted sandbox. |
+| `pome run [path]` | Run one task or all task files in a directory. Hosted is the default. |
+| `pome doctor` | Check the manifest, twin routing, and egress controls. |
+| `pome eval [run-dir]` | Upload recorded artifacts and request a hosted verdict. |
+| `pome inspect <run>` | Print a trace and audit report. |
+| `pome fix-prompt [target]` | Build a repair prompt from recorded traces and hosted verdicts. |
+| `pome twin start [name]` | Start a standalone local twin. |
+| `pome twin new-seed <name...>` | Print or write a starter seed file. |
+| `pome twin status` | Check the last standalone twin and print its connection values. |
+
+## Environment Variables
+
+Global hosted configuration:
+
+| Variable | Purpose |
+| --- | --- |
+| `POME_API_KEY` | Authenticate hosted commands. This value takes precedence over stored credentials. |
+| `POME_API_URL` | Set the control-plane URL. `--api-url` takes precedence. |
+| `POME_DASHBOARD_URL` | Set the dashboard URL for login and result links. |
+
+Agent process configuration:
+
+| Variable | Purpose |
+| --- | --- |
+| `POME_AGENT_ENV_ALLOWLIST` | Add comma-separated parent variable names to the agent process. |
+| `POME_EGRESS_ALLOW` | Add comma-separated host patterns to the capture proxy allowlist. |
+| `POME_INHERIT_AGENT_ENV=1` | Pass the full parent environment to the agent. Use this only with trusted agents. |
+| `POME_TRUST_AGENT_COMMAND=1` | Run the agent command through a shell. Use this only with trusted commands. |
 
-The files come from GitHub at the commit that built your CLI, so an example is
-always the one this version was released with. `POME_EXAMPLE_REF` overrides the
-ref when you want a branch.
+The CLI passes these provider variables to the agent by default when they are set:
 
-See [docs.pome.sh](https://docs.pome.sh) for the task library, authentication,
-the Stripe/Slack twins, and everything else.
+- `AI_GATEWAY_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `CLAUDE_CODE_OAUTH_TOKEN`
+- `GOOGLE_API_KEY`
+- `GOOGLE_GENERATIVE_AI_API_KEY`
+- `OPENAI_API_KEY`
+- `OPENROUTER_API_KEY`
 
-## CI one-shot — the exit-code contract
+`pome compile-seeds` requires `ANTHROPIC_API_KEY`.
 
-`pome run <task>` is the CI one-shot: one hosted, scored run, and its **exit
-code is the verdict**. Gate CI on it directly.
+Standalone twin configuration:
 
-| Exit code | Meaning |
+| Variable | Purpose |
 | --- | --- |
-| `0` | pass (hosted/scored run), or trace captured (`--local`, not scored) |
-| `1` | ran and scored **below** the pass threshold, **or ran `INCOMPLETE`** |
-| `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) |
-
-Three 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>`.
-- **`INCOMPLETE` shares exit `1`, and it is not the agent's failure.** A run
-  whose criteria could not all be graded exits `1` rather than mapping its
-  partial score to a code — a run whose checks never ran is not a green CI
-  signal. The cost is stated rather than hidden: **`1` cannot tell "the agent
-  regressed" from "we could not grade it."** To separate them programmatically,
-  do not compare `score` against `pass_threshold` yourself — a run with a third
-  of its criteria unevaluated can still read `score: 100, pass_threshold: 100`
-  with nothing in those two fields alone saying so. Read `state` in the
-  `verdict.json` a hosted `pome run` writes to
-  `<artifacts-dir>/<task-slug>/<session-id>/verdict.json`: `"pass"`, `"fail"`,
-  or `"incomplete"` — the same word the terminal prints beside the score, and
-  the field to gate on. The `evaluated` / `not_evaluated` / `pre_satisfied` /
-  `total` counts alongside it say how much of the task `score` covers:
-  **`score` is a percentage over `evaluated` alone**, so `not_evaluated > 0`
-  means `score` is silent about part of the run, and `evaluated: 0` means it
-  scored nothing at all (the cloud sends `0` there for want of a denominator
-  — "nothing was scored", not "nothing was correct").
-- **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 **or was
-  incomplete**; `2` = no trial completed. Errored and incomplete trials are
-  excluded from the verdict fraction (`3 of 4 passed · 1 incomplete`) so neither
-  is counted as a pass nor charged to the agent as a loss — but a group holding
-  one cannot exit `0`.
-- **`pome fix-prompt` uses the same codes, and its `1` is only ever
-  INCOMPLETE.** Building a prompt for a failed run set exits `0` (the prompt is
-  on stdout, and stdout being non-empty is the signal that there was something
-  to fix); an all-green root exits `0` with nothing on stdout; a bad argument or
-  a root with no readable run sets exits `5`. `1` is reserved for the one case
-  where the newest non-passing set was never fully graded: no prompt is built,
-  because a run whose checks never ran is not evidence of an agent defect. This
-  matches `pome run`, where `1` also covers INCOMPLETE — the two commands do not
-  disagree about what an ungraded run exits, and `verdict.json`'s `state` stays
-  the field to read when a script needs the reason rather than the code.
-
-## Development
+| `PORT` | Set the listen port for `pome twin start`. `--port` takes precedence. |
+| `POME_SEED_JSON` | Supply seed JSON. `--seed` takes precedence. |
+| `TWIN_AUTH_SECRET` | Supply the secret that signs local session JWTs. |
+| `POME_TWIN_DATA_DIR` | Set the directory for the persisted twin secret. |
+
+The twin entry points also accept their provider-specific host, port, database, and no-seed variables.
+See [`CONTRACT.md`](../CONTRACT.md) for that runtime interface.
+
+## Artifacts
+
+The default artifact root is `runs/`.
+Use the global `--artifacts-dir <dir>` option to select another root.
+
+Each completed run uses this directory format:
+
+```text
+<artifacts-dir>/<task-slug>/<run-id>/
+```
+
+The six core files are:
+
+| File | Content |
+| --- | --- |
+| `meta.json` | Run identity, times, agent exit, twins, and format versions. |
+| `events.jsonl` | Redacted twin, model, and adapter events. |
+| `state_initial.json` | Initial state for the primary twin. |
+| `state_final.json` | Final state for the primary twin. |
+| `stdout.txt` | Redacted agent standard output. |
+| `stderr.log` | Redacted agent standard error. |
+
+A run can also contain these files:
+
+| File | Condition |
+| --- | --- |
+| `egress.jsonl` | The capture proxy records refused connections here. |
+| `state_final.<twin>.json` | A multi-twin run records each additional final state. |
+| `verdict.json` | A hosted `pome run` caches the hosted verdict for `pome fix-prompt`. |
+| `eval-session.json` | `pome eval` records the hosted evaluation session for safe reuse. |
+
+The artifact root also contains `latest.json`.
+It points to the most recent run directory.
+
+The CLI never writes `score.json`.
+A hosted verdict comes from Pome.
+
+## Exit Codes
+
+### Hosted `pome run` And `pome eval`
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The hosted verdict is `pass`. |
+| `1` | The hosted verdict is `fail` or `incomplete`. |
+| `2` | A twin, missing agent command, malformed task configuration, network, or orchestration error prevented a verdict. |
+| `3` | Authentication failed. |
+| `4` | The account exceeded a quota. |
+| `5` | The CLI rejected the invocation during validation, for example because a path, option, or option combination is invalid. |
+
+For `pome run`, the task supplies the pass threshold.
+For `pome eval`, the pass threshold is `100`.
+
+For a hosted `pome run`, read `state` in `verdict.json` to distinguish `fail` from `incomplete`.
+The possible values are `"pass"`, `"fail"`, and `"incomplete"`.
+
+The `evaluated`, `not_evaluated`, `pre_satisfied`, and `total` fields describe grading coverage.
+`score` is a percentage over `evaluated` criteria only.
+Thus, `not_evaluated > 0` means that the score does not cover the complete task.
+
+### Hosted Trial Groups
+
+`pome run -n k` returns one code for the group when `k` is greater than `1`.
+
+| Code | Meaning |
+| --- | --- |
+| `0` | At least one trial completed and every completed trial passed. |
+| `1` | At least one completed trial failed or was incomplete. |
+| `2` | No trial completed. |
+
+Errored trials do not enter the verdict fraction.
+An incomplete trial also prevents exit `0`.
+
+### Local `pome run --local`
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The agent completed and the CLI recorded the trace. This code is not a verdict. |
+| `2` | A local twin, missing agent command, malformed task configuration, or runner error prevented capture. |
+| `3` | The agent failed, timed out, or failed its preflight. |
+| `5` | The CLI rejected the invocation during validation, for example because a path, option, or option combination is invalid. |
+
+Do not use a local exit `0` as a CI quality gate.
+Run `pome eval <run-dir>` to request a verdict.
+
+### `pome fix-prompt`
+
+- Exit `0` means that the command succeeded. Standard output can be empty when all run sets passed.
+- Exit `1` means that the newest non-passing set is incomplete.
+- Exit `5` means that the target or arguments are invalid.
+
+## Contribute
+
+Run these commands from the repository root:
 
 ```bash
 npm install
-npm run typecheck
 npm run build
+npm run typecheck
 npx vitest run --project cli
 ```
 
-The package publishes the `pome` binary from `dist/src/cli/main.js`.
-
-### Versioning — every behavior change ships with a release, and you do not write the number
+Use `npm run test:contract` for the packaged twin runtime contract.
+Run `node --test contract/cli-start.test.mjs` after you build the CLI front door.
 
-Add the user-facing entry to `CHANGELOG.md` under an `## Unreleased (patch)` (or
-`(minor)`) heading, above the newest released one, and leave `version` in
-`cli/package.json` alone — a PR that moves it fails CI. Merging to `main` is the
-release trigger: `.github/workflows/allocate-version.yml` allocates the number
-there, rewriting that heading and the manifest in one commit, and
-`.github/workflows/release.yml` compares the local version against npm and
-publishes when they differ. `pome --version` reports the allocated value from a
-build-time constant, so a user can always tell whether their install carries a
-given fix.
+The package publishes `pome` from `cli/dist/src/cli/main.js`.
 
 ## License
 
-Apache-2.0. See [`LICENSE`](./LICENSE).
+Apache-2.0. See [`LICENSE`](../LICENSE).

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "package": "pome-sh",
-  "version": "0.43.0",
-  "git_sha": "589885b59adab9a5fded977620a6adc25125da85",
-  "build_time": "2026-09-01T07:18:35.031Z"
+  "version": "0.44.0",
+  "git_sha": "a80259dcddd5ec6f1a16dba3a6f252539996ebb7",
+  "build_time": "2026-09-16T12:52:26.327Z"
 }

package/dist/{checks-QYUPKBPT.js → checks-BOOQNOGJ.js}

@@ -1,9 +1,10 @@
 import { getAvailablePort } from './chunk-XDU6TD4O.js';
-import { findManifestPath, readManifest } from './chunk-CS7O2ZXB.js';
+import { findManifestPath, readManifest } from './chunk-26UAPLHK.js';
+import './chunk-M7ATJ423.js';
 import { buildEgressAllowlist } from './chunk-CBFKZZBR.js';
 import './chunk-NBOQN5VX.js';
 import './chunk-YBWG5JK2.js';
-import './chunk-5KFDRR53.js';
+import './chunk-7VZBAHQ2.js';
 import './chunk-SG6ZTIMT.js';
 import './chunk-2K6BJ3PI.js';
 import './chunk-FBSA5L36.js';
@@ -182,7 +183,7 @@ async function checkTwinReachable(_configDir) {
   });
   let harness;
   try {
-    const { bootTwin } = await import('./twinHarness-WJFDLEAO.js');
+    const { bootTwin } = await import('./twinHarness-YDGIGB4P.js');
     harness = await bootTwin({
       twin: "github",
       seedState: void 0,

package/dist/chunk-26UAPLHK.js

@@ -0,0 +1,191 @@
+import { manifestSchema, deriveAgentSlug, SLUG_RE } from './chunk-M7ATJ423.js';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve, join, dirname } from 'node:path';
+import { stringify, parse } from 'yaml';
+
+// src/hosted/errors.ts
+var HostedAuthError = class extends Error {
+  constructor(message, requestId) {
+    super(message);
+    this.requestId = requestId;
+    this.name = "HostedAuthError";
+  }
+  requestId;
+};
+var HostedQuotaError = class extends Error {
+  /** `details` mirrors the cloud error envelope's machine-readable details
+   *  (e.g. `{ kind: "daily_judge_cap" }`) so `pome demo` can
+   *  render honest labeled at-capacity states. Optional: older responses and
+   *  the twin-pod 401 shape carry none. */
+  constructor(message, requestId, details) {
+    super(message);
+    this.requestId = requestId;
+    this.details = details;
+    this.name = "HostedQuotaError";
+  }
+  requestId;
+  details;
+};
+var HostedOrchError = class extends Error {
+  /** `status` is the HTTP status that produced this error, when one exists
+   *  (network/parse failures leave it undefined). `pome eval` uses it to
+   *  scope its reaped-session retry to 404/410 only. */
+  constructor(message, requestId, status, type) {
+    super(message);
+    this.requestId = requestId;
+    this.status = status;
+    this.type = type;
+    this.name = "HostedOrchError";
+  }
+  requestId;
+  status;
+  type;
+};
+var HostedUsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HostedUsageError";
+  }
+};
+var HostedTrialError = class extends Error {
+  constructor(message, errorCode) {
+    super(message);
+    this.errorCode = errorCode;
+    this.name = "HostedTrialError";
+  }
+  errorCode;
+};
+var HostedDiscardRefusedError = class extends Error {
+  constructor(message, sessionId, state, taskName, openSeconds, discardToken) {
+    super(message);
+    this.sessionId = sessionId;
+    this.state = state;
+    this.taskName = taskName;
+    this.openSeconds = openSeconds;
+    this.discardToken = discardToken;
+    this.name = "HostedDiscardRefusedError";
+  }
+  sessionId;
+  state;
+  taskName;
+  openSeconds;
+  discardToken;
+};
+function exitCodeFor(err) {
+  if (err instanceof HostedAuthError) return 3;
+  if (err instanceof HostedQuotaError) return 4;
+  if (err instanceof HostedUsageError) return 5;
+  if (err instanceof HostedDiscardRefusedError) return 5;
+  return 2;
+}
+var MANIFEST_JSON = "pome.json";
+var MANIFEST_YAML = "pome.yaml";
+var MANIFEST_YML = "pome.yml";
+var MANIFEST_FILES = [MANIFEST_JSON, MANIFEST_YAML, MANIFEST_YML];
+var SCHEMA_URL = "https://pome.sh/schemas/v1/pome.json";
+var YAML_SCHEMA_COMMENT = `# yaml-language-server: $schema=${SCHEMA_URL}`;
+function formatFor(fileName) {
+  return fileName === MANIFEST_JSON ? "json" : "yaml";
+}
+async function findManifestPath(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  for (; ; ) {
+    const present = [];
+    for (const fileName of MANIFEST_FILES) {
+      if (await fileExists(join(dir, fileName))) present.push(fileName);
+    }
+    if (present.length > 1) {
+      throw new HostedOrchError(
+        `Multiple pome manifests in ${dir}: ${present.join(", ")}. Keep exactly one (pome.json is canonical).`
+      );
+    }
+    if (present.length === 1) {
+      const fileName = present[0];
+      return { path: join(dir, fileName), format: formatFor(fileName) };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+async function readManifest(startDir = process.cwd()) {
+  const found = await findManifestPath(startDir);
+  if (!found) return null;
+  const text = await readFile(found.path, "utf8");
+  const raw = parseManifestText(text, found);
+  const manifest = validateManifest(raw, found.path);
+  return { ...found, manifest, raw };
+}
+async function readRequiredManifest(startDir = process.cwd()) {
+  const read = await readManifest(startDir);
+  if (!read) {
+    throw new HostedOrchError(
+      `No pome manifest found (${MANIFEST_JSON} or ${MANIFEST_YAML}). Run \`pome init\` first.`
+    );
+  }
+  return read;
+}
+async function writeManifest(path, format, data) {
+  if (format === "json") {
+    await writeFile(path, `${JSON.stringify(data, null, 2)}
+`);
+    return;
+  }
+  const { $schema: _dropped, ...body } = data;
+  await writeFile(path, `${YAML_SCHEMA_COMMENT}
+${stringify(body)}`);
+}
+function parseManifestText(text, found) {
+  let parsed;
+  try {
+    parsed = found.format === "json" ? JSON.parse(text) : parse(text);
+  } catch (err) {
+    throw new HostedOrchError(
+      `${found.path} is not valid ${found.format.toUpperCase()}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new HostedOrchError(`${found.path} is not a ${found.format} object`);
+  }
+  return parsed;
+}
+function validateManifest(raw, path) {
+  const result = manifestSchema.safeParse(raw);
+  if (result.success) return result.data;
+  const slugIssue = result.error.issues.find(
+    (issue) => issue.path[0] === "agent" && issue.path[1] === "slug"
+  );
+  if (slugIssue) {
+    throw new HostedOrchError(slugErrorMessage(raw, path));
+  }
+  const summary = result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+  throw new HostedOrchError(`Invalid pome manifest ${path}: ${summary}`);
+}
+function slugErrorMessage(raw, path) {
+  const agent = typeof raw.agent === "object" && raw.agent !== null ? raw.agent : {};
+  const name = typeof agent.name === "string" ? agent.name : "";
+  const badSlug = typeof agent.slug === "string" ? agent.slug : "";
+  const suggestion = deriveAgentSlug(name || badSlug);
+  const base = `Invalid agent.slug in ${path}: must match ${SLUG_RE} (lowercase kebab-case, max 64 chars).`;
+  return suggestion.length > 0 ? `${base} Did you mean "${suggestion}"?` : base;
+}
+function normalizeManifestTwins(manifestTwins) {
+  if (manifestTwins === void 0) return void 0;
+  const out = /* @__PURE__ */ new Set();
+  for (const twin of manifestTwins) {
+    const norm = twin.trim().toLowerCase();
+    if (norm.length > 0) out.add(norm);
+  }
+  return out.size > 0 ? [...out] : void 0;
+}
+async function fileExists(path) {
+  try {
+    await readFile(path, "utf8");
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+export { HostedAuthError, HostedDiscardRefusedError, HostedOrchError, HostedQuotaError, HostedTrialError, HostedUsageError, MANIFEST_JSON, exitCodeFor, findManifestPath, normalizeManifestTwins, readManifest, readRequiredManifest, writeManifest };

package/dist/{chunk-5A6HHA54.js → chunk-3T4FUF43.js}

@@ -1,5 +1,5 @@
-import { TWIN_NAMES, isTwinName, TWIN_REGISTRY } from './chunk-ELIEDNF3.js';
-import { createFileBackedRecorderStore, createRecorderStore } from './chunk-HRAD7MRX.js';
+import { TWIN_NAMES, isTwinName, TWIN_REGISTRY } from './chunk-RYAQ2ZYA.js';
+import { createFileBackedRecorderStore, createRecorderStore } from './chunk-TWURH7YM.js';
 
 // src/recorder/recorder.ts
 function createRecorder(options = {}) {

package/dist/chunk-4LQ4IJOC.js

@@ -0,0 +1 @@
+