@pome-sh/cli 0.1.0 → 0.2.0

package/README.md

@@ -15,16 +15,15 @@ Run `pome --help` (or `pome help <command>`) for the CLI reference, and
 
 ## Install
 
-Until the first npm release ships, install from the GitHub source checkout:
-
 ```bash
-git clone --depth 1 https://github.com/pome-sh/pome-twins.git
-cd pome-twins/cli
-npm install        # installs deps + runs the `prepare` build
-npm install -g .
+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.
+
 ## Quickstart
 
 ```bash

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "package": "pome-sh",
-  "version": "0.1.0",
-  "git_sha": "aa4ca816d3a90491953220fa5e2a3f67ab968a17",
-  "build_time": "2026-07-10T13:24:30.193Z"
+  "version": "0.2.0",
+  "git_sha": "17b5b8731c3f6428580f76916d73f7328b3d3fcc",
+  "build_time": "2026-07-16T09:21:08.927Z"
 }

package/dist/src/cli/eval.js

@@ -26,9 +26,10 @@ import { HostedOrchError, HostedUsageError, exitCodeFor, } from "../hosted/error
 import { redactJsonl, scoreFromFinalizeResponse, uploadRunBlobs, } from "../hosted/uploadAndFinalize.js";
 import { readLatestRun, toTwinHttpEvent } from "../recorder/artifacts.js";
 import { redactEvent, redactSecrets } from "../recorder/redaction.js";
-import { markerFor, outcomeOf, runScoreLine, scoreCountsSummary, scoreStatus, } from "../hosted/evalResultView.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 { isLegacyEventRow } from "../types/shared.js";
 const EVAL_SESSION_FILE = "eval-session.json";
 // The eval command has no scenario file (and therefore no per-scenario
 // threshold); mirror `pome run`'s default binary gate.
@@ -248,15 +249,32 @@ export async function runEval(options) {
         });
     // Re-apply wrapping + redaction before anything leaves the machine.
     // events.jsonl and the state blobs are written pre-redacted (and
-    // pre-wrapped) by artifacts.ts, but `pome eval` also accepts
-    // hand-assembled dirs — redaction is idempotent, and toTwinHttpEvent
-    // passes rows that already carry a `kind` through untouched, so this is
-    // cheap insurance that exactly mirrors what the hosted runner uploads
-    // (cloud's FDRS-398 schema gate rejects raw legacy rows).
+    // pre-wrapped) by artifacts.ts, but `pome eval` also accepts hand-assembled
+    // dirs — redaction is idempotent, so this is cheap insurance that mirrors
+    // what the hosted runner uploads (cloud's FDRS-398 schema gate rejects raw
+    // legacy rows).
+    //
+    // Only LEGACY rows (pre-FDRS-398 — no `kind` discriminator) get wrapped into
+    // a TwinHttpEvent. Rows that already carry a `kind` (any union member —
+    // LlmTurnEvent, ToolUseEvent, LlmCallEvent, …) are preserved as-is: routing
+    // them through toTwinHttpEvent re-wraps every non-TwinHttpEvent kind,
+    // clobbering `kind` to "TwinHttpEvent" and setting event_id to an absent
+    // `request_id` (the pre-F-766 corruption bug).
     const eventsJsonl = artifacts.eventsJsonl
         .split("\n")
         .filter((line) => line.trim().length > 0)
