@humwick/runner 0.0.0-stage → 0.130.0

package/src/question-decision.ts

@@ -0,0 +1,18 @@
+import { COORDINATOR_PROFILE_NAMES, errMessage, type OperatorDecisionFileInput, type HumwickHttpClient } from "@humwick/sdk";
+
+// #2914: a coordinator's AskUserQuestion becomes a durable operator decision (same store, dashboard card and
+// answer-as-message as relay_decision). Any other agent, or a failed file, keeps the live relayed question.
+export async function fileQuestionDecision(
+  deps: { http: Pick<HumwickHttpClient, "fileDecision">; profile?: string; log(message: string): void },
+  input: OperatorDecisionFileInput,
+): Promise<{ id: number } | undefined> {
+  if (!(COORDINATOR_PROFILE_NAMES as readonly string[]).includes(deps.profile ?? "")) return undefined;
+  try {
+    const decision = await deps.http.fileDecision(input);
+    deps.log(`AskUserQuestion filed as operator decision #${decision.id}`);
+    return { id: decision.id };
+  } catch (error) {
+    deps.log(`AskUserQuestion not filed as a decision (${errMessage(error)}); relaying it as a live question`);
+    return undefined;
+  }
+}

package/src/quota.ts

@@ -0,0 +1,22 @@
+export {
+  DEFAULT_PROVIDER_QUOTA_CONFIG,
+  QuotaRetryAfterError,
+  claudeRateLimitHeadersQuotaState,
+  claudeUsageQuotaState,
+  collectClaudeQuotaState,
+  collectCodexQuotaSample,
+  collectCodexQuotaState,
+  codexRateLimitsQuotaState,
+  credentialAccountKey,
+  defaultClaudeConfigDir,
+  defaultZaiCredentialsPath,
+  normalizeProviderQuotaConfig,
+  providerPayloadAccountKey,
+  resolveClaudeQuotaIdentity,
+  resolveClaudeStatuslineQuotaIdentity,
+  resolveCodexQuotaIdentity,
+  resolveStableClaudeQuotaIdentity,
+  resolveStableCodexQuotaIdentity,
+  resolveStableZaiQuotaIdentity,
+  type ProviderQuotaIdentity,
+} from "@humwick/sdk/provider-quota";

package/src/rate-limit.ts

