@retinue/agentkit 0.2.0 → 0.3.1

package/dist/runtime/index.d.ts

@@ -3,7 +3,7 @@
  */
 import type { PlatformError } from "../core/errors.js";
 import type { AgentId, ConversationId, PrincipalId, RunId, TenantId } from "../core/ids.js";
-export declare const RUN_STATUSES: readonly ["queued", "running", "waiting-for-question", "waiting-for-approval", "retry-pending", "completed", "failed", "cancelled"];
+export declare const RUN_STATUSES: readonly ["queued", "running", "waiting-for-question", "waiting-for-approval", "waiting-for-connection", "retry-pending", "completed", "failed", "cancelled"];
 export type RunStatus = (typeof RUN_STATUSES)[number];
 /**
  * The state machine from the specification. A transition absent from this map is a

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 " +

package/dist/server/bin.d.ts

@@ -0,0 +1,72 @@
+#!/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.
+ */
+/**
+ * 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.
+ */
+/**
+ * Create the configured schema if it is not there, before anything tries to use it.
+ *
+ * `migrate` is the command that owns provisioning, so the namespace it was told to provision into is
+ * its job too — and the reason is worse than a missing-schema error. **Postgres does not error.**
+ * `SET search_path TO retinue, public` succeeds when `retinue` does not exist: a missing entry is
+ * skipped, not rejected. `CREATE TABLE conversations` then lands in the first schema that *does*
+ * exist, which is `public` — so all 34 platform migrations would silently be created alongside the
+ * product's tables, reporting success the whole way. Verified against a real Postgres 17: the SET
+ * returns, the CREATE returns, and `information_schema` says `public`.
+ *
+ * That is the failure this function exists to prevent, and it is why it runs before the pool rather
+ * than relying on a connection error that never comes.
+ *
+ * On its own connection with the **default** search path, which is the part that is easy to get wrong.
+ * A connection configured for `retinue` cannot be the one that creates `retinue` — `openPostgres`
+ * destroys it during setup, before a statement of ours runs.
+ *
+ * `IF NOT EXISTS` and nothing else: no owner, no grants, no drop. Provisioning a namespace is additive;
+ * deciding who may use it is a deployment's decision and not a migration's.
+ */
+/**
+ * Which `migrate` invocations must change nothing.
+ *
+ * Its own function because it is the link between a flag and a side effect, and that link is invisible
+ * to a test of either end: sabotaging it to `false` — so `--dry-run` provisions a schema — broke
+ * nothing, while every assertion about `ensureSchema` itself stayed green. The list is also the same
+ * one the read-only branch below uses, so a third flag added to one and not the other cannot silently
+ * become a writing dry run.
+ */
+export declare const READ_ONLY_FLAGS: readonly ["--status", "--dry-run"];
+export declare const isReadOnly: (flags: ReadonlySet<string>) => boolean;
+export declare const ensureSchema: (config: {
+    readonly databaseUrl: string;
+    readonly databaseSchema?: string;
+}, { create, connect, }: {
+    readonly create: boolean;
+    readonly connect?: (settings: {
+        readonly databaseUrl: string;
+    }) => Promise<{
+        readonly sql: {
+            query<Row>(text: string, params?: readonly unknown[]): Promise<Row[]>;
+        };
+        readonly end: () => Promise<void>;
+    }>;
+}) => Promise<boolean>;
+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,304 @@
+#!/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.
+ *
+ * The pool itself comes from `pool.ts`, which is also what the API host and the worker use — the schema
+ * a deployment configures has to be the same one migrations run against, and that is only true while
+ * there is one place that decides it.
+ *
+ * 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 postgres = async (config) => {
+    const { openPostgres } = await import("./pool.js");
+    return openPostgres({ ...config, connectionTimeoutMillis: 5_000 });
+};
+/**
+ * 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.
+ */
+/**
+ * Create the configured schema if it is not there, before anything tries to use it.
+ *
+ * `migrate` is the command that owns provisioning, so the namespace it was told to provision into is
+ * its job too — and the reason is worse than a missing-schema error. **Postgres does not error.**
+ * `SET search_path TO retinue, public` succeeds when `retinue` does not exist: a missing entry is
+ * skipped, not rejected. `CREATE TABLE conversations` then lands in the first schema that *does*
+ * exist, which is `public` — so all 34 platform migrations would silently be created alongside the
+ * product's tables, reporting success the whole way. Verified against a real Postgres 17: the SET
+ * returns, the CREATE returns, and `information_schema` says `public`.
+ *
+ * That is the failure this function exists to prevent, and it is why it runs before the pool rather
+ * than relying on a connection error that never comes.
+ *
+ * On its own connection with the **default** search path, which is the part that is easy to get wrong.
+ * A connection configured for `retinue` cannot be the one that creates `retinue` — `openPostgres`
+ * destroys it during setup, before a statement of ours runs.
+ *
+ * `IF NOT EXISTS` and nothing else: no owner, no grants, no drop. Provisioning a namespace is additive;
+ * deciding who may use it is a deployment's decision and not a migration's.
+ */
+/**
+ * Which `migrate` invocations must change nothing.
+ *
+ * Its own function because it is the link between a flag and a side effect, and that link is invisible
+ * to a test of either end: sabotaging it to `false` — so `--dry-run` provisions a schema — broke
+ * nothing, while every assertion about `ensureSchema` itself stayed green. The list is also the same
+ * one the read-only branch below uses, so a third flag added to one and not the other cannot silently
+ * become a writing dry run.
+ */
+export const READ_ONLY_FLAGS = ["--status", "--dry-run"];
+export const isReadOnly = (flags) => READ_ONLY_FLAGS.some((flag) => flags.has(flag));
+export const ensureSchema = async (config, { create, 
+// Injectable so a test can run this against a real Postgres — PGlite — without a live server. The
+// default is the same `postgres` every command here uses.
+connect = (settings) => postgres(settings), }) => {
+    if (config.databaseSchema === undefined)
+        return true;
+    const { sql, end } = await connect({ databaseUrl: config.databaseUrl });
+    try {
+        if (create) {
+            // Validated as an unquoted identifier by `loadConfig` — the only reason this concatenation is safe,
+            // and the reason that check refuses anything Postgres would need quoted.
+            await sql.query(`CREATE SCHEMA IF NOT EXISTS ${config.databaseSchema}`);
+            console.log(`schema: ${config.databaseSchema} ready`);
+            return true;
+        }
+        /**
+         * The read-only paths report instead of creating, and that is not fussiness.
+         *
+         * `--dry-run` and `--status` are documented a few lines below as side-effect free — the note says
+         * `public` has 0 tables after a dry run against a fresh database — and a reader deciding whether to
+         * trust a dry run is exactly the reader who must not find it provisioned a schema. Creating one is
+         * a small side effect and a large broken promise.
+         */
+        const rows = await sql.query(`select exists (select 1 from pg_namespace where nspname = $1) as exists`, [config.databaseSchema]);
+        if (rows[0]?.exists === true)
+            return true;
+        console.error(`schema: ${config.databaseSchema} does not exist. Postgres will not complain — it skips a missing ` +
+            `entry in search_path — so tables would be created in the next schema on the path instead, ` +
+            `silently. Run \`retinue migrate\`, which creates it, or unset RETINUE_DATABASE_SCHEMA to use the ` +
+            `connection's own schema deliberately.`);
+        return false;
+    }
+    finally {
+        await end();
+    }
+};
+const migrate = async (flags, env = process.env) => {
+    const config = loadConfig(env);
+    // Before the pool, because a missing schema does not fail: `SET search_path` skips an entry that does
+    // not exist and every CREATE lands in `public` instead, silently. The read-only flags report rather
+    // than create — see `ensureSchema`.
+    if (!(await ensureSchema(config, { create: !isReadOnly(flags) })))
+        return 1;
+    const { sql, open, end } = await postgres(config);
+    try {
+        const { createSchemaManager, MIGRATION_LOCK } = await import("../entries/adapters-postgres.js");
+        if (isReadOnly(flags)) {
+            // 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 (settings) => {
+            const { sql, end } = await postgres(settings);
+            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[];