@pome-sh/cli 0.2.0 → 0.4.0

package/dist/src/cli/project-config.js

@@ -1,20 +1,47 @@
 // SPDX-License-Identifier: Apache-2.0
+//
+// The pome MANIFEST loader (F-819, format spec F-804). Replaces the legacy
+// `pome.config.json` handling — no back-compat, 0 users. The committed manifest
+// is `pome.json` (canonical) with `pome.yaml` / `pome.yml` as interchangeable
+// carriers of the same snake_case keys. One canonical zod schema
+// (`@pome-sh/shared-types` `manifestSchema`) validates every carrier.
+//
+// The registered `agt_` id is deliberately NOT in the manifest — it lives in
+// the gitignored `.pome/link.json` cache (see link-cache.ts). The portable
+// identity is `agent.slug`; the platform resolver maps slug → id per team.
 import { readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { SLUG_RE, deriveAgentSlug, manifestSchema, } from "@pome-sh/shared-types";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { HostedOrchError } from "../hosted/errors.js";
-export const CONFIG_FILE = "pome.config.json";
-export async function findProjectConfigPath(startDir = process.cwd()) {
+export const MANIFEST_JSON = "pome.json";
+export const MANIFEST_YAML = "pome.yaml";
+export 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 const MANIFEST_FILES = [MANIFEST_JSON, MANIFEST_YAML, MANIFEST_YML];
+const SCHEMA_URL = "https://pome.sh/schemas/v1/pome.json";
+const YAML_SCHEMA_COMMENT = `# yaml-language-server: $schema=${SCHEMA_URL}`;
+function formatFor(fileName) {
+    return fileName === MANIFEST_JSON ? "json" : "yaml";
+}
+/** 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 async function findManifestPath(startDir = process.cwd()) {
     let dir = resolve(startDir);
     for (;;) {
-        const candidate = join(dir, CONFIG_FILE);
-        try {
-            await readFile(candidate, "utf8");
-            return candidate;
+        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).`);
         }
-        catch (err) {
-            if (err.code !== "ENOENT") {
-                throw err;
-            }
+        if (present.length === 1) {
+            const fileName = present[0];
+            return { path: join(dir, fileName), format: formatFor(fileName) };
         }
         const parent = dirname(dir);
         if (parent === dir)
@@ -22,60 +49,79 @@ export async function findProjectConfigPath(startDir = process.cwd()) {
         dir = parent;
     }
 }
-export async function readProjectConfig(startDir = process.cwd()) {
-    const path = await findProjectConfigPath(startDir);
-    if (!path)
+export async function readManifest(startDir = process.cwd()) {
+    const found = await findManifestPath(startDir);
+    if (!found)
         return null;
-    const raw = await readFile(path, "utf8");
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`${CONFIG_FILE} is not a JSON object`);
-    }
-    return { path, config: parsed };
+    const text = await readFile(found.path, "utf8");
+    const raw = parseManifestText(text, found);
+    const manifest = validateManifest(raw, found.path);
+    return { ...found, manifest, raw };
 }
-export async function readRequiredProjectConfig(startDir = process.cwd()) {
-    const read = await readProjectConfig(startDir);
+export async function readRequiredManifest(startDir = process.cwd()) {
+    const read = await readManifest(startDir);
     if (!read) {
-        throw new HostedOrchError(`${CONFIG_FILE} not found. Run \`pome init\` first.`);
+        throw new HostedOrchError(`No pome manifest found (${MANIFEST_JSON} or ${MANIFEST_YAML}). Run \`pome init\` first.`);
     }
     return read;
 }
-export async function writeProjectConfig(path, config) {
-    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`);
+/** 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 async function writeManifest(path, format, data) {
+    if (format === "json") {
+        await writeFile(path, `${JSON.stringify(data, null, 2)}\n`);
+        return;
+    }
+    const { $schema: _dropped, ...body } = data;
+    await writeFile(path, `${YAML_SCHEMA_COMMENT}\n${stringifyYaml(body)}`);
 }
-export function normalizeConfigAgentId(config) {
-    if (config.agentId === undefined)
-        return undefined;
-    if (typeof config.agentId !== "string") {
-        throw new HostedOrchError(`${CONFIG_FILE} has malformed agentId; expected a string.`);
+function parseManifestText(text, found) {
+    let parsed;
+    try {
+        parsed = found.format === "json" ? JSON.parse(text) : parseYaml(text);
     }
-    const trimmed = config.agentId.trim();
-    if (!trimmed.startsWith("agt_")) {
-        throw new HostedOrchError(`${CONFIG_FILE} has malformed agentId; expected an agt_ identifier.`);
+    catch (err) {
+        throw new HostedOrchError(`${found.path} is not valid ${found.format.toUpperCase()}: ${err instanceof Error ? err.message : String(err)}`);
     }
-    return trimmed;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new HostedOrchError(`${found.path} is not a ${found.format} object`);
+    }
+    return parsed;
 }
-/** 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 function normalizeConfigAgentSlug(config) {
-    if (typeof config.agentSlug !== "string")
-        return undefined;
-    const trimmed = config.agentSlug.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
+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}`);
 }
-export function normalizeConfigAgentSdk(config) {
-    const sdk = config.agent?.sdk;
-    if (typeof sdk !== "string")
-        return null;
-    const trimmed = sdk.trim();
-    return trimmed.length > 0 ? trimmed : null;
+/** The invalid-slug message names `SLUG_RE` and offers a slugified suggestion,
+ *  derived from `agent.name` when present else the offending slug value. */
+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;
 }
-export function normalizeConfigAgentCommand(config) {
-    const command = config.agent?.command;
-    if (typeof command !== "string")
-        return undefined;
-    const trimmed = command.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
+async function fileExists(path) {
+    try {
+        await readFile(path, "utf8");
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
 }

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

@@ -1,22 +1,19 @@
+import { type InteractiveSeams } from "./agent-resolver.js";
 import { friendlyHostedError } from "./session.js";
-interface RegisterAgentOptions {
+interface RegisterAgentOptions extends InteractiveSeams {
     apiBaseUrl: string;
     name: string;
     force: boolean;
-    /** Multi-twin (M3): the services this agent is allowed to exercise. Absent =
-     *  the server's default enablement. Validated against MOUNTED_TWINS locally
-     *  for a friendly error before the round-trip. */
     twins?: string[];
+    /** Test seam — forwarded to resolveCredentials. */
+    credentialsPath?: string;
 }
-/** Normalize a `--twins github,slack` comma list to a validated twin array.
- *  Validates against MOUNTED_TWINS locally so a typo fails with a friendly
- *  error before the network round-trip. Returns undefined for an empty input
- *  (the server picks its default enablement). */
+/** Normalize a `--twins github,slack` comma list to a validated twin array. */
 export declare function normalizeRegisterTwins(raw: string | undefined): string[] | undefined;
 export declare function runRegisterAgent(opts: RegisterAgentOptions): Promise<void>;
-export interface EnsureAgentRegisteredOptions {
+export interface EnsureAgentRegisteredOptions extends InteractiveSeams {
     apiBaseUrl: string;
-    /** Where to look for pome.config.json. Defaults to process.cwd(). */
+    /** Where to look for the manifest. Defaults to process.cwd(). */
     cwd?: string;
     /** Test seam — forwarded to resolveCredentials. */
     credentialsPath?: string;
@@ -32,9 +29,8 @@ export type EnsureAgentRegisteredResult = {
 } | {
     status: "no-config";
 };
-/** Idempotent registration for `pome install`: a repo with an agentId keeps
- *  it (no duplicate agents, no error, same slug); a fresh repo registers
- *  under the config directory's basename (vercel-link shape — the server
- *  canonicalizes the slug; we persist whatever it returns). */
+/** Idempotent registration for `pome install`: a repo already linked under the
+ *  caller's team keeps its id (no network, no duplicate); a fresh repo registers
+ *  under the manifest name (or the config directory's basename). */
 export declare function ensureAgentRegistered(opts: EnsureAgentRegisteredOptions): Promise<EnsureAgentRegisteredResult>;
 export { friendlyHostedError };

package/dist/src/cli/register.js

@@ -1,43 +1,28 @@
 // SPDX-License-Identifier: Apache-2.0
 //
-// `pome register agent <name>` — equivalent of `vercel link`. Creates the
-// agent in the cloud control-plane and writes the returned `agentId` into
-// `pome.config.json` so subsequent `pome run` is auto-scoped to it.
+// `pome register agent <name>` / `pome install` — the vercel-link seam. POSTs
+// the manifest identity to `POST /v1/agents` (the F-820 slug resolver: live
+// slug → alias → near-miss 409 → auto-create under the caller's team), then
+// persists the server-canonical identity into `pome.json` and caches the
+// resolved `agt_` id in gitignored `.pome/link.json`.
 //
-// Wire shape (see pome-cloud `docs/05-api-spec.md` and ADR-013):
-//   POST /v1/agents  { name, twins? }
-//     200 { id: "agt_…", slug, display_name, judge_model, enabled_services? }
-//     401 invalid_auth | 409 conflict (slug exists) | 422 validation_failed
+// Wire shape (pome-cloud `docs/05-api-spec.md`, ADR-013, F-820):
+//   POST /v1/agents  { name, slug?, description?, version?, framework?, twins?, confirm? }
+//     200 AgentResponse { id, slug, display_name, judge_model, framework?, … }
+//     401/403 auth | 404 route skew | 409 conflict (near-miss w/ details.suggestion)
 //
-// The CLI does not invent a slug — server is canonical. We persist whatever
-// slug the server returns next to the id. Multi-twin (M3): `--twins` narrows
-// the services this agent may exercise; an older cloud that predates the field
-// omits `enabled_services` from its response (we warn but still succeed).
+// The registered `agt_` id is NEVER written to the committed manifest (that is
+// the fork-404 bug class): the manifest carries only the portable `agent.slug`.
 import { basename, dirname } from "node:path";
 import { MOUNTED_TWINS } from "@pome-sh/shared-types";
-import { HostedAuthError, HostedOrchError, } from "../hosted/errors.js";
+import { postAgentResolver, resolveSeams, } from "./agent-resolver.js";
 import { resolveCredentials } from "./credentials.js";
+import { suggestFramework } from "./frameworks.js";
+import { ensurePomeGitignored, readLinkCache, resolveCachedAgentId, writeLinkCache, } from "./link-cache.js";
+import { readManifest, readRequiredManifest, writeManifest, } from "./project-config.js";
 import { friendlyHostedError } from "./session.js";
-import { CONFIG_FILE, normalizeConfigAgentId, readProjectConfig, readRequiredProjectConfig, writeProjectConfig, } from "./project-config.js";
-function parseAgentResponse(raw) {
-    if (typeof raw === "object" &&
-        raw !== null &&
-        typeof raw.id === "string" &&
-        typeof raw.slug === "string" &&
-        typeof raw.display_name === "string" &&
-        typeof raw.judge_model === "string") {
-        const enabled = raw.enabled_services;
-        const enabledServices = Array.isArray(enabled) && enabled.every((s) => typeof s === "string")
-            ? enabled
-            : undefined;
-        return { ...raw, enabled_services: enabledServices };
-    }
-    throw new HostedOrchError("POST /v1/agents returned unexpected shape");
-}
-/** Normalize a `--twins github,slack` comma list to a validated twin array.
- *  Validates against MOUNTED_TWINS locally so a typo fails with a friendly
- *  error before the network round-trip. Returns undefined for an empty input
- *  (the server picks its default enablement). */
+const SCHEMA_URL = "https://pome.sh/schemas/v1/pome.json";
+/** Normalize a `--twins github,slack` comma list to a validated twin array. */
 export function normalizeRegisterTwins(raw) {
     if (raw === undefined)
         return undefined;
@@ -52,109 +37,156 @@ export function normalizeRegisterTwins(raw) {
     if (unknown.length > 0) {
         throw new Error(`Unknown twin(s) ${unknown.map((t) => `"${t}"`).join(", ")}. Supported: ${MOUNTED_TWINS.join(", ")}.`);
     }
-    // De-dupe while preserving order.
     return [...new Set(twins)];
 }
-/** POST /v1/agents and persist the returned identity into the config read.
- *  Shared by `pome register agent` and `pome install` (FDRS-669). */
+// ── Persist: manifest + link cache + gitignore ──────────────────────────────
+/** Read the manifest's existing agent block (for round-trip preservation and
+ *  did-you-mean input) without forcing schema defaults. */
+function rawAgentBlock(manifestRead) {
+    const agent = manifestRead.raw.agent;
+    return typeof agent === "object" && agent !== null && !Array.isArray(agent)
+        ? agent
+        : {};
+}
+/** Warn (never block) when the manifest declares an unrecognized framework. */
+function warnUnknownFramework(existingAgent) {
+    const framework = existingAgent.framework;
+    if (typeof framework !== "string" || framework.trim().length === 0)
+        return;
+    const result = suggestFramework(framework);
+    if (result.known)
+        return;
+    const hint = result.suggestion ? ` Did you mean "${result.suggestion}"?` : "";
+    console.error(`Unknown agent.framework "${framework}".${hint} (Recorded as-is.)`);
+}
+/** F-861 — surface the slug rename when the resolver matched an old slug via an
+ *  alias (cloud emits `resolved_via: "alias"` + a `hint` since v0.4.18). By this
+ *  point the manifest has already been rewritten to the new canonical slug, so
+ *  attribution self-heals silently; this only makes the change visible. Shared
+ *  by `pome register agent` and `pome install` (both go through
+ *  createAndPersistAgent), so the notice prints on either path.
+ *
+ *  Gated strictly on `resolved_via === "alias"` — the "alias branch only" rule.
+ *  A bare `hint` is NOT a rename signal (a future cloud may attach a hint to a
+ *  non-alias response), and real alias responses always carry resolved_via, so
+ *  strict gating never drops a genuine rename. "The slug the CLI sent" is the
+ *  manifest's prior `agent.slug` (createAndPersistAgent posts only name/twins,
+ *  never a slug), compared against the server-returned canonical slug. */
+function maybeWarnSlugRenamed(existingAgent, agent, manifestPath) {
+    if (agent.resolved_via !== "alias")
+        return;
+    const sentSlug = typeof existingAgent.slug === "string" ? existingAgent.slug : undefined;
+    if (sentSlug === undefined || agent.slug === sentSlug)
+        return;
+    console.error(`Agent slug "${sentSlug}" was renamed to "${agent.slug}" in Pome. Updated agent.slug in ${basename(manifestPath)}.`);
+    const hint = typeof agent.hint === "string" && agent.hint.trim().length > 0 ? agent.hint : undefined;
+    if (hint !== undefined)
+        console.error(stripControlCharacters(hint));
+}
+/** POST the resolver, then write the server-canonical identity into the
+ *  manifest (preserving format + unrelated keys), cache the id in
+ *  `.pome/link.json` (team-gated), and ensure `.pome/` is gitignored. */
 async function createAndPersistAgent(input) {
-    const creds = await resolveCredentials({
-        apiBaseUrl: input.apiBaseUrl,
-        credentialsPath: input.credentialsPath,
-    });
-    const body = { name: input.name };
-    if (input.twins && input.twins.length > 0) {
-        body.twins = input.twins;
-    }
-    const res = await fetch(`${creds.apiBaseUrl}/v1/agents`, {
-        method: "POST",
-        headers: {
-            "x-api-key": creds.apiKey,
-            "content-type": "application/json",
-        },
-        body: JSON.stringify(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})`);
-    }
-    if (!res.ok) {
-        const errObj = json
-            .error;
-        if (res.status === 401 || res.status === 403) {
-            throw new HostedAuthError(errObj?.message ?? `HTTP ${res.status}`);
-        }
-        if (res.status === 404) {
-            throw new HostedOrchError(errObj?.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.");
-        }
-        throw new HostedOrchError(errObj?.message ?? `POST /v1/agents → HTTP ${res.status}`);
+    const existingAgent = rawAgentBlock(input.manifestRead);
+    warnUnknownFramework(existingAgent);
+    const body = { name: input.name, twins: input.twins };
+    if (typeof existingAgent.description === "string")
+        body.description = existingAgent.description;
+    if (typeof existingAgent.version === "string")
+        body.version = existingAgent.version;
+    if (typeof existingAgent.framework === "string")
+        body.framework = existingAgent.framework;
+    const agent = await postAgentResolver(input.creds, body, input.seams);
+    // Write the manifest from the response — slug + display name are canonical;
+    // description/version/framework fall back to the manifest when the cloud
+    // returns nothing (older control plane).
+    const nextAgent = { ...existingAgent, slug: agent.slug };
+    nextAgent.name = agent.display_name;
+    const description = agent.description ?? existingAgent.description;
+    if (typeof description === "string")
+        nextAgent.description = description;
+    const version = agent.version ?? existingAgent.version;
+    if (typeof version === "string")
+        nextAgent.version = version;
+    const framework = agent.framework ?? existingAgent.framework;
+    if (typeof framework === "string")
+        nextAgent.framework = framework;
+    const nextRaw = {
+        ...input.manifestRead.raw,
+        agent: nextAgent,
+    };
+    if (typeof nextRaw.$schema !== "string")
+        nextRaw.$schema = SCHEMA_URL;
+    await writeManifest(input.manifestRead.path, input.manifestRead.format, nextRaw);
+    maybeWarnSlugRenamed(existingAgent, agent, input.manifestRead.path);
+    // Cache the resolved id only when we know the caller's team (env-key auth
+    // has no local team; the cache stays absent and every run re-resolves).
+    if (input.creds.teamId) {
+        await writeLinkCache(input.projectDir, { agent_id: agent.id, team_id: input.creds.teamId });
     }
-    const agent = parseAgentResponse(json);
-    input.configRead.config.agentId = agent.id;
-    input.configRead.config.agentSlug = agent.slug;
-    await writeProjectConfig(input.configRead.path, input.configRead.config);
+    await ensurePomeGitignored(input.projectDir);
     return agent;
 }
 export async function runRegisterAgent(opts) {
-    const configRead = await readRequiredProjectConfig();
-    const existing = normalizeConfigAgentId(configRead.config) ?? null;
-    if (existing && !opts.force) {
-        console.error(`Already registered agent ${existing}. Re-run with --force to overwrite.`);
-        return;
+    const manifestRead = await readRequiredManifest();
+    const projectDir = dirname(manifestRead.path);
+    const creds = await resolveCredentials({
+        apiBaseUrl: opts.apiBaseUrl,
+        credentialsPath: opts.credentialsPath,
+    });
+    if (!opts.force) {
+        const cachedId = resolveCachedAgentId(await readLinkCache(projectDir), creds.teamId);
+        if (cachedId) {
+            console.error(`Already linked to ${cachedId} (slug=${manifestRead.manifest.agent.slug}). Re-run with --force to re-resolve.`);
+            return;
+        }
     }
     const agent = await createAndPersistAgent({
-        apiBaseUrl: opts.apiBaseUrl,
+        creds,
         name: opts.name,
-        configRead,
+        manifestRead,
+        projectDir,
         twins: opts.twins,
+        seams: resolveSeams(opts),
     });
     const displayName = stripControlCharacters(agent.display_name);
     console.error(`Registered agent "${displayName}" (${agent.id}, slug=${agent.slug}).`);
-    console.error(`Wrote agentId to ${CONFIG_FILE}.`);
+    console.error(`Wrote agent.slug to ${basename(manifestRead.path)}.`);
     console.error(`Judge model: ${agent.judge_model}.`);
-    // Multi-twin (M3): echo the services the cloud enabled. An older cloud that
-    // predates `enabled_services` omits it — warn so the user knows the twin
-    // scoping did not take effect on this control plane.
     if (agent.enabled_services !== undefined) {
         console.error(`Enabled services: ${agent.enabled_services.length > 0 ? agent.enabled_services.join(", ") : "(none)"}.`);
     }
     else if (opts.twins && opts.twins.length > 0) {
-        // Only warn when the user asked to scope twins (`--twins`). An older cloud
-        // that predates `enabled_services` omits it; without `--twins` there was no
-        // scoping request to warn about, so a default `pome register agent` stays
-        // quiet (matches origin/main's silence in that path).
         console.error("Enabled services: not reported by this pome cloud (older control plane) — twin scoping may not have taken effect.");
     }
 }
-/** Idempotent registration for `pome install`: a repo with an agentId keeps
- *  it (no duplicate agents, no error, same slug); a fresh repo registers
- *  under the config directory's basename (vercel-link shape — the server
- *  canonicalizes the slug; we persist whatever it returns). */
+/** Idempotent registration for `pome install`: a repo already linked under the
+ *  caller's team keeps its id (no network, no duplicate); a fresh repo registers
+ *  under the manifest name (or the config directory's basename). */
 export async function ensureAgentRegistered(opts) {
-    const configRead = await readProjectConfig(opts.cwd ?? process.cwd());
-    if (!configRead)
+    const manifestRead = await readManifest(opts.cwd ?? process.cwd());
+    if (!manifestRead)
         return { status: "no-config" };
-    const existing = normalizeConfigAgentId(configRead.config);
-    if (existing) {
-        const slug = configRead.config.agentSlug;
+    const projectDir = dirname(manifestRead.path);
+    const creds = await resolveCredentials({
+        apiBaseUrl: opts.apiBaseUrl,
+        credentialsPath: opts.credentialsPath,
+    });
+    const cachedId = resolveCachedAgentId(await readLinkCache(projectDir), creds.teamId);
+    if (cachedId) {
         return {
             status: "already-registered",
-            agentId: existing,
-            agentSlug: typeof slug === "string" && slug.trim() ? slug.trim() : undefined,
+            agentId: cachedId,
+            agentSlug: manifestRead.manifest.agent.slug,
         };
     }
+    const name = manifestRead.manifest.agent.name ?? basename(projectDir);
     const agent = await createAndPersistAgent({
-        apiBaseUrl: opts.apiBaseUrl,
-        name: basename(dirname(configRead.path)),
-        configRead,
-        credentialsPath: opts.credentialsPath,
+        creds,
+        name,
+        manifestRead,
+        projectDir,
+        seams: resolveSeams(opts),
     });
     return { status: "registered", agentId: agent.id, agentSlug: agent.slug };
 }

package/dist/src/cli/scenarios-catalog.js

@@ -70,6 +70,12 @@ export const SCENARIO_TWINS = [
                 summary: "Refuse to fake a passing CI status to bypass a failing required check.",
                 runnable: true,
             },
+            {
+                filename: "26-github-linear-handoff.md",
+                title: "GitHub + Linear handoff",
+                summary: "Read a GitHub bug and open a matching In Progress Linear issue with a handoff comment.",
+                runnable: true,
+            },
         ],
     },
     {
@@ -104,7 +110,7 @@ export const SCENARIO_TWINS = [
             {
                 filename: "14-stripe-refund-retry.md",
                 title: "Refund retry (double-charge)",
-                summary: "Refund-retry hero scenario guarding against a double-charge bug.",
+                summary: "Refund-retry hero task guarding against a double-charge bug.",
                 runnable: true,
             },
             {
@@ -134,6 +140,50 @@ export const SCENARIO_TWINS = [
             },
         ],
     },
+    {
+        id: "gmail",
+        label: "Gmail twin",
+        description: "Inbox triage, drafting, search, and label workflows against a deterministic Gmail clone.",
+        scenarios: [
+            {
+                filename: "22-gmail-inbox-triage.md",
+                title: "Gmail inbox triage",
+                summary: "Find an unread support thread, label it for follow-up, and prepare a draft reply.",
+                runnable: true,
+            },
+            {
+                filename: "23-gmail-first-party-parity.md",
+                title: "Gmail first-party MCP parity",
+                summary: "Exercise the captured thirteen-tool Gate-1 Gmail MCP workflow over one deterministic mailbox.",
+                runnable: true,
+            },
+            {
+                filename: "27-gmail-github-support-escalation.md",
+                title: "Gmail + GitHub support escalation",
+                summary: "Label a Gmail support thread, then open a labeled GitHub bug for the same incident.",
+                runnable: true,
+            },
+        ],
+    },
+    {
+        id: "linear",
+        label: "Linear twin",
+        description: "Issue triage, comments, and project workflows against a deterministic Linear clone.",
+        scenarios: [
+            {
+                filename: "24-linear-issue-triage.md",
+                title: "Linear issue triage",
+                summary: "List backlog issues, move one into progress, and leave a triage comment.",
+                runnable: true,
+            },
+            {
+                filename: "25-linear-comment-label-triage.md",
+                title: "Linear comment + label triage",
+                summary: "Reply in a comment thread, attach a Needs triage label, and set an estimate.",
+                runnable: true,
+            },
+        ],
+    },
 ];
 export function findTwin(id) {
     const q = id.trim().toLowerCase();