@ravefox/space 0.2.0 → 0.3.0

package/src/lib/skill-prompt.js

@@ -1,74 +0,0 @@
-// A public seat cannot load its declared skills as files, so each adapter
-// delivers the SKILL.md bodies as instructions text instead:
-//   - claude: skills are disabled outright (`--disable-slash-commands`,
-//     `--setting-sources ''`), so the text rides as `--append-system-prompt`;
-//   - codex: `exec` has no skill loader the seat can use, and a public seat's
-//     CODEX_HOME is one this CLI owns, so the text is that home's AGENTS.md.
-// One reader for both, so the two runtimes cannot drift on what a skill says.
-import { readFile } from 'fs/promises';
-import { isAbsolute, join, resolve as pathResolve } from 'path';
-import { homedir } from 'os';
-
-const SKILL_FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/;
-
-export const SKILLS_AS_TEXT_PREAMBLE = 'These skills are part of how you work here. Skills are not loaded as files in this seat, '
-  + 'so each one is given in full below. Follow them as you would a loaded skill.';
-
-/**
- * A declared skill path as the environment spec means it: `~/` expanded,
- * relative paths taken from `baseDir`. The same resolution mountSkills applies.
- */
-export const resolveSkillSource = (rawSource, baseDir) => {
-  let source = rawSource;
-  if (source === '~') source = homedir();
-  else if (typeof source === 'string' && source.startsWith('~/')) source = join(homedir(), source.slice(2));
-  return isAbsolute(source) ? source : pathResolve(baseDir, source);
-};
-
-const SECTION_SEPARATOR = '\n\n';
-
-/**
- * Each source's SKILL.md as `## Skill: <name>` plus its body without the
- * frontmatter, in declared order. `maxBytes` bounds the whole text
- * skillsAsText returns (preamble, separators and `trailer` included), so a cap
- * is the size of what the runtime reads. A source with no SKILL.md, or one that
- * would cross the cap, is skipped with a warning naming the runtime (`label`)
- * rather than failing the spawn.
- */
-export const readSkillSections = async (skillSources, { maxBytes, label, trailer = '', onIncluded }) => {
-  const sections = [];
-  let total = Buffer.byteLength(SKILLS_AS_TEXT_PREAMBLE, 'utf8') + Buffer.byteLength(trailer, 'utf8');
-  for (const source of skillSources || []) {
-    let markdown;
-    try {
-      // eslint-disable-next-line no-await-in-loop
-      markdown = await readFile(join(source, 'SKILL.md'), 'utf8');
-    } catch {
-      // eslint-disable-next-line no-console
-      console.warn(`[${label}] public seat: no SKILL.md to inline at ${source}`);
-      continue;
-    }
-    const frontmatter = SKILL_FRONTMATTER_RE.exec(markdown);
-    const name = (frontmatter && /^name:\s*(.+)$/m.exec(frontmatter[1])?.[1].trim())
-      || source.split(/[\\/]/).filter(Boolean).pop();
-    const section = `## Skill: ${name}\n\n${markdown.slice(frontmatter ? frontmatter[0].length : 0).trim()}`;
-    const bytes = Buffer.byteLength(SECTION_SEPARATOR, 'utf8') + Buffer.byteLength(section, 'utf8');
-    if (total + bytes > maxBytes) {
-      // eslint-disable-next-line no-console
-      console.warn(`[${label}] public seat: skill ${name} not inlined (over ${maxBytes} bytes in total)`);
-      continue;
-    }
-    total += bytes;
-    sections.push(section);
-    onIncluded?.(source);
-  }
-  return sections;
-};
-
-/** The preamble, every section and `trailer`, or null when no skill could be read. */
-export const skillsAsText = async (skillSources, options) => {
-  const sections = await readSkillSections(skillSources, options);
-  return sections.length
-    ? `${SKILLS_AS_TEXT_PREAMBLE}${SECTION_SEPARATOR}${sections.join(SECTION_SEPARATOR)}${options.trailer || ''}`
-    : null;
-};

package/src/lib/skills-import.js

