melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/workflow.js

@@ -41,16 +41,23 @@
  * A delegated `yaml_reference` to a workflow syndicate is the whole graph,
  * walked under the subagent entry's name and description on a child
  * session (lib/compileNative.ts workflowSubagentOf); its answer is the
- * graph's last event's text. A nested workflow with an
- * `ask_user` node is refused by name (lib/compile.ts compileWorkflowSpec): a
- * pause inside a tool call cannot reach the caller (ADR 0028).
+ * graph's last event's text. A walk that pauses (an `ask_user` node, a
+ * gated agent node) leaves the call open, and the turn ends input-required
+ * with the agent path down to the node; the answer walks the graph again
+ * (lib/runtime/native/delegate.ts resumeWorkflowSubagent, ADR 0111).
  *
  * ── As a dispatch route or a workflow node (ADR 0106) ────────────────────
  * A `yaml_reference` to a workflow syndicate runs its whole graph there too,
- * on the child session filed under the entry's name, as a subagent does. A
- * route's answer is what the graph would answer as its own syndicate
- * (lib/runtime/syndicateTurn.ts); a node's is the nested walk's
- * (lib/workflow/turn.ts). A map over one is refused (lib/compile.ts).
+ * on the child session filed under the agent path and its kind
+ * (`<app>/route:<entry>`, `<walk's app>/node:<entry>`, ADR 0119, ADR 0120),
+ * as a subagent does. A route's answer is what the graph would
+ * answer as its own syndicate (lib/runtime/syndicateTurn.ts); a node's is
+ * the nested walk's (lib/workflow/turn.ts). A map over one is refused
+ * (lib/compile.ts). Its pauses (an `ask_user` node, a gate) reach the turn
+ * with the path from the entry down to the node that asked: a route's
+ * through the route's pause record in the conversation, a node's through
+ * its own pause on the caller's walk; the answer walks the nested graph
+ * again (ADR 0119).
  *
  * ── Approval gates (ADR 0098, ADR 0106) ──────────────────────────────────
  * A tool in a node agent's `require_approval`, and a skill script

package/dist/lib/workflowConfig.d.ts

@@ -80,6 +80,12 @@ export interface PendingInput {
     payload?: unknown;
     /** JSON Schema a structured answer must satisfy, when the node declared one. */
     schema?: unknown;
+    /**
+     * For a question asked inside a delegated subagent (ADR 0110): the agents
+     * from the turn's own agent down to the one that asked, `node` last.
+     * Absent when the turn's own agent (or a workflow node) asked.
+     */
+    path?: string[];
 }
 /** ADK's function-call name for a workflow input request. */
 export declare const INPUT_REQUEST = "adk_request_input";

package/dist/scripts/a2a_server.d.ts

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 import type { Server } from 'node:http';
 import { createA2AApp } from '../lib/a2a/app.ts';
+import type { SyndicateYamlConfig } from '../lib/loadSyndicate.ts';
+import type { OAuthServerSetup } from '../lib/a2a/oauthSetup.ts';
+import type { AuditSink } from '../lib/observability/audit.ts';
+import type { CredentialRows } from '../lib/tools/credentialStore.ts';
 export { describeTurnError } from '../lib/a2a/executor.ts';
 /**
  * What a deployment adds on top of the environment-driven server: its own
@@ -15,4 +19,36 @@ export interface ServerExtensions {
     /** Any other createA2AApp option; wins over what the environment sets. */
     options?: Partial<Parameters<typeof createA2AApp>[0]>;
 }
