@pome-sh/cli 0.3.0 → 0.5.0

package/dist/src/cli/link-cache.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// `.pome/link.json` — the gitignored, machine-local resolver cache (F-819,
+// spec F-804). It maps the committed `agent.slug` to the `agt_` id the platform
+// resolved for it, scoped to the team that resolved it. The cache is TRUSTED
+// only when its `team_id` matches the caller's team: a re-clone under the same
+// team short-circuits (Champion TTHW), a fork or team switch silently
+// re-resolves by slug so we never send a foreign `agt_` id.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const POME_DIR = ".pome";
+export const LINK_FILE = "link.json";
+const GITIGNORE_ENTRY = `${POME_DIR}/`;
+function linkPath(projectDir) {
+    return join(projectDir, POME_DIR, LINK_FILE);
+}
+/** Read the link cache next to a manifest. Missing or malformed → null: this
+ *  is a cache, never a hard failure (a bad file just forces re-resolution). */
+export 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 };
+}
+/** Persist `.pome/link.json`, stamping `resolved_at` now. Creates `.pome/`. */
+export 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: new Date().toISOString(),
+    };
+    await writeFile(linkPath(projectDir), `${JSON.stringify(body, null, 2)}\n`);
+}
+/** The team gate: the cached id is usable only when it was resolved under the
+ *  caller's own team. Any mismatch (or unknown caller team) → undefined, so the
+ *  caller re-resolves by slug instead of sending a foreign `agt_` id. */
+export function resolveCachedAgentId(cache, callerTeamId) {
+    if (!cache || !callerTeamId)
+        return undefined;
+    return cache.team_id === callerTeamId ? cache.agent_id : undefined;
+}
+/** Ensure the project's `.gitignore` ignores `.pome/`. Creates the file when
+ *  absent; appends the entry when missing. Idempotent, and a bare `.pome`
+ *  (no trailing slash) already counts as ignored. */
+export 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}\n`);
+        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}\n`);
+}

package/dist/src/cli/login.js

@@ -40,7 +40,7 @@ export async function loginWithClerk(options) {
         console.error(`Saved Pome credentials to ${path}`);
     }
     console.error("Pome login complete.");
-    console.error("Next: `pome session create --twin github` or `pome run <scenario>.md`");
+    console.error("Next: `pome session create --twin github` or `pome run <task>.md`");
 }
 async function exchangeCode(input) {
     const ctrl = new AbortController();

package/dist/src/cli/main.js

@@ -3,7 +3,7 @@
 import { Command } from "commander";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { cp, mkdir, readdir, readFile, rm } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readLatestRun, readMetaSummary, } from "../recorder/artifacts.js";
 import { LEGACY_EVENTS_MESSAGE, computeTraceHealth, readEventsJsonl, renderEvents, renderTraceHealth, } from "../recorder/inspect.js";
@@ -18,7 +18,6 @@ import { runDocsCommand } from "./docs.js";
 import { runCompileSeeds } from "./compile-seeds.js";
 import { runScenariosCommand } from "./scenarios.js";
 import { runEvalCommand } from "./eval.js";
-import { runSkillsInstall } from "./skills.js";
 import { copyAnnounceLine, ensureDefaultTask, runYoursFrameLines, trialsPinFallbackLine, } from "./default-task.js";
 import { findTwin, runnableScenarios, } from "./scenarios-catalog.js";
 import { friendlyHostedError, runSessionCreate, runSessionList, runSessionStop, } from "./session.js";
@@ -26,7 +25,8 @@ import { normalizeRegisterTwins, runRegisterAgent } from "./register.js";
 import { resolvePackageRoot } from "./resolve-package-root.js";
 import { ClaudeManagedDeferredError, writeSdkScaffold, } from "./init-sdk.js";
 import { DEFAULT_CONTROL_PLANE_URL, DEFAULT_DASHBOARD_URL, } from "./defaults.js";