@@ -1,113 +0,0 @@
-/**
- * Local skills import — the metadata half of "your agent arrives whole"
- * (retention plan Phase C, D3). Scans a local skills directory
- * (<cwd>/.claude/skills or ~/.claude/skills) for SKILL.md files, parses
- * NAME + DESCRIPTION out of the frontmatter, and registers agent-scoped
- * skill entries so the agent's profile shows what it can do.
- *
- * Deliberately metadata-only (plan D3): skill *content* stays on the
- * user's machine — local agents execute their skills locally, Commonly
- * doesn't need the body, and skill files can carry private material. The
- * uploaded SKILL.md is a frontmatter-only stub that says exactly that.
- */
-
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { homedir } from 'os';
-import { join } from 'path';
-
-export const MAX_SKILLS = 50;
-
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
-
-/** Parse `name:` and `description:` out of SKILL.md frontmatter. */
-export const parseSkillMeta = (markdown, fallbackName) => {
-  const fm = FRONTMATTER_RE.exec(markdown);
-  if (!fm) return { name: fallbackName, description: '' };
-  const fields = {};
-  for (const line of fm[1].split(/\r?\n/)) {
-    const m = /^(name|description):\s*(.+)$/.exec(line.trim());
-    if (m && !fields[m[1]]) fields[m[1]] = m[2].trim().replace(/^['"]|['"]$/g, '');
-  }
-  return {
-    name: fields.name || fallbackName,
-    description: (fields.description || '').slice(0, 500),
-  };
-};
-
-/**
- * Find skill directories. Explicit dir wins; otherwise check the two
- * well-known locations. Each candidate is a directory whose subdirs
- * contain a SKILL.md.
- */
-export const detectSkills = ({ cwd = process.cwd(), home = homedir(), explicitDir = null } = {}) => {
-  const roots = [];
-  if (explicitDir) {
-    if (!existsSync(explicitDir) || !statSync(explicitDir).isDirectory()) {
-      throw new Error(`No such directory: ${explicitDir}`);
-    }
-    roots.push(explicitDir);
-  } else {
-    for (const candidate of [join(cwd, '.claude', 'skills'), join(home, '.claude', 'skills')]) {
-      try {
-        if (existsSync(candidate) && statSync(candidate).isDirectory()) roots.push(candidate);
-      } catch {
-        // symlinked skill roots can dangle; skip quietly
-      }
-    }
-  }
-
-  const skills = [];
-  const seen = new Set();
-  for (const root of roots) {
-    for (const entry of readdirSync(root).sort()) {
-      const skillFile = join(root, entry, 'SKILL.md');
-      try {
-        if (!existsSync(skillFile) || !statSync(skillFile).isFile()) continue;
-      } catch {
-        continue;
-      }
-      const meta = parseSkillMeta(readFileSync(skillFile, 'utf8'), entry);
-      if (seen.has(meta.name)) continue;
-      seen.add(meta.name);
-      skills.push({ ...meta, path: skillFile });
-      if (skills.length >= MAX_SKILLS) return skills;
-    }
-  }
-  return skills;
-};
-
-/** The frontmatter-only stub that gets uploaded in place of skill content. */
-export const skillStub = ({ name, description }) => [
-  '---',
-  `name: ${name}`,
-  `description: ${description || name}`,
-  '---',
-  '',
-  'Imported as metadata from a local agent — the skill itself runs on the',
-  "agent's own machine; its content was intentionally not uploaded.",
-  '',
-].join('\n');
-
-/**
- * Register the skills as agent-scoped entries via POST /api/skills/import.
- * `client` must be authenticated as the USER (pod membership is checked),
- * not the agent runtime token.
- */
-export const importSkills = async (client, { skills, podId, agentName, instanceId = 'default' }) => {
-  const results = [];
-  for (const skill of skills) {
-    // eslint-disable-next-line no-await-in-loop
-    await client.post('/api/skills/import', {
-      podId,
-      name: skill.name,
-      content: skillStub(skill),
-      metadataOnly: true,
-      description: skill.description || undefined,
-      scope: 'agent',
-      agentName,
-      instanceId,
-    });
-    results.push(skill.name);
-  }
-  return { imported: results.length, names: results };
-};

package/src/lib/spawn-credential.js

@@ -1,402 +0,0 @@
-/**
- * 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
-);
-
-/**
- * The events a turn reads: its batch, or the one event it ran. A batch's own
- * `_id` is synthetic, so the batch list is the only real answer for one. Only
- * the wrapper builds that list, so it counts only on the batch type.
- */
-export const turnEventIds = (event) => {
-  if (event?.type === 'inbox.batch' && Array.isArray(event.payload?.batchEventIds)) return event.payload.batchEventIds;
-  return event?._id ? [String(event._id)] : [];
-};
-
-/**
- * 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, ownerWoken }`.
- *
- * `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.
- *
- * `ownerWoken` (F145) is true only when the server said exactly that. A seat
- * token can't be marked, and an older backend doesn't answer, so both read as
- * false and the memory tools stay withheld.
- */
-export const openSpawnCredential = async ({
-  client,
-  seatToken,
-  spawnId,
-  desiredTtlSeconds = null,
-  policy = null,
-  publicSeat = false,
-  eventIds = [],
-  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,
-      {
-        spawnId,
-        ...(ask === null ? {} : { ttlSeconds: ask }),
-        ...(publicSeat ? { publicSeat: true, eventIds } : {}),
-      },
-    );
-  } 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, ownerWoken: false,
-      };
-    }
-    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, ownerWoken: false, 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, ownerWoken: false, 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,
-    ownerWoken: minted.ownerWoken === true,
-  };
-};
-
-/** 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,
-  publicSeat = false,
-  eventIds = [],
-  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, publicSeat, eventIds, 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; },
-  };
-};