@pome-sh/cli 0.1.1 → 0.3.0

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

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Structured fidelity inventory (F-730). Each twin ships a machine-readable
+// surface list — `fidelity.inventory.json` — carrying, per MCP tool and REST
+// surface, the heat tier (how deep the endpoint SHOULD be, ruled by the
+// F-729 rubric) orthogonal to the fidelity tier (how deep it IS, per
+// `fidelityTierSchema`), plus a justification for the classification.
+//
+// The FIDELITY doc tables are 1:1-linted against this inventory instead of
+// the old soft "docs mention the tool name" checks (which let twin-stripe's
+// implemented-but-undocumented refunds drift by silently). Known, ticketed
+// doc gaps are declared in `doc_drift`: the lint accepts exactly those
+// gaps and fails loudly once the docs catch up, so a declaration can never
+// outlive the drift it describes.
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { fidelityTierSchema } from "./index.js";
+export const heatTierSchema = z.enum(["hot", "warm", "cold", "unclassified"]);
+export const fidelitySurfaceSchema = z.strictObject({
+    /** MCP tool name, or the REST surface string exactly as documented. */
+    name: z.string().min(1),
+    heat: heatTierSchema,
+    fidelity: fidelityTierSchema,
+    justification: z.string().min(1),
+});
+export const fidelityDocDriftSchema = z.strictObject({
+    kind: z.enum(["tool", "rest"]),
+    /** Must match an inventory entry of the same kind. */
+    name: z.string().min(1),
+    reason: z.string().min(1),
+    /** The Linear ticket that owns reconciling the docs. */
+    ticket: z.string().regex(/^F-\d+$/),
+});
+export const fidelityInventorySchema = z.strictObject({
+    twin: z.string().min(1),
+    package: z.string().min(1),
+    /** ISO date (YYYY-MM-DD) of the last human review of this inventory. */
+    updated: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    notes: z.string().optional(),
+    tools: z.array(fidelitySurfaceSchema).min(1),
+    rest: z.array(fidelitySurfaceSchema),
+    doc_drift: z.array(fidelityDocDriftSchema).default([]),
+});
+export function loadFidelityInventory(path) {
+    return fidelityInventorySchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+const TOOL_NAME_HEADERS = new Set(["tool"]);
+const REST_NAME_HEADERS = new Set(["route", "endpoint", "surface"]);
+function splitTableRow(line) {
+    return line
+        .replace(/^\s*\|/, "")
+        .replace(/\|\s*$/, "")
+        .split("|")
+        .map((cell) => cell.trim());
+}
+function isSeparatorRow(cells) {
+    return cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+/**
+ * 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 function expandSurfaceCell(cell) {
+    const spans = [...cell.matchAll(/`([^`]+)`/g)].map((match) => match[1].trim());
+    if (spans.length === 0) {
+        const text = cell.trim();
+        return text.length > 0 ? [text] : [];
+    }
+    const [first, ...rest] = spans;
+    const lastDot = first.lastIndexOf(".");
+    const prefix = lastDot >= 0 ? first.slice(0, lastDot + 1) : "";
+    return [
+        first,
+        ...rest.map((span) => /[./ ]/.test(span) || prefix === "" ? span : `${prefix}${span}`),
+    ];
+}
+/**
+ * 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 function parseFidelityDocRows(markdown, kind) {
+    const nameHeaders = kind === "tool" ? TOOL_NAME_HEADERS : REST_NAME_HEADERS;
+    const rows = [];
+    const lines = markdown.split("\n");
+    let nameIdx = -1;
+    let tierIdx = -1;
+    let heatIdx = -1;
+    let inTable = false;
+    for (const line of lines) {
+        if (!line.trimStart().startsWith("|")) {
+            inTable = false;
+            nameIdx = -1;
+            tierIdx = -1;
+            heatIdx = -1;
+            continue;
+        }
+        const cells = splitTableRow(line);
+        if (!inTable) {
+            const headers = cells.map((cell) => cell.toLowerCase());
+            nameIdx = headers.findIndex((header) => nameHeaders.has(header));
+            tierIdx = headers.findIndex((header) => header === "tier");
+            heatIdx = headers.findIndex((header) => header === "heat");
+            inTable = true;
+            continue;
+        }
+        if (isSeparatorRow(cells) || nameIdx < 0 || tierIdx < 0)
+            continue;
+        const fidelity = cells[tierIdx] ?? "";
+        const heat = heatIdx >= 0 ? { heat: cells[heatIdx] ?? "" } : {};
+        for (const name of expandSurfaceCell(cells[nameIdx] ?? "")) {
+            rows.push({ name, fidelity, ...heat });
+        }
+    }
+    return rows;
+}
+// ─── Lint: inventory ⇔ docs, both directions ─────────────────────────────────
+/**
+ * 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 function lintFidelityInventory(inventory, docs) {
+    const problems = [];
+    for (const kind of ["tool", "rest"]) {
+        const sources = docs.filter((doc) => doc.kind === kind);
+        if (sources.length === 0)
+            continue;
+        const labels = sources.map((doc) => doc.label).join(", ");
+        const entries = kind === "tool" ? inventory.tools : inventory.rest;
+        const drift = new Map(inventory.doc_drift.filter((d) => d.kind === kind).map((d) => [d.name, d]));
+        const inventoryByName = new Map();
+        for (const entry of entries) {
+            if (inventoryByName.has(entry.name)) {
+                problems.push(`inventory ${kind} '${entry.name}' is listed twice`);
+            }
+            inventoryByName.set(entry.name, entry);
+        }
+        const documented = new Map();
+        for (const source of sources) {
+            for (const row of parseFidelityDocRows(source.markdown, kind)) {
+                const existing = documented.get(row.name);
+                if (existing && existing.fidelity !== row.fidelity) {
+                    problems.push(`${labels}: ${kind} '${row.name}' is documented twice with conflicting tiers ('${existing.fidelity}' vs '${row.fidelity}')`);
+                    continue;
+                }
+                if (existing &&
+                    existing.heat !== undefined &&
+                    row.heat !== undefined &&
+                    existing.heat !== row.heat) {
+                    problems.push(`${labels}: ${kind} '${row.name}' is documented twice with conflicting heat ('${existing.heat}' vs '${row.heat}')`);
+                    continue;
+                }
+                documented.set(row.name, row);
+            }
+        }
+        for (const [name, row] of documented) {
+            const entry = inventoryByName.get(name);
+            if (!entry) {
+                problems.push(`${labels}: ${kind} '${name}' documented but missing from fidelity.inventory.json`);
+                continue;
+            }
+            if (entry.fidelity !== row.fidelity) {
+                problems.push(`${kind} '${name}': inventory says fidelity '${entry.fidelity}' but ${labels} says '${row.fidelity}'`);
+            }
+            if (row.heat !== undefined && entry.heat !== row.heat) {
+                problems.push(`${kind} '${name}': inventory says heat '${entry.heat}' but ${labels} says '${row.heat}'`);
+            }
+        }
+        for (const entry of entries) {
+            if (documented.has(entry.name))
+                continue;
+            const declared = drift.get(entry.name);
+            if (!declared) {
+                problems.push(`${kind} '${entry.name}' is in fidelity.inventory.json but undocumented in ${labels}; add the row or declare doc_drift`);
+            }
+        }
+        for (const declared of drift.values()) {
+            if (!inventoryByName.has(declared.name)) {
+                problems.push(`doc_drift ${kind} '${declared.name}' (${declared.ticket}) matches no inventory entry`);
+            }
+            if (documented.has(declared.name)) {
+                problems.push(`doc_drift ${kind} '${declared.name}' (${declared.ticket}) is stale — ${labels} now documents it; remove the declaration`);
+            }
+        }
+    }
+    return problems;
+}
+/** Set-compare tool names: inventory vs the live `listTools()` surface. */
+export function compareToolNames(inventoryNames, liveNames) {
+    const inventory = new Set(inventoryNames);
+    const live = new Set(liveNames);
+    return {
+        missing: [...live].filter((name) => !inventory.has(name)).sort(),
+        extra: [...inventory].filter((name) => !live.has(name)).sort(),
+    };
+}
+//# sourceMappingURL=fidelity-inventory.js.map

package/node_modules/@pome-sh/sdk/dist/fidelity-inventory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-inventory.js","sourceRoot":"","sources":["../src/fidelity-inventory.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,55 @@
+import { type FidelityInventory } from "./fidelity-inventory.js";
+export type ParityState = Record<string, unknown>;
+export interface ParityStep {
+    tool: string;
+    arguments?: Record<string, unknown> | ((state: ParityState) => Record<string, unknown>);
+    /** Pull cross-call state (ids, numbers, shas) out of the response body. */
+    capture?: (body: unknown, state: ParityState) => void;
+    /** Expected HTTP status; default: any 2xx. */
+    status?: number;
+    /** Extra body assertion; return a problem string to fail the step. */
+    verify?: (body: unknown) => string | undefined;
+}
+export interface ParityRestProbe {
+    /** Label in the report, e.g. "unsupported-rest". */
+    surface: string;
+    method?: string;
+    /** Session-relative path, e.g. "/repos/acme/api/actions/runs". */
+    path: string;
+    /** Expected HTTP status. */
+    status: number;
+    /** Assert the body carries a `fidelity: "unsupported"` marker. */
+    expectUnsupportedEnvelope?: boolean;
+}
+export interface ParityAppLike {
+    request(path: string | Request, init?: RequestInit): Response | Promise<Response>;
+}
+export interface RunParityOptions {
+    app: ParityAppLike;
+    twin: string;
+    inventory: FidelityInventory;
+    /** `listTools()` names from the twin source — the code truth. */
+    liveToolNames: string[];
+    steps: ParityStep[];
+    restProbes?: ParityRestProbe[];
+    /** Session id; default "fidelity-parity". */
+    sid?: string;
+    /** JWT secret; default env TWIN_AUTH_SECRET or the engine dev secret. */
+    secret?: string;
+    /** Extra JWT claims (login, team_id, account_id, ...). */
+    claims?: Record<string, unknown>;
+    /** Applied to every step without its own `verify` (twin error envelopes). */
+    stepVerify?: (body: unknown) => string | undefined;
+    /** Optional live upstream probes; entries are appended to the report. */
+    live?: () => Promise<unknown[]>;
+}
+export interface ParityResult {
+    ok: boolean;
+    failures: string[];
+    report: unknown[];
+}
+export declare function runFidelityParity(options: RunParityOptions): Promise<ParityResult>;
+/** Script entrypoint: run, print the JSON report, set the exit code. */
+export declare function runParityCli(options: RunParityOptions): Promise<ParityResult>;
+export { compareToolNames, expandSurfaceCell, fidelityDocDriftSchema, fidelityInventorySchema, fidelitySurfaceSchema, heatTierSchema, lintFidelityInventory, loadFidelityInventory, parseFidelityDocRows, } from "./fidelity-inventory.js";
+export type { FidelityDocDrift, FidelityDocRow, FidelityDocSource, FidelityInventory, FidelitySurface, HeatTier, } from "./fidelity-inventory.js";

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

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Shared fidelity:parity runner (F-730). One engine-level runner; each twin
+// supplies declarative scenario data — an ordered, stateful chain of MCP
+// calls with cross-call captures (a PR number, a charge id, a message ts) —
+// plus its structured fidelity inventory. No per-twin runner copies (M1
+// "twin-infra copies: 0" gate).
+//
+// The runner asserts three rings agree before it reports green:
+//   1. live tool list (code truth from listTools())
+//   2. fidelity.inventory.json tools (the machine-readable inventory)
+//   3. scenario step coverage (every inventory tool exercised)
+// and that every step answers its expected status through the frozen
+// `POST /s/:sid/mcp/call` surface. Optional REST probes pin the loud-501
+// unsupported envelope; an optional `live` hook lets a twin compare
+// read-only shapes against the real upstream (e.g. `gh api`).
+import { sign } from "hono/jwt";
+import { compareToolNames, } from "./fidelity-inventory.js";
+function bodyKeys(body) {
+    if (Array.isArray(body))
+        return ["array"];
+    if (body && typeof body === "object") {
+        return Object.keys(body).sort();
+    }
+    return [];
+}
+export async function runFidelityParity(options) {
+    const sid = options.sid ?? "fidelity-parity";
+    const secret = options.secret ?? process.env.TWIN_AUTH_SECRET ?? "dev-only-insecure-secret";
+    const token = await sign({ sid, exp: Math.floor(Date.now() / 1000) + 3600, ...options.claims }, secret);
+    const base = `/s/${sid}`;
+    const failures = [];
+    const report = [];
+    // Ring 1 ⇔ ring 2: inventory tools must equal the live tool list.
+    const inventoryNames = options.inventory.tools.map((entry) => entry.name);
+    const inventoryDiff = compareToolNames(inventoryNames, options.liveToolNames);
+    for (const name of inventoryDiff.missing) {
+        failures.push(`tool '${name}' is live in listTools() but missing from fidelity.inventory.json`);
+    }
+    for (const name of inventoryDiff.extra) {
+        failures.push(`tool '${name}' is in fidelity.inventory.json but not in listTools()`);
+    }
+    // Ring 2 ⇔ ring 3: every inventory tool needs at least one scenario step.
+    const covered = new Set(options.steps.map((step) => step.tool));
+    for (const name of inventoryNames) {
+        if (!covered.has(name))
+            failures.push(`no parity scenario step covers tool '${name}'`);
+    }
+    for (const tool of covered) {
+        if (!inventoryNames.includes(tool)) {
+            failures.push(`scenario step calls '${tool}' which is not in fidelity.inventory.json`);
+        }
+    }
+    const state = {};
+    for (const step of options.steps) {
+        const args = typeof step.arguments === "function" ? step.arguments(state) : step.arguments ?? {};
+        const response = await options.app.request(`${base}/mcp/call`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+            body: JSON.stringify({ tool: step.tool, arguments: args }),
+        });
+        const body = await response.json().catch(() => ({}));
+        const expected = step.status === undefined ? response.ok : response.status === step.status;
+        if (!expected) {
+            failures.push(`${step.tool}: expected ${step.status ?? "2xx"}, got ${response.status} ${JSON.stringify(body).slice(0, 300)}`);
+        }
+        else {
+            const problem = (step.verify ?? options.stepVerify)?.(body);
+            if (problem)
+                failures.push(`${step.tool}: ${problem}`);
+            step.capture?.(body, state);
+        }
+        report.push({ tool: step.tool, status: response.status, ok: response.ok, keys: bodyKeys(body) });
+    }
+    for (const probe of options.restProbes ?? []) {
+        const response = await options.app.request(`${base}${probe.path}`, {
+            method: probe.method ?? "GET",
+            headers: { authorization: `Bearer ${token}` },
+        });
+        const body = await response.json().catch(() => ({}));
+        if (response.status !== probe.status) {
+            failures.push(`${probe.surface}: expected ${probe.status}, got ${response.status}`);
+        }
+        if (probe.expectUnsupportedEnvelope && !JSON.stringify(body).includes('"fidelity":"unsupported"')) {
+            failures.push(`${probe.surface}: body does not carry the fidelity:"unsupported" envelope`);
+        }
+        report.push({ surface: probe.surface, status: response.status, body });
+    }
+    if (options.live) {
+        report.push(...(await options.live()));
+    }
+    return { ok: failures.length === 0, failures, report };
+}
+/** Script entrypoint: run, print the JSON report, set the exit code. */
+export async function runParityCli(options) {
+    const result = await runFidelityParity(options);
+    console.log(JSON.stringify({
+        twin: options.twin,
+        tools: options.inventory.tools.length,
+        rest_surfaces: options.inventory.rest.length,
+        ok: result.ok,
+        failures: result.failures,
+        report: result.report,
+    }, null, 2));
+    if (!result.ok) {
+        console.error(`fidelity:parity FAILED for ${options.twin} (${result.failures.length} problem(s))`);
+        process.exitCode = 1;
+    }
+    return result;
+}
+export { compareToolNames, expandSurfaceCell, fidelityDocDriftSchema, fidelityInventorySchema, fidelitySurfaceSchema, heatTierSchema, lintFidelityInventory, loadFidelityInventory, parseFidelityDocRows, } from "./fidelity-inventory.js";
+//# sourceMappingURL=parity.js.map

package/node_modules/@pome-sh/sdk/dist/parity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parity.js","sourceRoot":"","sources":["../src/parity.ts"],"names":[],"mappings":"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"}

package/node_modules/@pome-sh/sdk/dist/server-helpers.d.ts

@@ -13,6 +13,21 @@ export declare function makeDeltaSink(): {
 };
 /** Hostnames the boot guard treats as loopback binds. */
 export declare function isLoopbackHost(value: string): boolean;
+/**
+ * F-708: self-generate `TWIN_AUTH_SECRET` on first boot. An env-injected
+ * secret always wins (pome-cloud injects per-tenant secrets — that contract
+ * is untouched), and loopback binds keep the dev-fallback path. Otherwise
+ * the secret persisted at the compose-era contract location
+ * `.pome-data/<twin>/secret` (cwd-relative; `POME_TWIN_DATA_DIR` overrides
+ * the directory) is reused, or a fresh 32-byte hex secret is generated,
+ * persisted there, and printed once to stdout so the operator can mint JWTs.
+ *
+ * The resolved secret lands in `process.env.TWIN_AUTH_SECRET`, which is
+ * process-global by design: the engine's auth (`resolveAuthSecret`) reads
+ * the env, so one process serves one secret — the frozen boot contract is
+ * one twin per process, and a multi-twin process shares the first secret.
+ */
+export declare function ensureTwinAuthSecret(twin: string, host: string): void;
 export declare function shadowedPrefix(routePath: string): string | null;
 export declare function assertUniqueToolNames<TDomain>(tools: ReadonlyArray<ToolSpec<TDomain>>, twinId: string): void;
 export declare function findTool<TDb, TSeed, TDomain>(definition: TwinDefinition<TDb, TSeed, TDomain>, name: string): ToolSpec<TDomain>;

package/node_modules/@pome-sh/sdk/dist/server-helpers.js

@@ -4,6 +4,9 @@
 // out of server.ts (F-685) purely for module-size hygiene; everything a twin
 // may import (TwinBootError, isLoopbackHost) is re-exported from server.ts,
 // which stays the only public entry.
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { RESERVED_SESSION_PREFIXES } from "./index.js";
 import { UnknownToolError } from "./errors.js";
 export class TwinBootError extends Error {
@@ -29,6 +32,99 @@ export function makeDeltaSink() {
 export function isLoopbackHost(value) {
     return value === "127.0.0.1" || value === "::1" || value === "localhost";
 }
+/**
+ * F-708: self-generate `TWIN_AUTH_SECRET` on first boot. An env-injected
+ * secret always wins (pome-cloud injects per-tenant secrets — that contract
+ * is untouched), and loopback binds keep the dev-fallback path. Otherwise
+ * the secret persisted at the compose-era contract location
+ * `.pome-data/<twin>/secret` (cwd-relative; `POME_TWIN_DATA_DIR` overrides
+ * the directory) is reused, or a fresh 32-byte hex secret is generated,
+ * persisted there, and printed once to stdout so the operator can mint JWTs.
+ *
+ * The resolved secret lands in `process.env.TWIN_AUTH_SECRET`, which is
+ * process-global by design: the engine's auth (`resolveAuthSecret`) reads
+ * the env, so one process serves one secret — the frozen boot contract is
+ * one twin per process, and a multi-twin process shares the first secret.
+ */
+export function ensureTwinAuthSecret(twin, host) {
+    if (process.env.TWIN_AUTH_SECRET)
+        return;
+    if (isLoopbackHost(host))
+        return;
+    const dataDir = process.env.POME_TWIN_DATA_DIR || join(".pome-data", twin);
+    const secretPath = join(dataDir, "secret");
+    try {
+        const persisted = readSecretFile(secretPath);
+        if (persisted) {
+            process.env.TWIN_AUTH_SECRET = persisted;
+            console.log(`[twin-${twin}] TWIN_AUTH_SECRET not set — using the persisted secret from ${secretPath}`);
+            return;
+        }
+        const secret = randomBytes(32).toString("hex");
+        mkdirSync(dataDir, { recursive: true });
+        try {
+            // Compose-era file format: hex secret + trailing newline, owner-only.
+            // "wx" never clobbers a secret written by a concurrent first boot.
+            writeFileSync(secretPath, `${secret}\n`, { mode: 0o600, flag: "wx" });
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            const winner = readSecretFile(secretPath);
+            if (winner) {
+                process.env.TWIN_AUTH_SECRET = winner;
+                console.log(`[twin-${twin}] TWIN_AUTH_SECRET not set — using the persisted secret from ${secretPath}`);
+                return;
+            }
+            // A blank file is an aborted earlier write: remove it and retry the
+            // exclusive write, so a concurrent booter losing this second race
+            // adopts the winner's secret instead of overwriting it.
+            rmSync(secretPath, { force: true });
+            try {
+                writeFileSync(secretPath, `${secret}\n`, { mode: 0o600, flag: "wx" });
+            }
+            catch (err2) {
+                if (err2.code !== "EEXIST")
+                    throw err2;
+                const late = readSecretFile(secretPath);
+                if (!late)
+                    throw err2;
+                process.env.TWIN_AUTH_SECRET = late;
+                console.log(`[twin-${twin}] TWIN_AUTH_SECRET not set — using the persisted secret from ${secretPath}`);
+                return;
+            }
+        }
+        process.env.TWIN_AUTH_SECRET = secret;
+        console.log(`[twin-${twin}] TWIN_AUTH_SECRET not set — generated ${secret} (persisted to ${secretPath}; subsequent boots reuse it, an env-injected TWIN_AUTH_SECRET overrides it)`);
+    }
+    catch (err) {
+        if (err instanceof TwinBootError)
+            throw err;
+        throw new TwinBootError(`TWIN_AUTH_SECRET is not set and self-generating one at ${secretPath} failed: ${err.message}`);
+    }
+}
+/** The persisted secret, trimmed; undefined when absent or blank. */
+function readSecretFile(secretPath) {
+    let raw;
+    try {
+        raw = readFileSync(secretPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    // The compose-era contract documents >= 32 chars. A shorter file (hand
+    // edit, truncation) must fail the boot loudly — never silently serve a
+    // weak HS256 key, and never silently regenerate over operator content.
+    if (trimmed.length < 32) {
+        throw new TwinBootError(`TWIN_AUTH_SECRET is not set and the persisted secret at ${secretPath} is shorter than 32 chars — fix or delete the file, or inject TWIN_AUTH_SECRET.`);
+    }
+    return trimmed;
+}
 export function shadowedPrefix(routePath) {
     for (const prefix of RESERVED_SESSION_PREFIXES) {
         if (routePath === prefix || routePath.startsWith(`${prefix}/`))

package/node_modules/@pome-sh/sdk/dist/server-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-helpers.js","sourceRoot":"","sources":["../src/server-helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server-helpers.js","sourceRoot":"","sources":["../src/server-helpers.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,4EAA4E;AAC5E,qCAAqC;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,yBAAyB,EAAsC,MAAM,YAAY,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE5E,MAAM,UAAU,aAAa;IAC3B,IAAI,KAAK,GAAiE,IAAI,CAAC;IAC/E,OAAO;QACL,MAAM,CAAC,CAA+D;YACpE,KAAK,GAAG,CAAC,CAAC;QACZ,CAAC;QACD,KAAK;YACH,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,WAAW,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,IAAY;IAC7D,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO;IACzC,IAAI,cAAc,CAAC,IAAI,CAAC;QAAE,OAAO;IAEjC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAC3E,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAE3C,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,SAAS,CAAC;YACzC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,gEAAgE,UAAU,EAAE,CAAC,CAAC;YACvG,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/C,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC;YACH,sEAAsE;YACtE,mEAAmE;YACnE,aAAa,CAAC,UAAU,EAAE,GAAG,MAAM,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YAChE,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;YAC1C,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,MAAM,CAAC;gBACtC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,gEAAgE,UAAU,EAAE,CAAC,CAAC;gBACvG,OAAO;YACT,CAAC;YACD,oEAAoE;YACpE,kEAAkE;YAClE,wDAAwD;YACxD,MAAM,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,IAAI,CAAC;gBACH,aAAa,CAAC,UAAU,EAAE,GAAG,MAAM,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACxE,CAAC;YAAC,OAAO,IAAI,EAAE,CAAC;gBACd,IAAK,IAA8B,CAAC,IAAI,KAAK,QAAQ;oBAAE,MAAM,IAAI,CAAC;gBAClE,MAAM,IAAI,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;gBACxC,IAAI,CAAC,IAAI;oBAAE,MAAM,IAAI,CAAC;gBACtB,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,IAAI,CAAC;gBACpC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,gEAAgE,UAAU,EAAE,CAAC,CAAC;gBACvG,OAAO;YACT,CAAC;QACH,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,MAAM,CAAC;QACtC,OAAO,CAAC,GAAG,CACT,SAAS,IAAI,0CAA0C,MAAM,kBAAkB,UAAU,6EAA6E,CACvK,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,aAAa;YAAE,MAAM,GAAG,CAAC;QAC5C,MAAM,IAAI,aAAa,CACrB,0DAA0D,UAAU,YAAa,GAAa,CAAC,OAAO,EAAE,CACzG,CAAC;IACJ,CAAC;AACH,CAAC;AAED,qEAAqE;AACrE,SAAS,cAAc,CAAC,UAAkB;IACxC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACvE,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,uEAAuE;IACvE,uEAAuE;IACvE,uEAAuE;IACvE,IAAI,OAAO,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,aAAa,CACrB,2DAA2D,UAAU,iFAAiF,CACvJ,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,KAAK,MAAM,MAAM,IAAI,yBAAyB,EAAE,CAAC;QAC/C,IAAI,SAAS,KAAK,MAAM,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC;YAAE,OAAO,MAAM,CAAC;IAChF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,KAAuC,EACvC,MAAc;IAEd,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,aAAa,CAAC,SAAS,MAAM,8BAA8B,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,UAA+C,EAC/C,IAAY;IAEZ,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAY;IACzC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,WAAW;YAAE,MAAM,GAAG,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,EAAE,CAAC,IAAa,EAAE,QAAQ,GAAG,KAAK;IAChD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,IAAa;IACnC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC/C,CAAC"}

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

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { type TwinDefinition } from "./index.js";
 import { type RecorderStore } from "./recorder.js";
-export { TwinBootError, isLoopbackHost, created, ok } from "./server-helpers.js";
+export { TwinBootError, ensureTwinAuthSecret, isLoopbackHost, created, ok } from "./server-helpers.js";
 export { createRecorderHandle, createRecorderStore, createFileBackedRecorderStore, resolveRecorderStore, toTwinHttpEventRow, POME_RECORDER_EVENTS_PATH, } from "./recorder.js";
 export type { RecorderStore, RecorderStoreOptions, FileBackedRecorderStoreOptions, ErrorEnvelopeFn, } from "./recorder.js";
 export { bearerAuth, requireAdminAuth, resolveAuthSecret } from "./auth.js";

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

@@ -31,10 +31,10 @@ import { handleMcpJsonRpc, mcpMethodNotAllowed } from "./mcp-jsonrpc.js";
 import { createRecorderHandle, resolveRecorderStore } from "./recorder.js";
 import { redactSecrets } from "./redaction.js";
 import { TwinError, envelopeFor } from "./errors.js";
-import { POME_CORE_ROUTE_NAMES, TwinBootError, assertUniqueToolNames, findTool, isLoopbackHost, makeDeltaSink, readJson, shadowedPrefix, } from "./server-helpers.js";
+import { POME_CORE_ROUTE_NAMES, TwinBootError, assertUniqueToolNames, ensureTwinAuthSecret, findTool, isLoopbackHost, makeDeltaSink, readJson, shadowedPrefix, } from "./server-helpers.js";
 // Public boot surface consumed by twin entrypoints
-// (`import { TwinBootError, isLoopbackHost, serve } from "@pome-sh/sdk/server"`).
-export { TwinBootError, isLoopbackHost, created, ok } from "./server-helpers.js";
+// (`import { ensureTwinAuthSecret, serve } from "@pome-sh/sdk/server"`).
+export { TwinBootError, ensureTwinAuthSecret, isLoopbackHost, created, ok } from "./server-helpers.js";
 export { createRecorderHandle, createRecorderStore, createFileBackedRecorderStore, resolveRecorderStore, toTwinHttpEventRow, POME_RECORDER_EVENTS_PATH, } from "./recorder.js";
 export { bearerAuth, requireAdminAuth, resolveAuthSecret } from "./auth.js";
 // Alternate serving bridges (anything that isn't @hono/node-server) must feed
@@ -314,11 +314,13 @@ export function createApp(definition, options = {}) {
  */
 export async function serve(definition, options = {}) {
     const hostname = options.hostname ?? "127.0.0.1";
-    // Contract boot guard: a twin must refuse to serve real traffic with the
-    // dev fallback secret. Checked before the app is built so the process
+    // Contract boot guard: a twin must never serve real traffic with the dev
+    // fallback secret. Since F-708 a non-loopback bind with no env-injected
+    // secret self-generates + persists one instead of refusing to boot; a
+    // failed generation still throws before the app is built, so the process
     // exits non-zero without ever listening.
-    if (options.port !== undefined && !isLoopbackHost(hostname) && !process.env.TWIN_AUTH_SECRET) {
-        throw new TwinBootError(`TWIN_AUTH_SECRET is required when a twin listens on a non-loopback host (${hostname}).`);
+    if (options.port !== undefined && !isLoopbackHost(hostname)) {
+        ensureTwinAuthSecret(definition.id, hostname);
     }
     // Resolve the store once so `close()` can flush the same instance the app
     // records into (durable when POME_RECORDER_EVENTS_PATH is set).