@pome-sh/cli 0.1.1 → 0.3.0

package/dist/src/scenario/scenarioSchema.d.ts

@@ -114,9 +114,9 @@ export declare const seedStateSchema: z.ZodUnion<readonly [z.ZodObject<{
                 context: z.ZodDefault<z.ZodString>;
                 state: z.ZodDefault<z.ZodEnum<{
                     error: "error";
-                    success: "success";
                     failure: "failure";
                     pending: "pending";
+                    success: "success";
                 }>>;
                 description: z.ZodDefault<z.ZodString>;
             }, z.core.$strip>>>;
@@ -147,6 +147,104 @@ export declare const seedStateSchema: z.ZodUnion<readonly [z.ZodObject<{
         body: z.ZodUnknown;
     }, z.core.$strip>>>;
 }, z.core.$strict>]>;
+export declare const seedEnvelopeSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    team: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    users: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    channels: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strict>, z.ZodObject<{
+    users: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        login: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            User: "User";
+            Organization: "Organization";
+        }>>;
+        name: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>>;
+    repositories: z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodDefault<z.ZodString>;
+        private: z.ZodDefault<z.ZodBoolean>;
+        default_branch: z.ZodDefault<z.ZodString>;
+        collaborators: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        labels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            color: z.ZodDefault<z.ZodString>;
+            description: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>>;
+        files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            content: z.ZodString;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        issues: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            number: z.ZodOptional<z.ZodNumber>;
+            title: z.ZodString;
+            body: z.ZodDefault<z.ZodString>;
+            state: z.ZodDefault<z.ZodEnum<{
+                open: "open";
+                closed: "closed";
+            }>>;
+            labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            assignees: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+        pull_requests: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            number: z.ZodOptional<z.ZodNumber>;
+            title: z.ZodString;
+            body: z.ZodDefault<z.ZodString>;
+            head: z.ZodString;
+            base: z.ZodDefault<z.ZodString>;
+            state: z.ZodDefault<z.ZodEnum<{
+                open: "open";
+                closed: "closed";
+            }>>;
+            author: z.ZodOptional<z.ZodString>;
+            reviews: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                author: z.ZodString;
+                state: z.ZodDefault<z.ZodEnum<{
+                    APPROVED: "APPROVED";
+                    CHANGES_REQUESTED: "CHANGES_REQUESTED";
+                    COMMENTED: "COMMENTED";
+                }>>;
+                body: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>>;
+            statuses: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                context: z.ZodDefault<z.ZodString>;
+                state: z.ZodDefault<z.ZodEnum<{
+                    error: "error";
+                    failure: "failure";
+                    pending: "pending";
+                    success: "success";
+                }>>;
+                description: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    api_keys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodDefault<z.ZodString>;
+        sid: z.ZodDefault<z.ZodString>;
+        account_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    customers: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    products: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    prices: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    payment_intents: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    charges: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    events: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    balances: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    failure_injection: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        method: z.ZodString;
+        path: z.ZodString;
+        attempt: z.ZodNumber;
+        mode: z.ZodDefault<z.ZodEnum<{
+            before_handler: "before_handler";
+            after_handler: "after_handler";
+        }>>;
+        status: z.ZodNumber;
+        body: z.ZodUnknown;
+    }, z.core.$strip>>>;
+}, z.core.$strict>]>>;
 export declare const scenarioSchema: z.ZodObject<{
     slug: z.ZodString;
     title: z.ZodString;
@@ -161,6 +259,7 @@ export declare const scenarioSchema: z.ZodObject<{
             P: "P";
         }>, z.ZodTransform<"model" | "code", "model" | "code" | "D" | "P">>;
         text: z.ZodString;
+        twin: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     config: z.ZodObject<{
         twins: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -168,7 +267,7 @@ export declare const scenarioSchema: z.ZodObject<{
         runs: z.ZodDefault<z.ZodNumber>;
         passThreshold: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>;
-    seedState: z.ZodUnion<readonly [z.ZodObject<{
+    seedState: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
         team: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         users: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
         channels: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -233,9 +332,106 @@ export declare const scenarioSchema: z.ZodObject<{
                     context: z.ZodDefault<z.ZodString>;
                     state: z.ZodDefault<z.ZodEnum<{
                         error: "error";
+                        failure: "failure";
+                        pending: "pending";
                         success: "success";
+                    }>>;
+                    description: z.ZodDefault<z.ZodString>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        api_keys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodDefault<z.ZodString>;
+            sid: z.ZodDefault<z.ZodString>;
+            account_id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        customers: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        products: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        prices: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        payment_intents: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        charges: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        events: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        balances: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        failure_injection: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            method: z.ZodString;
+            path: z.ZodString;
+            attempt: z.ZodNumber;
+            mode: z.ZodDefault<z.ZodEnum<{
+                before_handler: "before_handler";
+                after_handler: "after_handler";
+            }>>;
+            status: z.ZodNumber;
+            body: z.ZodUnknown;
+        }, z.core.$strip>>>;
+    }, z.core.$strict>]>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        team: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        users: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        channels: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        users: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            login: z.ZodString;
+            type: z.ZodDefault<z.ZodEnum<{
+                User: "User";
+                Organization: "Organization";
+            }>>;
+            name: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>>;
+        repositories: z.ZodArray<z.ZodObject<{
+            owner: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodDefault<z.ZodString>;
+            private: z.ZodDefault<z.ZodBoolean>;
+            default_branch: z.ZodDefault<z.ZodString>;
+            collaborators: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            labels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                color: z.ZodDefault<z.ZodString>;
+                description: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>>;
+            files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                content: z.ZodString;
+                branch: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            issues: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                number: z.ZodOptional<z.ZodNumber>;
+                title: z.ZodString;
+                body: z.ZodDefault<z.ZodString>;
+                state: z.ZodDefault<z.ZodEnum<{
+                    open: "open";
+                    closed: "closed";
+                }>>;
+                labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                assignees: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>>;
+            pull_requests: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                number: z.ZodOptional<z.ZodNumber>;
+                title: z.ZodString;
+                body: z.ZodDefault<z.ZodString>;
+                head: z.ZodString;
+                base: z.ZodDefault<z.ZodString>;
+                state: z.ZodDefault<z.ZodEnum<{
+                    open: "open";
+                    closed: "closed";
+                }>>;
+                author: z.ZodOptional<z.ZodString>;
+                reviews: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    author: z.ZodString;
+                    state: z.ZodDefault<z.ZodEnum<{
+                        APPROVED: "APPROVED";
+                        CHANGES_REQUESTED: "CHANGES_REQUESTED";
+                        COMMENTED: "COMMENTED";
+                    }>>;
+                    body: z.ZodDefault<z.ZodString>;
+                }, z.core.$strip>>>;
+                statuses: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    context: z.ZodDefault<z.ZodString>;
+                    state: z.ZodDefault<z.ZodEnum<{
+                        error: "error";
                         failure: "failure";
                         pending: "pending";
+                        success: "success";
                     }>>;
                     description: z.ZodDefault<z.ZodString>;
                 }, z.core.$strip>>>;
@@ -265,7 +461,7 @@ export declare const scenarioSchema: z.ZodObject<{
             status: z.ZodNumber;
             body: z.ZodUnknown;
         }, z.core.$strip>>>;
-    }, z.core.$strict>]>;
+    }, z.core.$strict>]>>]>;
 }, z.core.$strip>;
 export type Criterion = z.infer<typeof criterionSchema>;
 export type ScenarioConfig = z.infer<typeof scenarioConfigSchema>;