-import { CONFIG_FILE, normalizeConfigAgentCommand, readProjectConfig, writeProjectConfig, } from "./project-config.js";
+import { deriveAgentSlug } from "@pome-sh/shared-types";
+import { MANIFEST_JSON, readManifest, writeManifest, } from "./project-config.js";
 import { createGitHubCloneApp } from "../twin/githubCloneAdapter.js";
 import { buildFixPrompt, buildGroupFixPrompt, } from "../fix-prompt/index.js";
 import { discoverRunSet, loadTrialEvents, } from "../hosted/evalResultCache.js";
@@ -34,6 +34,7 @@ import { parseScenarioFile } from "../scenario/parseScenario.js";
 const PACKAGE_VERSION = readPackageVersion();
 const SESSION_CREATE_FORMATS = new Set(["text", "json", "env"]);
 const DEFAULT_AGENT_COMMAND = "npx tsx examples/agents/scripted-triage-agent.ts";
+const MANIFEST_SCHEMA_URL = "https://pome.sh/schemas/v1/pome.json";
 function readPackageVersion() {
     try {
         const here = dirname(fileURLToPath(import.meta.url));
@@ -65,7 +66,7 @@ export function createProgram() {
     program
         .command("init")
         .description("Create starter Pome config and folders")
-        .option("--sdk <name>", "Scaffold for a specific agent SDK (claude | claude-managed). Adds the SDK-specific example file and pre-fills agent.sdk so the dashboard badges runs correctly.")
+        .option("--sdk <name>", "Scaffold for a specific agent SDK (claude | claude-managed). Adds the SDK-specific example file and pre-fills agent.framework so the dashboard badges runs correctly.")
         .action(async (opts) => {
         const sdk = opts.sdk?.trim();
         if (sdk !== undefined &&
@@ -84,67 +85,71 @@ export function createProgram() {
         await mkdir("examples/agents", { recursive: true });
         await mkdir("runs", { recursive: true });
         await copyStarterFiles();
-        let agentBlock = {
-            command: DEFAULT_AGENT_COMMAND,
-        };
+        let command = DEFAULT_AGENT_COMMAND;
+        let framework;
         let postInitMessage = "Pome initialized.\n" +
             "Next steps:\n" +
             "  1. pome login                    # one-time, opens the dashboard to sign in\n" +
-            "  2. pome register agent <name>    # scopes runs to this project (writes agentId + agentSlug to pome.config.json)\n" +
+            "  2. pome register agent <name>    # scopes runs to this project (writes agent.slug to pome.json)\n" +
             "  3. pome run scenarios/01-bug-happy-path.md\n" +
             "\n" +
             "Optional follow-ups:\n" +
             "  - pome init --sdk claude         # scaffold a Claude Agent SDK starter\n" +
-            "  - pome scenarios stripe --copy   # add Stripe payment scenarios when needed\n" +
+            "  - pome scenarios stripe --copy   # add Stripe payment tasks when needed\n" +
             "\n" +
             "See `pome docs getting-started` for a narrative walkthrough.";
         if (sdk) {
             const scaffold = await writeSdkScaffold(sdk);
-            agentBlock = {
-                sdk: scaffold.agentSdkValue,
-                command: scaffold.agentCommand,
-            };
+            command = scaffold.agentCommand;
+            framework = scaffold.agentSdkValue;
             postInitMessage =
                 `Pome initialized with --sdk ${sdk}. Scaffolded ${scaffold.exampleAgentRelativePath}.\n` +
                     scaffold.postInstallHint;
         }
-        const existingConfig = await readProjectConfig(process.cwd());
-        if (!existingConfig) {
-            await writeProjectConfig(CONFIG_FILE, {
-                agent: agentBlock,
-                artifactsDir: "runs",
-                passThreshold: 100,
+        // The manifest requires `agent.slug` (F-804). `pome init` runs before
+        // `pome register`, so seed a portable slug derived from the directory
+        // name; register later overwrites it with the server-canonical slug.
+        const existing = await readManifest(process.cwd());
+        if (!existing) {
+            const slug = deriveAgentSlug(basename(process.cwd())) || "my-agent";
+            const agent = { slug };
+            if (framework)
+                agent.framework = framework;
+            await writeManifest(join(process.cwd(), MANIFEST_JSON), "json", {
+                $schema: MANIFEST_SCHEMA_URL,
+                agent,
+                command,
+                artifacts_dir: "runs",
+                pass_threshold: 100,
             });
         }
         else if (sdk) {
-            await writeProjectConfig(existingConfig.path, {
-                ...existingConfig.config,
-                agent: {
-                    ...(typeof existingConfig.config.agent === "object" &&
-                        existingConfig.config.agent !== null
-                        ? existingConfig.config.agent
-                        : {}),
-                    ...agentBlock,
-                },
+            const priorAgent = typeof existing.raw.agent === "object" && existing.raw.agent !== null
+                ? existing.raw.agent
+                : {};
+            const nextAgent = { ...priorAgent };
+            if (framework)
+                nextAgent.framework = framework;
+            await writeManifest(existing.path, existing.format, {
+                ...existing.raw,
+                agent: nextAgent,
+                command,
             });
         }
         console.error(postInitMessage);
     });
     program
         .command("install")
-        .description("Wire this repo to pome with your own coding agent: checks auth (routes through pome login when needed), runs the wiring headless on your own Claude credentials, shows the full diff in this terminal, and applies it only on [y] — then verifies with pome doctor. --interactive hands off to a live agent session instead; no coding agent on PATH → prints manual wiring steps + a paste-into-any-agent prompt.")
-        .option("--interactive", "Hand off to an interactive agent session (approve edits in the agent's own UI) instead of the headless staged-diff flow.")
-        .option("--api-url <url>", "Control-plane base URL.", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
-        .option("--dashboard-url <url>", "App URL for Clerk sign-in (must serve /cli/login).", process.env.POME_DASHBOARD_URL ?? DEFAULT_DASHBOARD_URL)
-        .action(async (opts) => {
-        // Dynamic import mirrors the doctor/run commands: keep install's
-        // dependency graph out of every other command's startup path.
+        // F-893 — the Gen-1 agent-driven wiring is retired; this is a redirect to
+        // the Gen-2 path. allowUnknownOption + allowExcessArguments keep old
+        // invocations (`pome install --interactive`, `--api-url …`) landing on the
+        // redirect instead of erroring on a now-removed flag or stray operand.
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .description("Retired (F-893). Prints the Gen-2 wiring path: `claude mcp add … pome` + `npx skills add pome-sh/digital-twins`, then the pome-intake / REST-launch preflight.")
+        .action(async () => {
         const { runInstall } = await import("./install.js");
-        await runInstall({
-            apiUrl: opts.apiUrl,
-            dashboardUrl: opts.dashboardUrl,
-            interactive: opts.interactive,
-        });
+        runInstall();
     });
     program
         .command("login")
@@ -175,10 +180,10 @@ export function createProgram() {
     program
         .command("scenarios")
         .argument("[twin]", "Twin id (e.g. github). Omit to list available twins.")
-        .option("--copy", "Copy the twin's runnable scenarios into the local project.", false)
+        .option("--copy", "Copy the twin's runnable tasks into the local project.", false)
         .option("--force", "With --copy, overwrite existing files in the destination.", false)
         .option("--dest <dir>", "With --copy, write into this directory instead of ./scenarios/.")
-        .description("Browse the bundled scenarios library (or copy a twin's scenarios into the local project)")
+        .description("Browse the bundled task library (or copy a twin's tasks into the local project)")
         .action(async (twin, opts) => {
         await runScenariosCommand(twin, {
             copy: opts.copy,
@@ -188,7 +193,7 @@ export function createProgram() {
     });
     program
         .command("compile-seeds")
-        .argument("[target]", "Scenario .md file or directory (defaults to ./scenarios)")
+        .argument("[target]", "Task .md file or directory (defaults to ./scenarios)")
         .option("--force", "Recompile even if the sidecar's source hash matches", false)
         .option("--hosted", "Compile via the Pome control plane instead of calling Anthropic directly (uses your Pome API key; no ANTHROPIC_API_KEY needed)", false)
         .option("--api-url <url>", "Control-plane base URL (only relevant with --hosted).", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
@@ -202,22 +207,9 @@ export function createProgram() {
         if (code !== 0)
             process.exitCode = code;
     });
-    const skills = program
-        .command("skills")
-        .description("Manage the bundled pome agent skills (/pome-setup, /pome-test)");
-    skills
-        .command("install")
-        .description("Install /pome-setup and /pome-test into ~/.claude/skills/ (symlinked to this pome install by default)")
-        .option("--copy", "Copy each skill instead of symlinking (CI, Windows without symlink permission)", false)
-        .option("--force", "Overwrite an existing install of the same skill", false)
-        .option("--dest <dir>", "Install into <dir> instead of ~/.claude/skills/ (testing and advanced users)")
-        .action(async (opts) => {
-        await runSkillsInstall({
-            copy: opts.copy,
-            force: opts.force,
-            dest: opts.dest,
-        });
-    });
+    // F-893 — `pome skills` / `pome skills install` retired. It only symlinked
+    // the two Gen-1 tombstone skills into ~/.claude/skills/; the Gen-2 coach set
+    // installs via `npx skills add pome-sh/digital-twins`.
     const register = program
         .command("register")
         .description("Register a cloud entity (agent, ...) and link this project to it");
@@ -225,9 +217,9 @@ export function createProgram() {
         .command("agent")
         .argument("<name>", "Human-readable agent name (e.g. \"triage-bot\")")
         .option("--api-url <url>", "Control-plane URL", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
-        .option("--force", "Overwrite an existing agentId in pome.config.json", false)
+        .option("--force", "Re-resolve the agent even when .pome/link.json already links one", false)
         .option("--twins <list>", "Comma-separated services this agent may exercise (e.g. github,slack). Default: the cloud's default enablement.")
-        .description("Create a cloud agent under the current team and write agentId to pome.config.json")
+        .description("Create a cloud agent under the current team and write agent.slug to pome.json")
         .action(async (name, opts) => {
         try {
             await runRegisterAgent({
@@ -248,7 +240,7 @@ export function createProgram() {
     session
         .command("create")
         .description("Create a hosted sandbox session for one or more twins and print its connection info")
-        .requiredOption("--twin <name>", "github | stripe | slack. Repeat the flag for a multi-twin session (e.g. --twin github --twin slack).", (value, previous = []) => [...previous, value])
+        .requiredOption("--twin <name>", "github | stripe | slack | gmail. Repeat the flag for a multi-twin session (e.g. --twin github --twin gmail).", (value, previous = []) => [...previous, value])
         .option("--api-url <url>", "Control-plane URL", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
         .option("--show-secrets", "Deprecated: secrets are never printed; use --secrets-file", false)
         .option("--secrets-file <path>", "Write shell exports containing session secrets to a local file with mode 0600")
@@ -327,7 +319,7 @@ export function createProgram() {
         .argument("[path]", 'Task markdown file or directory. Omit to run the demo task ("that was ours, run yours"): scenarios/first-run-demo.md is dropped into your project on first use with runs: 5 pinned.')
         .option("--agent <command>", "Agent command to run")
         .option("-n, --trials <count>", "FDRS-636: run <count> isolated trials of the task as ONE trial group (integer 1-20; hosted only). " +
-        "Default is the scenario config's `runs` field (capped at 20). k>1 mints sessions with a shared group id up to your " +
+        "Default is the task config's `runs` field (capped at 20). k>1 mints sessions with a shared group id up to your " +
         "plan's concurrent-twin quota (FDRS-663: remaining trials reuse slots as earlier trials finish), runs trials at that " +
         "concurrency, prints the per-trial verdict table (numeric cloud-judge scores), and exits 0 iff at least one " +
         "trial completed and every completed trial passed (1: a completed trial failed; 2: nothing completed). " +
@@ -339,6 +331,7 @@ export function createProgram() {
         .option("--hosted", "Deprecated: hosted is now the default. Flag is a no-op.")
         .option("--api-url <url>", "Control-plane base URL.", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
         .option("--agent-model <name>", "Informational; recorded on the cloud run.", "unknown")
+        .option("--agent-version <version>", "Override the manifest's agent.version for this run (stamped on the session/run).")
         .option("--no-capture", "Self-host only: skip spawning the capture-server child and don't inject HTTP_PROXY/HTTPS_PROXY into the agent. Used by the CI overhead gate (FDRS-405) to baseline proxy-on-vs-off latency. No-op on hosted runs.")
         .option("--local", "Self-host: run against an in-process twin and CAPTURE a raw trace only (an audit log — no score, no verdict, no judge). A verdict comes from the cloud: run `pome eval <run-dir>` on the captured trace, or `pome login` and run against Pome cloud.")
         .description('Run one or more Pome tasks. With no path, runs the demo task (scenarios/first-run-demo.md, copied into your project on first use — "that was ours, run yours"). Refuses to start if the doctor wiring checks fail (see `pome doctor`); there is no --force.')
@@ -396,10 +389,8 @@ export function createProgram() {
             process.exitCode = code;
             return;
         }
-        const configRead = await readProjectConfig(process.cwd());
-        const configCommand = configRead
-            ? normalizeConfigAgentCommand(configRead.config)
-            : undefined;
+        const manifestRead = await readManifest(process.cwd()).catch(() => null);
+        const configCommand = manifestRead?.manifest.command;
         const agentCommand = options.agent ?? configCommand ?? DEFAULT_AGENT_COMMAND;
         let worstExit = 0;
         // Hosted is the default. Self-host runs against an in-process twin via
@@ -496,7 +487,7 @@ export function createProgram() {
                             agentCommandSource: options.agent
                                 ? "--agent"
                                 : configCommand
-                                    ? "pome.config.json"
+                                    ? "pome.json"
                                     : "built-in default",
                             trials: k,
                             artifactsDir: options.artifactsDir,
@@ -506,6 +497,7 @@ export function createProgram() {
                             },
                             dashboardBaseUrl: process.env.POME_DASHBOARD_URL ?? DEFAULT_DASHBOARD_URL,
                             agentModel: options.agentModel,
+                            agentVersion: options.agentVersion,
                             rerunCommand,
                         });
                         if (groupResult.exitCode > worstExit) {
@@ -519,6 +511,7 @@ export function createProgram() {
                         artifactsDir: options.artifactsDir,
                         hosted: { baseUrl: hostedCreds.apiBaseUrl, apiKey: hostedCreds.apiKey },
                         agentModel: options.agentModel,
+                        agentVersion: options.agentVersion,
                     });
                     const status = scoreStatus(result.score, result.scenario.config.passThreshold);
                     const label = status === "pass" ? "PASS" : status === "fail" ? "FAIL" : "UNEVAL";
@@ -608,7 +601,7 @@ export function createProgram() {
     });
     program
         .command("doctor")
-        .description("Check the agent↔twin wiring: pome.config.json present + valid, twin reachable, requests routed to the twin (not a hardcoded production host), egress floor active. On failure prints one named cause (file:line where knowable) + one concrete fix and exits non-zero.")
+        .description("Check the agent↔twin wiring: pome.json (or pome.yaml) present + valid, twin reachable, requests routed to the twin (not a hardcoded production host), egress floor active. On failure prints one named cause (file:line where knowable) + one concrete fix and exits non-zero.")
         .action(async () => {
         const { runDoctorChecks } = await import("../doctor/checks.js");
         const { renderDoctorReport } = await import("../doctor/render.js");
@@ -620,10 +613,10 @@ export function createProgram() {
     });
     program
         .command("eval")
-        .argument("[run-dir]", "Existing run directory (runs/<scenario>/<run-id>). Omit to use <artifacts-dir>/latest.json.")
+        .argument("[run-dir]", "Existing run directory (runs/<task>/<run-id>). Omit to use <artifacts-dir>/latest.json.")
         .option("--artifacts-dir <dir>", "Directory whose latest.json picks the run when no run dir is given.", "runs")
-        .option("--agent <slug>", "Agent identity for the eval session. Defaults to agentSlug/agentId from pome.config.json.")
-        .option("--task <name>", "Task name recorded on the eval session. Defaults to meta.json's scenario slug (then title).")
+        .option("--agent <slug>", "Agent identity for the eval session. Defaults to agent.slug from pome.json.")
+        .option("--task <name>", "Task name recorded on the eval session. Defaults to meta.json's `scenario` slug (a legacy key name; then title).")
         .option("--api-url <url>", "Control-plane base URL.", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
         .description("Upload an existing raw trace directory to Pome cloud for evaluation and print the authoritative score (capture/eval split — no local scoring; requires a control plane with POST /v1/eval-sessions)")
         .action(async (runDir, opts) => {
@@ -676,15 +669,15 @@ export function createProgram() {
     });
     program
         .command("fix-prompt")
-        .argument("[target]", "Artifacts root or a trial run dir (default: runs). Legacy form: a path to events.jsonl — then <scenario> is required.")
-        .argument("[scenario]", "Path to scenario.md (only with an events.jsonl target)")
-        .description("Assemble a paste-into-IDE fix prompt (no LLM call, no network). With no args, reads the latest FAILED run set under ./runs: the persisted cloud verdicts (verdict.json) become grouped failure signatures over the raw traces, in one prompt. Point it at a trial run dir to target that set, or use the legacy `<events.jsonl> <scenario.md>` form for a single trace.")
+        .argument("[target]", "Artifacts root or a trial run dir (default: runs). Legacy form: a path to events.jsonl — then <task> is required.")
+        .argument("[task]", "Path to the task .md file (only with an events.jsonl target)")
+        .description("Assemble a paste-into-IDE fix prompt (no LLM call, no network). With no args, reads the latest FAILED run set under ./runs: the persisted cloud verdicts (verdict.json) become grouped failure signatures over the raw traces, in one prompt. Point it at a trial run dir to target that set, or use the legacy `<events.jsonl> <task.md>` form for a single trace.")
         .action(async (target, scenarioArg) => {
         // Legacy 2-arg form: <events.jsonl> <scenario.md> — unchanged
         // (CAPTURE-ONLY, FDRS-657: raw trace + declared criteria, no verdict).
         if (target !== undefined && target.endsWith(".jsonl")) {
             if (!scenarioArg) {
-                console.error("The events.jsonl form needs the scenario: pome fix-prompt <events.jsonl> <scenario.md>");
+                console.error("The events.jsonl form needs the task file: pome fix-prompt <events.jsonl> <task.md>");
                 process.exitCode = 5;
                 return;
             }
@@ -701,7 +694,7 @@ export function createProgram() {
             return;
         }
         if (scenarioArg !== undefined) {
-            console.error("The second argument only applies to the events.jsonl form: pome fix-prompt <events.jsonl> <scenario.md>");
+            console.error("The second argument only applies to the events.jsonl form: pome fix-prompt <events.jsonl> <task.md>");
             process.exitCode = 5;
             return;
         }
@@ -749,8 +742,8 @@ export function createProgram() {
     const twin = program.command("twin").description("Manage local twins");
     twin
         .command("start")
-        .argument("<name>", "Twin name (github | slack | stripe)")
-        .option("--port <port>", "Port to bind (default: $PORT or 3333)")
+        .argument("<name>", "Twin name (github | slack | stripe | gmail)")
+        .option("--port <port>", "Port to bind (default: $PORT, else GMAIL_TWIN_PORT/3336 for gmail, else 3333)")
         .description("Start a standalone twin as a long-lived foreground server (Ctrl-C to stop)")
         .action(async (name, options) => {
         const { runTwinStartCommand } = await import("../twin/twinStart.js");
@@ -758,13 +751,23 @@ export function createProgram() {
     });
     twin
         .command("reset")
+        .argument("[name]", "Twin name (default: github)", "github")
         .description("Reset standalone twin state")
-        .action(async () => {
-        await rm(".pome/github.db", { force: true });
-        await rm(".pome/github.db-wal", { force: true });
-        await rm(".pome/github.db-shm", { force: true });
+        .action(async (name) => {
+        const supported = new Set(["github", "slack", "stripe", "gmail"]);
+        if (!supported.has(name)) {
+            throw new Error(`Unknown twin '${name}'. Supported: ${[...supported].join(", ")}.`);
+        }
+        const dbPaths = name === "gmail"
+            ? [".pome/gmail.db", ".pome-data/gmail/gmail.db"]
+            : [`.pome/${name}.db`, `.pome-data/${name}/${name}.db`];
+        for (const dbPath of dbPaths) {
+            await rm(dbPath, { force: true });
+            await rm(`${dbPath}-wal`, { force: true });
+            await rm(`${dbPath}-shm`, { force: true });
+        }
         await rm(".pome/twin-status.json", { force: true });
-        console.log("Standalone GitHub twin state reset.");
+        console.log(`Standalone ${name} twin state reset.`);
     });
     twin
         .command("status")
@@ -781,9 +784,15 @@ export function createProgram() {
         .argument("<name>", "Twin name")
         .description("List supported endpoints")
         .action((name) => {
-        if (name !== "github")
-            throw new Error("Only the github twin exists in the MSP.");
-        for (const endpoint of SUPPORTED_GITHUB_ENDPOINTS) {
+        const endpoints = name === "github"
+            ? SUPPORTED_GITHUB_ENDPOINTS
+            : name === "gmail"
+                ? SUPPORTED_GMAIL_ENDPOINTS
+                : null;
+        if (!endpoints) {
+            throw new Error("Endpoint listing is available for: github, gmail.");
+        }
+        for (const endpoint of endpoints) {
             console.log(`${endpoint}  semantic`);
         }
     });
@@ -845,6 +854,29 @@ const SUPPORTED_GITHUB_ENDPOINTS = [
     "GET /repos/:owner/:repo/collaborators",
     "POST /repos/:owner/:repo/issues/:number/assignees"
 ];
+const SUPPORTED_GMAIL_ENDPOINTS = [
+    "GET /gmail/v1/users/:userId/profile",
+    "GET|POST /gmail/v1/users/:userId/messages",
+    "GET|DELETE /gmail/v1/users/:userId/messages/:id",
+    "POST /gmail/v1/users/:userId/messages/{send,import,batchModify,batchDelete}",
+    "POST /gmail/v1/users/:userId/messages/:id/{modify,trash,untrash}",
+    "GET /gmail/v1/users/:userId/messages/:messageId/attachments/:id",
+    "GET|POST /gmail/v1/users/:userId/drafts",
+    "GET|PUT|DELETE /gmail/v1/users/:userId/drafts/:id",
+    "POST /gmail/v1/users/:userId/drafts/send",
+    "GET /gmail/v1/users/:userId/threads",
+    "GET|DELETE /gmail/v1/users/:userId/threads/:id",
+    "POST /gmail/v1/users/:userId/threads/:id/{modify,trash,untrash}",
+    "GET|POST /gmail/v1/users/:userId/labels",
+    "GET|PUT|PATCH|DELETE /gmail/v1/users/:userId/labels/:id",
+    "GET /gmail/v1/users/:userId/history",
+    "GET|POST /gmail/v1/users/:userId/settings/filters",
+    "GET|DELETE /gmail/v1/users/:userId/settings/filters/:id",
+    "GET /gmail/v1/users/:userId/settings/{forwardingAddresses,sendAs}",
+    "GET /gmail/v1/users/:userId/settings/forwardingAddresses/:email",
+    "GET /gmail/v1/users/:userId/settings/sendAs/:email",
+    "POST /upload/gmail/v1/users/:userId/{messages,drafts} (media|multipart)",
+];
 async function scenarioFiles(target) {
     const resolved = resolve(target);
     // F0-5a — surface bad-input paths as `HostedUsageError` so the top-level
@@ -852,7 +884,7 @@ async function scenarioFiles(target) {
     // of the default 2 ("twin/orch"). CI consumers branching on $? expect
     // 5 to mean "fix your command", not "retry the cloud".
     if (!existsSync(resolved)) {
-        throw new HostedUsageError(`Scenario path not found: ${target}`);
+        throw new HostedUsageError(`Task path not found: ${target}`);
     }
     const stat = await import("node:fs/promises").then((fs) => fs.stat(resolved));
     if (stat.isFile())

package/dist/src/cli/project-config.d.ts

@@ -1,27 +1,29 @@
-export declare const CONFIG_FILE = "pome.config.json";
-export interface ProjectConfig {
-    agent?: {
-        command?: unknown;
-        sdk?: unknown;
-        [key: string]: unknown;
-    };
-    agentId?: unknown;
-    agentSlug?: unknown;
-    [key: string]: unknown;
-}
-export interface ProjectConfigRead {
+import { type Manifest } from "@pome-sh/shared-types";
+export declare const MANIFEST_JSON = "pome.json";
+export declare const MANIFEST_YAML = "pome.yaml";
+export declare const MANIFEST_YML = "pome.yml";
+/** Discovery order is fixed; a directory carrying more than one is a hard
+ *  error (a repo must have exactly one manifest). */
+export declare const MANIFEST_FILES: readonly ["pome.json", "pome.yaml", "pome.yml"];
+export type ManifestFormat = "json" | "yaml";
+export interface ManifestLocation {
     path: string;
-    config: ProjectConfig;
+    format: ManifestFormat;
+}
+export interface ManifestRead extends ManifestLocation {
+    /** Validated + defaulted view — read fields off this. */
+    manifest: Manifest;
+    /** Pre-validation object, for format-preserving round-trip writes
+     *  (`pome register --force` must not drop unrelated top-level keys). */
+    raw: Record<string, unknown>;
 }
-export declare function findProjectConfigPath(startDir?: string): Promise<string | null>;
-export declare function readProjectConfig(startDir?: string): Promise<ProjectConfigRead | null>;
-export declare function readRequiredProjectConfig(startDir?: string): Promise<ProjectConfigRead>;
-export declare function writeProjectConfig(path: string, config: ProjectConfig): Promise<void>;
-export declare function normalizeConfigAgentId(config: ProjectConfig): string | undefined;
-/** FDRS-665 — the registered slug (written next to agentId by
- *  `pome register agent` / `pome install`). Server-canonical; treated as
- *  opaque here. Absent or malformed → undefined (the URL print falls back
- *  to the legacy /runs/task shape). */
-export declare function normalizeConfigAgentSlug(config: ProjectConfig): string | undefined;
-export declare function normalizeConfigAgentSdk(config: ProjectConfig): string | null;
-export declare function normalizeConfigAgentCommand(config: ProjectConfig): string | undefined;
+/** Walk up from `startDir` looking for a manifest. In each directory a single
+ *  manifest is required; two present (e.g. `pome.json` + `pome.yaml`) is a hard
+ *  error naming both files. Returns null when none is found up to the root. */
+export declare function findManifestPath(startDir?: string): Promise<ManifestLocation | null>;
+export declare function readManifest(startDir?: string): Promise<ManifestRead | null>;
+export declare function readRequiredManifest(startDir?: string): Promise<ManifestRead>;
+/** Serialize a manifest object to `path` in the given format. JSON is
+ *  pretty-printed with a trailing newline; YAML carries the schema pointer as a
+ *  language-server comment (the `$schema` key is dropped from the YAML body). */
+export declare function writeManifest(path: string, format: ManifestFormat, data: Record<string, unknown>): Promise<void>;