quoxcli 0.0.0-stage → 0.2.0

package/lib/core/residentAuth.js

@@ -0,0 +1,243 @@
+/**
+ * Resident agent authentication for QuoxCLI (quox#453 phase 15)
+ *
+ * A dev server's resident agent authenticates with an Ed25519 key on disk
+ * instead of a password, zero human minting. The exchange is a signed
+ * challenge:
+ *
+ *   1. POST {baseUrl}/api/auth/resident/challenge {org_id, host_id}
+ *        -> {challenge_id, challenge_b64, expires_in}
+ *   2. sign the raw challenge bytes with the Ed25519 private key at key_path
+ *   3. POST {baseUrl}/api/auth/resident/token {challenge_id, org_id, host_id, signature_b64}
+ *        -> {access_token, token_type, expires_in, user}
+ *
+ * Bootstrap file on a dev host (not secret itself, points at the real key):
+ *   ~/.config/quox/resident-profile.json
+ *   {kind: 'resident', org_id, host_id, key_id, key_path, instance_url}
+ *
+ * Neither the private key nor any resulting token is ever printed or logged
+ * by this module.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { sign, createPrivateKey } from 'node:crypto';
+import { QuoxError, QuoxAuthError, QuoxTransientAuthError } from './errors.js';
+
+export function defaultResidentProfilePath() {
+  return join(homedir(), '.config', 'quox', 'resident-profile.json');
+}
+
+export function expandHome(p) {
+  if (!p) return p;
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  return p;
+}
+
+/**
+ * Load and validate the resident bootstrap profile.
+ * @param {string} [explicitPath] - overrides the default ~/.config/quox/resident-profile.json
+ */
+export function loadResidentProfile(explicitPath) {
+  const path = expandHome(explicitPath) || defaultResidentProfilePath();
+
+  if (!existsSync(path)) {
+    throw new QuoxError(
+      `No resident profile found at ${path}. A resident agent needs this bootstrap file `
+      + `({kind, org_id, host_id, key_id, key_path, instance_url}) before it can authenticate. `
+      + `Run --resident-profile <path> to point at a different one.`
+    );
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch (err) {
+    throw new QuoxError(`Could not read resident profile at ${path}: ${err.message}`);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    throw new QuoxError(`Resident profile at ${path} is not valid JSON: ${err.message}`);
+  }
+
+  const required = ['org_id', 'host_id', 'key_path'];
+  const missing = required.filter((key) => !data[key]);
+  if (missing.length > 0) {
+    throw new QuoxError(
+      `Resident profile at ${path} is missing required field(s): ${missing.join(', ')}.`
+    );
+  }
+
+  return { ...data, kind: 'resident', _path: path };
+}
+
+/**
+ * Prefer the bootstrap file's instance_url when the active CLI profile has
+ * no explicit URL of its own: a resident agent bootstraps its own instance
+ * pointer, it shouldn't need a human to also run `quox config`.
+ */
+export function resolveResidentBaseUrl(config, profile) {
+  // quox#455 gap 1: the resident endpoints live on the instance EDGE
+  // (https://<host>:3000/api/auth/resident/*, proxied to auth). NEVER
+  // derive them by port-swapping to :3101: auth binds loopback on the
+  // control box, so :3101 is connection-refused from every remote host.
+  if (process.env.QUOX_AUTH_URL) return process.env.QUOX_AUTH_URL;
+  if (process.env.QUOX_URL) return process.env.QUOX_URL;
+  const activeProfile = typeof config.getActiveProfile === 'function' ? config.getActiveProfile() : null;
+  const hasExplicitUrl = !!(activeProfile && activeProfile.url && activeProfile.url !== 'http://localhost:3000');
+  if (hasExplicitUrl) return activeProfile.url;
+  if (profile?.instance_url) return profile.instance_url;
+  // Local default profile on the control box itself: auth is directly
+  // reachable on loopback :3101, keep the historical local-dev behaviour.
+  return config.getServiceUrl('auth');
+}
+
+/**
+ * True only when `urlStr` is https AND its host is a bare IP or a
+ * .local/LAN-style single-label name: the shapes that can never carry a
+ * real, publicly-issued certificate, so a self-signed edge is the expected
+ * (not the exceptional) case. A public FQDN with a real cert must never get
+ * this baked in, even if it happens to be reachable over the LAN.
+ */
+function isSelfSignedLikelyHost(urlStr) {
+  let u;
+  try {
+    u = new URL(urlStr);
+  } catch {
+    return false;
+  }
+  if (u.protocol !== 'https:') return false;
+  const host = u.hostname;
+  if (!host) return false;
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) return true; // bare IPv4
+  if (host.includes(':')) return true; // bare IPv6 (URL strips the brackets)
+  if (/\.local$/i.test(host)) return true; // mDNS / LAN-style
+  if (!host.includes('.')) return true; // single-label hostname, never a public FQDN
+  return false;
+}
+
+/**
+ * Derive the systemd unit environment for a resident's headless supervisor
+ * from its bootstrap profile (item 1, live outage 2026-08-23: a unit run
+ * directly by systemd inherits none of the caller's shell environment, so
+ * every re-auth against a self-signed LAN edge died with a bare "fetch
+ * failed"). Baked in once, at install time, from the same profile the
+ * resident already trusts for its own identity: QUOX_URL and QUOX_AUTH_URL
+ * from instance_url, QUOX_COLLECTOR_URL from collector_url, and
+ * QUOX_INSECURE only when isSelfSignedLikelyHost(instance_url) is true.
+ * Returns {} for a missing profile or a profile with neither URL: the
+ * caller is responsible for warning in that case, this function only ever
+ * derives, never decides whether the result is enough.
+ */
+export function deriveSupervisorEnv(profile) {
+  const env = {};
+  if (!profile) return env;
+  if (profile.instance_url) {
+    env.QUOX_URL = profile.instance_url;
+    env.QUOX_AUTH_URL = profile.instance_url;
+    if (isSelfSignedLikelyHost(profile.instance_url)) env.QUOX_INSECURE = '1';
+  }
+  if (profile.collector_url) env.QUOX_COLLECTOR_URL = profile.collector_url;
+  return env;
+}
+
+const TRANSIENT_STATUSES = new Set([429, 502, 503, 504]);
+
+// Retry-After is delta-seconds or an HTTP date; returns ms or null.
+function parseRetryAfterMs(res) {
+  const raw = res?.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null;
+  if (!raw) return null;
+  const secs = Number(raw);
+  if (Number.isFinite(secs) && secs >= 0) return Math.round(secs * 1000);
+  const at = Date.parse(raw);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : null;
+}
+
+function exchangeFailure(what, res, data) {
+  const msg = `${what} failed (${res.status}): ${data?.error || res.statusText || 'unknown error'}`;
+  if (TRANSIENT_STATUSES.has(res.status)) return new QuoxTransientAuthError(msg, parseRetryAfterMs(res));
+  return new QuoxAuthError(msg);
+}
+
+async function safeJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run the challenge/sign/token exchange and return the token response.
+ * Never logs the private key or the returned token.
+ *
+ * @param {object} opts
+ * @param {string} opts.baseUrl
+ * @param {object} opts.profile - result of loadResidentProfile()
+ * @param {typeof fetch} [opts.fetchImpl]
+ */
+export async function residentLogin({ baseUrl, profile, fetchImpl = fetch }) {
+  const { org_id, host_id, key_path } = profile;
+  const keyPath = expandHome(key_path);
+
+  if (!existsSync(keyPath)) {
+    throw new QuoxError(
+      `Resident identity key not found at ${keyPath}. Provision the Ed25519 key before logging in.`
+    );
+  }
+
+  let keyPem;
+  try {
+    keyPem = readFileSync(keyPath, 'utf-8');
+  } catch (err) {
+    throw new QuoxError(`Could not read resident identity key at ${keyPath}: ${err.message}`);
+  }
+
+  let privateKey;
+  try {
+    privateKey = createPrivateKey(keyPem);
+  } catch (err) {
+    throw new QuoxError(`Resident identity key at ${keyPath} is not a valid private key: ${err.message}`);
+  }
+
+  // Step 1: request a fresh challenge.
+  const challengeRes = await fetchImpl(`${baseUrl}/api/auth/resident/challenge`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ org_id, host_id }),
+  });
+  const challengeData = await safeJson(challengeRes);
+  if (!challengeRes.ok) {
+    throw exchangeFailure('Resident challenge request', challengeRes, challengeData);
+  }
+  const { challenge_id, challenge_b64 } = challengeData || {};
+  if (!challenge_id || !challenge_b64) {
+    throw new QuoxError('Resident challenge response is missing challenge_id or challenge_b64.');
+  }
+
+  // Step 2: sign the raw challenge bytes with the Ed25519 key.
+  const challengeBytes = Buffer.from(challenge_b64, 'base64');
+  const signatureBytes = sign(null, challengeBytes, privateKey);
+  const signature_b64 = signatureBytes.toString('base64');
+
+  // Step 3: exchange the signature for an access token.
+  const tokenRes = await fetchImpl(`${baseUrl}/api/auth/resident/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ challenge_id, org_id, host_id, signature_b64 }),
+  });
+  const tokenData = await safeJson(tokenRes);
+  if (!tokenRes.ok) {
+    throw exchangeFailure('Resident token exchange', tokenRes, tokenData);
+  }
+  if (!tokenData?.access_token) {
+    throw new QuoxError('Resident token response is missing access_token.');
+  }
+
+  return tokenData;
+}

package/lib/core/residentPump.js

@@ -0,0 +1,229 @@
+/**
+ * Resident pump — QUOXPERTICUS-REVISIT P4 "steer pump".
+ *
+ * When a resident's slot is held by a FULL INTERACTIVE claude session (the
+ * resident itself, deployed via `quox dev resident deploy`), the warden
+ * process never answers (see the HOLD-IS-THE-VOICE gate in
+ * supervisorEngine.js): the resident already holds the voice. What the
+ * warden does instead, while that hold lasts, is PUMP: relay new owner
+ * messages from the slot channel into the resident's live tmux pane via the
+ * dev-sessions `keys` route (services/collector/lib/devSessionsProxy.js), so
+ * the interactive session hears its owner without anyone opening the pane
+ * by hand.
+ *
+ * Live-spike findings this reads (2026-09-04, real injection into a real
+ * claude TUI on .131 via tmux send-keys):
+ *   - Text injected mid-turn queues cleanly in the composer and submits when
+ *     the turn ends. Injection mid-turn is SAFE.
+ *   - A permission dialog ("Do you want to proceed? ... Esc to cancel")
+ *     BLOCKS the pipeline indefinitely. Queued input survives but does not
+ *     process. This pump NEVER injects bare Enter or any control key to
+ *     resolve one; a stuck dialog is a residentAlarm.js condition, not
+ *     something this module resolves. See paneHasDialog below.
+ *   - `keys` is one line, max 4096 chars (the collector's MAX_KEYS_LENGTH),
+ *     and the collector appends Enter itself.
+ *
+ * Every I/O dependency (fetch, pane read, key injection, heartbeat, the
+ * clock, sleep) is injected, matching supervisorEngine.js's contract, so
+ * this runs under vitest with no real network, no real tmux pane.
+ */
+
+import { pickNewMessages, boundSeenIds, pruneOldTurns, shouldPostErrorNotice, ERROR_NOTICE_WINDOW_MS, DEFAULT_SETTINGS } from './supervisorEngine.js';
+
+// The exact literal markers a Claude Code permission dialog shows
+// ("Do you want to proceed? 1. Yes 2. No ... Esc to cancel"). Either marker
+// alone is enough to hold injection: better to over-detect (delay a message
+// one pass) than under-detect and blind-inject into a live approval prompt.
+export const DIALOG_MARKERS = ['Do you want to proceed?', 'Esc to cancel'];
+
+export function paneHasDialog(paneText) {
+  const text = String(paneText || '');
+  return DIALOG_MARKERS.some((marker) => text.includes(marker));
+}
+
+function sanitizeOneLine(text) {
+  return String(text || '').replace(/\r?\n+/g, ' ').replace(/[ \t]{2,}/g, ' ').trim();
+}
+
+/**
+ * Build the `keys` line(s) for one owner message: `[slot:<name> owner]
+ * <text>`, newlines collapsed to spaces (a literal newline mid-line would
+ * submit a half-typed line early — same reasoning as residentSeed.js's
+ * oneLine()). A message that overflows maxLen is CHUNKED, never truncated
+ * (silent data loss is worse than several turns): each chunk carries its
+ * own prefix and a `(i/n)` suffix so the resident can read each line
+ * standalone.
+ */
+export function buildPumpLines({ slotName, text, maxLen = 4000 }) {
+  const prefix = `[slot:${slotName} owner] `;
+  const sanitized = sanitizeOneLine(text);
+  if (prefix.length + sanitized.length <= maxLen) {
+    return [`${prefix}${sanitized}`];
+  }
+  // Reserve headroom for the ` (NN/NN)` suffix appended to every chunk.
+  const suffixReserve = 10;
+  const available = Math.max(1, maxLen - prefix.length - suffixReserve);
+  const parts = [];
+  for (let i = 0; i < sanitized.length; i += available) {
+    parts.push(sanitized.slice(i, i + available));
+  }
+  return parts.map((part, i) => `${prefix}${part} (${i + 1}/${parts.length})`);
+}
+
+export function createInitialPumpState() {
+  return {
+    bootstrapped: false,
+    seen_ids: [],
+    // Owner messages picked up from the channel but not yet delivered to
+    // the pane: held back by a stuck dialog, or by the per-hour cap. A
+    // message only ever leaves `pending` by being injected, never dropped.
+    pending: [],
+    injection_timestamps: [],
+    overflow_notices: [],
+    // Set the moment a permission dialog is first observed; cleared the
+    // moment it is no longer observed. residentAlarm.js reads the age of
+    // this field to decide whether the stuck-dialog condition should alarm.
+    stuck_dialog_since: null,
+  };
+}
+
+/**
+ * Heartbeat the resident's slot hold with retry/backoff. The pump must not
+ * rely on the wait long-poll alone to keep the hold warm: a failed poll
+ * pass must never stop heartbeats while the collector is genuinely
+ * reachable, so this is a small standalone retry loop, called every pump
+ * pass regardless of what else happens this pass.
+ */
+export async function heartbeatWithBackoff({
+  heartbeatHold,
+  log = () => {},
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  maxAttempts = 3,
+  baseDelayMs = 2000,
+}) {
+  let lastErr = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await heartbeatHold();
+      return { ok: true, attempts: attempt };
+    } catch (err) {
+      lastErr = err;
+      log('warn', `pump: heartbeat attempt ${attempt}/${maxAttempts} failed: ${err.message}`);
+      if (attempt < maxAttempts) {
+        await sleep(baseDelayMs * attempt);
+      }
+    }
+  }
+  log('warn', `pump: heartbeat failed after ${maxAttempts} attempt(s), giving up this pass (hold may lapse): ${lastErr ? lastErr.message : 'unknown error'}`);
+  return { ok: false, attempts: maxAttempts, error: lastErr };
+}
+
+/**
+ * Run one pump pass: heartbeat the resident's hold, read the pane for a
+ * stuck permission dialog, pick up new owner messages, and inject whatever
+ * is safe to inject this pass (never while a dialog is visible, never past
+ * the per-hour cap).
+ *
+ * Injected dependencies:
+ *   fetchMessages()      -> array of slot messages (same shape the engine
+ *                           uses; a `wait`-mode caller can pass the same
+ *                           closure it already built for the headless path)
+ *   readPane()            -> current pane text (string)
+ *   injectKeys(line)      -> POST one `keys` line to the resident's pane
+ *   heartbeatHold()       -> heartbeat the slot AS the resident's own
+ *                           holder_session (not this warden's identity)
+ *   postReply(text)       -> slot `say`, used only for the once-per-hour
+ *                           overflow notice
+ */
+export async function runPumpOnce({
+  hostId,
+  slot,
+  selfIdentity,
+  fromFilters = [],
+  fetchMessages,
+  readPane,
+  injectKeys,
+  heartbeatHold,
+  postReply,
+  state,
+  log = () => {},
+  now = () => Date.now(),
+  maxSeenIds = 500,
+  maxTurnsPerHour = DEFAULT_SETTINGS.max_turns_per_hour,
+  maxLineLen = 4000,
+  heartbeatMaxAttempts = 3,
+  heartbeatBaseDelayMs = 2000,
+  sleep,
+}) {
+  const heartbeat = await heartbeatWithBackoff({
+    heartbeatHold, log, sleep, maxAttempts: heartbeatMaxAttempts, baseDelayMs: heartbeatBaseDelayMs,
+  });
+
+  const paneText = await readPane();
+  const dialogPresent = paneHasDialog(paneText);
+
+  let nextState = { ...state, pending: [...(state.pending || [])] };
+
+  if (dialogPresent) {
+    if (nextState.stuck_dialog_since == null) {
+      nextState.stuck_dialog_since = now();
+      log('warn', `slot ${slot}: permission dialog detected in the resident's pane on ${hostId}; holding owner messages until it clears (never injecting Enter to resolve it).`);
+    }
+  } else if (nextState.stuck_dialog_since != null) {
+    log('info', `slot ${slot}: permission dialog cleared after ${Math.round((now() - nextState.stuck_dialog_since) / 1000)}s; resuming injection.`);
+    nextState.stuck_dialog_since = null;
+  }
+
+  const messages = await fetchMessages();
+  const firstRun = nextState.bootstrapped !== true;
+  const picked = pickNewMessages({ messages, seenIds: nextState.seen_ids, selfIdentity, fromFilters, firstRun });
+  nextState.seen_ids = boundSeenIds(picked.seenIds, maxSeenIds);
+  if (firstRun) {
+    nextState.bootstrapped = true;
+    log('info', `pump first run on ${slot}: seeded seen-set with ${picked.allSeen.length} existing message id(s), queuing none for injection.`);
+  }
+
+  const newPending = picked.toAnswer.filter((m) => !nextState.pending.some((p) => p.id === m.id));
+  nextState.pending = [...nextState.pending, ...newPending];
+  if (newPending.length > 0) {
+    log('info', `pump: queued ${newPending.length} new owner message(s) for ${slot}'s resident.`);
+  }
+
+  let injected = 0;
+  let capHit = false;
+
+  if (!dialogPresent) {
+    let timestamps = pruneOldTurns(nextState.injection_timestamps, now(), ERROR_NOTICE_WINDOW_MS);
+    const stillPending = [];
+    for (const message of nextState.pending) {
+      if (timestamps.length >= maxTurnsPerHour) {
+        capHit = true;
+        stillPending.push(message);
+        continue;
+      }
+      const lines = buildPumpLines({ slotName: slot, text: message.text, maxLen: maxLineLen });
+      for (const line of lines) {
+        await injectKeys(line);
+      }
+      timestamps = [...timestamps, now()];
+      injected += 1;
+      log('info', `pump: injected message ${message.id} from ${message.from} into ${slot}'s resident pane (${lines.length} line(s)).`);
+    }
+    nextState.pending = stillPending;
+    nextState.injection_timestamps = timestamps;
+  } else if (nextState.pending.length > 0) {
+    log('warn', `pump: ${nextState.pending.length} owner message(s) on ${slot} held, waiting for the permission dialog to clear.`);
+  }
+
+  if (capHit && nextState.pending.length > 0) {
+    const notice = shouldPostErrorNotice(nextState.overflow_notices, 'pump_rate_cap', now(), ERROR_NOTICE_WINDOW_MS);
+    nextState.overflow_notices = notice.notices;
+    if (notice.shouldPost) {
+      const text = `Pump injection cap reached (${maxTurnsPerHour}/hour) on slot ${slot}: ${nextState.pending.length} owner message(s) still queued, will resume as the hour rolls over.`;
+      await postReply(text);
+      log('warn', `pump: posted once-per-hour overflow notice on ${slot} (${nextState.pending.length} still queued).`);
+    }
+  }
+
+  return { state: nextState, injected, dialogPresent, pendingCount: nextState.pending.length, heartbeat };
+}