@@ -274,4 +470,5 @@ export type StripeSeedState = z.infer<typeof stripeSeedStateSchema>;
 export type SlackSeedState = z.infer<typeof slackSeedStateSchema>;
 export type StripeFailureInjectionRule = z.infer<typeof stripeFailureInjectionRuleSchema>;
 export type SeedState = z.infer<typeof seedStateSchema>;
+export type SeedEnvelope = z.infer<typeof seedEnvelopeSchema>;
 export type Scenario = z.infer<typeof scenarioSchema>;

package/dist/src/scenario/scenarioSchema.js

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 import { seedSchema as githubSeedStateSchema } from "@pome-sh/twin-github";
-// Criterion kinds are owned by the published contract. `criterionSchema`
-// accepts the legacy `D`/`P` spellings and normalizes them to `code`/`model`,
-// so existing scenario files keep parsing. The former local `["D","P"]` fork is
+// Criterion kinds are owned by the published contract. The markdown marker
+// grammar is `[code]`/`[model]` (F-778); `criterionSchema`'s tolerant input
+// (legacy `D`/`P` enum values) exists only for 0.3.0-era persisted artifacts,
+// never for scenario markdown. The former local criterion-kind fork is
 // retired here (M6 — one published contract).
 import { criterionSchema } from "@pome-sh/shared-types";
 import { z } from "zod";