-        .map((line) => JSON.stringify(redactEvent(toTwinHttpEvent(JSON.parse(line)))))
+        .map((line) => {
+        const parsed = JSON.parse(line);
+        // Already-kinded rows pass through unchanged (redacted). Only legacy
+        // rows are wrapped — and we do NOT re-validate kinded rows here: the
+        // original path never did, cloud's schema gate is the arbiter, and
+        // strict parsing would reject the intentionally-terse hand-assembled
+        // dirs `pome eval` also accepts.
+        const event = isLegacyEventRow(parsed)
+            ? toTwinHttpEvent(parsed)
+            : parsed;
+        return JSON.stringify(redactEvent(event));
+    })
         .join("\n") + "\n";
     const blobs = {
         eventsJsonl,
@@ -399,7 +417,7 @@ export async function runEvalCommand(runDirArg, opts) {
         if (result.score.results.length > 0) {
             console.error(`  criteria: ${scoreCountsSummary(result.score)}`);
             for (const criterionResult of result.score.results) {
-                console.error(`  ${markerFor(outcomeOf(criterionResult))} [${criterionResult.criterion.type}] ${criterionResult.criterion.text}`);
+                console.error(`  ${markerFor(outcomeOf(criterionResult))} ${criterionMarkerLabel(criterionResult.criterion)} ${criterionResult.criterion.text}${twinSkipSuffix(criterionResult)}`);
             }
         }
         if (result.reusedSession) {

package/dist/src/cli/init-sdk.d.ts

@@ -7,9 +7,6 @@ export interface ScaffoldResult {
     postInstallHint: string;
 }
 export declare function writeSdkScaffold(sdk: SupportedSdk): Promise<ScaffoldResult>;
-export declare class ClaudeSdkDeferredError extends Error {
-    constructor();
-}
 export declare class ClaudeManagedDeferredError extends Error {
     constructor();
 }

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

@@ -4,44 +4,137 @@
 // a minimal-but-runnable starter set so a Claude Agent SDK / OpenAI Agents /
 // other-framework user reaches a green hosted run in under five minutes.
 //
-// Both `claude` and `claude-managed` are deferral stubs right now:
-//   - `claude` scaffolds an import from `@pome-sh/adapter-claude-sdk`, which is
-//     held back from npm until OSS Launch Stage 1. Without the package, the
-//     scaffolded file dies at `pome run` with "Cannot find module …". Defer
-//     the flag until the publish unblocks it.
-//   - `claude-managed` is waiting on Anthropic's Managed Agents API (v2).
-// Add new SDKs by appending a writer in SCAFFOLDS below.
-//
-// See the Claude Agent SDK integration plan (internal docs).
+// `claude-managed` remains deferred (waiting on Anthropic's Managed Agents API).
+// Add new SDKs by appending a case in writeSdkScaffold below.
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 export const SUPPORTED_SDKS = ["claude", "claude-managed"];
+const CLAUDE_SDK_AGENT_RELATIVE = "examples/agents/claude-sdk-agent.ts";
+const CLAUDE_SDK_AGENT_SOURCE = `\
+// SPDX-License-Identifier: Apache-2.0
+//
+// Scaffolded by \`pome init --sdk claude\`. Minimal Claude Agent SDK starter
+// wired through @pome-sh/adapter-claude-sdk so \`pome run\` captures adapter
+// signals. Swap the tool body for your own agent logic.
+
+import { createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { query, tool, withPome } from "@pome-sh/adapter-claude-sdk";
+import { z } from "zod";
+
+withPome();
+
+const restUrl = process.env.POME_GITHUB_REST_URL;
+const authToken = process.env.POME_AUTH_TOKEN;
+const task =
+  process.env.POME_TASK?.trim() ||
+  "List open issues in acme/api and summarize their titles.";
+
+if (!restUrl) {
+  throw new Error(
+    "POME_GITHUB_REST_URL is required (injected by \`pome run\`, or set it when driving a twin yourself).",
+  );
+}
+
+if (process.env.POME_PREFLIGHT === "1") {
+  const res = await fetch(\`\${restUrl.replace(/\\/+$/, "")}/rate_limit\`, {
+    headers: {
+      accept: "application/vnd.github+json",
+      ...(authToken ? { authorization: \`Bearer \${authToken}\` } : {}),
+    },
+  });
+  if (!res.ok) {
+    throw new Error(\`preflight failed: HTTP \${res.status}\`);
+  }
+  console.log("preflight ok");
+  process.exit(0);
+}
+
+const listOpenIssues = tool(
+  "list_open_issues",
+  "List open issues on the GitHub twin for owner/repo.",
+  {
+    owner: z.string(),
+    repo: z.string(),
+  },
+  async ({ owner, repo }) => {
+    const res = await fetch(
+      \`\${restUrl.replace(/\\/+$/, "")}/repos/\${owner}/\${repo}/issues?state=open\`,
+      {
+        headers: {
+          accept: "application/vnd.github+json",
+          ...(authToken ? { authorization: \`Bearer \${authToken}\` } : {}),
+        },
+      },
+    );
+    const body = await res.text();
+    if (!res.ok) {
+      return {
+        content: [{ type: "text" as const, text: \`HTTP \${res.status}: \${body}\` }],
+        isError: true,
+      };
+    }
+    return { content: [{ type: "text" as const, text: body }] };
+  },
+);
+
+const server = createSdkMcpServer({
+  name: "github-twin",
+  version: "0.1.0",
+  tools: [listOpenIssues],
+});
+
+for await (const message of query({
+  prompt: task,
+  options: {
+    permissionMode: "bypassPermissions",
+    maxTurns: 10,
+    allowedTools: ["list_open_issues"],
+    mcpServers: {
+      "github-twin": {
+        type: "sdk",
+        name: "github-twin",
+        instance: server.instance,
+      },
+    },
+  },
+})) {
+  if (message.type === "result" && message.subtype === "success" && message.result) {
+    console.log(message.result);
+  }
+}
+`;
 export async function writeSdkScaffold(sdk) {
     switch (sdk) {
         case "claude":
-            // Deferred — the scaffolded file imports `@pome-sh/adapter-claude-sdk`,
-            // which is held back from npm until OSS Launch Stage 1. Until then the
-            // scaffold dies at runtime with "Cannot find module …". Recommend the
-            // bundled scripted starter (`pome init` without --sdk) for now.
-            throw new ClaudeSdkDeferredError();
+            return writeClaudeSdkScaffold();
         case "claude-managed":
-            // Deferred — surface reserved so v2 doesn't churn the flag.
             throw new ClaudeManagedDeferredError();
     }
 }
-export class ClaudeSdkDeferredError extends Error {
-    constructor() {
-        super("Claude Agent SDK scaffold is gated on the npm publish of " +
-            "`@pome-sh/adapter-claude-sdk`, tracked under OSS Launch Stage 1. " +
-            "Run `pome init` (without --sdk) for the bundled scripted starter, " +
-            "or write your own agent against POME_TASK / POME_GITHUB_REST_URL.");
-        this.name = "ClaudeSdkDeferredError";
-    }
+async function writeClaudeSdkScaffold() {
+    const path = join(process.cwd(), CLAUDE_SDK_AGENT_RELATIVE);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, CLAUDE_SDK_AGENT_SOURCE, "utf8");
+    return {
+        agentSdkValue: "claude",
+        agentCommand: `npx tsx ${CLAUDE_SDK_AGENT_RELATIVE}`,
+        exampleAgentRelativePath: CLAUDE_SDK_AGENT_RELATIVE,
+        postInstallHint: "Next steps:\n" +
+            "  1. npm install @pome-sh/adapter-claude-sdk @anthropic-ai/claude-agent-sdk zod\n" +
+            "  2. pome login\n" +
+            "  3. pome register agent <name>\n" +
+            "  4. pome run scenarios/01-bug-happy-path.md\n" +
+            "\n" +
+            "See `pome docs getting-started` for a narrative walkthrough.",
+    };
 }
 export class ClaudeManagedDeferredError extends Error {
     constructor() {
         super("Claude Managed Agent is not yet supported — three blockers " +
             "(no injection point inside Anthropic-hosted runtime, no sidechannel " +
             "for adapter signals, Managed Agents API still moving). Follow the " +
-            "tracking issue for v2 timing. For now, use `pome init` (without --sdk).");
+            "tracking issue for v2 timing. For now, use `pome init` (without --sdk) " +
+            "or `pome init --sdk claude`.");
         this.name = "ClaudeManagedDeferredError";
     }
 }

package/dist/src/cli/main.js

@@ -1,13 +1,10 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: Apache-2.0
-import { serve } from "@hono/node-server";
 import { Command } from "commander";
-import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readdir, readFile, rm } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { sign } from "hono/jwt";
 import { readLatestRun, readMetaSummary, } from "../recorder/artifacts.js";
 import { LEGACY_EVENTS_MESSAGE, computeTraceHealth, readEventsJsonl, renderEvents, renderTraceHealth, } from "../recorder/inspect.js";
 import { runScenario } from "../runner/runScenario.js";
@@ -25,12 +22,12 @@ 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";
-import { runRegisterAgent } from "./register.js";
+import { normalizeRegisterTwins, runRegisterAgent } from "./register.js";
 import { resolvePackageRoot } from "./resolve-package-root.js";
-import { ClaudeManagedDeferredError, ClaudeSdkDeferredError, writeSdkScaffold, } from "./init-sdk.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 { createGitHubCloneApp, openGitHubCloneDatabase, seedGitHubCloneDatabase } from "../twin/githubCloneAdapter.js";
+import { createGitHubCloneApp } from "../twin/githubCloneAdapter.js";
 import { buildFixPrompt, buildGroupFixPrompt, } from "../fix-prompt/index.js";
 import { discoverRunSet, loadTrialEvents, } from "../hosted/evalResultCache.js";
 import { parseScenarioFile } from "../scenario/parseScenario.js";
@@ -83,15 +80,6 @@ export function createProgram() {
             process.exitCode = 2;
             return;
         }
-        if (sdk === "claude") {
-            // Deferred until @pome-sh/adapter-claude-sdk publishes to npm
-            // (OSS Launch Stage 1). The scaffolded file would import a package
-            // that 404s on `npm install`. Mirror the claude-managed short-circuit:
-            // bail before touching the filesystem.
-            console.error(new ClaudeSdkDeferredError().message);
-            process.exitCode = 2;
-            return;
-        }
         await mkdir("scenarios", { recursive: true });
         await mkdir("examples/agents", { recursive: true });
         await mkdir("runs", { recursive: true });
@@ -106,29 +94,19 @@ export function createProgram() {
             "  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 (gated on @pome-sh/adapter-claude-sdk npm publish — see Stage 1)\n" +
+            "  - pome init --sdk claude         # scaffold a Claude Agent SDK starter\n" +
             "  - pome scenarios stripe --copy   # add Stripe payment scenarios when needed\n" +
             "\n" +
             "See `pome docs getting-started` for a narrative walkthrough.";
         if (sdk) {
-            try {
-                const scaffold = await writeSdkScaffold(sdk);
-                agentBlock = {
-                    sdk: scaffold.agentSdkValue,
-                    command: scaffold.agentCommand,
-                };
-                postInitMessage =
-                    `Pome initialized with --sdk ${sdk}. Scaffolded ${scaffold.exampleAgentRelativePath}.\n` +
-                        scaffold.postInstallHint;
-            }
-            catch (err) {
-                if (err instanceof ClaudeManagedDeferredError) {
-                    console.error(err.message);
-                    process.exitCode = 2;
-                    return;
-                }
-                throw err;
-            }
+            const scaffold = await writeSdkScaffold(sdk);
+            agentBlock = {
+                sdk: scaffold.agentSdkValue,
+                command: scaffold.agentCommand,
+            };
+            postInitMessage =
+                `Pome initialized with --sdk ${sdk}. Scaffolded ${scaffold.exampleAgentRelativePath}.\n` +
+                    scaffold.postInstallHint;
         }
         const existingConfig = await readProjectConfig(process.cwd());
         if (!existingConfig) {
@@ -248,6 +226,7 @@ export function createProgram() {
         .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("--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")
         .action(async (name, opts) => {
         try {
@@ -255,6 +234,7 @@ export function createProgram() {
                 apiBaseUrl: opts.apiUrl,
                 name,
                 force: opts.force,
+                twins: normalizeRegisterTwins(opts.twins),
             });
         }
         catch (err) {
@@ -267,8 +247,8 @@ export function createProgram() {
         .description("Hosted sandbox sessions (same API as the dashboard Twins page — requires login)");
     session
         .command("create")
-        .description("Create a hosted sandbox session for a twin and print its connection info")
-        .requiredOption("--twin <name>", "github | stripe")
+        .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])
         .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")
@@ -283,7 +263,7 @@ export function createProgram() {
             }
             await runSessionCreate({
                 apiBaseUrl: opts.apiUrl,
-                twin: opts.twin,
+                twins: opts.twin,
                 showSecrets: opts.showSecrets,
                 format: format,
                 secretsFile: opts.secretsFile,
@@ -769,38 +749,12 @@ export function createProgram() {
     const twin = program.command("twin").description("Manage local twins");
     twin
         .command("start")
-        .argument("<name>", "Twin name")
-        .option("--port <port>", "Port to bind", "3333")
-        .description("Start a standalone twin")
+        .argument("<name>", "Twin name (github | slack | stripe)")
+        .option("--port <port>", "Port to bind (default: $PORT or 3333)")
+        .description("Start a standalone twin as a long-lived foreground server (Ctrl-C to stop)")
         .action(async (name, options) => {
-        if (name !== "github")
-            throw new Error("Only the github twin exists in the MSP.");
-        await mkdir(".pome", { recursive: true });
-        const db = await openGitHubCloneDatabase(".pome/github.db");
-        await seedGitHubCloneDatabase(db);
-        const port = Number(options.port);
-        const app = (await createGitHubCloneApp({ db, runId: "standalone" }));
-        const baseUrl = `http://127.0.0.1:${port}`;
-        const restUrl = `${baseUrl}/s/standalone`;
-        const mcpUrl = `${restUrl}/mcp`;
-        const authSecret = process.env.TWIN_AUTH_SECRET ?? randomBytes(32).toString("hex");
-        process.env.TWIN_AUTH_SECRET = authSecret;
-        const token = await sign({ sid: "standalone", team_id: "tm_local", exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24 }, 
-        // The secret was just pinned into the env above; the ported twin no
-        // longer exports resolveAuthSecret (engine-owned, F-682).
-        authSecret);
-        serve({ fetch: app.fetch, port, hostname: "127.0.0.1" });
-        await writeFile(".pome/twin-status.json", JSON.stringify({ name, url: restUrl, rest_url: restUrl, mcp_url: mcpUrl, auth_token: token }, null, 2));
-        console.log(`Pome ${name} twin listening at ${restUrl}`);
-        console.log(`POME_GITHUB_REST_URL=${restUrl}`);
-        console.log(`POME_GITHUB_MCP_URL=${mcpUrl}`);
-        console.log(`POME_AUTH_TOKEN=${token}`);
-        // F28 — every `/s/<sid>/*` endpoint requires a Bearer JWT, including
-        // /s/standalone/healthz. New users curling the printed `${restUrl}`
-        // get HTTP 401 and assume the twin is broken. The unauth liveness
-        // probe lives at the root `/healthz`. Print the curl command so
-        // copy-paste debugging works without a JWT.
-        console.log(`Health check (no auth): curl ${baseUrl}/healthz`);
+        const { runTwinStartCommand } = await import("../twin/twinStart.js");
+        await runTwinStartCommand(name, options);
     });
     twin
         .command("reset")

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

@@ -3,7 +3,16 @@ interface RegisterAgentOptions {
     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[];
 }
+/** 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). */
+export declare function normalizeRegisterTwins(raw: string | undefined): string[] | undefined;
 export declare function runRegisterAgent(opts: RegisterAgentOptions): Promise<void>;
 export interface EnsureAgentRegisteredOptions {
     apiBaseUrl: string;

package/dist/src/cli/register.js

@@ -5,13 +5,16 @@
 // `pome.config.json` so subsequent `pome run` is auto-scoped to it.
 //
 // Wire shape (see pome-cloud `docs/05-api-spec.md` and ADR-013):
-//   POST /v1/agents  { name }
-//     200 { id: "agt_…", slug, display_name, judge_model }
+//   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
 //
 // The CLI does not invent a slug — server is canonical. We persist whatever
-// slug the server returns next to the id.
+// 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).
 import { basename, dirname } from "node:path";
+import { MOUNTED_TWINS } from "@pome-sh/shared-types";
 import { HostedAuthError, HostedOrchError, } from "../hosted/errors.js";
 import { resolveCredentials } from "./credentials.js";
 import { friendlyHostedError } from "./session.js";
@@ -23,10 +26,35 @@ function parseAgentResponse(raw) {
         typeof raw.slug === "string" &&
         typeof raw.display_name === "string" &&
         typeof raw.judge_model === "string") {
-        return raw;
+        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). */
+export function normalizeRegisterTwins(raw) {
+    if (raw === undefined)
+        return undefined;
+    const twins = raw
+        .split(",")
+        .map((t) => t.trim().toLowerCase())
+        .filter((t) => t.length > 0);
+    if (twins.length === 0)
+        return undefined;
+    const allowed = new Set(MOUNTED_TWINS);
+    const unknown = twins.filter((t) => !allowed.has(t));
+    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). */
 async function createAndPersistAgent(input) {
@@ -34,13 +62,17 @@ async function createAndPersistAgent(input) {
         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({ name: input.name }),
+        body: JSON.stringify(body),
     }).catch((err) => {
         throw new HostedOrchError(err instanceof Error ? err.message : "network error");
     });
@@ -81,11 +113,25 @@ export async function runRegisterAgent(opts) {
         apiBaseUrl: opts.apiBaseUrl,
         name: opts.name,
         configRead,
+        twins: opts.twins,
     });
     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(`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

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

@@ -1,6 +1,12 @@
+export declare function ensureMcpSuffix(url: string): string;
+/** Normalize one-or-more `--twin` flags into a validated, de-duped twin list.
+ *  Repeated flags stand up an ad-hoc multi-twin session; each is validated
+ *  against MOUNTED_TWINS for a friendly error before the round-trip. */
+export declare function normalizeSessionTwins(raw: string[]): string[];
 export declare function runSessionCreate(opts: {
     apiBaseUrl: string;
-    twin: string;
+    /** One-or-more twins. Repeated `--twin` flags stand up a multi-twin session. */
+    twins: string[];
     showSecrets: boolean;
     format: "text" | "json" | "env";
     secretsFile?: string;