@commonlyai/cli 0.1.72 → 0.1.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.72",
+  "version": "0.1.73",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -17,6 +17,13 @@ import { homedir, tmpdir } from 'os';
 import { fileURLToPath } from 'url';
 
 import { createClient } from '../lib/api.js';
+import {
+  buildSpawnId,
+  createSpawnCredentialLease,
+  readSpawnPolicy,
+  resolveSpawnTtlSeconds,
+  revokeOrphanedSpawnCredentials,
+} from '../lib/spawn-credential.js';
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
 import { startPoller, terminalDeliveryAckError } from '../lib/poller.js';
 import { startWebhookServer, forwardToLocalWebhook } from '../lib/webhook-server.js';
@@ -925,10 +932,46 @@ export const performRun = ({
   // Kept injectable for small-page regression cases; the runtime ships with
   // the server's ordinary ten-event page.
   inboxBatchLimit = 10,
+  // TASK-102 part B. Undefined means "use the server's published default"; a
+  // number here is the operator's ask, and the policy read at boot is what
+  // makes a clamp visible instead of silent.
+  spawnCredentialTtlSeconds = null,
+  spawnCredentialLeaseFactory = createSpawnCredentialLease,
+  revokeOrphansImpl = revokeOrphanedSpawnCredentials,
   sleepImpl = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
 }) => {
   const client = createClient({ instance: instanceUrl, token });
 
+  // THE BOOT SWEEP IS THE SECOND NET, AND IT HAPPENS ONCE PER PROCESS. A seat
+  // that dies mid-turn (kill, crash, reboot) leaves its child credential live
+  // until its own TTL expires, because `close()` never ran; this is what collects
+  // those. Fire-and-forget by contract: `performRun` is synchronous for its
+  // callers, the sweep is best-effort, and a sweep that failed must not stop a
+  // seat from spawning — it logs and returns. Per process rather than per spawn
+  // because the orphans being collected belong to the PREVIOUS process.
+  //
+  // The promise wrapper is not ceremony: it makes a throwing OR rejecting
+  // implementation of the seam a log line instead of an unhandled rejection,
+  // which is the difference between a diagnostic and a crash in a seat that is
+  // otherwise fine.
+  void Promise.resolve()
+    .then(() => revokeOrphansImpl({ client, log }))
+    .catch((err) => log(`spawn credential boot sweep failed (${err?.message ?? err})`));
+
+  // The bounds the server will clamp to. READ ONLY IF THERE IS AN ASK TO CLAMP:
+  // with no `COMMONLY_SPAWN_TTL_SECONDS` the cli sends no `ttlSeconds` at all
+  // and the server's default is what it is, so a per-run read would be a request
+  // on every seat's boot in exchange for nothing. Read once and cached, because
+  // the bounds are constants for the life of a process. `readSpawnPolicy` never
+  // rejects (a failure resolves to null), so this cannot fail a spawn; it just
+  // sends the ask unclamped and lets the server decide.
+  let spawnPolicyPromise = null;
+  const spawnPolicyForAsk = () => {
+    if (spawnCredentialTtlSeconds === null || spawnCredentialTtlSeconds === undefined) return null;
+    if (spawnPolicyPromise === null) spawnPolicyPromise = readSpawnPolicy({ client, log });
+    return spawnPolicyPromise;
+  };
+
   // THE SEAT'S OWN RECORD IS THE ONLY DECLARATION THERE IS. The broker reaches a
   // seat as an injected MCP entry written by hand into its environment — no
   // server projection puts it there (`GRANT_BROKER_URL` is imported by one
@@ -1267,21 +1310,90 @@ export const performRun = ({
     const promptWithFocus = `${focusFrame}\n\n${prompt}`;
 
     log(`[${event.type}] spawning ${adapter.name}`);
-    const result = await adapter.spawn(frameDecisionForkRule(promptWithFocus), {
-      sessionId,
-      cwd: agentCwd,
-      env: process.env,
-      memoryLongTerm,
-      environment: seatEnvironment,
-      // Runtime context the Claude/Codex adapters expose only to their
-      // per-spawn MCP environment. Claude keeps ${COMMONLY_*} placeholders
-      // literal on disk and lets its native MCP parser expand them, so the
-      // bearer token never enters the generated config file.
-      runtimeToken: token,
-      instanceUrl,
-      agentName,
-      metadata: { event },
+    // TASK-102 part B. The CHILD gets a scoped credential; the wrapper keeps
+    // the seat token for its own polling, claiming and posting (`client` was
+    // built from `token` above and is not touched here). The lease renews while
+    // the child runs and revokes when it returns, so the window in which a
+    // leaked child credential is usable is one turn rather than a seat's life.
+    //
+    // A refusal throws: `openSpawnCredential` only falls back to the seat token
+    // for capacity, and a verdict (401/403/400/404/409) must fail the spawn
+    // rather than restore the authority the refusal was about. The catch below
+    // turns that throw into a NAMED refusal on the turn result, so the claim is
+    // released as `delivery-refused` instead of being re-delivered forever.
+    const spawnPolicyOrNull = spawnPolicyForAsk();
+    const lease = spawnCredentialLeaseFactory({
+      client,
+      seatToken: token,
+      spawnId: buildSpawnId({ agentName, eventId: event?._id || event?.payload?.batchEventIds || null }),
+      desiredTtlSeconds: spawnCredentialTtlSeconds,
+      policy: spawnPolicyOrNull === null ? null : await spawnPolicyOrNull,
+      log,
     });
+    let opened;
+    try {
+      opened = await lease.open();
+    } catch (err) {
+      // A VERDICT IS NOT A CRASH, AND IT IS NOT A NO-OP (wren 72153, vera
+      // 72157). Letting it escape as a bare throw left `turnResult` undefined,
+      // so `claimReleaseFor` returned the legacy holder-only DELETE — right for
+      // a transient failure, wrong for a refusal that recurs on every
+      // redelivery: the wake loops forever with one local log line as its only
+      // record. Naming it on the turn result is what lets the release carry the
+      // class, and on a human wake lets the kernel hand the message to a
+      // remaining listener instead of stranding it.
+      if (!err?.spawnCredentialRefused) {
+        // ONLY a verdict is named as a refusal. An unexpected failure inside
+        // the lease — a bug in our own code, not the server's answer — keeps
+        // the legacy release, because `delivery-refused` would hand a human's
+        // message away and close the row on the strength of our own defect.
+        // Redelivery is the right remedy for a crash.
+        log(`spawn credential lease failed (${err?.message ?? err}) — not spawning`);
+        throw err;
+      }
+      const status = Number.isInteger(err.status) ? err.status : null;
+      const code = typeof err.body?.code === 'string' ? err.body.code : null;
+      log(`spawn credential refused (HTTP ${status ?? 'no response'}) — not spawning`);
+      // `delivery-refused` claims the least of the three classes: the model
+      // never ran, and the refuser is our own mint rather than the model
+      // provider (that would be `upstream-refused`, and its status is the HTTP
+      // status of an upstream call — a meaning this refusal does not have, so
+      // the number travels in the ack instead of on the claim record).
+      return {
+        outcome: 'no_action',
+        refused: { reason: 'delivery-refused' },
+        reason: `spawn-credential-refused-${status ?? 'unknown'}`,
+        details: {
+          ...(status !== null ? { status } : {}),
+          ...(code !== null ? { code } : {}),
+        },
+      };
+    }
+    let result;
+    try {
+      result = await adapter.spawn(frameDecisionForkRule(promptWithFocus), {
+        sessionId,
+        cwd: agentCwd,
+        env: process.env,
+        memoryLongTerm,
+        environment: seatEnvironment,
+        // Runtime context the Claude/Codex adapters expose only to their
+        // per-spawn MCP environment. Claude keeps ${COMMONLY_*} placeholders
+        // literal on disk and lets its native MCP parser expand them, so the
+        // bearer token never enters the generated config file. Since TASK-102
+        // part B this is the per-spawn credential when one could be minted, and
+        // the seat token only when the server could not mint.
+        runtimeToken: opened.token,
+        instanceUrl,
+        agentName,
+        metadata: { event },
+      });
+    } finally {
+      // Best-effort by construction: `close` logs and returns on a failed
+      // revoke, so a turn that already produced an answer is not failed by
+      // cleanup. The boot sweep collects anything left behind.
+      await lease.close();
+    }
 
     if (result.newSessionId) {
       setSession(agentName, eventPodId, result.newSessionId);
@@ -2611,6 +2723,10 @@ Docs:
         workspacePath: record.workspacePath || null,
         intervalMs: parseInt(opts.interval, 10),
         ...cascadeOverridesFromOpts(opts),
+        // TASK-102 part B: the operator's TTL ask, if any. Unset means the
+        // server's published default, which is the only lifetime we can justify
+        // without an operator saying otherwise.
+        spawnCredentialTtlSeconds: resolveSpawnTtlSeconds(process.env),
         log: (line) => console.log(`${stamp()} [${name}] ${line}`),
         // Both sinks are stamped, and both must be — but not for the reason
         // this comment gave until now, which its own PR falsified.

package/src/lib/spawn-credential.js

@@ -0,0 +1,375 @@
+/**
+ * spawn-credential.js — TASK-102 part B (the cli half of TASK-094).
+ *
+ * WHAT THIS REPLACES. Every adapter used to hand the child the seat's own
+ * runtime token (`ctx.runtimeToken`, sourced from `COMMONLY_AGENT_TOKEN`): one
+ * long-lived credential, the full authority of the seat, inherited by every
+ * process the child spawns and written to a credential file that outlives the
+ * turn. The backend half (TASK-094 PR A, merged as `3e08c328`) can mint a
+ * per-spawn child instead — bounded lifetime, named in a ledger, revocable —
+ * and this module is the caller that makes that real rather than available.
+ *
+ * WHY A LEASE AND NOT A SINGLE MINT. The granted TTL is 900s by default
+ * (`SPAWN_TTL_MAX_SECONDS`), and a turn can outlive it: a long coding turn
+ * would start failing mid-flight with 401s the seat cannot explain, which is
+ * strictly worse than the seat token it replaced. So the lease renews at
+ * half-life while the child runs (the absolute lifetime is 24h, so renewal is
+ * the mechanism the backend already provides for exactly this) and revokes at
+ * the end of the turn, which is what bounds a leaked child credential to one
+ * turn instead of forever.
+ *
+ * THE FALLBACK PREDICATE IS ABOUT WHAT A FAILURE TELLS US (vera 71068/`#1823`
+ * thread). Four arms, each named here so a reader checking the predicate against
+ * this comment does not have to re-derive one:
+ *
+ *   capacity — 429, 5xx, or no HTTP response at all. The server could not mint
+ *     *right now*; that says nothing about whether this seat may mint, and the
+ *     seat token is an authority the seat already holds, so falling back grants
+ *     nothing new and keeps the seat working. `no status` belongs here because
+ *     the request never got a verdict at all: an availability fact, not an
+ *     authorization one.
+ *   route absent — a 404 whose body carries NO `code`. The mint's own refusals
+ *     always name themselves (`REFUSAL_STATUS` in
+ *     `backend/routes/spawnCredentials.ts` maps `not_found` → 404), so a bare
+ *     404 is Express's default page from a backend deployed before this route
+ *     existed. Failing THAT closed would stop every spawn on such a fleet and
+ *     re-deliver the event forever — strictly worse than the seat token every
+ *     seat was using before this module existed. `readSpawnPolicy` reads its own
+ *     404 the same way; one reading of "404" per file, not two.
+ *   verdict — every other 4xx (401 dead token, 403 not this seat's installation,
+ *     400 malformed spawn id, 409 not renewable, or a 404 that DOES carry a
+ *     code). A refusal is about the caller or the request, and falling back
+ *     there would silently restore the exact authority the refusal was about,
+ *     making the whole mechanism decorative.
+ *   malformed success — a 2xx carrying no usable token. Deliberately NOT filed
+ *     under capacity: the server answered, and the answer is a server bug
+ *     rather than anything about this caller. It falls back for the same reason
+ *     route-absent does — the seat's authority is what it already had, and
+ *     failing closed would take a fleet down over someone else's bug — but it is
+ *     its own arm so that the choice is visible as a choice.
+ *
+ * The caller's own identity is never used for its own HTTP call: the lease is
+ * minted with the SEAT token over the seat's client, and only the CHILD gets
+ * the scoped token. The wrapper keeps polling, claiming and posting with the
+ * seat token, which is why `performRun` passes `spawnToken.token` to the
+ * adapter and keeps `token` for its client.
+ *
+ * THE POLICY READ EXISTS SO THE CLAMP IS VISIBLE. `GET /policy` publishes the
+ * bounds `clampSpawnTtlSeconds` actually applies (`minTtlSeconds`,
+ * `maxTtlSeconds`, `absoluteLifetimeSeconds`). A caller that asks for 3600 used
+ * to receive a 900s credential with no way to find out; here the ask is
+ * compared against the published cap and the difference is logged once at
+ * open. The read is best-effort: a missing policy degrades to sending the ask
+ * and letting the server clamp, never to refusing to spawn.
+ */
+
+export const SPAWN_CREDENTIAL_BASE = '/api/agents/runtime/spawn-credentials';
+
+// Renew at half the granted lifetime: one renewal is missed and the credential
+// still has 450s of headroom at the default TTL, which covers a slow span
+// between the timer firing and the request landing.
+export const RENEW_AT_FRACTION = 0.5;
+
+// Never renew faster than this. A server that grants a TTL shorter than two
+// minutes would otherwise produce a renewal loop tight enough to be its own
+// traffic; the floor keeps the loop's cadence a function of our intent rather
+// than of an unexpectedly small grant.
+export const MIN_RENEW_INTERVAL_MS = 30 * 1000;
+
+/** Capacity (the server could not mint) vs verdict (the server refused). */
+export const isCapacityRefusal = (status) => (
+  status === undefined || status === null || status === 429 || status >= 500
+);
+
+/**
+ * A 404 with no `code` is the route missing, not this caller being refused.
+ *
+ * The mint's refusals are always typed (`not_found` → 404 via
+ * `REFUSAL_STATUS`), so an untyped 404 cannot have come from the route — it is
+ * Express's default page. Treated as its own arm rather than as a verdict
+ * because the two call for opposite handling: a verdict must fail the spawn
+ * closed, while a route that does not exist yet must not stop the fleet from
+ * spawning at all.
+ */
+export const isRouteAbsentRefusal = (status, body) => (
+  status === 404 && !body?.code
+);
+
+/**
+ * The ledger names the spawn, and the name has to be stable per spawn and
+ * unique across spawns: the event id is the only identifier the wrapper has
+ * that means "this turn" (a session id recurs across turns, an agent name
+ * recurs forever). Truncated to the route's `MAX_SPAWN_ID_LENGTH`, keeping the
+ * tail — the event id — because the prefix is the part a reader can infer.
+ */
+export const buildSpawnId = ({ agentName = 'agent', eventId = null, maxLength = 128 } = {}) => {
+  const suffix = eventId === null || eventId === undefined ? 'unknown' : String(eventId);
+  const tail = `:${suffix}`;
+  // The bound is on the WHOLE id. Bounding only the suffix (the first version)
+  // let a long enough agent name through the bound entirely: the backend
+  // refuses anything over MAX_SPAWN_ID_LENGTH with `invalid_spawn_id` → 400 →
+  // fail closed, so a name would have made its own seat unspawnable. The name is
+  // shortened first because it is the part a reader can infer from the pod; the
+  // event id is what makes the row unique across turns, so it is kept whole
+  // whenever it fits. Longest live `instanceId` is 25 chars (vera, 566 seats),
+  // so this guards a future name rather than a live path.
+  const nameBudget = Math.max(1, maxLength - tail.length);
+  const name = String(agentName).slice(0, nameBudget) || 'agent';
+  const id = `${name}${tail}`;
+  return id.length > maxLength ? id.slice(0, maxLength) : id;
+};
+
+/**
+ * The operator's ask, read from `COMMONLY_SPAWN_TTL_SECONDS`.
+ *
+ * Unset is the normal case and means "the server's published default" — the
+ * cli has no business inventing a lifetime for a credential it does not own.
+ * A malformed value degrades to unset rather than to a guess: this knob exists
+ * so an operator can discover the cap, and a typo must not become a different
+ * number that nobody chose.
+ */
+export const resolveSpawnTtlSeconds = (env = {}) => {
+  const raw = String(env.COMMONLY_SPAWN_TTL_SECONDS || '').trim();
+  if (!raw) return null;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return parsed;
+};
+
+/**
+ * Best-effort bounds read. Returns null when the route is absent (an older
+ * server) or unreachable — the caller then sends its ask unclamped and lets the
+ * server's own clamp decide, which is the pre-policy behaviour and never worse.
+ */
+export const readSpawnPolicy = async ({ client, log = () => {} }) => {
+  try {
+    const policy = await client.get(`${SPAWN_CREDENTIAL_BASE}/policy`);
+    return policy && typeof policy === 'object' ? policy : null;
+  } catch (err) {
+    log(`spawn credential policy unavailable (${err?.status ?? 'no response'}) — sending the TTL ask unclamped`);
+    return null;
+  }
+};
+
+/**
+ * The boot sweep: collect credentials orphaned by a process that died before it
+ * could revoke them (a killed seat, a crashed daemon, a machine that rebooted
+ * mid-turn). `POST /revoke-orphans` is the net behind `close()`.
+ *
+ * Called once per process from the run entry, and best-effort on purpose: it is
+ * the SECOND net, so a failure has to leave the seat starting normally. It also
+ * cannot be allowed to hold up the first turn, which is why the caller does not
+ * await it.
+ */
+export const revokeOrphanedSpawnCredentials = async ({ client, log = () => {} }) => {
+  try {
+    const result = await client.post(`${SPAWN_CREDENTIAL_BASE}/revoke-orphans`, {});
+    const revoked = typeof result?.revoked === 'number' ? result.revoked : null;
+    log(revoked
+      ? `spawn credential boot sweep revoked ${revoked} orphan(s)`
+      : 'spawn credential boot sweep found no orphans');
+    return { ok: true, revoked };
+  } catch (err) {
+    // Includes the route-absent case: a backend older than the mint has no
+    // sweep to run, and that must be a log line, never a failed boot.
+    log(`spawn credential boot sweep skipped (${err?.status ?? 'no response'})`);
+    return { ok: false, reason: 'sweep-failed' };
+  }
+};
+
+/**
+ * Open one lease. Returns `{ token, credentialId, source, expiresAt, grantedSeconds }`.
+ *
+ * `source` is `'spawn'` when the child got a scoped credential and
+ * `'seat-fallback'` when it got the seat token because the server could not
+ * mint. A refusal (a verdict — see the header) throws with
+ * `spawnCredentialRefused` set and the status attached, so the caller fails the
+ * spawn closed rather than falling back.
+ */
+export const openSpawnCredential = async ({
+  client,
+  seatToken,
+  spawnId,
+  desiredTtlSeconds = null,
+  policy = null,
+  log = () => {},
+}) => {
+  const cap = typeof policy?.maxTtlSeconds === 'number' ? policy.maxTtlSeconds : null;
+  let ask = desiredTtlSeconds;
+  if (typeof ask === 'number' && Number.isFinite(ask)) {
+    if (cap !== null && ask > cap) {
+      log(`spawn credential: asked for ${ask}s, the server's cap is ${cap}s — asking for ${cap}s instead`);
+      ask = cap;
+    }
+  } else {
+    ask = null;
+  }
+
+  let minted;
+  try {
+    minted = await client.post(
+      SPAWN_CREDENTIAL_BASE,
+      ask === null ? { spawnId } : { spawnId, ttlSeconds: ask },
+    );
+  } catch (err) {
+    const status = err?.status ?? null;
+    if (isCapacityRefusal(status === null ? undefined : status)) {
+      log(`spawn credential unavailable (${status === null ? 'no response' : `HTTP ${status}`}) — spawning with the seat token`);
+      return { token: seatToken, credentialId: null, source: 'seat-fallback', expiresAt: null, grantedSeconds: null };
+    }
+    if (isRouteAbsentRefusal(status, err?.body)) {
+      log('spawn credential route absent on this backend (HTTP 404 with no code) — spawning with the seat token');
+      return {
+        token: seatToken, credentialId: null, source: 'seat-fallback', expiresAt: null, grantedSeconds: null, reason: 'route-absent',
+      };
+    }
+    const code = err?.body?.code ? ` code=${err.body.code}` : '';
+    const refusal = new Error(`spawn credential refused: HTTP ${status}${code}`);
+    refusal.spawnCredentialRefused = true;
+    refusal.status = status;
+    refusal.body = err?.body ?? null;
+    throw refusal;
+  }
+
+  // A 201 with no usable token is not a credential. Treat it as un-mintable
+  // and fall back, rather than handing the child `undefined` — which would
+  // look like a scoped credential everywhere downstream while silently being
+  // no credential at all. (It is also the shape a stub client returns, so this
+  // guard is what keeps a test that does not care about minting on the seat
+  // token instead of on nothing.)
+  if (typeof minted?.token !== 'string' || !minted.token.trim()) {
+    log('spawn credential response carried no token — spawning with the seat token');
+    return {
+      token: seatToken, credentialId: null, source: 'seat-fallback', expiresAt: null, grantedSeconds: null, reason: 'no-token',
+    };
+  }
+
+  const grantedSeconds = minted?.expiresAt
+    ? Math.max(0, Math.round((new Date(minted.expiresAt).getTime() - Date.now()) / 1000))
+    : (typeof ask === 'number' ? ask : cap);
+  return {
+    token: minted.token,
+    credentialId: minted.credentialId || null,
+    source: 'spawn',
+    expiresAt: minted.expiresAt || null,
+    grantedSeconds,
+  };
+};
+
+/** Renewal cadence for a granted lifetime. */
+export const renewIntervalMs = (grantedSeconds) => {
+  const half = typeof grantedSeconds === 'number' && grantedSeconds > 0
+    ? (grantedSeconds * 1000) * RENEW_AT_FRACTION
+    : MIN_RENEW_INTERVAL_MS;
+  return Math.max(MIN_RENEW_INTERVAL_MS, Math.round(half));
+};
+
+/**
+ * A lease owns the credential's lifetime: open, renew while the child runs,
+ * revoke when it ends. `setIntervalImpl`/`clearIntervalImpl` are injected so a
+ * test can drive the cadence without waiting on wall-clock time.
+ */
+export const createSpawnCredentialLease = ({
+  client,
+  seatToken,
+  spawnId,
+  desiredTtlSeconds = null,
+  policy = null,
+  log = () => {},
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+}) => {
+  let credentialId = null;
+  let timer = null;
+  let grantedSeconds = null;
+
+  const stopRenewal = () => {
+    if (timer !== null) {
+      clearIntervalImpl(timer);
+      timer = null;
+    }
+  };
+
+  const renew = async () => {
+    if (!credentialId) return;
+    // A renewal extends the SAME credential, so the TTL to ask for is the one
+    // the server already granted rather than the caller's original desire: a
+    // caller that asked for 3600 and was capped at 900 must not turn every
+    // renewal into another request for 3600.
+    const ask = typeof grantedSeconds === 'number' && grantedSeconds > 0
+      ? Math.floor(grantedSeconds)
+      : undefined;
+    try {
+      await client.post(
+        `${SPAWN_CREDENTIAL_BASE}/${credentialId}/renew`,
+        ask === undefined ? {} : { ttlSeconds: ask },
+      );
+      log(`spawn credential renewed (${credentialId})`);
+    } catch (err) {
+      const status = err?.status ?? null;
+      if (isCapacityRefusal(status === null ? undefined : status)) {
+        // The credential is still live; we simply could not reach the server.
+        // Keep the timer: the next tick is a fresh attempt.
+        log(`spawn credential renewal deferred (${status === null ? 'no response' : `HTTP ${status}`})`);
+        return;
+      }
+      if (isRouteAbsentRefusal(status, err?.body)) {
+        // Same reading of 404 as `openSpawnCredential`: an untyped 404 is the
+        // route missing, so keep the timer and do not treat it as a verdict
+        // about this credential. The credential keeps its remaining lifetime
+        // either way, and a route that comes back is picked up next tick.
+        log('spawn credential renewal deferred (route absent, HTTP 404 with no code)');
+        return;
+      }
+      // A verdict — expired or revoked. The route's contract is explicit that
+      // this is the caller's signal to stop, not to retry harder: a late
+      // renewal must not resurrect a dead child.
+      stopRenewal();
+      log(`spawn credential renewal refused (HTTP ${status}) — the child keeps its remaining lifetime and is not extended`);
+    }
+  };
+
+  const startRenewal = () => {
+    const interval = renewIntervalMs(grantedSeconds);
+    timer = setIntervalImpl(() => { renew(); }, interval);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+  };
+
+  return {
+    async open() {
+      const opened = await openSpawnCredential({ client, seatToken, spawnId, desiredTtlSeconds, policy, log });
+      credentialId = opened.credentialId;
+      grantedSeconds = opened.grantedSeconds;
+      if (opened.source === 'spawn' && credentialId) startRenewal();
+      log(opened.source === 'spawn'
+        ? `spawn credential minted (${credentialId}, granted ${opened.grantedSeconds}s)`
+        : 'spawning with the seat token (spawn credential unavailable)');
+      return opened;
+    },
+
+    /**
+     * End the spawn: stop extending it and revoke it. Revocation is
+     * best-effort on purpose — the boot sweep (`revokeOrphanedSpawnCredentials`,
+     * called once per process from the run entry) is the second net, and a
+     * failed revoke must never fail a turn that already produced an answer.
+     */
+    async close() {
+      stopRenewal();
+      if (!credentialId) return { revoked: false, reason: 'no-credential' };
+      const id = credentialId;
+      credentialId = null;
+      try {
+        await client.del(`${SPAWN_CREDENTIAL_BASE}/${id}`);
+        log(`spawn credential revoked (${id})`);
+        return { revoked: true };
+      } catch (err) {
+        log(`spawn credential revoke failed (${id}, ${err?.status ?? 'no response'}) — the boot sweep will collect it`);
+        return { revoked: false, reason: 'revoke-failed' };
+      }
+    },
+
+    // Exposed for tests and for a caller that wants the cadence it got.
+    get credentialId() { return credentialId; },
+    get grantedSeconds() { return grantedSeconds; },
+  };
+};