aegis-desktop 1.0.7 → 1.0.8

package/lib/local/claude-pro.js

@@ -0,0 +1,755 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
+// AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
+// Conveying a modified copy, or running one as a network service, owes the
+// corresponding source under this licence (§5/§13) — see LICENSING.md.
+'use strict';
+
+/**
+ * claude-pro.js — the Claude Code Pro class: the user's own Claude
+ * subscription, driven through the `claude` CLI.
+ *
+ * ── why this is a CLASS and not a provider row ──────────────────────────────
+ *
+ * The other three classes reach a model over an HTTP API: `aegis` and `byok`
+ * post to the AEGIS relay, `local` posts to a daemon on loopback. This one
+ * reaches no API at all. A Pro/Max subscription is not an API key and is
+ * deliberately not usable as one — Claude Code's OAuth session is bound to the
+ * `claude` binary, and the only supported way for another program to spend that
+ * subscription is to spawn that binary. `~/aegiscodex-dev` proved the shape
+ * (src/backend.js runClaude): `claude -p <prompt> --output-format stream-json
+ * --include-partial-messages --verbose`, reading the stream off stdout.
+ *
+ * So the class has no baseURL, no key row, and no relay. It has an ARGV.
+ *
+ * ── the two rules this file exists to keep ──────────────────────────────────
+ *
+ * 1. **The argv is DERIVED, never hand-typed.** `one/src/child.js` already owns
+ *    that decision (AEGISONE decision D8 rule 4) and states why: a spawn site
+ *    that writes its own flags is a second policy, and the child's permission
+ *    system is the one nobody on this side can answer. The only argv builder is
+ *    `claudeArgv(descriptor)`, fed a posture record from
+ *    `one/src/permissions.js resolvePosture()`. This module therefore does NOT
+ *    build flags; it asks for a posture record and hands over a descriptor.
+ *
+ * 2. **Auth is the CLI's, not ours.** ~/.claude/.credentials.json is read to
+ *    ANSWER "is there a subscription here", and never written. That is the same
+ *    read-only contract the rest of the repo states (client/credentials.js's
+ *    "another product's file"), and it is why `claudeProStatus()` is an
+ *    inspector rather than a login.
+ *
+ * Resolution of both sibling modules is by EXISTENCE in the two layouts the
+ * repo already uses (a checkout, and the staged vendor tree), and a missing
+ * child.js is a thrown error rather than a local re-implementation — a second
+ * argv builder is exactly the drift rule 4 forbids.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// client/env-file.js, resolved the same two ways engine.js already resolves
+// it (a checkout, and a packaged desktop build's flat vendor dir) — the CLI's
+// mirrored tree preserves this file's own relative position, so the same
+// checkout path also resolves there.
+let envFileLib = null;
+try {
+  envFileLib = require('../../../client/env-file.js');
+} catch {
+  try {
+    envFileLib = require('../../vendor/env-file.js');
+  } catch {
+    envFileLib = null;
+  }
+}
+
+/** Claude Code's own config dir; `$CLAUDE_CONFIG_DIR` wins, as the CLI's does. */
+function claudeConfigDir(env) {
+  const e = env || process.env;
+  const override = e && e.CLAUDE_CONFIG_DIR;
+  if (override && String(override).trim()) return String(override).trim();
+  return path.join(os.homedir(), '.claude');
+}
+
+/**
+ * The user's Claude Code OAuth token, read the way the `claude` binary itself
+ * wants it handed to it: into the CHILD's environment only, never exported
+ * into this process's own `process.env`.
+ *
+ * `CLAUDE_CODE_OAUTH_TOKEN` is on client/env-file.js's FOREIGN_SECRET_NAMES —
+ * a credential for a different CLI, deliberately left OUT of the ambient
+ * `~/.aegiscode/.env` load every host does at start-up, because until this
+ * class existed no host in this repo read it. This class is now that one
+ * reader, and it reads it the way the split was designed for — explicitly,
+ * for the one process that needs it, never ambient to every other process on
+ * the machine.
+ *
+ * Checked in the order that keeps a real shell export authoritative:
+ *   1. the caller's own env bag (an explicit `CLAUDE_CODE_OAUTH_TOKEN=…`
+ *      export always wins — the same rule `loadEnvFile`'s rule 1 states).
+ *   2. `~/.aegiscode/secrets.env` — the file the split moves this name to.
+ *   3. `~/.aegiscode/.env`, parsed directly and never applied to any env
+ *      object — covers a token that has not been migrated to secrets.env yet
+ *      (`tools/split-env-secrets.mjs` is the migration), without this class
+ *      having to make the value ambient to get there.
+ *
+ * @param {object} [env] defaults to process.env
+ * @returns {string} '' when no source has it
+ */
+function claudeOAuthToken(env) {
+  // client/env-file.js owns the deny list AND the secrets-file resolution, so
+  // it is the one place that answers "does a foreign secret exist anywhere" —
+  // the CLI's model picker (cli/src/models.js) reads the SAME function to
+  // decide whether `/model` still needs to collect this token, and a second
+  // implementation here is exactly the drift that would let the two disagree.
+  if (!envFileLib) return '';
+  return envFileLib.resolveForeignSecret('CLAUDE_CODE_OAUTH_TOKEN', { env });
+}
+
+/**
+ * The env names that SHADOW the subscription when the `claude` CLI starts.
+ *
+ * Claude Code authenticates with `ANTHROPIC_API_KEY` (or `ANTHROPIC_AUTH_TOKEN`)
+ * when either is set, and that choice wins over the `claudeAiOauth` entry the
+ * subscription lives in. So a value that is not a credential at all does not
+ * merely fail on its own — it takes the plan down with it.
+ */
+const SHADOWING_ENV_VARS = Object.freeze(['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN']);
+
+/**
+ * The env for one `claude` child, with a shadowing value that cannot be a
+ * credential removed.
+ *
+ * ── why this exists (measured, 2026-10-14) ──────────────────────────────────
+ *
+ * `claude auth status` in the shell that launched this host:
+ *
+ *   { "loggedIn": true, "authMethod": "claude.ai", "apiProvider": "firstParty",
+ *     "apiKeySource": "ANTHROPIC_API_KEY", "email": null, "orgId": null,
+ *     "subscriptionType": null }                       ← the two-character state
+ *
+ * and the identical command with the one variable unset (`env -u
+ * ANTHROPIC_API_KEY claude auth status`):
+ *
+ *   { … "email": "…", "orgId": "9d5e56e1-…", "orgName": "…",
+ *     "subscriptionType": "pro" }                      ← the plan this user pays for
+ *
+ * The session was signed in the whole time; `~/.claude/.credentials.json` holds
+ * a valid `claudeAiOauth` entry naming `pro` (verified read-only). What was
+ * missing was only that the shell exported `ANTHROPIC_API_KEY=he` — two
+ * characters, the residue of a paste that lost its payload — so every `claude`
+ * child this host spawned authenticated as "API key: he" instead of as the
+ * subscription, and Claude Pro was unavailable in exactly the state a user is
+ * most likely to be in: the shell where they once pasted a key.
+ *
+ * ── what it does NOT do ─────────────────────────────────────────────────────
+ *
+ * It does not strip a real key. The floor is `client/env-file.js`'s
+ * `credentialLooksUsable` — the one place this repo decides "too short to be a
+ * credential" — so a genuine `ANTHROPIC_API_KEY` keeps its precedence, because
+ * a user who set one deliberately is asking for the pay-per-token path. Only a
+ * value that provably cannot be a key is dropped, and the drop is REPORTED
+ * rather than silent (see `envDroppedLine`).
+ *
+ * @param {object} [baseEnv] the caller's env bag
+ * @param {string} [token]   a `CLAUDE_CODE_OAUTH_TOKEN` to hand the child
+ * @returns {{env: object, dropped: Array<{name: string, length: number}>}}
+ */
+function childEnvPlan(baseEnv, token) {
+  const env = { ...(baseEnv || {}) };
+  const dropped = [];
+  const usable = envFileLib && typeof envFileLib.credentialLooksUsable === 'function'
+    ? envFileLib.credentialLooksUsable
+    : null;
+  // A host whose env module predates the floor keeps today's behaviour (the
+  // variable passes through): a second copy of the floor here is the drift
+  // client/env-file.js exists to prevent.
+  if (usable) {
+    for (const name of SHADOWING_ENV_VARS) {
+      const value = env[name];
+      if (typeof value !== 'string' || usable(value)) continue;
+      delete env[name];
+      // A variable set to '' shadows nothing worth reporting — it is removed
+      // (harmless) but the user is not told about a value they never gave.
+      const length = value.trim().length;
+      if (length > 0) dropped.push({ name, length });
+    }
+  }
+  if (token) env.CLAUDE_CODE_OAUTH_TOKEN = token;
+  return { env, dropped };
+}
+
+/** The one-line report for a child that started without a shadowing value. */
+function envDroppedLine(dropped) {
+  const list = Array.isArray(dropped) ? dropped : [];
+  if (!list.length) return null;
+  const names = list.map((d) => `${d.name} (${d.length} character${d.length === 1 ? '' : 's'})`).join(', ');
+  return `aegis: not passed to the claude child — ${names}: too short to be a credential, and the CLI would have spent it instead of your subscription`;
+}
+
+/** The shadowing value in `env` that cannot be a credential, if any (see above). */
+function shadowingValue(env) {
+  const bag = env || {};
+  const usable = envFileLib && typeof envFileLib.credentialLooksUsable === 'function'
+    ? envFileLib.credentialLooksUsable
+    : null;
+  if (!usable) return null;
+  for (const name of SHADOWING_ENV_VARS) {
+    const value = bag[name];
+    if (typeof value === 'string' && !usable(value)) return { name, length: value.trim().length };
+  }
+  return null;
+}
+
+/**
+ * Read Claude Code's credential file, without ever writing it.
+ *
+ * `kind` is 'oauth' (a `claudeAiOauth` entry — the Pro/Max subscription),
+ * 'apikey', or 'env-token' (see below). `subscription` is the plan the file
+ * itself names ('pro', 'max'), so the picker can say which subscription is
+ * being spent instead of guessing from the token's shape.
+ *
+ * `loggedIn` is deliberately NOT `!expired`: access tokens are short-lived and
+ * refreshed by the CLI on its next run, so a file holding a refresh token is a
+ * working subscription even when the access token has lapsed. Only a file with
+ * NO token at all is "not signed in" — anything stricter would tell a signed-in
+ * user to sign in again.
+ *
+ * A file that genuinely has no usable token (never logged in, or a refresh
+ * token that outright expired — the CLI's own `claude auth status` agrees in
+ * that case, there is no stricter-than-the-CLI check being applied here) falls
+ * back to `claudeOAuthToken()`: a `CLAUDE_CODE_OAUTH_TOKEN` the user has set
+ * aside (shell export, `secrets.env`, or an unmigrated `.env` line) is handed
+ * to the `claude` child directly by `runClaudePro`, and the CLI authenticates
+ * with it regardless of what is on disk. Reporting "not logged in" while that
+ * token would actually work is the gap this closes — the file is read-only
+ * state, the token is a second, equally real way to be signed in.
+ */
+function claudeProStatus(opts) {
+  const o = opts || {};
+  const env = o.env || process.env;
+  const file = path.join(o.dir || claudeConfigDir(env), '.credentials.json');
+  const out = {
+    claude: o.claudeVersion || null,
+    file,
+    exists: false,
+    kind: null,
+    subscription: null,
+    expiresAt: 0,
+    loggedIn: false,
+  };
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    out.exists = true;
+  } catch {
+    data = null;
+  }
+  const oauth = data && data.claudeAiOauth;
+  if (oauth && (oauth.accessToken || oauth.refreshToken)) {
+    out.kind = 'oauth';
+    out.subscription = oauth.subscriptionType || null;
+    out.expiresAt = Number(oauth.refreshTokenExpiresAt) || 0;
+    out.loggedIn = true;
+  } else if (data && typeof data.token === 'string' && data.token) {
+    out.kind = 'apikey';
+    out.loggedIn = true;
+  } else if (claudeOAuthToken(env)) {
+    out.kind = 'env-token';
+    out.loggedIn = true;
+  }
+  // A shadowing env var that cannot be a credential does NOT change `loggedIn`
+  // — the subscription is there — but it is the one state where "signed in" and
+  // "actually spends the plan" differ, because the CLI prefers that name. The
+  // child is fixed regardless (childEnvPlan); this reports it so a status
+  // surface can say why, rather than leaving `apiKeySource: ANTHROPIC_API_KEY`
+  // to be discovered from `claude auth status` by hand.
+  out.shadowed = shadowingValue(env);
+  return out;
+}
+
+/** The model aliases the `claude` CLI itself accepts (`claude --model <alias>`). */
+const PRO_MODELS = Object.freeze([
+  { id: 'default', label: 'Default (recommended)', note: 'the CLI picks for the subscription' },
+  { id: 'sonnet', label: 'Sonnet', note: 'alias the CLI resolves' },
+  { id: 'opus', label: 'Opus', note: 'alias the CLI resolves' },
+  { id: 'haiku', label: 'Haiku', note: 'alias the CLI resolves' },
+]);
+
+/**
+ * The extra argv this class owns (what the child is told about the turn),
+ * separate from the argv `one/src/child.js` owns (what the child is allowed to
+ * do). Keeping the two apart is the point of rule 4: the permission half is
+ * derived from the posture record, and this half is derived from the payload.
+ *
+ * NOTE: the session flags are NOT here even though they are "about the turn".
+ * `--resume`/`--session-id` decide whether this turn is the same conversation
+ * as the previous one — that is a policy about continuity, and it lives with
+ * the other flags in the one argv builder, so a second spawn site cannot grow
+ * its own opinion about it. `runClaudePro` passes `resumeSessionId`/
+ * `sessionId` through the descriptor instead.
+ */
+function turnArgs(payload) {
+  const args = [];
+  const p = payload || {};
+  if (p.system && String(p.system).trim()) {
+    args.push('--append-system-prompt', String(p.system));
+  }
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// The stream-json reader
+// ---------------------------------------------------------------------------
+
+/**
+ * Line-oriented parser for `claude --output-format stream-json`. Pure: it feeds
+ * callbacks and keeps only the tool bookkeeping between lines, so a test can
+ * replay a captured transcript without spawning anything.
+ *
+ * Ported from ~/aegiscodex-dev src/backend.js createStreamParser(), which is
+ * the reference implementation on this machine and carries the field names the
+ * protocol actually uses. Two details there are load-bearing and are kept
+ * verbatim:
+ *
+ *   - `input_json_delta` fragments arrive routed BY BLOCK INDEX. Parallel
+ *     same-name tool calls interleave their argument JSON, and matching on
+ *     "the first collecting block" pairs a fragment with the wrong call.
+ *   - one `user` line can carry a tool_result for EVERY call in a parallel
+ *     round, so all of them are resolved, not just the first.
+ */
+function createStreamParser(handlers) {
+  const h = handlers || {};
+  const tools = new Map(); // id -> {id, index, name, args, startedAt, phase}
+  let text = '';
+  let resultLine = null;
+
+  const emitRun = (block) => {
+    let args = block.args;
+    try {
+      args = block.args ? JSON.parse(block.args) : {};
+    } catch {
+      args = {};
+    }
+    tools.set(block.id, { ...block, args, phase: 'run' });
+    if (h.onTool) h.onTool({ id: block.id, name: block.name, args, phase: 'run' });
+  };
+
+  const collecting = (index) =>
+    [...tools.values()].find((t) => t.phase === 'collecting' && t.index === index) ||
+    [...tools.values()].find((t) => t.phase === 'collecting');
+
+  return {
+    line(raw) {
+      let j;
+      try {
+        j = JSON.parse(raw);
+      } catch {
+        return;
+      }
+
+      if (j.type === 'stream_event' && j.event) {
+        const e = j.event;
+        if (e.type === 'content_block_start' && e.content_block) {
+          if (e.content_block.type === 'tool_use') {
+            tools.set(e.content_block.id, {
+              id: e.content_block.id,
+              index: e.index == null ? 0 : e.index,
+              name: e.content_block.name,
+              args: '',
+              startedAt: Date.now(),
+              phase: 'collecting',
+            });
+          }
+        } else if (e.type === 'content_block_delta' && e.delta) {
+          if (e.delta.type === 'text_delta') {
+            const t = (e.delta.text || '').replace(/\x00/g, '');
+            text += t;
+            if (h.onText && t) h.onText(t);
+          } else if (e.delta.type === 'input_json_delta') {
+            const t = collecting(e.index == null ? 0 : e.index);
+            if (t) t.args += e.delta.partial_json || '';
+          }
+        } else if (e.type === 'content_block_stop') {
+          const t = collecting(e.index == null ? 0 : e.index);
+          if (t) emitRun(t);
+        }
+      } else if (j.type === 'user' && j.message) {
+        const content = Array.isArray(j.message.content) ? j.message.content : [];
+        for (const tr of content) {
+          if (!tr || tr.type !== 'tool_result' || !tr.tool_use_id) continue;
+          const t = tools.get(tr.tool_use_id);
+          if (!t) continue;
+          const elapsed = Math.max(0, Date.now() - (t.startedAt || Date.now()));
+          if (h.onTool) {
+            h.onTool({ id: t.id, name: t.name, phase: 'done', elapsed, error: !!tr.is_error });
+          }
+          tools.delete(tr.tool_use_id);
+        }
+      } else if (j.type === 'result') {
+        resultLine = j;
+        if (h.onDone) {
+          h.onDone({
+            text: text || j.result || '',
+            error: j.is_error ? j.result || 'api error' : undefined,
+            usage: j.usage || null,
+            costUsd: typeof j.total_cost_usd === 'number' ? j.total_cost_usd : undefined,
+            durationMs: j.duration_ms,
+            sessionId: j.session_id,
+          });
+        }
+      }
+      // system / assistant / rate_limit_event lines carry no UI data.
+    },
+    get text() {
+      return text;
+    },
+    get resultLine() {
+      return resultLine;
+    },
+  };
+}
+
+/**
+ * Resolve `one/src/child.js` and `one/src/permissions.js` in the two layouts the
+ * repo uses, or throw naming the file. No fallback implementation: rule 4's
+ * whole guarantee is that there is exactly ONE argv builder, so a local copy
+ * here would be the drift the decision forbids.
+ */
+function loadSeam(dir) {
+  const here = dir || __dirname;
+  const candidates = [
+    // A checkout: desktop/lib/local → <repo>/one/src
+    path.join(here, '..', '..', '..', 'one', 'src'),
+    // A packaged desktop app: desktop/lib/local → desktop/vendor/one/src
+    path.join(here, '..', '..', 'vendor', 'one', 'src'),
+    // The published CLI's mirrored tree: cli/vendor/desktop/lib/local →
+    // cli/vendor/one/src (the manifest stages one/src there under 'mirror').
+    path.join(here, '..', '..', '..', '..', 'one', 'src'),
+  ];
+  for (const base of candidates) {
+    try {
+      const child = require(path.join(base, 'child.js'));
+      const permissions = require(path.join(base, 'permissions.js'));
+      if (typeof child.claudeArgv === 'function' && typeof permissions.resolvePosture === 'function') {
+        return { child, permissions };
+      }
+    } catch {
+      /* try the next layout */
+    }
+  }
+  throw new Error(
+    'aegis: the Claude child argv builder (one/src/child.js + one/src/permissions.js) is missing ' +
+      'from this install — refusing to build a second argv, because a second argv is a second policy.'
+  );
+}
+
+/** Whether the argv seam resolves here, without throwing. For status panels. */
+function seamAvailable(dir) {
+  try {
+    loadSeam(dir);
+    return { ok: true, error: null };
+  } catch (e) {
+    return { ok: false, error: (e && e.message) || String(e) };
+  }
+}
+
+/**
+ * Run one turn on the user's Claude Code subscription.
+ *
+ * Returns the SAME shape the other three transports return, because the engine
+ * loop reads one shape (`choices[0].message.content`, `usage`, `stop_reason`) —
+ * `extractToolCalls`, `assistantText`, `finishReasonOf` and `addUsage` all read
+ * it. Returns NO tool_calls, and that is the design rather than an omission:
+ * the `claude` child runs its own agent loop with its own tools, so the work is
+ * already done by the time this resolves. Emitting tool_calls as well would
+ * hand a second, parallel loop the same task and run every tool twice.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.prompt
+ * @param {string}   [opts.model]        a `claude --model` alias (PRO_MODELS)
+ * @param {string}   [opts.system]       appended to the child's own prompt
+ * @param {string}   [opts.cwd]          the directory the child works in
+ * @param {string[]} [opts.addDir]       extra directories the child may work in.
+ *                                       The child resolves every relative path
+ *                                       and every tool's root against `cwd`
+ *                                       alone, so a turn started in a
+ *                                       subdirectory cannot see the tree above
+ *                                       it; this is what widens that. Spelled
+ *                                       by the ONE argv builder (one/src/child.js
+ *                                       addDirArgs), never typed here.
+ * @param {object}   [opts.rules]        CLI permission rules (cli/src/config.js)
+ * @param {boolean}  [opts.gate]         the stored /confirm posture, if known
+ * @param {string}   [opts.permissionMode] explicit passthrough, validated in child.js
+ * @param {string}   [opts.resumeSessionId] reattach to the session a prior turn
+ *                                       reported → the turn keeps its context
+ * @param {string}   [opts.sessionId]   name a NEW session (UUID) for a first turn
+ * @param {AbortSignal} [opts.signal]
+ * @param {Function} [opts.onSpawn]      receives the child the moment it exists
+ * @param {number}   [opts.idleTimeoutMs] silence budget (default 10 min)
+ * @returns {Promise<object>} an engine-shaped completion
+ */
+function runClaudePro(opts, deps) {
+  const o = opts || {};
+  const d = deps || {};
+  const seam = d.seam || loadSeam(d.dir);
+  const spawnFn = d.spawn || require('node:child_process').spawn;
+
+  // One posture per turn, from the single resolver — never re-derived here.
+  const posture = seam.permissions.resolvePosture({
+    rules: o.rules,
+    gate: o.gate,
+    interactive: false,
+    childKind: seam.permissions.CHILD_KINDS.HEADLESS,
+    env: o.env || process.env,
+  });
+
+  const built = seam.child.claudeArgv({
+    posture,
+    prompt: o.prompt,
+    model: o.model || undefined,
+    permissionMode: o.permissionMode,
+    // Continuity, handed to the ONE argv builder rather than typed as `extra`.
+    // Without these the child starts a brand-new conversation every turn: the
+    // engine does not replay the transcript into it (`pro` runs its own agent
+    // loop), so the CLI's own session store is the ONLY thing that can carry
+    // context across turns. `resumeSessionId` reattaches to the session a
+    // previous turn reported; `sessionId` names a new one for a later resume.
+    resumeSessionId: o.resumeSessionId,
+    sessionId: o.sessionId,
+    // The widened sandbox for this turn, if the caller asked for one. It rides
+    // the descriptor rather than `extra` because `--add-dir` is variadic and its
+    // correct spelling is a decision (child.js addDirArgs), not a flag a caller
+    // may type.
+    addDir: o.addDir,
+    // `--include-partial-messages` is what makes `stream_event` lines arrive at
+    // all, and `--verbose` is required by the CLI alongside stream-json in print
+    // mode. Both belong to the transport (this file), not to the posture.
+    extra: [...turnArgs(o), '--include-partial-messages', '--verbose'],
+  });
+
+  return new Promise((resolve) => {
+    if (o.signal && o.signal.aborted) {
+      resolve({ choices: [{ message: { content: '' }, finish_reason: 'stop' }], stopped: true });
+      return;
+    }
+
+    // `CLAUDE_CODE_OAUTH_TOKEN` is merged into the CHILD's env only — never
+    // written back to `o.env`/`process.env` — so a token the on-disk
+    // credential file lacks (or has let expire) still reaches the one process
+    // that can spend it, without making the value ambient to this host or any
+    // other child it spawns. See claudeOAuthToken() for where it comes from.
+    //
+    // `childEnvPlan` additionally refuses to hand over a shadowing var that
+    // cannot be a credential. Without it a signed-in machine runs the child as
+    // "API key: he" and the subscription is unreachable — see childEnvPlan.
+    const baseEnv = o.env || process.env;
+    const token = claudeOAuthToken(baseEnv);
+    const plan = childEnvPlan(baseEnv, token);
+    const childEnv = plan.env;
+    const droppedLine = envDroppedLine(plan.dropped);
+    if (droppedLine && o.onDelta) {
+      // Same channel the transcript already paints notes on, and emitted BEFORE
+      // the spawn so the line lands above the child's own tool rows.
+      try {
+        o.onDelta({ delta: '', note: droppedLine });
+      } catch {
+        /* a throwing renderer must not take the turn down */
+      }
+    }
+
+    let child;
+    try {
+      child = spawnFn(d.executable || 'claude', built.argv, {
+        cwd: o.cwd || process.cwd(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: childEnv,
+      });
+    } catch (e) {
+      resolve({
+        choices: [{ message: { content: '' }, finish_reason: 'error' }],
+        error: `claude: could not start the child (${(e && e.message) || e})`,
+        ...(plan.dropped.length ? { envDropped: plan.dropped } : {}),
+      });
+      return;
+    }
+
+    if (o.onSpawn) {
+      try {
+        o.onSpawn(child, built.record);
+      } catch {
+        /* a throwing hook must not take the turn down */
+      }
+    }
+
+    let finished = false;
+    let stderr = '';
+    let buffer = '';
+    let idle = null;
+    const idleMs = Number(o.idleTimeoutMs) || 10 * 60 * 1000;
+
+    const settle = (result) => {
+      if (finished) return;
+      finished = true;
+      if (idle) clearTimeout(idle);
+      if (o.signal) o.signal.removeEventListener('abort', kill);
+      // Recorded on every settle path, the same way `childRecord` is: what the
+      // child was NOT given is part of what this turn did, and a caller logging
+      // only the argv would show a turn that "should" have failed as a mystery.
+      resolve(plan.dropped.length ? { ...result, envDropped: plan.dropped } : result);
+    };
+
+    const kill = () => {
+      try {
+        child.kill('SIGTERM');
+      } catch {
+        /* already gone */
+      }
+      setTimeout(() => {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          /* already gone */
+        }
+      }, 1500);
+    };
+    if (o.signal) o.signal.addEventListener('abort', kill, { once: true });
+
+    // Idle watchdog, not a flat turn cap: it resets on every byte, so it fires
+    // only on true silence — which is what a lapsed OAuth session looks like
+    // when the child opens a re-auth prompt nobody on this side can answer.
+    const armIdle = () => {
+      if (idle) clearTimeout(idle);
+      idle = setTimeout(() => {
+        kill();
+        settle({
+          choices: [{ message: { content: '' }, finish_reason: 'stop' }],
+          error: `claude: the child went silent for ${Math.round(idleMs / 1000)}s and was stopped`,
+        });
+      }, idleMs);
+    };
+    armIdle();
+
+    const parser = createStreamParser({
+      onText: (t) => {
+        armIdle();
+        if (o.onDelta) o.onDelta({ delta: t });
+      },
+      onTool: (info) => {
+        armIdle();
+        if (!o.onDelta) return;
+        // Same tool frame the engine's own loop emits, so the renderers paint a
+        // subscription turn's tool rows with no second code path.
+        o.onDelta({
+          delta: '',
+          tool: {
+            name: info.name,
+            args: info.args,
+            ok: info.phase === 'done' ? !info.error : undefined,
+            id: info.id,
+            cwd: o.cwd,
+            phase: info.phase,
+          },
+        });
+      },
+      onDone: (r) => {
+        if (r.error) {
+          settle({
+            choices: [{ message: { content: r.text || '' }, finish_reason: 'error' }],
+            usage: r.usage || undefined,
+            error: r.error,
+          });
+          return;
+        }
+        settle({
+          choices: [{ message: { content: r.text || '' }, finish_reason: 'stop' }],
+          usage: r.usage || undefined,
+          costUsd: r.costUsd,
+          durationMs: r.durationMs,
+          sessionId: r.sessionId,
+          // Carried so a caller can log WHICH flags the child actually got —
+          // rule 4's "recorded, never inferred".
+          childRecord: built.record,
+        });
+      },
+    });
+
+    child.stdout.on('data', (chunk) => {
+      armIdle();
+      buffer += chunk.toString('utf8');
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+      for (const line of lines) {
+        const t = line.trim();
+        if (t) parser.line(t);
+      }
+    });
+    child.stderr.on('data', (chunk) => {
+      armIdle();
+      if (stderr.length < 8192) stderr += chunk.toString('utf8');
+    });
+
+    child.on('error', (e) => {
+      settle({
+        choices: [{ message: { content: '' }, finish_reason: 'error' }],
+        error:
+          `claude: could not run the child (${(e && e.message) || e}). ` +
+          'Install it with `npm i -g @anthropic-ai/claude-code`, then sign in with `claude auth login`.',
+      });
+    });
+
+    child.on('close', (code) => {
+      if (buffer.trim()) parser.line(buffer.trim());
+      // Only reached when no `result` line arrived — a clean exit always emits
+      // one. Anything else is a real failure and is reported as one rather than
+      // as an empty successful answer.
+      settle({
+        choices: [{ message: { content: parser.text }, finish_reason: 'stop' }],
+        usage: (parser.resultLine && parser.resultLine.usage) || undefined,
+        childRecord: built.record,
+        error:
+          parser.text || code === 0
+            ? undefined
+            : `claude: the child exited with status ${code}${
+                stderr.trim() ? ` — ${stderr.trim().split('\n').slice(-3).join(' ')}` : ''
+              }`,
+      });
+    });
+  });
+}
+
+/**
+ * The run-log line for a child argv, from the seam that owns the wording. A
+ * missing seam degrades to a short local summary rather than throwing — this is
+ * a reporting path, and a turn that already ran must not fail to describe
+ * itself.
+ */
+function childLine(record, dir) {
+  if (!record) return '';
+  try {
+    return loadSeam(dir).child.childRecordLine(record);
+  } catch {
+    const flag = record.skipFlag || 'no permission flag';
+    return `aegis: claude child [${record.kind}] ${flag}`;
+  }
+}
+
+module.exports = {
+  claudeConfigDir,
+  claudeOAuthToken,
+  claudeProStatus,
+  // The child-env half of "the subscription actually gets spent": the plan for
+  // what the `claude` child is given (and what a shadowing value cost), the
+  // one-line report of it, and the inspector `claudeProStatus` reports.
+  childEnvPlan,
+  envDroppedLine,
+  shadowingValue,
+  SHADOWING_ENV_VARS,
+  PRO_MODELS,
+  turnArgs,
+  createStreamParser,
+  loadSeam,
+  seamAvailable,
+  childLine,
+  runClaudePro,
+};