@retinue/agentkit 0.1.0 → 0.3.0

package/dist/runtime/index.js

@@ -7,6 +7,14 @@ export const RUN_STATUSES = [
     "running",
     "waiting-for-question",
     "waiting-for-approval",
+    /**
+     * The run needs a connection the tenant does not have, and a person must complete a consent — task #264.
+     *
+     * A third pause beside question and approval, and deliberately the *same shape*: the runtime already stops a
+     * run and resumes it twice over, and a bespoke polling loop or a failed run somebody restarts by hand would
+     * be a second mechanism for the thing the durable runtime exists to do.
+     */
+    "waiting-for-connection",
     "retry-pending",
     "completed",
     "failed",
@@ -21,6 +29,7 @@ export const RUN_TRANSITIONS = {
     running: [
         "waiting-for-question",
         "waiting-for-approval",
+        "waiting-for-connection",
         "retry-pending",
         "completed",
         "failed",
@@ -28,6 +37,9 @@ export const RUN_TRANSITIONS = {
     ],
     "waiting-for-question": ["queued", "cancelled"],
     "waiting-for-approval": ["queued", "cancelled"],
+    // Resumes to `queued` exactly as the other two do: consent completing is an answer, and the run rejoins the
+    // queue rather than continuing in whatever process happened to receive the callback.
+    "waiting-for-connection": ["queued", "cancelled"],
     "retry-pending": ["queued", "cancelled"],
     completed: [],
     failed: [],

package/dist/runtime/worker.d.ts

@@ -101,16 +101,51 @@ export type DurableWorkerDeps = {
      * lost message costs latency rather than a stuck flow. A hook whose delivery was load-bearing would need a
      * queue, not a callback.
      */
+    /**
+     * The tenant's concurrent-run limit, or undefined for unlimited — REQ-058 (#246), task #265.
+     *
+     * A function rather than a value, for the reason `RateLimitGuardDeps.policyFor` gives: limits are per tenant
+     * and change without a redeploy, and a value captured at construction would be the limits of whoever booted
+     * the process.
+     *
+     * **Absent or non-positive means unlimited**, which is the branch that matters on the day this ships. A
+     * deployment upgrading into the feature with nothing configured must keep working; the alternative is an
+     * outage caused by adding a safety feature, which is how safety features get removed.
+     */
+    readonly concurrencyFor?: (tenantId: Run["tenantId"]) => Promise<number | undefined> | number | undefined;
+    /**
+     * How long a deferred run waits before its next attempt. Default one second.
+     *
+     * Not zero, and not the lease length. Zero spins a worker against the cap, burning capacity on the check
+     * itself; a full lease is longer than most runs, so a freed slot would sit idle. A second is short enough
+     * that a slot is picked up promptly and long enough that the retry is not the load.
+     */
+    readonly deferralBackoffMs?: number;
     readonly onRunSettled?: (input: {
         readonly context: ExecutionContext;
         readonly run: Run;
         readonly outcome: "completed" | "failed" | "cancelled";
     }) => Promise<void> | void;
 };
-export type ProcessOutcome = "completed" | "failed" | "cancelled" | "skipped" | "lost" | "paused";
+/**
+ * `deferred` is distinct from `skipped`, and conflating them would strand work — #265.
+ *
+ * `skipped` means *somebody else has this, or it is already finished* — there is nothing to do and the job is
+ * done with. `deferred` means *this tenant is at its concurrency limit right now*: the run is still queued, it
+ * still needs to run, and a caller that acknowledged it the way it acknowledges a `skipped` job would drop it
+ * for ever. A `deferred` result must be re-enqueued, and `ProcessResult.retryAfterMs` says when.
+ */
+export type ProcessOutcome = "completed" | "failed" | "cancelled" | "skipped" | "lost" | "paused" | "deferred";
 export type ProcessResult = {
     readonly run: Run | null;
     readonly outcome: ProcessOutcome;
+    /**
+     * How long to wait before trying this run again. Set only for `deferred`.
+     *
+     * Without it a deferred run is re-enqueued immediately and spins against the cap, burning a worker slot on
+     * the check itself — which would make a concurrency limit cost more capacity than it saves.
+     */
+    readonly retryAfterMs?: number;
 };
 export declare const createDurableWorker: (deps: DurableWorkerDeps) => {
     /** Claim (under an optional lock) and drive a run. Idempotent: a claimed/terminal run is skipped. */

package/dist/runtime/worker.js

@@ -37,6 +37,7 @@ export const createDurableWorker = (deps) => {
     const clock = deps.clock ?? (() => new Date(now()).toISOString());
     const leaseMs = deps.leaseMs ?? 30_000;
     const keepaliveEveryMs = deps.keepaliveEveryMs ?? Math.max(1, Math.floor(leaseMs / 3));
+    const deferralBackoffMs = Math.max(1, deps.deferralBackoffMs ?? 1_000);
     const channelFor = deps.channelFor ?? ((r) => `conversation:${r.conversationId}`);
     const { runs, checkpoints, publisher, engine, workerId } = deps;
     /** Drive one already-claimed run to a terminal state. */
@@ -114,6 +115,7 @@ export const createDurableWorker = (deps) => {
                     inputTokens: event.inputTokens,
                     outputTokens: event.outputTokens,
                     cachedInputTokens: event.cachedInputTokens ?? 0,
+                    ...(event.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: event.cacheWriteTokens }),
                     ...(event.reasoningTokens === undefined ? {} : { reasoningTokens: event.reasoningTokens }),
                     ...(event.imageCount === undefined ? {} : { imageCount: event.imageCount }),
                     ...(event.audioSeconds === undefined ? {} : { audioSeconds: event.audioSeconds }),
@@ -322,7 +324,13 @@ export const createDurableWorker = (deps) => {
                     pause = "waiting-for-question";
                 else if (body.type === "approval.requested")
                     pause = "waiting-for-approval";
-                else if (body.type === "question.answered" || body.type === "approval.decided")
+                // The third pause — #264. Same shape as the other two: an event the engine emits, a status the worker
+                // parks in, and a resume back to `queued`.
+                else if (body.type === "connection.requested")
+                    pause = "waiting-for-connection";
+                else if (body.type === "question.answered" ||
+                    body.type === "approval.decided" ||
+                    body.type === "connection.completed")
                     pause = null;
                 await heartbeat(); // throttled; runs on every event so a tool-heavy run keeps its lease alive
                 if (cancelRequested)
@@ -382,9 +390,34 @@ export const createDurableWorker = (deps) => {
             if (!lock)
                 return { run: await runs.findById({ tenantId, id: runId }), outcome: "skipped" };
             try {
-                const claimed = await runs.claim({ tenantId, id: runId, workerId, leaseMs, now: clock() });
-                if (!claimed)
-                    return { run: await runs.findById({ tenantId, id: runId }), outcome: "skipped" };
+                const maxConcurrent = await deps.concurrencyFor?.(tenantId);
+                const now = clock();
+                const claimed = await runs.claim({
+                    tenantId,
+                    id: runId,
+                    workerId,
+                    leaseMs,
+                    now,
+                    ...(maxConcurrent === undefined ? {} : { maxConcurrent }),
+                });
+                if (!claimed) {
+                    const run = await runs.findById({ tenantId, id: runId });
+                    /**
+                     * Why the claim failed, diagnosed *after* the fact — #265.
+                     *
+                     * The decision was already made atomically inside `claim`; this only chooses which outcome to report,
+                     * so a slightly stale count costs a wrong label rather than a wrong admission. The run being still
+                     * `queued` is the discriminator: a run somebody else is driving is `running`, and a finished one is
+                     * terminal, so `queued` after a refused claim means the cap is what stopped it.
+                     */
+                    if (maxConcurrent !== undefined && maxConcurrent > 0 && run?.status === "queued") {
+                        const live = await runs.countLive({ tenantId, now });
+                        if (live >= maxConcurrent) {
+                            return { run, outcome: "deferred", retryAfterMs: deferralBackoffMs };
+                        }
+                    }
+                    return { run, outcome: "skipped" };
+                }
                 return await drive(claimed);
             }
             finally {

package/dist/security/checklist.js

@@ -190,6 +190,52 @@ export const SECURITY_CHECKS = [
  * forgotten case.
  */
 export const CREDENTIAL_FIELD_EXEMPTIONS = [
+    {
+        file: "connections/oauth/client.ts",
+        reason: "`ResolvedOAuthClient.clientSecret` and `registerTenantOAuthApp`'s parameter are a *tenant's own* OAuth " +
+            "client secret, which is exactly as much a secret as the deployment's above and is treated more " +
+            "carefully, not less: it is sealed by the same `SecretCipher` as every access token before it reaches " +
+            "the database, and the stored row holds ciphertext — asserted by the same raw-row test that covers " +
+            "connections. It exists in memory only between being opened for one flow and being handed to the token " +
+            "request, is never written to a table in plaintext, never placed in a message part, a result envelope or " +
+            "an audit row, and never put in an authorization URL. The readable half of a registration — client id, " +
+            "redirect URIs, scopes — is deliberately *not* sealed, so a settings screen renders without a key.",
+    },
+    {
+        file: "connections/oauth/index.ts",
+        reason: "`OAuthProviderConfig.clientSecret` is the *deployment's own* OAuth client secret, supplied by the host " +
+            "at wiring time — the same shape and the same limits as the model provider's key above. It goes into one " +
+            "token-request body over the back channel and is never put in an authorization URL, because a secret in " +
+            "a URL is in the browser history, the referrer header and every proxy log between. `TokenResponse` " +
+            "carries `accessToken`/`refreshToken` for the moments between the exchange and sealing them: the " +
+            "connection service passes them straight to `SecretCipher.seal`, and what reaches the database is " +
+            "ciphertext. Neither is written to a table, placed in a message part or a result envelope, and the " +
+            "provider's own error body is deliberately not echoed because it routinely quotes the request.",
+    },
+    {
+        file: "tools/credentials.ts",
+        reason: "The `Credential` union is the *resolved* value — the one place a third-party secret legitimately exists, " +
+            "for the duration of one call. `password` and the other secret-bearing fields are named honestly rather " +
+            "than hidden behind a generic `value`, because a `basic` credential genuinely has two parts and calling " +
+            "them `a` and `b` would make every call site guess. This module is what makes this the *only* such place: " +
+            "it is why a tool takes a `credentialRef` instead of a secret, and why nothing is stored on the tool. " +
+            "The exemption comes with compensating controls rather than on its own — #260 defines the secret fields " +
+            "**non-enumerably** and overrides `toJSON`, `toString` and `util.inspect`, so a spread, a " +
+            "`JSON.stringify` or a `console.log` of a credential yields `[credential redacted]` and never the secret. " +
+            "It is still never written to a table, never placed in a message part, a result envelope or an audit " +
+            "row, and `CredentialAudit` receives the scheme and the ref, never the value.",
+    },
+    {
+        file: "adapters/audio/openai.ts",
+        reason: "`OpenAiAudioConfig.apiKey` is the *deployment's own* provider key, supplied by the host at wiring time — " +
+            "the same shape, the same limits and the same reasoning as the embeddings adapter and the model provider " +
+            "factory. It reaches one `authorization` header on an operator-configured endpoint and nowhere else: it " +
+            "is never written to a table, never placed in a message part, a result envelope or an audit row, and the " +
+            "provider's error body is truncated rather than echoed whole. A `credentialRef` would be the wrong shape " +
+            "here for the reason it is wrong for the model provider — this is one deployment's key for its own " +
+            "provider account, not a per-tenant third-party grant, and routing it through the credential resolver " +
+            "would imply a per-tenant secret that does not exist.",
+    },
     {
         file: "models/provider-factory.ts",
         reason: "`ProviderCredentials.apiKey` is the model provider's own key, supplied by the host at wiring time and " +
@@ -198,6 +244,15 @@ export const CREDENTIAL_FIELD_EXEMPTIONS = [
             "credential must exist in memory to authenticate; what AC-1 forbids is storing, passing, returning or " +
             "logging one, and none of those happen here.",
     },
+    {
+        file: "adapters/embeddings/openai.ts",
+        reason: "`OpenAiEmbeddingsConfig.apiKey` is the same shape as the model provider's, for the same reason and with " +
+            "the same limits: a key the host supplies at wiring time and this adapter puts in one Authorization " +
+            "header. Process-local — never written to a table, never in a message part or a result envelope, and no " +
+            "allowlisted log field could carry it. It is also never reachable from a model: an embedding is computed " +
+            "for a chunk the platform is indexing, not for text a model asked about, so there is no input path that " +
+            "could name or read it.",
+    },
 ];
 /** Checks with no automated backing. The set a person must actually walk at each release. */
 export const manualChecks = () => SECURITY_CHECKS.filter((check) => check.verifiedBy === "manual");

package/dist/security/findings.js

@@ -134,19 +134,28 @@ export const FINDINGS = [
         id: "SEC-006",
         area: "egress",
         severity: "informational",
-        title: "There is no research or web-fetch path to audit",
+        title: "The web-fetch path exists now, and the audit had been passing it for the wrong reason",
         impact: "AC-2 asks for the allow-list to be enforced at a single point covered by *both* the research and MCP paths. " +
-            "The research path does not exist in this package: the only outbound HTTP is the MCP transport and the " +
-            "Supabase storage adapter, whose destination is operator configuration rather than a model's choice. So the " +
-            "single-point property holds trivially today and is not evidence that it will hold once research lands.",
-        foundBy: "grepping for every `fetch(` call in the tree and finding two, neither model-directed",
+            "When this was written the research path did not exist and the property held trivially. It exists now — " +
+            "REQ-039 (#188) shipped `fetch_url`, `fetch_json`, `http_request` and `http_write`, all through " +
+            "`toolkit/http.ts`, and #219 added an embedding adapter — so the property is real rather than trivial: the " +
+            "model-directed path goes through `validateHttpEgress`, which refuses private ranges, cloud metadata, " +
+            "non-https schemes, credentials in the URL and followed redirects.\n\n" +
+            "The finding that replaces the original: the audit asserting 'no other outbound call' matched `fetch(` and " +
+            "not `?? fetch`, and every injectable client in this codebase captures the global that way. So " +
+            "`toolkit/http.ts` had never appeared in that check at all. Not a vulnerability — its destination was " +
+            "policed throughout — but the check was passing it by accident, and would have passed the next such file " +
+            "the same way.",
+        foundBy: "adding a third outbound path in #219 and asking why the audit's allow-list had only ever had three " +
+            "entries when the tree had four outbound sites",
         resolution: {
             kind: "accepted",
             owner: "azeem@snipe-solutions.de",
-            reason: "Nothing to fix; recording it so the AC is not read as stronger than the evidence. A test asserts the " +
-                "*absence* of any other outbound call, so adding one fails the audit and forces the author to route it " +
-                "through `validateEndpoint` — which is the durable version of this guarantee.",
-            revisitBy: "when a research or web-fetch tool is implemented",
+            reason: "The audit now matches a captured `fetch` as well as a called one, and its allow-list names five paths " +
+                "with the reason each destination is auditable. Adding a sixth fails the test and forces its author to " +
+                "say which policy governs the destination — which is the durable version of this guarantee, and is what " +
+                "the original entry was reaching for before there was anything to govern.",
+            revisitBy: "2027-06-30",
         },
     },
 ];

package/dist/server/bin.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * `retinue` — the executable, task #252.
+ *
+ * `cli.ts` and `cli-worker.ts` have been here since #110 and the package had **no `bin`**, so a consumer had to
+ * write an entrypoint before anything ran. Applying the schema was the sharpest case:
+ * `adapters/postgres/migrations.ts` is a module, so provisioning a database meant writing a program first.
+ *
+ * ## What this does and does not invent
+ *
+ * It does not invent a deployment's wiring. `serve` and `worker` load `RETINUE_APP_MODULE` exactly as they did,
+ * and refuse to start without it — a permissive default would serve an open API to anyone who forgot to set it,
+ * which is the rule `cli.ts` established and this keeps.
+ *
+ * `migrate` and `doctor` deliberately need **no** app module: a database is provisioned before an application
+ * exists, and a diagnostic that cannot run until everything else is configured is a diagnostic nobody can use.
+ */
+export declare const main: (argv: readonly string[], env?: NodeJS.ProcessEnv) => Promise<number>;
+//# sourceMappingURL=bin.d.ts.map

package/dist/server/bin.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * `retinue` — the executable, task #252.
+ *
+ * `cli.ts` and `cli-worker.ts` have been here since #110 and the package had **no `bin`**, so a consumer had to
+ * write an entrypoint before anything ran. Applying the schema was the sharpest case:
+ * `adapters/postgres/migrations.ts` is a module, so provisioning a database meant writing a program first.
+ *
+ * ## What this does and does not invent
+ *
+ * It does not invent a deployment's wiring. `serve` and `worker` load `RETINUE_APP_MODULE` exactly as they did,
+ * and refuse to start without it — a permissive default would serve an open API to anyone who forgot to set it,
+ * which is the rule `cli.ts` established and this keeps.
+ *
+ * `migrate` and `doctor` deliberately need **no** app module: a database is provisioned before an application
+ * exists, and a diagnostic that cannot run until everything else is configured is a diagnostic nobody can use.
+ */
+import { runApiHost } from "./cli.js";
+import { runWorker } from "./cli-worker.js";
+import { loadConfig } from "./config.js";
+import { report, runChecks } from "./doctor.js";
+const USAGE = `retinue <command>
+
+  migrate            Apply pending migrations to RETINUE_DATABASE_URL.
+    --status         Report applied and pending migrations; change nothing.
+    --dry-run        Print the statements that would run; change nothing.
+  serve              Start the API host. Needs RETINUE_APP_MODULE.
+  worker             Start a run worker. Needs RETINUE_APP_MODULE.
+  doctor             Check configuration, database, schema and Redis. Reports every failure.
+
+Configuration comes from the environment; see .env.example.`;
+/** Opened lazily and per command, so `doctor` and `migrate` never load a driver they do not use. */
+const postgres = async (url) => {
+    const { Pool } = await import("pg");
+    const { createPgExecutor, createPoolOpener } = await import("../entries/adapters-postgres.js");
+    // A connect timeout, because the default is *none*: `doctor` against a refused port sat silently instead of
+    // reporting the failure it exists to report. Short, since every command here either connects immediately or
+    // is misconfigured.
+    const pool = new Pool({ connectionString: url, connectionTimeoutMillis: 5_000 });
+    return { sql: createPgExecutor(pool), open: createPoolOpener(pool), end: () => pool.end() };
+};
+/**
+ * The advisory-lock key comes from `schema.ts` — #252's AC-2, and #266's AC-4.
+ *
+ * It used to be defined here. That made "the CLI and `auto` mode use the same key" a property of two constants
+ * happening to be equal, and a copy that drifted would produce two locks, no serialisation, and the original
+ * crash returning with the fix apparently in place. Two constants that must be equal are one constant.
+ */
+const migrate = async (flags, env = process.env) => {
+    const config = loadConfig(env);
+    const { sql, open, end } = await postgres(config.databaseUrl);
+    try {
+        const { createSchemaManager, MIGRATION_LOCK } = await import("../entries/adapters-postgres.js");
+        if (flags.has("--status") || flags.has("--dry-run")) {
+            // Read-only paths take no lock. `plan()` and `currentVersion()` are documented as side-effect free — only
+            // `apply()` creates the ledger table — which is what makes a dry run honest rather than a dry run that
+            // provisions one table. Verified: after `--dry-run` against a fresh database, `public` has 0 tables.
+            const manager = createSchemaManager(sql);
+            const pending = await manager.plan();
+            const current = await manager.currentVersion();
+            const target = manager.targetVersion();
+            if (flags.has("--status")) {
+                console.log(`schema: ${current} of ${target} migrations applied`);
+                for (const change of pending)
+                    console.log(`  pending ${change.id} (${change.statements.length} statement(s))`);
+                if (pending.length === 0)
+                    console.log("  nothing pending");
+                return 0;
+            }
+            console.log(`schema: ${current} of ${target} applied; ${pending.length} pending`);
+            for (const change of pending) {
+                console.log(`\n-- ${change.id}`);
+                for (const statement of change.statements)
+                    console.log(`${statement};`);
+            }
+            return 0;
+        }
+        /**
+         * Applied under a session advisory lock, on **one** connection — AC-2.
+         *
+         * Measured before this existed: two concurrent `retinue migrate` runs against one database left the ledger
+         * correct (30 rows, 30 distinct) and **crashed one process** with
+         * `duplicate key value violates unique constraint "pg_type_typname_nsp_index"` — Postgres's own type
+         * catalogue, racing on DDL. The data was safe and the operator experience was not: running migrate from two
+         * pods, which is the ordinary Kubernetes init-container pattern, gives one crash loop and an error that
+         * names nothing an operator can act on.
+         *
+         * `createPoolOpener` rather than `createPgExecutor`, because `pool.query` picks a different connection per
+         * call — so a `pg_advisory_lock` taken through it would be held by a connection we might never get back, and
+         * the unlock would land elsewhere. One checked-out client makes the pair correct, and the lock is released
+         * by the session ending if the process dies mid-migration.
+         */
+        return await open(async (locked) => {
+            await locked.query("select pg_advisory_lock($1)", [MIGRATION_LOCK]);
+            try {
+                const manager = createSchemaManager(locked);
+                const pending = await manager.plan();
+                const target = manager.targetVersion();
+                if (pending.length === 0) {
+                    console.log(`schema already at ${target}; nothing to apply`);
+                    return 0;
+                }
+                await manager.apply();
+                console.log(`applied ${pending.length} migration(s); schema now at ${await manager.currentVersion()}`);
+                return 0;
+            }
+            finally {
+                await locked.query("select pg_advisory_unlock($1)", [MIGRATION_LOCK]);
+            }
+        });
+    }
+    finally {
+        await end();
+    }
+};
+const doctor = async (env = process.env) => {
+    const results = await runChecks({
+        env,
+        connectPostgres: async (url) => {
+            const { sql, end } = await postgres(url);
+            return { query: (text, params) => sql.query(text, params), end };
+        },
+        connectRedis: async (url) => {
+            const { Redis } = await import("ioredis");
+            /**
+             * Fail fast, on every axis ioredis has one.
+             *
+             * `maxRetriesPerRequest` alone was not enough: it bounds *command* retries, and a refused **connection**
+             * is retried for ever by the default `retryStrategy`. So `doctor` against a closed port hung rather than
+             * reporting it. `retryStrategy: () => null` stops reconnecting, `enableOfflineQueue: false` makes a
+             * command fail immediately instead of queueing for a connection that will never come, and `connectTimeout`
+             * bounds the first attempt.
+             */
+            const redis = new Redis(url, {
+                maxRetriesPerRequest: 1,
+                connectTimeout: 3_000,
+                // No reconnection: a refused connection must fail, not be retried behind a spinner.
+                retryStrategy: () => null,
+                /**
+                 * The offline queue stays **on**, and that is a correction.
+                 *
+                 * Turning it off made the check fail against a *working* Redis: `lazyConnect: false` starts connecting
+                 * but `ping()` is called before the socket is ready, and with no offline queue the command is rejected
+                 * immediately with "Stream isn't writeable". So the queue is what lets the first command wait for the
+                 * connection; `retryStrategy` and `connectTimeout` are what stop it waiting for ever, and `withTimeout`
+                 * is the backstop.
+                 */
+                lazyConnect: false,
+            });
+            // Otherwise an unreachable Redis emits an unhandled 'error' and takes the process down before the report.
+            redis.on("error", () => undefined);
+            return {
+                ping: () => redis.ping(),
+                /**
+                 * `disconnect()`, not `quit()`, and wrapped so it is always a promise.
+                 *
+                 * `quit()` sends a QUIT command, which needs a working connection — so on the failure path it hangs or
+                 * rejects, which is the path where closing matters most. `disconnect()` drops the socket unilaterally.
+                 * It returns `void`, and returning that raw produced `Cannot read properties of undefined (reading
+                 * 'catch')` in the caller's cleanup.
+                 */
+                quit: async () => {
+                    redis.disconnect();
+                },
+            };
+        },
+        schemaVersions: async (sql) => {
+            const { createSchemaManager, MIGRATION_LOCK } = await import("../entries/adapters-postgres.js");
+            const manager = createSchemaManager(sql);
+            return { current: await manager.currentVersion(), target: manager.targetVersion() };
+        },
+    });
+    return report(results);
+};
+export const main = async (argv, env = process.env) => {
+    const [command, ...rest] = argv;
+    const flags = new Set(rest.filter((a) => a.startsWith("--")));
+    switch (command) {
+        case "migrate":
+            return migrate(flags, env);
+        case "doctor":
+            return doctor(env);
+        case "serve":
+            await runApiHost(env);
+            // Resolves once listening; the process stays alive on the server's own handles.
+            return 0;
+        case "worker":
+            await runWorker(env);
+            return 0;
+        case undefined:
+        case "--help":
+        case "-h":
+        case "help":
+            console.log(USAGE);
+            return command === undefined ? 1 : 0;
+        default:
+            console.error(`unknown command "${command}"\n\n${USAGE}`);
+            return 1;
+    }
+};
+/** Commands that finish and must return the prompt. `serve` and `worker` deliberately do not. */
+const ONE_SHOT = new Set(["migrate", "doctor", "help", "--help", "-h"]);
+// Only when invoked as the binary, so importing this module for a test starts nothing.
+if (process.argv[1] !== undefined && /(^|\/)(retinue|bin\.js)$/.test(process.argv[1])) {
+    const command = process.argv[2];
+    main(process.argv.slice(2))
+        .then((code) => {
+        /**
+         * A one-shot command **exits**, rather than setting `exitCode` and hoping the loop drains.
+         *
+         * `doctor` reported correctly and then hung: a driver that has been asked to stop reconnecting can still
+         * hold a socket handle, and one lingering handle keeps Node alive for ever. Closing every client is the
+         * fix and this is the guarantee — a diagnostic that never returns the prompt is a diagnostic nobody runs
+         * twice. `serve` and `worker` are excluded because their whole job is to stay up.
+         */
+        if (command === undefined || ONE_SHOT.has(command))
+            process.exit(code);
+        if (code !== 0)
+            process.exitCode = code;
+    })
+        .catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=bin.js.map

package/dist/server/boot.d.ts

@@ -5,7 +5,8 @@
  * substance: configuration is validated *before* anything connects, so a misconfigured deployment
  * fails with a message about the variable rather than a connection error that names nothing useful.
  */
-import { type SchemaMode, type SqlExecutor } from "../entries/adapters-postgres.js";
+import { type ConnectionOpener, type SchemaMode, type SqlExecutor } from "../entries/adapters-postgres.js";
+import { type TransactionRunner } from "../adapters/postgres/transaction.js";
 import { type RetinueConfig, type Env } from "./config.js";
 export type StartupLog = {
     readonly event: string;
@@ -13,16 +14,33 @@ export type StartupLog = {
 };
 export type BootOptions = {
     readonly env: Env;
-    /** Built after configuration validates, so a bad variable never opens a connection. */
+    /**
+     * Built after configuration validates, so a bad variable never opens a connection.
+     *
+     * `open` is optional and is what a `TransactionRunner` needs — the one primitive a pool-backed `SqlExecutor`
+     * cannot express, because `pool.query` picks a different connection per call. A caller that supplies it gets a
+     * runner in the result; one that does not gets `undefined`, and anything needing a transaction refuses by name.
+     */
     readonly connect: (config: RetinueConfig) => Promise<{
         readonly sql: SqlExecutor;
+        readonly open?: ConnectionOpener;
     }>;
     readonly log?: (entry: StartupLog) => void;
     readonly version?: string;
 };
 export type BootResult = {
     readonly config: RetinueConfig;
+    /**
+     * The executor an application should build its stores over.
+     *
+     * **Scoped when a runner exists**, so a store built on it joins the ambient transaction without knowing
+     * transactions exist. Handing back the unscoped executor alongside a runner is the trap
+     * `transaction.ts` warns about: "a store built over a *non*-scoped executor silently escapes the
+     * transaction rather than failing".
+     */
     readonly sql: SqlExecutor;
+    /** Present when `connect` supplied an `open`. `undefined` for a process that needs no transactions. */
+    readonly runner?: TransactionRunner;
     readonly schema: {
         readonly mode: SchemaMode;
         readonly applied: readonly string[];

package/dist/server/boot.js

@@ -5,16 +5,37 @@
  * substance: configuration is validated *before* anything connects, so a misconfigured deployment
  * fails with a message about the variable rather than a connection error that names nothing useful.
  */
-import { provisionSchema } from "../entries/adapters-postgres.js";
+import { provisionSchema, } from "../entries/adapters-postgres.js";
+import { createTransactionScope } from "../adapters/postgres/transaction.js";
 import { loadConfig } from "./config.js";
 export const boot = async (options) => {
     const log = options.log ?? ((entry) => console.log(JSON.stringify(entry)));
     // Configuration first, and it throws. A half-configured process that boots is worse than one that
     // refuses: it passes its own health check and fails on the first real request.
     const config = loadConfig(options.env);
-    const { sql } = await options.connect(config);
+    const { sql: base, open } = await options.connect(config);
+    /**
+     * The transaction scope, when the caller can open a connection — found by #254.
+     *
+     * `runApiHost` never built one, so `app.deps({ config, sql })` was called without a runner and the reference
+     * app's coordinator refused: *"this process has no TransactionRunner, so the conversation run coordinator
+     * cannot be used. The API host supplies one"*. It did not. `sendMessage` — the mutation that starts every run
+     * — therefore failed with an internal error in the shipped API host and in `npm run api`, which is the
+     * documented way to run the reference app.
+     */
+    const scope = open === undefined ? undefined : createTransactionScope(open);
+    const sql = scope === undefined ? base : scope.scoped(base);
     const provisioned = await provisionSchema(sql, {
         mode: config.schemaMode,
+        /**
+         * Passed so `auto` mode serialises — #266.
+         *
+         * Several workers booting against a fresh database is the ordinary Kubernetes init pattern, and without
+         * this one of them crashes on Postgres's own type catalogue with an error naming nothing actionable.
+         * `undefined` for a process whose adapter cannot hold a connection, which is correct: those are
+         * single-process and have nothing to race with.
+         */
+        ...(open === undefined ? {} : { open }),
         // Routed through the structured log rather than printed, so `plan` mode's diff is machine-readable
         // in the same stream as everything else.
         log: (message) => log({ event: "schema", mode: config.schemaMode, message }),
@@ -31,6 +52,11 @@ export const boot = async (options) => {
         // The adapters actually selected, so a support question does not start with "which database?".
         adapters: { store: "postgres", queue: "bullmq", lock: "redis" },
     });
-    return { config, sql, schema: { mode: config.schemaMode, applied: provisioned.applied } };
+    return {
+        config,
+        sql,
+        ...(scope === undefined ? {} : { runner: scope.runner }),
+        schema: { mode: config.schemaMode, applied: provisioned.applied },
+    };
 };
 //# sourceMappingURL=boot.js.map

package/dist/server/cli.d.ts

@@ -2,6 +2,7 @@ import { type Authenticate } from "./host.js";
 import { type RetinueConfig } from "./config.js";
 import type { ResolverDeps } from "../index.js";
 import type { SqlExecutor } from "../entries/adapters-postgres.js";
+import type { TransactionRunner } from "../adapters/postgres/transaction.js";
 /**
  * What a deployment's app module must default-export.
  *
@@ -10,9 +11,21 @@ import type { SqlExecutor } from "../entries/adapters-postgres.js";
  */
 export type RetinueApp = {
     readonly authenticate: Authenticate;
+    /**
+     * `runner` added by #254, and it was not optional in practice — it was missing.
+     *
+     * The reference app's `deps` has always accepted an optional `TransactionRunner`, and this host never passed
+     * one, so the conversation run coordinator refused with *"this process has no TransactionRunner… The API host
+     * supplies one"*. It did not. `sendMessage` — the mutation that starts every run — failed with an internal
+     * error in this command and in `npm run api`, which is the documented way to run the reference app.
+     *
+     * Still optional on the signature, because a worker genuinely does not need it and an app that ignores it
+     * keeps compiling.
+     */
     readonly deps: (input: {
         readonly config: RetinueConfig;
         readonly sql: SqlExecutor;
+        readonly runner?: TransactionRunner;
     }) => Promise<ResolverDeps> | ResolverDeps;
     /** Optional liveness/readiness extras beyond Postgres, Redis and the schema version. */
     readonly redis?: (config: RetinueConfig) => {