+/**
+ * The syndicates this server serves from FILES: the default (unless it is a
+ * registry row), each served id that is not a registry id, and, when every
+ * file is served (A2A_SERVED_AGENTS unset or *), every syndicate at the
+ * agents directory's root. The consent step's OAuth clients come from these
+ * only (ADR 0114): a registry row may name a provider they declare, never
+ * define one. A file that does not load is skipped with a warning (its route
+ * fails on its own).
+ */
+export declare function servedFileSyndicates(syndicateName: string, servedAgents: string[] | undefined, registryAgents: string[] | undefined, warn?: (m: string) => void): SyndicateYamlConfig[];
+/** The server's tool credentials, from the environment: what createA2AApp takes, and what to print. */
+export interface ServerOAuth extends OAuthServerSetup {
+    toolCredentials?: OAuthServerSetup['toolCredentials'] & {
+        requireCallerIdentity?: boolean;
+    };
+}
+/**
+ * Tool credentials and the consent step for the served syndicates, from
+ * MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI, OAUTH_CALLBACK_IDENTITY,
+ * MELCHIZEDEK_OAUTH_HOSTS and MELCHIZEDEK_CREDENTIAL_HOSTS (lib/a2a/oauthSetup.ts). Throws, naming
+ * variables only, on a configuration that is unsafe or cannot work.
+ */
+export declare function serverOAuth(options: {
+    syndicateName: string;
+    servedAgents?: string[];
+    registryAgents?: string[];
+    rows?: CredentialRows;
+    audit?: AuditSink;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+    warn?: (m: string) => void;
+}): ServerOAuth;
 export declare function startServer(syndicateName?: string, extensions?: ServerExtensions): Promise<Server>;

package/dist/scripts/a2a_server.js

@@ -75,9 +75,29 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *                             running turn (default 20). Behind a session-mode
  *                             pooler (Supabase :5432) keep the two sums under its
  *                             client limit, per instance.
