@pome-sh/cli 0.1.0 → 0.2.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

@@ -78,6 +78,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 +94,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 = {
@@ -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

@@ -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/db.d.ts

@@ -1,7 +1,8 @@
 /**
  * Mutation outcome — the shape both better-sqlite3's `RunResult` and
- * node:sqlite's `StatementResultingChanges` return, so the M2 swap (F-703)
- * keeps this interface as-is.
+ * node:sqlite's `StatementResultingChanges` return; `changes` is coerced to
+ * number, `lastInsertRowid` may be a bigint for rowids beyond safe-integer
+ * range.
  */
 export interface TwinRunResult {
     changes: number;
@@ -15,8 +16,7 @@ export interface TwinStatement {
 /**
  * A wrapped transaction function (better-sqlite3's shape). The `.immediate`
  * variant takes the write lock up front (BEGIN IMMEDIATE) — github's domain
- * runs its mutations under it. The M2 node:sqlite implementation backs both
- * call forms with explicit BEGIN [IMMEDIATE]/COMMIT/ROLLBACK.
+ * runs its mutations under it.
  */
 export type TwinTransaction<F extends (...args: never[]) => unknown> = F & {
     immediate: F;

package/node_modules/@pome-sh/sdk/dist/db.js

@@ -1,28 +1,97 @@
 // SPDX-License-Identifier: Apache-2.0
 //
-// Engine SQLite driver wrapper (F-681). Twins never import a sqlite driver
-// directly — they call `openTwinDatabase()` and consume the `TwinDatabase`
-// interface below. The interface is a same-shape subset of better-sqlite3
-// (prepare/exec/pragma/transaction/close), which is exactly the surface the
-// M2 node:sqlite swap (F-703) re-implements: swapping the driver is a change
-// to THIS file only. `transaction(fn)` keeps better-sqlite3's shape (returns
-// a callable running fn atomically) because twin domain code has dozens of
-// call sites relying on it and node:sqlite ships no equivalent — the M2
-// implementation backs it with BEGIN IMMEDIATE/COMMIT/ROLLBACK.
-//
-// The driver is loaded lazily via createRequire so @pome-sh/sdk can declare
-// better-sqlite3 as an optional peer dependency: twins that bring their own
-// database never pay for (or compile) the native module.
+// Engine SQLite driver wrapper (F-681), backed by node:sqlite since F-703 —
+// zero native deps, no compiler toolchain at install. Twins never import a
+// sqlite driver directly — they call `openTwinDatabase()` and consume the
+// `TwinDatabase` interface below. The interface keeps better-sqlite3's shape
+// (prepare/exec/pragma/transaction/close) because twin domain code has dozens
+// of call sites relying on it; node:sqlite ships no pragma()/transaction()
+// equivalents, so this file emulates them: `pragma()` prepares a `PRAGMA …`
+// statement, `transaction(fn)` (+ `.immediate`) wraps fn in explicit
+// BEGIN [IMMEDIATE]/COMMIT/ROLLBACK at the outermost level and in a SAVEPOINT
+// when called inside an open transaction — better-sqlite3's nesting semantics,
+// which twin-github's seed() relies on (it wraps createIssue et al., each of
+// which opens its own transaction).
 import { mkdirSync } from "node:fs";
-import { createRequire } from "node:module";
 import { dirname } from "node:path";
-let driver;
-function loadDriver() {
-    if (!driver) {
-        const require = createRequire(import.meta.url);
-        driver = require("better-sqlite3");
+import { DatabaseSync } from "node:sqlite";
+class NodeSqliteTwinDatabase {
+    #db;
+    #savepointId = 0;
+    constructor(path) {
+        this.#db = new DatabaseSync(path);
+    }
+    prepare(sql) {
+        const statement = this.#db.prepare(sql);
+        return {
+            run: (...params) => {
+                const result = statement.run(...params);
+                return { changes: Number(result.changes), lastInsertRowid: result.lastInsertRowid };
+            },
+            get: (...params) => statement.get(...params),
+            all: (...params) => statement.all(...params),
+        };
+    }
+    exec(sql) {
+        this.#db.exec(sql);
+    }
+    pragma(statement, options = {}) {
+        const rows = this.#db.prepare(`PRAGMA ${statement}`).all();
+        if (!options.simple)
+            return rows;
+        const row = rows[0];
+        if (row === undefined)
+            return undefined;
+        return row[Object.keys(row)[0]];
+    }
+    transaction(fn) {
+        const wrap = (begin) => ((...args) => {
+            if (this.#db.isTransaction)
+                return this.#nested(fn, args);
+            this.#db.exec(begin);
+            try {
+                const out = fn(...args);
+                this.#db.exec("COMMIT");
+                return out;
+            }
+            catch (error) {
+                // Certain failures (e.g. ON CONFLICT ROLLBACK) end the transaction
+                // themselves — only roll back when one is still open.
+                if (this.#db.isTransaction)
+                    this.#db.exec("ROLLBACK");
+                throw error;
+            }
+        });
+        const tx = wrap("BEGIN");
+        tx.immediate = wrap("BEGIN IMMEDIATE");
+        return tx;
+    }
+    /**
+     * A transaction function called inside an open transaction joins it under a
+     * SAVEPOINT (better-sqlite3's semantics): success releases the savepoint,
+     * failure rolls back only the inner work. The BEGIN variant is irrelevant
+     * here — the outermost transaction already holds the lock mode.
+     */
+    #nested(fn, args) {
+        const name = `_pome_tx_${this.#savepointId++}`;
+        this.#db.exec(`SAVEPOINT ${name}`);
+        try {
+            const out = fn(...args);
+            this.#db.exec(`RELEASE ${name}`);
+            return out;
+        }
+        catch (error) {
+            if (this.#db.isTransaction) {
+                this.#db.exec(`ROLLBACK TO ${name}`);
+                this.#db.exec(`RELEASE ${name}`);
+            }
+            throw error;
+        }
+    }
+    close() {
+        if (this.#db.isOpen)
+            this.#db.close();
     }
-    return driver;
 }
 /**
  * Open a twin database with the pome pragma set applied:
@@ -34,11 +103,10 @@ export function openTwinDatabase(path = ":memory:", options = {}) {
     if (path !== ":memory:") {
         mkdirSync(dirname(path), { recursive: true });
     }
-    const Database = loadDriver();
-    const db = new Database(path);
-    db.pragma("busy_timeout = 5000");
-    db.pragma("journal_mode = WAL");
-    db.pragma("foreign_keys = ON");
+    const db = new NodeSqliteTwinDatabase(path);
+    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
     options.migrate?.(db);
     return db;
 }