package/lib/core/residentSeed.js

@@ -0,0 +1,104 @@
+/**
+ * Resident seed prompt — QUOXPERTICUS-REVISIT P3 "Resident lifecycle v1".
+ *
+ * The seed is the one line of text typed into a freshly-deployed interactive
+ * `claude` tmux pane (via the dev-sessions `keys` route) that turns a bare
+ * shell into the host's resident: read the revival kit before acting, claim
+ * the slot, then say a short hello. This encodes the proven 2026-09-04
+ * revival recipe (read MEMORY.md + indexed memories + NOTES_TO_SELF.md
+ * before acting, then claim, then greet) as a template, parameterized by
+ * host and slot.
+ *
+ * `keys` is a single line per call (the collector appends Enter — see
+ * services/collector/lib/devSessionsProxy.js MAX_KEYS_LENGTH=4096), so the
+ * rendered seed collapses to ONE line: no literal newlines, which would
+ * otherwise submit a half-typed prompt early.
+ *
+ * LATER PHASE SEAM: a collector-stored per-org/per-host seed override is a
+ * follow-up (dashboard-editable, versioned). Until that lands,
+ * `loadSeedOverride()` is the only override point, reading a local file on
+ * the CONTROL side (the box running `quox dev resident deploy`) verbatim.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function defaultSeedOverridePath() {
+  return join(homedir(), '.quox', 'resident', 'seed.md');
+}
+
+/**
+ * Read a local seed override file, if present. Returns null when the file
+ * is missing, unreadable, or empty — never throws, since a missing override
+ * simply means "use the built-in template", not an error.
+ *
+ * SEAM: a later phase replaces/augments this with a collector-stored
+ * config record (org/host-scoped, dashboard-editable). This function is the
+ * one place that phase needs to change.
+ */
+export function loadSeedOverride(path = defaultSeedOverridePath()) {
+  try {
+    if (!existsSync(path)) return null;
+    const content = readFileSync(path, 'utf-8');
+    return content && content.trim() ? content : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Collapse arbitrary text to one line safe for a single `keys` send. */
+function oneLine(text) {
+  return String(text || '').replace(/\s*\r?\n+\s*/g, ' ').replace(/[ \t]{2,}/g, ' ').trim();
+}
+
+function builtInTemplate({ hostId, slotName }) {
+  const claimCmd = `quox slot checkout ${slotName} --session resident-${slotName} --kind interactive --host ${hostId} --create`;
+  return (
+    `You are the resident Claude session for host ${hostId} (slot ${slotName}). ` +
+    `Before doing anything else: read ~/.claude/projects/-home-control/memory/MEMORY.md and every ` +
+    `memory file it indexes, then read ~/NOTES_TO_SELF.md if it exists, then read any identity or ` +
+    `onboarding docs in your home directory for this host. Read all of it before you act on anything. ` +
+    `Once you have read everything, claim your slot with: ${claimCmd}. ` +
+    `Then post one short hello (1-2 lines, no em dashes, lead with outcome) into the slot channel ` +
+    `confirming you are up and what you found.`
+  );
+}
+
+/**
+ * Render the seed prompt for a host/slot pair, as one line.
+ * @param {object} params
+ * @param {string} params.hostId
+ * @param {string} params.slotName
+ * @param {string} [params.overrideText] - test seam; when omitted, falls
+ *   back to loadSeedOverride().
+ */
+export function renderSeedPrompt({ hostId, slotName, overrideText } = {}) {
+  if (!hostId) throw new Error('renderSeedPrompt: hostId is required');
+  if (!slotName) throw new Error('renderSeedPrompt: slotName is required');
+
+  const override = overrideText !== undefined ? overrideText : loadSeedOverride();
+  if (override) {
+    return oneLine(
+      override.replace(/\{\{?\s*hostId\s*\}?\}/g, hostId).replace(/\{\{?\s*slotName\s*\}?\}/g, slotName)
+    );
+  }
+  return oneLine(builtInTemplate({ hostId, slotName }));
+}
+
+/**
+ * Split a one-line seed into <= maxLen chunks, each sent as its own `keys`
+ * call (each call appends its own Enter). Under maxLen this is a single
+ * chunk — the preferred, normal path. Splitting a seed that overflows
+ * maxLen means the resident receives it as multiple separate turns rather
+ * than one line, which is a documented degrade, not silent truncation.
+ */
+export function chunkSeedText(text, maxLen = 4000) {
+  const s = String(text || '');
+  if (s.length <= maxLen) return [s];
+  const chunks = [];
+  for (let i = 0; i < s.length; i += maxLen) {
+    chunks.push(s.slice(i, i + maxLen));
+  }
+  return chunks;
+}