+ *   MELCHIZEDEK_CREDENTIAL_KEY  32 random bytes (base64 or hex) that seal each user's
+ *                             third-party OAuth tokens (ADR 0072). Unset = no tool
+ *                             credentials. Rows live in Postgres with DATABASE_URL,
+ *                             else in process memory
+ *   OAUTH_REDIRECT_URI        the consent callback, exactly as registered at every
+ *                             provider (https://agents.example.com/oauth/callback);
+ *                             mounts the callback and lets a run ask a user to
+ *                             connect (ADR 0085). Needs MELCHIZEDEK_CREDENTIAL_KEY
+ *   OAUTH_CALLBACK_IDENTITY   required (default): the callback's browser must carry the
+ *                             flow's user's identity (A2A_AUTH=header behind a gateway);
+ *                             state: the single-use state nonce alone binds it (ADR 0114)
+ *   MELCHIZEDEK_OAUTH_HOSTS   provider=host,host;…: the hosts each provider's tokens may
+ *                             be sent to. Unset: authorization_code grants are refused,
+ *                             client_credentials allowed (ADR 0114)
+ *   MELCHIZEDEK_CREDENTIAL_HOSTS  VARIABLE=host,host;…: the hosts each static credential
+ *                             variable a YAML sends (bearer_env, api_key.env,
+ *                             client_secret_env) may be sent to. Set, it is the whole
+ *                             list. Unset: sent where the YAML says, and the boot names
+ *                             each unbound variable (ADR 0122)
  */
 import { randomBytes } from 'node:crypto';
-import { realpathSync, writeFileSync } from 'node:fs';
+import { readdirSync, realpathSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createA2AApp } from '../lib/a2a/app.js';
 import { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, sharedSecret, trustedHeader, } from '../lib/a2a/identity.js';
@@ -90,6 +110,11 @@ import { postgresStorage } from '../lib/storage/postgres/index.js';
 import { isPlaceholderValue, loadEnv } from '../lib/loadEnv.js';
 import { flushTracing } from '../lib/observability/tracer.js';
 import { setLogLevel } from '../lib/runtime/logging.js';
+import { loadSyndicate } from '../lib/loadSyndicate.js';
+import { callbackIdentity, callbackIdentityProblem, oauthServerSetup } from '../lib/a2a/oauthSetup.js';
+import { postgresCredentialRows } from '../lib/storage/postgres/credentialStore.js';
+import { setOAuthHosts } from '../lib/tools/oauthHosts.js';
+import { setCredentialHosts } from '../lib/tools/credentialHosts.js';
 // Re-exported for existing importers (tests/failNarration.test.ts).
 export { describeTurnError } from '../lib/a2a/executor.js';
 /** Minimum bearer-secret length below which the server warns. */
@@ -132,6 +157,87 @@ function fatal(message) {
     emit('error', `[A2A] ✗ FATAL: ${message}`);
     process.exit(1);
 }
+/**
+ * The syndicates this server serves from FILES: the default (unless it is a
+ * registry row), each served id that is not a registry id, and, when every
+ * file is served (A2A_SERVED_AGENTS unset or *), every syndicate at the
+ * agents directory's root. The consent step's OAuth clients come from these
+ * only (ADR 0114): a registry row may name a provider they declare, never
+ * define one. A file that does not load is skipped with a warning (its route
+ * fails on its own).
+ */
+export function servedFileSyndicates(syndicateName, servedAgents, registryAgents, warn = () => { }) {
+    const registry = new Set(registryAgents ?? []);
+    const files = new Set();
+    const add = (id) => {
+        if (id.startsWith('registry:') || registry.has(id))
+            return;
+        files.add(id.endsWith('.yaml') || id.endsWith('.yml') ? id : `${id}.yaml`);
+    };
+    add(syndicateName);
+    if (servedAgents) {
+        for (const id of servedAgents)
+            add(id);
+    }
+    else {
+        const agentsDir = path.resolve(process.env.MELCHIZEDEK_AGENTS_DIR ?? path.join(process.cwd(), 'config', 'agents'));
+        let names = [];
+        try {
+            names = readdirSync(agentsDir);
+        }
+        catch {
+            names = [];
+        }
+        for (const f of names.sort())
+            if ((f.endsWith('.yaml') || f.endsWith('.yml')) && f !== 'syndicateSchema.yaml')
+                files.add(f);
+    }
+    const out = [];
+    for (const file of files) {
+        try {
+            out.push(loadSyndicate(file, { shippedFallback: servedAgents !== undefined || file === syndicateName }));
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                warn(`OAuth setup skipped ${file}: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}`);
+        }
+    }
+    return out;
+}
+/**
+ * Tool credentials and the consent step for the served syndicates, from
+ * MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI, OAUTH_CALLBACK_IDENTITY,
+ * MELCHIZEDEK_OAUTH_HOSTS and MELCHIZEDEK_CREDENTIAL_HOSTS (lib/a2a/oauthSetup.ts). Throws, naming
+ * variables only, on a configuration that is unsafe or cannot work.
+ */
+export function serverOAuth(options) {
+    const env = options.env ?? process.env;
+    const identity = callbackIdentity(env);
+    const setup = oauthServerSetup({
+        configs: servedFileSyndicates(options.syndicateName, options.servedAgents, options.registryAgents, options.warn),
+        load: (ref) => loadSyndicate(ref),
+        env,
+        ...(options.rows ? { rows: options.rows } : {}),
+        ...(options.audit ? { audit: options.audit } : {}),
+        allowPrivate: env.ALLOW_PRIVATE_OPENAPI === 'true' || env.ALLOW_PRIVATE_MCP === 'true',
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    if (!setup.toolCredentials?.consent)
+        return setup;
+    const warnings = [...setup.warnings];
+    const refused = callbackIdentityProblem(env);
+    if (identity === 'state') {
+        warnings.push('OAUTH_CALLBACK_IDENTITY=state: the single-use state alone binds a consent callback to its user, so a forwarded authorization link can connect the forwarder\'s account to the user who was asked.');
+    }
+    else if (refused) {
+        warnings.push(`${refused.charAt(0).toUpperCase()}${refused.slice(1)}.`);
+    }
+    return {
+        ...setup,
+        warnings,
+        toolCredentials: { ...setup.toolCredentials, requireCallerIdentity: identity === 'required' },
+    };
+}
 export async function startServer(syndicateName = 'syndicate.yaml', extensions = {}) {
     loadEnv(import.meta.url);
     // Conversation content stays out of stdout unless the operator opts in:
@@ -319,6 +425,27 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
     if (metricsToken && (isPlaceholderValue(metricsToken) || metricsToken.length < 24)) {
         fatal('A2A_METRICS_TOKEN must be a long random value (openssl rand -hex 32).');
     }
+    // ── Tool credentials and the OAuth consent step (ADR 0072, 0085, 0114) ────
+    let oauth;
+    try {
+        // An extension's allowlist wins over the environment's here too, as createA2AApp applies it.
+        if (extensions.options?.oauthHosts)
+            setOAuthHosts(extensions.options.oauthHosts);
+        if (extensions.options?.credentialHosts)
+            setCredentialHosts(extensions.options.credentialHosts);
+        oauth = serverOAuth({
+            syndicateName,
+            servedAgents,
+            registryAgents,
+            ...(pgStorage ? { rows: postgresCredentialRows(pgStorage.pool), audit: pgStorage.audit } : {}),
+            warn: (m) => emit('warn', `[A2A] ⚠ ${m}`),
+        });
+    }
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+    for (const w of oauth.warnings)
+        emit('warn', `[A2A] ⚠ ${w}`);
     let built;
     try {
         built = await createA2AApp({
@@ -345,6 +472,7 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
             keyMode,
             ...(pgStorage ? { storage: pgStorage } : {}),
             ...(policy ? { policy } : {}),
+            ...(oauth.toolCredentials ? { toolCredentials: oauth.toolCredentials } : {}),
             metricsToken,
             log: (m) => emit('info', `[A2A] ${m}`),
             warn: (m) => emit('warn', `[A2A] ⚠ ${m}`),
@@ -388,6 +516,8 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
     }
     if (budgetLabel)
         emit('info', `[A2A]   budgets  ${budgetLabel}`);
+    emit('info', `[A2A]   oauth    ${oauth.summary}`);
+    emit('info', `[A2A]   creds    ${oauth.credentialSummary}`);
     if (metricsToken)
         emit('info', `[A2A]   metrics  ${base}/metrics (bearer A2A_METRICS_TOKEN)`);
     emit('info', `[A2A]   health   ${base}/healthz  ${base}/readyz`);

package/dist/scripts/assistant_worker.d.ts

@@ -21,6 +21,16 @@
  *   instead of abandoning it while it keeps spending. Any syndicate and any
  *   subagent in it can serve as the worker.
  *
+ *   A run is durable (ADR 0113): runDurableTurn (lib/runtime/native/
+ *   checkpoint.ts) checkpoints the run's sessions at every step boundary
+ *   beside the job (TaskBackend.saveCheckpoint), and a job claimed again
+ *   after its worker stopped resumes from its last checkpoint instead of
+ *   starting over. SIGTERM aborts the step in flight and puts the job back
+ *   in the queue with its checkpoint; the next worker finishes it. A job
+ *   cancelled while it runs (task_update) loses its claim: the next lease
+ *   renewal or checkpoint save sees it, and the run is aborted without
+ *   writing a result over the cancellation.
+ *
  * Usage:
  *   npm run assistant:worker                      poll every 30 s until Ctrl-C
  *   npm run assistant:worker -- --once            drain the queue, then exit (cron)
@@ -30,5 +40,7 @@
  *   --agent names a subagent of the syndicate, or its orchestrator.
  *   MELCHIZEDEK_TASKS_FILE moves the store (default: outputs/tasks.json),
  *   and must match the chat process's value. Run ONE worker per store.
+ *   MELCHIZEDEK_CHECKPOINT_MAX_BYTES caps a stored checkpoint (bytes of
+ *   JSON, default 5 MiB); a larger one is skipped and the previous kept.
  */
 export {};

package/dist/scripts/assistant_worker.js

@@ -21,6 +21,16 @@
  *   instead of abandoning it while it keeps spending. Any syndicate and any
  *   subagent in it can serve as the worker.
  *
+ *   A run is durable (ADR 0113): runDurableTurn (lib/runtime/native/
+ *   checkpoint.ts) checkpoints the run's sessions at every step boundary
+ *   beside the job (TaskBackend.saveCheckpoint), and a job claimed again
+ *   after its worker stopped resumes from its last checkpoint instead of
+ *   starting over. SIGTERM aborts the step in flight and puts the job back
+ *   in the queue with its checkpoint; the next worker finishes it. A job
+ *   cancelled while it runs (task_update) loses its claim: the next lease
+ *   renewal or checkpoint save sees it, and the run is aborted without
+ *   writing a result over the cancellation.
+ *
  * Usage:
  *   npm run assistant:worker                      poll every 30 s until Ctrl-C
  *   npm run assistant:worker -- --once            drain the queue, then exit (cron)
@@ -30,16 +40,17 @@
  *   --agent names a subagent of the syndicate, or its orchestrator.
  *   MELCHIZEDEK_TASKS_FILE moves the store (default: outputs/tasks.json),
  *   and must match the chat process's value. Run ONE worker per store.
+ *   MELCHIZEDEK_CHECKPOINT_MAX_BYTES caps a stored checkpoint (bytes of
+ *   JSON, default 5 MiB); a larger one is skipped and the previous kept.
  */
 import { randomUUID } from 'node:crypto';
 import { loadEnv } from '../lib/loadEnv.js';
 import { loadSyndicate } from '../lib/loadSyndicate.js';
-import { runSyndicateTurn } from '../lib/runtime/syndicateTurn.js';
+import { runDurableTurn } from '../lib/runtime/native/checkpoint.js';
 import { runtimeSetting } from '../lib/runtime/runtimeFlag.js';
 import { setLogLevel } from '../lib/runtime/logging.js';
-import { InProcessSessionService } from '../lib/runtime/sessions.js';
 import { PROVIDERS, providerForModel, providerKeyPresent, } from '../lib/models/registry.js';
-import { getTaskBackend, setTaskBackend, taskStorePath } from '../lib/tools/taskTools.js';
+import { CHECKPOINT_MAX_BYTES_ENV, applyInterrupted, checkpointMaxBytesSetting, fileTaskBackendWith, getTaskBackend, setTaskBackend, taskStorePath, } from '../lib/tools/taskTools.js';
 import { postgresStorage } from '../lib/storage/postgres/index.js';
 import { dbSchema } from '../lib/storage/schema.js';
 import { hostname } from 'node:os';
@@ -81,10 +92,17 @@ if (!providerKeyPresent(provider)) {
 const log = (message) => console.log(`[worker] ${message}`);
 // The queue: the JSON file, or Postgres when DATABASE_URL is set, where any
 // number of workers may run (each claim is FOR UPDATE SKIP LOCKED).
+// A checkpoint above MELCHIZEDEK_CHECKPOINT_MAX_BYTES (bytes of JSON, default
+// 5 MiB) is not saved: the job keeps its previous one (ADR 0113).
+const rawCap = process.env[CHECKPOINT_MAX_BYTES_ENV];
+const checkpointMaxBytes = checkpointMaxBytesSetting(rawCap);
+if (rawCap?.trim() && Number(rawCap.trim()) !== checkpointMaxBytes) {
+    log(`${CHECKPOINT_MAX_BYTES_ENV} is not a positive whole number of bytes; using ${checkpointMaxBytes}`);
+}
+const taskQueue = { checkpointMaxBytes, log };
 const databaseUrl = process.env.DATABASE_URL?.trim();
-const pg = databaseUrl ? postgresStorage({ connectionString: databaseUrl, schema: dbSchema() }) : undefined;
-if (pg)
-    setTaskBackend(pg.taskQueue);
+const pg = databaseUrl ? postgresStorage({ connectionString: databaseUrl, schema: dbSchema(), taskQueue }) : undefined;
+setTaskBackend(pg ? pg.taskQueue : fileTaskBackendWith(taskQueue));
 const backend = getTaskBackend();
 /** A claimed job stays this worker's while it renews; the job timeout bounds a turn. */
 const lease = { workerId: `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`, leaseMs: 60_000 };
@@ -105,24 +123,43 @@ const workerConfig = !sub
         };
 /** The job in hand, so a signal can cancel it. */
 let current;
-// ── One job = one fresh single-turn session ─────────────────────────────────
+/** Set by SIGTERM: the job in hand goes back to the queue with its checkpoint. */
+let interrupted = false;
+/** The run lost its claim on the job (cancelled while it ran, or taken by another worker). */
+class ClaimLost extends Error {
+}
+/** SIGTERM stopped the run; the job is re-queued, not failed. */
+class Interrupted extends Error {
+}
+// ── One job = one durable single-turn run (ADR 0113) ────────────────────────
 async function runJob(job) {
-    current = new AbortController();
+    const controller = new AbortController();
+    current = controller;
     try {
-        const result = await runSyndicateTurn({
+        // A fresh in-process store per attempt, restored from the job's last
+        // checkpoint when an earlier attempt left one (ADR 0080, ADR 0113).
+        const result = await runDurableTurn({
             config: workerConfig,
             parts: [{ text: job.instruction ?? job.title }],
             appName: 'assistant-worker',
             userId: 'local-user',
-            sessionId: randomUUID(),
-            // A fresh in-process store per job, as the turn runner's signature
-            // names it (ADR 0080). The runtime follows MELCHIZEDEK_RUNTIME.
-            sessionService: new InProcessSessionService(),
+            runId: `${job.owner}:${job.id}`,
+            checkpoints: {
+                load: async () => ((await backend.loadCheckpoint?.(job)) ?? null),
+                save: async (checkpoint) => (backend.saveCheckpoint ? backend.saveCheckpoint(lease, job, checkpoint) : true),
+            },
+            onSaveError: (e) => log(`checkpoint not saved: ${e instanceof Error ? e.message : String(e)}`),
             compile: { log, onUnknownTool: (n) => log(`unknown tool '${n}' skipped`) },
-            signal: current.signal,
+            signal: controller.signal,
             deadlineMs: JOB_TIMEOUT_MS,
             events: { warn: (m) => log(`⚠ ${m}`) },
         });
+        if (result.resumedFromStep > 0)
+            log(`${job.id} resumed from step ${result.resumedFromStep}`);
+        if (result.lostClaim || controller.signal.reason instanceof ClaimLost)
+            throw new ClaimLost('the job was cancelled or claimed elsewhere');
+        if (interrupted)
+            throw new Interrupted('stopped by SIGTERM');
         if (result.status !== 'completed') {
             throw new Error(`${result.error?.code ?? 'ERROR'}: ${result.error?.message ?? ''}`.trim());
         }
@@ -142,10 +179,17 @@ async function drain() {
         const started = Date.now();
         const label = job.owner ? `${job.id} (${job.owner})` : job.id;
         log(`${label} started: ${job.title}`);
-        // Renew the lease while the job runs, so no other worker takes it back.
+        // Renew the lease while the job runs, so no other worker takes it back;
+        // a renewal that finds the claim gone (the job was cancelled) stops the run.
         const held = job;
         const heartbeat = setInterval(() => {
-            backend.renew(lease, held).catch((e) => log(`lease renewal failed: ${e instanceof Error ? e.message : e}`));
+            backend
+                .renew(lease, held)
+                .then((kept) => {
+                if (kept === false)
+                    current?.abort(new ClaimLost('claim lost'));
+            })
+                .catch((e) => log(`lease renewal failed: ${e instanceof Error ? e.message : e}`));
         }, Math.floor(lease.leaseMs / 3));
         try {
             const result = await runJob(job);
@@ -153,8 +197,22 @@ async function drain() {
             log(`${label} done in ${Math.round((Date.now() - started) / 1000)} s`);
         }
         catch (error) {
-            await backend.finish(job, { error: String(error?.message ?? error) });
-            log(`${label} failed: ${error?.message ?? error}`);
+            if (error instanceof ClaimLost) {
+                // Cancelled while it ran: the record already says so; nothing is written over it.
+                log(`${label} stopped: ${error.message}`);
+            }
+            else if (error instanceof Interrupted) {
+                // Back to the queue with its checkpoint, or failed after MAX_ATTEMPTS interruptions.
+                const outcome = await backend.mutate(job.owner, (store) => {
+                    const t = store.tasks.find((r) => r.id === held.id);
+                    return t && t.status === 'running' ? applyInterrupted(t) : 'left as is';
+                });
+                log(`${label} interrupted: ${outcome}`);
+            }
+            else {
+                await backend.finish(job, { error: String(error?.message ?? error) });
+                log(`${label} failed: ${error?.message ?? error}`);
+            }
         }
         finally {
             clearInterval(heartbeat);
@@ -183,12 +241,13 @@ process.on('SIGINT', () => {
     stopping = true;
     log('stopping after the current job (Ctrl-C again to quit now)');
 });
-// A container stop: cancel the job in hand (it is recorded as failed and the
-// store stays consistent), then exit.
+// A container stop: abort the step in flight and put the job back in the
+// queue with its checkpoint, so the next worker resumes it (ADR 0113).
 process.on('SIGTERM', () => {
     stopping = true;
-    log('SIGTERM — canceling the current job');
-    current?.abort();
+    interrupted = true;
+    log('SIGTERM — stopping the current job; it resumes from its last checkpoint');
+    current?.abort(new Interrupted('SIGTERM'));
 });
 while (!stopping) {
     await drain();

package/dist/scripts/doctor.d.ts

@@ -8,7 +8,12 @@
  * gateway stand-in, or local), which declared server-side tools it keeps or
  * drops, and one verdict per syndicate. Says first which runtime a turn runs
  * on (native; a leftover MELCHIZEDEK_RUNTIME=adk is a problem, since 1.0.0
- * removed that runtime). Closes with the env vars that would
+ * removed that runtime). Lists the tools that need an OAuth grant (an
+ * `auth: { oauth2 }` or `mcp_auth`, ADR 0112): each user's consent, or the
+ * server's own client credentials and whether their variables are set
+ * (names only). When any A2A identity or billing variable is set, a
+ * `serving` line names the A2A_AUTH mode and A2A_KEY_MODE and what the
+ * server would refuse to start on. Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key
@@ -17,7 +22,7 @@
  * Usage:
  *   npm run doctor
  *   npm run doctor -- --json          # machine-readable
- *   npm run doctor -- --check         # exit 1 when any syndicate is blocked
+ *   npm run doctor -- --check         # exit 1 on a blocked syndicate, a runtime problem, or an OAuth or credential host problem
  *   npm run doctor -- --matrix        # the provider × capability matrix
  *   npm run doctor -- --fix-namespaces [file…]   # give long-term syndicates a memory_namespace
  *   MELCHIZEDEK_AGENTS_DIR=/path npm run doctor

package/dist/scripts/doctor.js

@@ -8,7 +8,12 @@
  * gateway stand-in, or local), which declared server-side tools it keeps or
  * drops, and one verdict per syndicate. Says first which runtime a turn runs
  * on (native; a leftover MELCHIZEDEK_RUNTIME=adk is a problem, since 1.0.0
- * removed that runtime). Closes with the env vars that would
+ * removed that runtime). Lists the tools that need an OAuth grant (an
+ * `auth: { oauth2 }` or `mcp_auth`, ADR 0112): each user's consent, or the
+ * server's own client credentials and whether their variables are set
+ * (names only). When any A2A identity or billing variable is set, a
+ * `serving` line names the A2A_AUTH mode and A2A_KEY_MODE and what the
+ * server would refuse to start on. Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key
@@ -17,7 +22,7 @@
  * Usage:
  *   npm run doctor
  *   npm run doctor -- --json          # machine-readable
- *   npm run doctor -- --check         # exit 1 when any syndicate is blocked
+ *   npm run doctor -- --check         # exit 1 on a blocked syndicate, a runtime problem, or an OAuth or credential host problem
  *   npm run doctor -- --matrix        # the provider × capability matrix
  *   npm run doctor -- --fix-namespaces [file…]   # give long-term syndicates a memory_namespace
  *   MELCHIZEDEK_AGENTS_DIR=/path npm run doctor
@@ -25,7 +30,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadEnv } from '../lib/loadEnv.js';
-import { renderDoctor, runDoctor } from '../lib/doctor.js';
+import { checkProblems, renderDoctor, runDoctor } from '../lib/doctor.js';
 import { renderCapabilityMatrix } from '../lib/models/capabilities.js';
 import { assignMemoryNamespace, LEGACY_MEMORY_APP_NAME } from '../lib/memory/namespace.js';
 loadEnv();
@@ -88,5 +93,5 @@ if (json) {
 else {
     console.log(renderDoctor(result, { color: !noColor }));
 }
-if (check && (result.counts.blocked > 0 || result.runtime.problem))
+if (check && checkProblems(result).length)
     process.exit(1);

package/dist/scripts/setup.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * scripts/setup.ts — the `melchizedek-setup` bin and `npm run setup`.
+ *
+ * The onboarding command: a menu of authentication levels (no key, one
+ * provider, several, a gateway, a cloud platform, per-caller keys, caller
+ * tokens, OAuth tool grants, and an honest entry for subscription sign-ins),
+ * each with a startup guide: the variables to set (names and shapes only),
+ * the doctor command that confirms it, the shipped files that run there and
+ * the first commands to try. The levels and guides live in lib/onboarding.ts;
+ * ONBOARDING.md is generated from the same function.
+ *
+ *   npx melchizedek-setup                     # the menu (interactive terminal)
+ *   npx melchizedek-setup --auto              # detect from the environment, names only
+ *   npx melchizedek-setup --level gateway     # one guide, by id or number
+ *   npx melchizedek-setup --level 2 --write-env   # also create .env from .env.example
+ *   npx melchizedek-setup --list
+ *   npx melchizedek-setup --markdown          # ONBOARDING.md, regenerated
+ *
+ * Never prints a value. `--write-env` never overwrites `.env`, leaves every
+ * name blank, and refuses unless `git check-ignore` confirms `.env` is ignored.
+ */
+export declare function main(argv?: string[]): Promise<number>;