@@ -0,0 +1,351 @@
+// #286 — shared rate-limit hold construction + Claude pane detection.
+//
+// Two detection arms feed the SAME provider-neutral `blocked` hold:
+//   1. The StopFailure hook (clean API-error turn-end: API-429/auth/billing) → control-server.
+//   2. Pane-scrape of the subscription "session/weekly limit" modal (no hook exists for it —
+//      anthropics/claude-code#34817 was closed not-planned) → the Claude adapter.
+// Both build the hold here so the shape stays identical, and the relay's resume sweep
+// (services/rate-limit-resume.ts) lifts either once the window resets.
+
+import { PROXY_AUTH_HOLD_KIND, type ProviderState } from "@humwick/sdk";
+
+export const RATE_LIMIT_BLOCK_REASON = "rate_limit";
+
+// Reject a parsed reset that's in the past or implausibly far out — a bad parse would
+// otherwise resume too early (thrash) or hold for days. Beyond this we drop resetAt and
+// fall back to the resume sweep's poll window.
+const MAX_RESET_AHEAD_MS = 7 * 24 * 60 * 60 * 1000;
+
+interface RateLimitHoldInput {
+  errorType?: string;
+  kind?: "usage_limit" | "transient_overload";
+  /** Unix ms the limit window resets, when known. */
+  resetAt?: number;
+  message?: string;
+  source?: string;
+}
+
+// #3577 — Claude reports a proxy that refused CONNECT as "Couldn't connect through your proxy
+// (ERR_PROXY_TUNNEL)"; Agent Vault refuses an expired or revoked session with 407.
+const PROXY_AUTH_FAILURE_RE = /ERR_PROXY_TUNNEL|proxy authentication required|\b407\b[^\n]*proxy|proxy[^\n]*\b407\b/i;
+
+export function isProxyAuthFailure(message: string | undefined): boolean {
+  return PROXY_AUTH_FAILURE_RE.test(message ?? "");
+}
+
+/** The blocked providerState a rate-limit hold carries. Shared by every detection arm. */
+export function buildRateLimitProviderState(input: RateLimitHoldInput): ProviderState {
+  const now = Date.now();
+  // A rejected proxy credential is no overload or usage wall: hold under its own kind, never auto-retried.
+  if (isProxyAuthFailure(input.message)) {
+    return {
+      state: "blocked",
+      reason: RATE_LIMIT_BLOCK_REASON,
+      label: "proxy auth failed: Vault proxy refused the session (407)",
+      recommendedAction: "The credential proxy rejected this agent's session; retries cannot clear it. Check its Vault service access, then restart the agent.",
+      kind: PROXY_AUTH_HOLD_KIND,
+      source: input.source ?? "claude",
+      errorType: input.errorType ?? PROXY_AUTH_HOLD_KIND,
+      enteredAt: now,
+      message: input.message,
+      updatedAt: now,
+    };
+  }
+  const resetAt = typeof input.resetAt === "number" && Number.isFinite(input.resetAt) ? input.resetAt : undefined;
+  const kind = input.kind ?? rateLimitKindForError(input.errorType);
+  const label = kind === "transient_overload"
+    ? "provider overloaded"
+    : resetAt ? `usage limit · resets ${formatResetClock(resetAt)}` : "usage limit reached";
+  return {
+    state: "blocked",
+    reason: RATE_LIMIT_BLOCK_REASON,
+    label,
+    recommendedAction: kind === "transient_overload"
+      ? "Holding briefly for provider overload; Humwick will retry with bounded backoff."
+      : "Holding until the usage window resets; Humwick auto-resumes the agent.",
+    kind,
+    source: input.source ?? "claude",
+    errorType: input.errorType ?? RATE_LIMIT_BLOCK_REASON,
+    enteredAt: now,
+    ...(resetAt ? { resetAt } : {}),
+    ...(input.message ? { message: input.message } : {}),
+    updatedAt: now,
+  };
+}
+
+function rateLimitKindForError(errorType: string | undefined): "usage_limit" | "transient_overload" {
+  return /^(overloaded|server_error|api_error|unknown|529|5\d\d)$/i.test(errorType ?? "") ? "transient_overload" : "usage_limit";
+}
+
+/** Host-local HH:MM for the chat notice / badge label (matches how the CLI shows "resets 3:45pm"). */
+function formatResetClock(resetAtMs: number): string {
+  try {
+    return new Date(resetAtMs).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  } catch {
+    return new Date(resetAtMs).toISOString().slice(11, 16);
+  }
+}
+
+// The subscription limit line wordings seen in the wild (claude-auto-retry patterns +
+// claude-auto-retry#15: "session"/"weekly limit" slipped past older regexes). These match
+// PROSE as readily as the modal, so they are never sufficient on their own — see
+// parseClaudeUsageLimitModal for the structural gate that decides what is a real hold.
+const LIMIT_PHRASE_RE = /(?:hit (?:your|the)\s*(?:[\w-]+\s+)*limit|usage limit|\d+-hour limit|limit reached|out of (?:extra )?usage|rate limit(?:\s+(?:hit|reached|exceeded))?|weekly limit|session limit)/i;
+const RESET_AT_RE = /\bresets?\b(?:\s+at)?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*(?:\(([^)]+)\))?/i;
+const TRY_AGAIN_RE = /\btry again in\s+(\d+)\s*(second|minute|hour|day)s?/i;
+
+// #1611 — the limit phrase and its reset/retry must sit on the same line or within this many
+// lines of each other. The pairing was originally allowed to span the WHOLE pane so a modal
+// wrapping across rows still matched; that made the two halves collectable from unrelated
+// places on screen. A modal wraps onto the very next row, so a tight window keeps the wrapped
+// case (proven in rate-limit.test.ts) without the pane-wide collection.
+const MAX_PAIR_GAP_LINES = 2;
+
+interface PaneRateLimit {
+  /** The matched limit line, for the chat notice / observability. */
+  message: string;
+  /** Unix ms reset, when parseable from the pane (else undefined → resume falls back to poll). */
+  resetAt?: number;
+  /** Usage limits wait for reset; transient provider overloads retry quickly. */
+  kind?: "usage_limit" | "transient_overload";
+  errorType?: string;
+}
+
+/**
+ * Detect a Claude usage/rate-limit modal in a captured tmux pane and parse its reset time.
+ * Returns null when the pane shows no live hold. `nowMs` is injectable for tests.
+ */
+export function parseClaudeRateLimitPane(text: string, nowMs: number = Date.now()): PaneRateLimit | null {
+  if (!text) return null;
+  const overload = parseClaudeTransientOverloadPane(text);
+  if (overload) return overload;
+  return parseClaudeUsageLimitModal(text, nowMs);
+}
+
+/**
+ * #1611 — the usage-limit modal, distinguished from the agent's OWN pane output.
+ *
+ * The capture (`capture-pane -S -80`) contains the agent's rendered conversation, so a
+ * phrase test over the whole pane fires on any agent that WRITES about rate limits. It did:
+ * a coordinator briefing a worker rendered `usage limit · resets 21:00` — which is the very
+ * label buildRateLimitProviderState() above produces — and marked itself blocked. Requiring
+ * the limit/reset PAIRING does not help either, because that one string carries both halves;
+ * neither does any test of line shape, since an agent working on this file renders exact
+ * modal fixtures (this comment is itself on screen while you read it).
+ *
+ * So the gate is POSITIONAL, not textual. Claude Code pins its composer (input box +
+ * status/hint footer) to the bottom of the screen, separated from the conversation by a blank
+ * row, and draws blocking dialogs in that same spot. Everything the agent itself renders is
+ * therefore ABOVE the last blank row; the live modal is BELOW it. We only scan that trailing
+ * block — no phrase the agent can emit reaches it.
+ *
+ * Break condition (accepted, deliberate): if Claude Code ever draws the limit dialog ABOVE a
+ * blank row (e.g. above a persistent status bar), this stops firing and the hold is missed —
+ * a false negative, which costs one retry via the resume sweep. That is the cheap direction:
+ * a false positive marks a healthy agent blocked, and `isAgentUnavailable` (src/db/
+ * agent-predicates.ts) then QUEUES its inbound messages until the fabricated reset — real
+ * work idled on a fabricated signal. See #1611.
+ */
+function parseClaudeUsageLimitModal(text: string, nowMs: number): PaneRateLimit | null {
+  const block = livePaneBlock(text);
+  for (let i = 0; i < block.length; i++) {
+    const line = block[i]!;
+    if (!LIMIT_PHRASE_RE.test(line)) continue;
+    const message = cleanPaneLine(line);
+    // The reset may wrap onto a neighbouring row of the same modal, never further.
+    const window = block.slice(Math.max(0, i - MAX_PAIR_GAP_LINES), i + MAX_PAIR_GAP_LINES + 1).join("\n");
+
+    const relative = TRY_AGAIN_RE.exec(window);
+    if (relative) {
+      const unitMs = { second: 1000, minute: 60_000, hour: 3_600_000, day: 86_400_000 }[relative[2]!.toLowerCase()] ?? 0;
+      const resetAt = clampReset(nowMs + Number(relative[1]) * unitMs, nowMs);
+      return { message, ...(resetAt ? { resetAt } : {}) };
+    }
+    const reset = RESET_AT_RE.exec(window);
+    if (reset) {
+      const resetAt = clampReset(parseClockReset(reset, nowMs), nowMs);
+      return { message, ...(resetAt ? { resetAt } : {}) };
+    }
+    // Limit phrase but no reset/retry beside it — not confident it's the modal; skip.
+  }
+  return null;
+}
+
+// #2619 — account-level usage/quota walls as providers word them in an API error message (zai:
+// "Usage limit reached for 5 hour. Your limit will reset at 2026-09-24 03:47:08"). Narrower than
+// LIMIT_PHRASE_RE on purpose: a bare "rate limit" is a per-request throttle, not a quota wall.
+const USAGE_LIMIT_MESSAGE_RE = /usage limit|usage exceeded|quota|limit (?:will )?resets?\b|insufficient (?:balance|credits?)/i;
+const RESET_AT_TIMESTAMP_RE = /\bresets?\s+(?:at\s+)?(\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?\s*(?:Z|[+-]\d{2}:?\d{2}))/i;
+
+type ProviderRefusal = { message: string; errorType?: string; statusCode?: number };
+
+/** An account-level usage/quota wall: retrying in-session or re-rolling the session cannot clear it. */
+export function isProviderUsageLimit(error: ProviderRefusal): boolean {
+  return USAGE_LIMIT_MESSAGE_RE.test(error.message) || /quota|usage_limit|tier_limit/i.test(error.errorType ?? "");
+}
+
+/** #2619 — a provider-wide overload (5xx): not a broken session, so never worth a re-roll. */
+export function isProviderOverload(error: ProviderRefusal): boolean {
+  return (error.statusCode !== undefined && error.statusCode >= 500) || /overload/i.test(error.errorType ?? "");
+}
+
+// #2619 — per-request throttle wording. Some providers send it on a non-429 status flagged
+// non-retryable (zai: 403 "Rate limit exceeded"); it is still a throttle, never an auth/model failure.
+const THROTTLE_MESSAGE_RE = /rate[\s_-]?limit|too many requests|throttl/i;
+
+/** A per-request throttle (429, or throttle wording on any status). It holds and retries, but it
+ *  is NOT an account wall: see {@link isProviderUsageLimit} for that. */
+export function isProviderThrottle(error: ProviderRefusal): boolean {
+  return error.statusCode === 429 || THROTTLE_MESSAGE_RE.test(error.message) || THROTTLE_MESSAGE_RE.test(error.errorType ?? "");
+}
+
+/** Any throttle / quota refusal. These hold as usage-class (reset time or the relay's fallback
+ *  window, never exhausted) — only a 5xx/overload is a transient, backoff-class hold. */
+function isProviderRateLimited(error: ProviderRefusal): boolean {
+  return isProviderThrottle(error) || isProviderUsageLimit(error);
+}
+
+/**
+ * #2619 — the hold a RETRYABLE provider API refusal (429 quota wall, 5xx overload) ends a turn in,
+ * instead of a terminal failure: a terminal `error` status resolves runner-core's provider exit,
+ * which is how every zai/OpenCode session died ~10 min into a quota wall. The same
+ * `blocked/rate_limit` hold the Claude arms raise: runner-core keeps it across the idle, the relay
+ * queues inbound mail, and its resume sweep wakes the agent at reset or on bounded backoff.
+ */
+export function buildProviderRefusalHold(input: ProviderRefusal & { detail: string; source: string; resetAt?: number }, nowMs: number = Date.now()): ProviderState {
+  const usageLimit = isProviderRateLimited(input);
+  // A provider-stated reset (OpenCode's retry `next`, #2775) beats parsing one out of the message.
+  const resetAt = usageLimit ? clampReset(input.resetAt, nowMs) ?? providerLimitResetAt(input.message, nowMs) : undefined;
+  return buildRateLimitProviderState({
+    kind: usageLimit ? "usage_limit" : "transient_overload",
+    errorType: input.errorType ?? (input.statusCode !== undefined ? String(input.statusCode) : "provider_error"),
+    message: input.detail,
+    source: input.source,
+    ...(resetAt ? { resetAt } : {}),
+  });
+}
+
+/**
+ * Reset time from a provider API error message, only when unambiguous: a relative "try again in
+ * N unit" or a timezone-qualified timestamp. A bare timestamp (zai's shape) has no zone, so it is
+ * left to the relay's fallback poll window rather than guessed.
+ */
+function providerLimitResetAt(message: string, nowMs: number = Date.now()): number | undefined {
+  const relative = TRY_AGAIN_RE.exec(message);
+  if (relative) {
+    const unitMs = { second: 1000, minute: 60_000, hour: 3_600_000, day: 86_400_000 }[relative[2]!.toLowerCase()] ?? 0;
+    return clampReset(nowMs + Number(relative[1]) * unitMs, nowMs);
+  }
+  const absolute = RESET_AT_TIMESTAMP_RE.exec(message);
+  return absolute ? clampReset(Date.parse(absolute[1]!.replace(" ", "T").replace(/\s+/g, "")), nowMs) : undefined;
+}
+
+/**
+ * The live bottom block of a captured pane: the last run of consecutive non-blank rows
+ * (trailing blanks ignored). On a healthy Claude pane that is the composer + footer chrome;
+ * on a held one it is the modal that replaced them. Panes with no blank row at all (unit-test
+ * one-liners, a short modal-only capture) yield the whole text, which is what we want.
+ */
+function livePaneBlock(text: string): string[] {
+  const lines = text.split(/\r?\n/);
+  let end = lines.length;
+  while (end > 0 && lines[end - 1]!.trim() === "") end--;
+  let start = end;
+  while (start > 0 && lines[start - 1]!.trim() !== "") start--;
+  return lines.slice(start, end);
+}
+
+// Unlike the usage-limit modal, Claude Code renders a transient API error as a CONVERSATION
+// row (`● API Error: 529 Overloaded…`), i.e. in the body, above the composer — so the
+// positional gate above cannot apply here without losing the detection entirely.
+// #1611 — but the arm had the same own-output hole: the phrase was matched anywhere on any
+// line, so an agent rendering this file's diff or a quoted error tripped it (reproduced live:
+// the fragment `+ane("● API Error: 529 Ove` in a rendered patch marked the agent blocked).
+// Claude's own error row STARTS with the error, after nothing but its bullet/box chrome, so
+// anchor there: text that merely embeds the phrase mid-line no longer matches. A genuine
+// error pane is unchanged.
+const TRANSIENT_API_ERROR_RE = /^API Error:\s*((?:5\d\d)|529)\b[^\n]*(?:overload|server-side|temporar|try again|status\.claude\.com)?[^\n]*/i;
+const TRANSIENT_5XX_RE = /^(?:5(?:00|02|03|04|20|29)|529)\b[^\n]*(?:overload|server-side|temporar|try again|status\.claude\.com)\b[^\n]*/i;
+// Row chrome Claude prefixes its rendered lines with: whitespace, bullets/spinners, and the
+// box-drawing block (U+2500–U+257F).
+const PANE_ROW_PREFIX_RE = /^[\s─-╿●⏺✳✻✽⎿>❯»→✗✘ו*-]+/;
+
+function parseClaudeTransientOverloadPane(text: string): PaneRateLimit | null {
+  for (const line of text.split(/\r?\n/)) {
+    const row = line.replace(PANE_ROW_PREFIX_RE, "");
+    const match = TRANSIENT_API_ERROR_RE.exec(row) ?? TRANSIENT_5XX_RE.exec(row);
+    if (!match) continue;
+    const code = match[1] ?? /\b(5\d\d|529)\b/.exec(match[0])?.[1];
+    return {
+      message: cleanPaneLine(line) || match[0].trim(),
+      kind: "transient_overload",
+      errorType: code === "529" ? "overloaded" : "server_error",
+    };
+  }
+  return null;
+}
+
+// The clean line containing the match offset, stripped of box-drawing chrome.
+function limitLineAt(text: string, index: number): string {
+  const start = text.lastIndexOf("\n", index) + 1;
+  const endNl = text.indexOf("\n", index);
+  const end = endNl === -1 ? text.length : endNl;
+  return cleanPaneLine(text.slice(start, end));
+}
+
+function cleanPaneLine(line: string): string {
+  return line.replace(/[│┌┐└┘─┤├╭╮╯╰]/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function clampReset(resetAt: number | undefined, nowMs: number): number | undefined {
+  if (resetAt === undefined || !Number.isFinite(resetAt)) return undefined;
+  if (resetAt <= nowMs || resetAt - nowMs > MAX_RESET_AHEAD_MS) return undefined;
+  return resetAt;
+}
+
+// Next occurrence of a wall-clock "H[:MM] am/pm" in the message's IANA timezone (if given
+// and valid) or host-local. Timezone-aware so "resets 4:50pm (Asia/Shanghai)" is correct
+// regardless of where the runner host sits.
+function parseClockReset(match: RegExpExecArray, nowMs: number): number | undefined {
+  let hour = Number(match[1]);
+  const minute = match[2] ? Number(match[2]) : 0;
+  const meridiem = match[3]?.toLowerCase();
+  const tz = match[4]?.trim();
+  if (!Number.isFinite(hour) || hour > 23 || minute > 59) return undefined;
+  if (meridiem === "pm" && hour < 12) hour += 12;
+  if (meridiem === "am" && hour === 12) hour = 0;
+
+  if (tz && isValidTimeZone(tz)) {
+    const { y, mo, d, offsetMs } = tzWallAndOffset(tz, nowMs);
+    let target = Date.UTC(y, mo - 1, d, hour, minute, 0) - offsetMs;
+    if (target <= nowMs) target += 86_400_000;
+    return target;
+  }
+  const d = new Date(nowMs);
+  d.setHours(hour, minute, 0, 0);
+  let target = d.getTime();
+  if (target <= nowMs) target += 86_400_000;
+  return target;
+}
+
+function isValidTimeZone(tz: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The target TZ's wall-clock date and UTC offset at `atMs`, via Intl (no deps).
+function tzWallAndOffset(tz: string, atMs: number): { y: number; mo: number; d: number; offsetMs: number } {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz, hour12: false,
+    year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit",
+  });
+  const parts = Object.fromEntries(dtf.formatToParts(new Date(atMs)).map((p) => [p.type, p.value])) as Record<string, string>;
+  const y = Number(parts.year), mo = Number(parts.month), d = Number(parts.day);
+  const h = Number(parts.hour) % 24, mi = Number(parts.minute), s = Number(parts.second);
+  const asUtc = Date.UTC(y, mo - 1, d, h, mi, s);
+  return { y, mo, d, offsetMs: asUtc - atMs };
+}

package/src/refused-prompt-store.ts

@@ -0,0 +1,36 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { runnerOutboxDirFromEnv } from "./config";
+
+/** #2622: unconfirmed self-posts remain cancelled across restart, without an in-memory tombstone cap. */
+export class RefusedPromptStore {
+  private readonly db: Database;
+
+  constructor(options: { agentId: string; dir?: string }) {
+    const dir = options.dir ?? runnerOutboxDirFromEnv() ?? join(tmpdir(), "agent-relay-outbox");
+    const name = sanitizeFsName(options.agentId, { replacement: "_", maxLen: 180, fallback: "agent" });
+    if (dir !== ":memory:") mkdirSync(dir, { recursive: true });
+    this.db = new Database(dir === ":memory:" ? dir : join(dir, `refused-prompts-${name}.sqlite`), { create: true });
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec("PRAGMA busy_timeout = 2000");
+    this.db.exec("CREATE TABLE IF NOT EXISTS unconfirmed_prompts (key TEXT PRIMARY KEY)");
+  }
+
+  begin(key: string): void {
+    // Persist before the first POST: even a crash while waiting for its response leaves cancellation evidence.
+    this.db.query("INSERT INTO unconfirmed_prompts (key) VALUES (?)").run(key);
+  }
+
+  confirm(key: string): void {
+    this.db.query("DELETE FROM unconfirmed_prompts WHERE key = ?").run(key);
+  }
+
+  isUnconfirmed(key: string): boolean {
+    return this.db.query("SELECT 1 FROM unconfirmed_prompts WHERE key = ?").get(key) !== null;
+  }
+
+  close(): void { this.db.close(); }
+}

package/src/relay-injection-events.ts

@@ -0,0 +1,161 @@
+import type { MessageSessionMeta, RelayInjectionCategory } from "@humwick/sdk";
+import { isSpawnProvider } from "@humwick/sdk";
+import type { ProviderConfig, RunnerSpawnConfig } from "./adapter";
+import { assembleLaunch } from "./launch-assembly";
+
+export interface RunnerRelayInjectionEvent {
+  category: RelayInjectionCategory;
+  summary: string;
+  detail: Record<string, unknown>;
+}
+
+interface RunnerRelayInjectionSessionEvent {
+  from: string;
+  to: string;
+  body: string;
+  session: MessageSessionMeta;
+}
+
+interface KeyedRelayInjectionEvent {
+  key: string;
+  event: RunnerRelayInjectionEvent;
+}
+
+interface RunnerLaunchInjectionInput {
+  carried?: RunnerRelayInjectionEvent[];
+  provider: string;
+  config: RunnerSpawnConfig;
+  providerConfig: ProviderConfig;
+  agentId: string;
+  providerSessionId: string;
+  timestamp?: number;
+}
+
+function launchInjectionEvents(input: RunnerLaunchInjectionInput): KeyedRelayInjectionEvent[] {
+  let events: KeyedRelayInjectionEvent[] = (input.carried ?? []).map((event, index) => ({ key: `spawn-${index}`, event }));
+  if (!isSpawnProvider(input.provider)) return events;
+  const assembled = assembleLaunch(input.provider, input.config, input.providerConfig);
+  // OpenCode/zai transport systemPromptAppend only with the first accepted provider turn. The
+  // server-side composition events historically said "injected" at spawn time, which made the
+  // dashboard claim delivery even when no initial prompt/inbox turn had run. Preserve the event
+  // and its source details, but label the transport truth as prepared/pending until that turn.
+  if (assembled.launchContextPending) {
+    events = events.map(({ key, event }) => ({
+      key,
+      event: event.summary.startsWith("injected ")
+        ? {
+            ...event,
+            summary: `prepared ${event.summary.slice("injected ".length)}`,
+            detail: { ...event.detail, transportState: "pending-first-provider-turn" },
+          }
+        : event,
+    }));
+  }
+  // #1565 P5.7 — the native-memory lever gets its OWN `memory`-category event (the channel #1612
+  // established for the spawn-seam memory block), not a line in the tools summary: this decides
+  // whether the agent has one memory store or two, and a SUPPRESSED lever must be visible even on
+  // a launch that provisions nothing else and would otherwise return early below.
+  const lever = assembled.nativeMemory;
+  if (lever.policy !== "default") {
+    events.push({
+      key: "native-memory",
+      event: {
+        category: "memory",
+        summary: lever.suppressed
+          ? `native memory ${lever.policy}: PARTIALLY applied — ${lever.suppressed.reason}`
+          : `native memory ${lever.policy} (${lever.applied.join(", ") || "no lever"})`,
+        detail: {
+          source: "native-memory-lever",
+          provider: assembled.provider,
+          base: assembled.base,
+          policy: lever.policy,
+          applied: lever.applied,
+          ...(lever.suppressed ? { suppressed: lever.suppressed } : {}),
+        },
+      },
+    });
+  }
+  // #3025 — a host without agent-redact still launches the agent; that launch must say so loudly.
+  // Appended last, so readers that find the first "tools" event still get the provisioning summary.
+  const redaction = assembled.redaction;
+  const redactionEvents: KeyedRelayInjectionEvent[] = redaction.state === "unavailable" ? [{
+    key: "redaction",
+    event: {
+      category: "tools",
+      summary: `secret redaction UNAVAILABLE, tool output reaches the model unmasked: ${redaction.reason}`,
+      detail: { source: "agent-redact", provider: assembled.provider, ...redaction },
+    },
+  }] : [];
+  const toolCount = assembled.skills.length + assembled.plugins.length + assembled.mcp.servers.length
+    + assembled.hooks.length
+    + assembled.projectSkills.length
+    + assembled.mcp.projectServers.length
+    + (assembled.projectSettings.applied ? 1 : 0)
+    + (assembled.relaySkills ? 1 : 0)
+    + (assembled.relayPlugin ? 1 : 0)
+    + (assembled.mcp.relayEndpoint ? 1 : 0)
+    + (assembled.statusLine ? 1 : 0)
+    + (redaction.state === "on" ? 1 : 0);
+  if (toolCount === 0) return [...events, ...redactionEvents];
+  const parts = [
+    assembled.relaySkills ? "relay skills" : "",
+    assembled.relayPlugin ? "relay plugin" : "",
+    assembled.statusLine ? "status line" : "",
+    assembled.mcp.relayEndpoint ? "relay MCP" : "",
+    assembled.skills.length ? `${assembled.skills.length} skill${assembled.skills.length === 1 ? "" : "s"}` : "",
+    assembled.projectSkills.length ? `${assembled.projectSkills.length} project skill${assembled.projectSkills.length === 1 ? "" : "s"}` : "",
+    assembled.projectSettings.applied ? "project settings" : "",
+    assembled.hooks.length ? `${assembled.hooks.length} hook${assembled.hooks.length === 1 ? "" : "s"}` : "",
+    assembled.plugins.length ? `${assembled.plugins.length} plugin${assembled.plugins.length === 1 ? "" : "s"}` : "",
+    assembled.mcp.servers.length ? `${assembled.mcp.servers.length} MCP server${assembled.mcp.servers.length === 1 ? "" : "s"}` : "",
+    assembled.mcp.projectServers.length ? `${assembled.mcp.projectServers.length} project MCP server${assembled.mcp.projectServers.length === 1 ? "" : "s"}` : "",
+    redaction.state === "on" ? `secret redaction (agent-redact ${redaction.version}, ${redaction.mechanism})` : "",
+  ].filter(Boolean);
+  events.push({
+    key: "tools",
+    event: {
+      category: "tools",
+      summary: `provisioned ${parts.join(", ")}`,
+      detail: {
+        source: "launch-assembly",
+        provider: assembled.provider,
+        base: assembled.base,
+        vanilla: assembled.vanilla,
+        relayContext: assembled.relayContext,
+        relayContextPending: assembled.relayContextPending === true,
+        launchContextPending: assembled.launchContextPending === true,
+        relaySkills: assembled.relaySkills,
+        relayPlugin: assembled.relayPlugin,
+        statusLine: assembled.statusLine,
+        skills: assembled.skills,
+        projectSkills: assembled.projectSkills,
+        projectSettings: assembled.projectSettings,
+        hooks: assembled.hooks,
+        plugins: assembled.plugins,
+        mcp: assembled.mcp,
+        redaction,
+      },
+    },
+  });
+  return [...events, ...redactionEvents];
+}
+
+export function runnerLaunchInjectionSessionEvents(input: RunnerLaunchInjectionInput): RunnerRelayInjectionSessionEvent[] {
+  const timestamp = input.timestamp ?? Date.now();
+  return launchInjectionEvents(input).map(({ event, key }) => ({
+    from: input.agentId,
+    to: "user",
+    body: event.summary,
+    session: {
+      type: "relay-injection",
+      stepId: `relay-injection:${input.providerSessionId}:${key}`,
+      relayInjection: {
+        category: event.category,
+        summary: event.summary,
+        detail: event.detail,
+        agentId: input.agentId,
+        timestamp,
+      },
+    },
+  }));
+}