@@ -78,6 +79,14 @@ export const seedStateSchema = z.union([
     githubSeedStateSchema,
     stripeSeedStateSchema
 ]);
+// Multi-twin (M3): a per-twin seed envelope `{ <twin>: <flat seed> }`, produced
+// ONLY for scenarios whose `config.twins` has >1 entry (the envelope-iff-multi-twin
+// rule, decided from `twins` alone — never by sniffing the seed shape). Each value
+// is one twin's flat seed, the same shapes `seedStateSchema` unions. Single-twin
+// scenarios keep the flat shape byte-identical. parseScenario builds and validates
+// the envelope value-by-value with each twin's own schema; this record is the outer
+// shape scenarioSchema re-validates against.
+export const seedEnvelopeSchema = z.record(z.string(), seedStateSchema);
 export const scenarioSchema = z.object({
     slug: z.string().min(1),
     title: z.string().min(1),
@@ -86,5 +95,8 @@ export const scenarioSchema = z.object({
     expectedBehavior: z.string().default(""),
     criteria: z.array(criterionSchema).min(1),
     config: scenarioConfigSchema,
-    seedState: seedStateSchema
+    // Flat single-twin seed OR the multi-twin per-twin envelope. Flat is tried
+    // first so single-twin seeds match their strict arms; the envelope only
+    // matches when the flat union can't (its keys are twin ids, not seed fields).
+    seedState: z.union([seedStateSchema, seedEnvelopeSchema])
 });

package/dist/src/twin/twinHarness.d.ts

@@ -1,3 +1,4 @@
+import { type Recorder } from "../recorder/recorder.js";
 import type { RecorderEvent } from "@pome-sh/shared-types";
 export declare const STRIPE_LOCAL_ACCOUNT_ID = "acct_default";
 export type TwinHarness = {
@@ -7,7 +8,7 @@ export type TwinHarness = {
     };
     /** Uppercase env prefix: the agent reads `POME_<envName>_{REST,MCP}_URL`. */
     envName: string;
-    /** Twin state for `[D]` scoring (initial before the agent, final after). */
+    /** Twin state for `[code]` scoring (initial before the agent, final after). */
     exportState(): unknown | Promise<unknown>;
     /** Recorded twin HTTP events (shared buffer). */
     events(): RecorderEvent[];
@@ -37,4 +38,13 @@ export declare function bootTwin(opts: {
      * twin-core durable recorder (same file capture-server appends to).
      */
     eventsPath?: string;
+    /**
+     * Multi-twin (M3): a SHARED recorder so every twin harness in one local run
+     * buffers into a single events stream / events.jsonl. When provided, this
+     * harness does NOT own the recorder — `close()` releases only its DB handle
+     * and the caller is responsible for `flush()`/`close()` on the recorder. When
+     * omitted (single-twin), the harness creates and owns its own recorder, so
+     * `close()` flushes + closes it exactly as before.
+     */
+    recorder?: Recorder;
 }): Promise<TwinHarness>;

package/dist/src/twin/twinHarness.js

@@ -9,7 +9,7 @@
 // regardless of twin —
 //   - `app`         a Hono app (`.fetch`) the runner serves on a localhost port
 //   - `envName`     the `POME_<NAME>_{REST,MCP}_URL` prefix the agent reads
-//   - `exportState` initial/final twin state for deterministic `[D]` scoring
+//   - `exportState` initial/final twin state for deterministic `[code]` scoring
 //   - `events`      recorded twin HTTP events (one shared recorder buffer)
 //   - `close`       tear down the underlying SQLite handle
 //
@@ -37,13 +37,17 @@ export class UnsupportedTwinError extends Error {
     }
 }
 export async function bootTwin(opts) {
-    const recorder = createRecorder({ eventsPath: opts.eventsPath });
+    const ownsRecorder = opts.recorder === undefined;
+    const recorder = opts.recorder ?? createRecorder({ eventsPath: opts.eventsPath });
     const flushRecorder = async () => {
         await recorder.flush?.();
     };
     const closeRecorderAndDb = async (dbClose) => {
         await flushRecorder();
-        await recorder.close?.();
+        // A shared recorder is owned by the caller — only flush here, never close
+        // it out from under sibling harnesses still writing to it.
+        if (ownsRecorder)
+            await recorder.close?.();
         dbClose();
     };
     switch (opts.twin) {

package/dist/src/twin/twinStart.d.ts

@@ -0,0 +1,19 @@
+export declare const SUPPORTED_STANDALONE_TWINS: readonly ["github", "slack", "stripe"];
+export type StandaloneAuthSecret = {
+    secret: string;
+    source: "env" | "persisted" | "ephemeral";
+    /** Set when `source` is "persisted": the file the secret was read from. */
+    path?: string;
+};
+/**
+ * Read side of the F-708 secret contract. Resolution order:
+ *   1. env `TWIN_AUTH_SECRET` (always wins — same rule as the twin boots)
+ *   2. the persisted `.pome-data/<twin>/secret` (`POME_TWIN_DATA_DIR`
+ *      overrides the directory); blank file = absent, < 32 chars = loud
+ *      error (never mint against a weak HS256 key, never guess)
+ *   3. a fresh per-boot secret, NOT persisted (loopback dev path)
+ */
+export declare function resolveStandaloneAuthSecret(twin: string, env?: NodeJS.ProcessEnv): StandaloneAuthSecret;
+export declare function runTwinStartCommand(name: string, options: {
+    port?: string;
+}): Promise<void>;

package/dist/src/twin/twinStart.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// `pome twin start <twin>` (F-709) — the docker-free front door. Boots any
+// of the three twins as a long-lived foreground server (Ctrl-C to stop) on
+// the same in-process boot path `pome run --local` uses (`bootTwin`), so
+// `npx @pome-sh/cli twin start github` serves the identical control plane
+// the packaged twin entries serve, with zero installs beyond Node ≥ 24.
+//
+// Auth: the twin's bearer middleware reads `TWIN_AUTH_SECRET` from the env
+// (engine contract). The CLI resolves the secret the same way an operator
+// would — an env-injected `TWIN_AUTH_SECRET` always wins, else the secret a
+// prior twin boot persisted at `.pome-data/<twin>/secret` (F-708 write side;
+// `POME_TWIN_DATA_DIR` overrides the directory) is reused, else a per-boot
+// ephemeral secret is generated. Loopback binds deliberately do NOT persist
+// a new secret file — that mirrors F-708's loopback carve-out, and the
+// ready-to-use JWT is reprinted on every boot anyway.
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { serve } from "@hono/node-server";
+import { sign } from "hono/jwt";
+import { defaultSeedState as defaultSlackSeedState } from "@pome-sh/twin-slack";
+import { defaultSeed as defaultStripeSeed } from "@pome-sh/twin-stripe";
+import { bootTwin } from "./twinHarness.js";
+export const SUPPORTED_STANDALONE_TWINS = ["github", "slack", "stripe"];
+/** The fixed session id a standalone twin serves under (`/s/standalone`). */
+const STANDALONE_SID = "standalone";
+/**
+ * Read side of the F-708 secret contract. Resolution order:
+ *   1. env `TWIN_AUTH_SECRET` (always wins — same rule as the twin boots)
+ *   2. the persisted `.pome-data/<twin>/secret` (`POME_TWIN_DATA_DIR`
+ *      overrides the directory); blank file = absent, < 32 chars = loud
+ *      error (never mint against a weak HS256 key, never guess)
+ *   3. a fresh per-boot secret, NOT persisted (loopback dev path)
+ */
+export function resolveStandaloneAuthSecret(twin, env = process.env) {
+    const injected = env.TWIN_AUTH_SECRET;
+    if (injected)
+        return { secret: injected, source: "env" };
+    const dataDir = env.POME_TWIN_DATA_DIR || join(".pome-data", twin);
+    const secretPath = join(dataDir, "secret");
+    let raw;
+    try {
+        raw = readFileSync(secretPath, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    const persisted = raw?.trim() ?? "";
+    if (persisted.length >= 32) {
+        return { secret: persisted, source: "persisted", path: secretPath };
+    }
+    if (persisted.length > 0) {
+        // Same rule as the engine's readSecretFile (F-708): a short secret is
+        // operator content we must not silently serve or regenerate over.
+        throw new Error(`The persisted secret at ${secretPath} is shorter than 32 chars — fix or delete the file, or inject TWIN_AUTH_SECRET.`);
+    }
+    return { secret: randomBytes(32).toString("hex"), source: "ephemeral" };
+}
+function defaultSeedFor(twin) {
+    switch (twin) {
+        case "slack":
+            return defaultSlackSeedState();
+        case "stripe":
+            return defaultStripeSeed();
+        default:
+            // github: bootTwin's adapter seeds the default world when the seed is
+            // undefined (pre-existing standalone behavior).
+            return undefined;
+    }
+}
+export async function runTwinStartCommand(name, options) {
+    if (!SUPPORTED_STANDALONE_TWINS.includes(name)) {
+        throw new Error(`Unknown twin '${name}'. Supported: ${SUPPORTED_STANDALONE_TWINS.join(", ")}.`);
+    }
+    // `PORT` fallback keeps the spawn surface env-drivable (the contract
+    // suite injects PORT, same as the packaged twin entries).
+    const portRaw = options.port ?? process.env.PORT ?? "3333";
+    const port = Number(portRaw);
+    // Port 0 (ephemeral) is rejected: every printed URL and the status-file
+    // token would name a port nobody can discover from outside the process.
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`pome twin start: invalid --port "${portRaw}"`);
+    }
+    const resolved = resolveStandaloneAuthSecret(name);
+    // The in-process twin's auth middleware (resolveAuthSecret) reads the env;
+    // pinning the resolved secret here is what makes the minted JWT and the
+    // running twin agree.
+    process.env.TWIN_AUTH_SECRET = resolved.secret;
+    const baseUrl = `http://127.0.0.1:${port}`;
+    const harness = await bootTwin({
+        twin: name,
+        seedState: defaultSeedFor(name),
+        runId: STANDALONE_SID,
+        twinBaseUrl: baseUrl,
+    });
+    const token = await sign({
+        sid: STANDALONE_SID,
+        team_id: "tm_local",
+        // Same claims `pome run --local` mints: `login` so the GitHub REST
+        // merge gate resolves the agent user; twin-supplied extras (stripe's
+        // `account_id`) so the token lands on the seeded account.
+        login: "pome-agent",
+        ...(harness.extraClaims ?? {}),
+        exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24,
+    }, resolved.secret);
+    const restUrl = `${baseUrl}/s/${STANDALONE_SID}`;
+    const mcpUrl = `${restUrl}/mcp`;
+    const server = serve({ fetch: harness.app.fetch, port, hostname: "127.0.0.1" });
+    try {
+        await mkdir(".pome", { recursive: true });
+        await writeFile(".pome/twin-status.json", JSON.stringify({ name, url: restUrl, rest_url: restUrl, mcp_url: mcpUrl, auth_token: token }, null, 2));
+    }
+    catch (err) {
+        // Boot fails loudly or not at all: without this, the rejection leaves a
+        // bound listener keeping the process alive behind the error message.
+        await new Promise((resolve) => server.close(() => resolve()));
+        await harness.close();
+        throw err;
+    }
+    console.log(`Pome ${name} twin listening at ${restUrl}`);
+    if (resolved.source === "persisted") {
+        console.log(`Auth: using the persisted secret from ${resolved.path} (an env-injected TWIN_AUTH_SECRET overrides it).`);
+    }
+    console.log(`POME_${harness.envName}_REST_URL=${restUrl}`);
+    console.log(`POME_${harness.envName}_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`);
+    console.log("Ctrl-C to stop.");
+    // Foreground server: the bound socket keeps the event loop alive until a
+    // signal lands. Graceful path closes the listener, then flushes the
+    // recorder and releases the SQLite handle via the harness.
+    const shutdown = () => {
+        void (async () => {
+            // `close()` alone waits for in-flight keep-alive connections, so a
+            // stuck client would turn Ctrl-C into a hang: sever connections first,
+            // and keep an unref'd hard deadline in case a close callback never
+            // resolves anyway.
+            const hardExit = setTimeout(() => process.exit(1), 10_000);
+            hardExit.unref();
+            server.closeAllConnections?.();
+            await new Promise((resolve) => server.close(() => resolve()));
+            await harness.close();
+            process.exit(0);
+        })();
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}

package/node_modules/@pome-sh/sdk/dist/fidelity-inventory.d.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+export declare const heatTierSchema: z.ZodEnum<{
+    hot: "hot";
+    warm: "warm";
+    cold: "cold";
+    unclassified: "unclassified";
+}>;
+export type HeatTier = z.infer<typeof heatTierSchema>;
+export declare const fidelitySurfaceSchema: z.ZodObject<{
+    name: z.ZodString;
+    heat: z.ZodEnum<{
+        hot: "hot";
+        warm: "warm";
+        cold: "cold";
+        unclassified: "unclassified";
+    }>;
+    fidelity: z.ZodEnum<{
+        semantic: "semantic";
+        unsupported: "unsupported";
+        shape: "shape";
+    }>;
+    justification: z.ZodString;
+}, z.core.$strict>;
+export type FidelitySurface = z.infer<typeof fidelitySurfaceSchema>;
+export declare const fidelityDocDriftSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        tool: "tool";
+        rest: "rest";
+    }>;
+    name: z.ZodString;
+    reason: z.ZodString;
+    ticket: z.ZodString;
+}, z.core.$strict>;
+export type FidelityDocDrift = z.infer<typeof fidelityDocDriftSchema>;
+export declare const fidelityInventorySchema: z.ZodObject<{
+    twin: z.ZodString;
+    package: z.ZodString;
+    updated: z.ZodString;
+    notes: z.ZodOptional<z.ZodString>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        heat: z.ZodEnum<{
+            hot: "hot";
+            warm: "warm";
+            cold: "cold";
+            unclassified: "unclassified";
+        }>;
+        fidelity: z.ZodEnum<{
+            semantic: "semantic";
+            unsupported: "unsupported";
+            shape: "shape";
+        }>;
+        justification: z.ZodString;
+    }, z.core.$strict>>;
+    rest: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        heat: z.ZodEnum<{
+            hot: "hot";
+            warm: "warm";
+            cold: "cold";
+            unclassified: "unclassified";
+        }>;
+        fidelity: z.ZodEnum<{
+            semantic: "semantic";
+            unsupported: "unsupported";
+            shape: "shape";
+        }>;
+        justification: z.ZodString;
+    }, z.core.$strict>>;
+    doc_drift: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            tool: "tool";
+            rest: "rest";
+        }>;
+        name: z.ZodString;
+        reason: z.ZodString;
+        ticket: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type FidelityInventory = z.infer<typeof fidelityInventorySchema>;
+export declare function loadFidelityInventory(path: string): FidelityInventory;
+export interface FidelityDocRow {
+    name: string;
+    fidelity: string;
+    /** Present only when the table carries the optional Heat column. */
+    heat?: string;
+}
+export interface FidelityDocSource {
+    /** Shown in lint problems, e.g. "FIDELITY.md". */
+    label: string;
+    kind: "tool" | "rest";
+    markdown: string;
+}
+/**
+ * Expand one name cell into surface names. Backticked spans are the names;
+ * a span with no `.`, `/`, or space is shorthand for a sibling of the first
+ * span (Slack-style `` `reactions.add` / `remove` / `get` ``) and inherits
+ * its dotted prefix. Cells with no backticks name the surface verbatim
+ * (e.g. "Any unsupported path").
+ */
+export declare function expandSurfaceCell(cell: string): string[];
+/**
+ * Parse every markdown table whose header names surfaces of `kind` + Tier.
+ * The Heat column (ENDPOINT-TIERS.md) is optional: parsed when the header
+ * names it, omitted otherwise, so pre-heat tables stay legal.
+ */
+export declare function parseFidelityDocRows(markdown: string, kind: "tool" | "rest"): FidelityDocRow[];
+/**
+ * 1:1-lint the inventory against the FIDELITY doc tables. Returns human-
+ * readable problems (empty = clean). Directions checked per kind:
+ * every doc row must be in the inventory with the same fidelity tier, and
+ * every inventory entry must be documented unless a `doc_drift` entry
+ * (with its owning ticket) declares the gap. A drift declaration whose
+ * name IS documented is stale and reported, so drift entries self-expire.
+ */
+export declare function lintFidelityInventory(inventory: FidelityInventory, docs: FidelityDocSource[]): string[];
+/** Set-compare tool names: inventory vs the live `listTools()` surface. */
+export declare function compareToolNames(inventoryNames: string[], liveNames: string[]): {
+    missing: string[];
+    extra: string[];
+};