@humwick/runner 0.0.0-stage → 0.130.1

package/src/adapters/__fixtures__/codex-app-server.ts

@@ -0,0 +1,47 @@
+import { exitRunner } from "../../runner-exit";
+
+// A child whose bind and announcement are controlled independently by its parent test.
+const url = new URL(process.env.CODEX_APP_SERVER_URL!);
+let server: ReturnType<typeof Bun.serve>;
+let buffered = "";
+await Bun.connect({
+  hostname: "127.0.0.1",
+  port: Number(process.env.TEST_CONTROL_PORT),
+  socket: {
+    open(socket) { socket.write("booted\n"); },
+    data(socket, data) {
+      buffered += data.toString();
+      const lines = buffered.split("\n");
+      buffered = lines.pop()!;
+      for (const command of lines) {
+        if (command === "bind") {
+          server = Bun.serve({
+            hostname: url.hostname, port: Number(url.port),
+            fetch(req, srv) {
+              if (srv.upgrade(req, { data: undefined })) return;
+              return new Response(null, { status: 400 });
+            },
+            websocket: {
+              message(ws, raw) {
+                const request = JSON.parse(String(raw));
+                if (request.id !== undefined) ws.send(JSON.stringify({ id: request.id, result: { fixture: true } }));
+              },
+            },
+          });
+          socket.write("bound\n");
+        } else if (command === "partial") {
+          process.stderr.write("codex app-server (WebSockets)\n  listening on: ws://127.");
+          socket.write("partial\n");
+        } else if (command === "announce") {
+          process.stderr.write(`0.0.1:${server.port}\n`);
+        } else if (command === "wrong-port") {
+          process.stderr.write("  listening on: ws://127.0.0.1:1\n");
+        } else if (command === "fail") {
+          process.stderr.write("fatal: fixture bind failed: address already in use\n");
+          exitRunner(42, "fixture bind failure");
+        }
+      }
+    },
+    close() { exitRunner(0); },
+  },
+});

package/src/adapters/claude-api.ts

@@ -0,0 +1,243 @@
+import { relayEnv } from "@humwick/sdk/env";
+import type { Message, ProviderState } from "@humwick/sdk";
+import { resolveProviderApiAuth } from "@humwick/sdk/child-env";
+import { usdToMicroUsd } from "@humwick/sdk";
+import type { ApiBudgetDecision, ApiBudgetReservation } from "@humwick/sdk";
+import type { DeliverResult, ManagedProcess, PromptOfferOptions, ProviderConfig, ProviderDeliverContext, RunnerSpawnConfig, ShutdownOutcome, SpawnArgs } from "../adapter";
+import { ApiBudgetAccounting, isTransientBudgetFailure } from "../api-budget-accounting";
+import { ProviderSubmitFailure } from "../provider-submit-failure";
+import { buildRateLimitProviderState } from "../rate-limit";
+import { ClaudeHeadlessAdapter } from "./claude-headless";
+
+/** Native API auth plus a pre-launch reservation on the fleet's single durable ledger. */
+export class ClaudeApiAdapter extends ClaudeHeadlessAdapter {
+  private readonly budget = new ApiBudgetAccounting("claude-api", (action, body) => this.rpc(action, body), next => this.adoptReservation(next));
+  private get reservation() { return this.budget.reservation; }
+  private set reservation(value: ApiBudgetReservation | undefined) { this.budget.reservation = value; }
+  private get costMicroUsd() { return this.budget.costMicroUsd; }
+  private set costMicroUsd(value: number) { this.budget.costMicroUsd = value; }
+  private get accounting() { return this.budget.pending; }
+  private config?: RunnerSpawnConfig;
+  private managed?: ManagedProcess;
+  private held = false;
+  private budgetState?: ProviderState;
+  private heartbeat?: ReturnType<typeof setInterval>;
+  private expiry?: ReturnType<typeof setTimeout>;
+  private nativeCostMicroUsd = 0;
+  private nativeAllowanceMicroUsd = 0;
+  private nativeStartMicroUsd = 0;
+  private rollover = false;
+  private resumeSession?: string;
+
+  constructor() { super("claude-api"); }
+
+  override buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
+    if (!this.reservation) throw new ProviderSubmitFailure("Claude API requires a shared budget reservation before launch", false);
+    const built = super.buildSpawnArgs(config, providerConfig);
+    const args: string[] = [];
+    for (let i = 0; i < built.args.length; i++) {
+      const arg = built.args[i]!;
+      if (/^(?:--resume|--continue|-r|-c)(?:=|$)/.test(arg)) throw new ProviderSubmitFailure("Claude API resume requires separate accounting proof", false);
+      if (arg === "--max-budget-usd") { i++; continue; }
+      if (arg.startsWith("--max-budget-usd=")) continue;
+      args.push(arg);
+    }
+    this.nativeStartMicroUsd = this.costMicroUsd;
+    this.nativeAllowanceMicroUsd = this.reservation.allowanceMicroUsd - this.costMicroUsd;
+    return { ...built, args: [...args, "--max-budget-usd", String(this.nativeAllowanceMicroUsd / 1_000_000),
+      ...(this.resumeSession ? ["--resume", this.resumeSession] : [])],
+      env: resolveProviderApiAuth(this.provider, built.env, {
+        ANTHROPIC_API_KEY_FILE: providerConfig.env.ANTHROPIC_API_KEY_FILE ?? process.env.ANTHROPIC_API_KEY_FILE
+          ?? "~/.config/agent-relay/secrets/anthropic-api.key",
+      }) };
+  }
+
+  override async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    clearTimeout(this.expiry);
+    this.config = config;
+    // Validate fresh auth before reserving; no model child starts on denied/unknown accounting.
+    resolveProviderApiAuth(this.provider, config.env, { ...config.providerConfig.env,
+      ANTHROPIC_API_KEY_FILE: config.providerConfig.env.ANTHROPIC_API_KEY_FILE ?? process.env.ANTHROPIC_API_KEY_FILE
+        ?? "~/.config/agent-relay/secrets/anthropic-api.key" });
+    const endedSession = this.managed && (this.managed.process as Bun.Subprocess).exitCode !== null && this.reservation
+      ? { sessionId: this.reservation.sessionId, costMicroUsd: this.costMicroUsd } : undefined;
+    const decision = await this.budget.reserve(relayEnv(config.env, "AGENT_RELAY_PROVIDER_SESSION_ID") ?? crypto.randomUUID(), endedSession);
+    if (!decision.allowed || !decision.reservation) throw new ProviderSubmitFailure(`Claude API admission refused: ${decision.reason ?? "invalid reservation"}`, false);
+    this.managed = undefined;
+    this.held = false; this.costMicroUsd = 0;
+    this.budgetState = undefined;
+    this.nativeCostMicroUsd = 0; this.rollover = false; this.resumeSession = undefined;
+    this.reservation = decision.reservation;
+    try { this.managed = await super.spawn(config); }
+    catch (e) { this.held = true; throw e; } // Uncertain launch keeps the full reservation.
+    const managed = this.managed;
+    this.watchNativeProcess();
+    return managed;
+  }
+
+  private watchNativeProcess() {
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    const managed = this.managed!, child = managed.process as Bun.Subprocess;
+    const heartbeat = this.heartbeat = setInterval(() => { if (managed === this.managed) this.queueReport(); }, 5_000);
+    this.armExpiry();
+    void child.exited.finally(() => { if (managed === this.managed && managed.process === child) clearTimeout(this.expiry); clearInterval(heartbeat); }).catch(() => {});
+  }
+
+  /** One incarnation-owned expiry timer; re-read the window on every arm so a moved endsAt takes effect immediately (#3312). */
+  private armExpiry() {
+    clearTimeout(this.expiry);
+    const managed = this.managed, reservation = this.reservation;
+    if (!managed || !reservation) return;
+    this.armedEndsAt = reservation.endsAt;
+    const remaining = reservation.endsAt - Date.now();
+    if (remaining <= 0) this.stopForBudget("budget-window-ended");
+    else this.expiry = setTimeout(() => { if (managed === this.managed) this.armExpiry(); }, Math.min(remaining, 2_147_483_647));
+  }
+
+  private armedEndsAt?: number;
+
+  private adoptReservation(next: ApiBudgetReservation) {
+    const moved = next.endsAt !== this.armedEndsAt;
+    this.reservation = next;
+    if (moved) this.armExpiry();
+  }
+
+  override async deliver(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<number[] | DeliverResult> {
+    if (this.held) throw new ProviderSubmitFailure("Claude API budget requires operator action", false);
+    if (messages.length && this.rollover && !await this.prepareInput(process)) return { acknowledgedIds: [], providerHeldIds: messages.map(m => m.id) };
+    return super.deliver(process, messages, ctx);
+  }
+
+  override async deliverInitialPrompt(process: ManagedProcess, prompt: string, options?: PromptOfferOptions) {
+    if (!await this.prepareInput(process)) return "held" as const;
+    return super.deliverInitialPrompt(process, prompt, options);
+  }
+
+  private async prepareInput(process: ManagedProcess): Promise<boolean> {
+    await this.accounting;
+    if (this.held || !this.reservation || Date.now() >= this.reservation.endsAt) throw new ProviderSubmitFailure("Claude API budget is held or expired", false);
+    let decision: ApiBudgetDecision;
+    try { decision = await this.reportBudget(this.reservation.sessionId, { costMicroUsd: this.costMicroUsd, ...(this.rollover ? { renew: true } : {}) }); }
+    catch (e) {
+      if (isTransientBudgetFailure(e)) {
+        // Park the input under a transient hold: the relay's bounded resume backoff retries it, no operator step (#3373).
+        this.emitStatus({ status: "idle", providerState: { ...buildRateLimitProviderState({ kind: "transient_overload",
+          errorType: "budget_accounting_unavailable", message: "budget-accounting-unavailable", source: this.provider }),
+          label: "Claude API budget ledger unreachable; retrying" } });
+        return false;
+      }
+      this.accountingFailed(e, process);
+      throw new ProviderSubmitFailure("Claude API accounting refused input", false, e);
+    }
+    if (!decision.allowed) { this.stopForBudget(decision.reason ?? "budget-exhausted"); return false; }
+    if (this.rollover) {
+      try {
+        this.resumeSession = this.nativeSessionId(process);
+        if (!this.resumeSession) throw new Error("Claude API rollover has no native session to resume");
+        await this.replaceAtBoundary(process, this.config!);
+        this.rollover = false;
+        this.watchNativeProcess();
+      } catch (e) {
+        this.accountingFailed(e, process);
+        throw new ProviderSubmitFailure("Claude API accounting refused input", !this.held, e);
+      }
+    }
+    return true;
+  }
+
+  protected override onNativeResult(event: Record<string, unknown>) {
+    try {
+      if (typeof event.total_cost_usd !== "number") throw new Error("Missing final native spend");
+      const nativeCost = usdToMicroUsd(event.total_cost_usd);
+      this.costMicroUsd += Math.max(0, nativeCost - this.nativeCostMicroUsd);
+      this.nativeCostMicroUsd = Math.max(this.nativeCostMicroUsd, nativeCost);
+      if (this.costMicroUsd - this.nativeStartMicroUsd >= this.nativeAllowanceMicroUsd / 2) this.rollover = true;
+      this.queueReport();
+    } catch { this.stopForBudget("budget-final-spend-unknown"); }
+  }
+
+  protected override nativeResultHold(event: Record<string, unknown>): ProviderState | undefined {
+    if (event.subtype !== "error_max_budget_usd" || !this.managed) return undefined;
+    this.rollover = true;
+    this.retireAtBoundary(this.managed);
+    if (this.budgetState) return this.budgetState;
+    return { state: "blocked", reason: "rate_limit", kind: "usage_limit", source: this.provider,
+      label: "Claude API allowance reached; renewing reservation", resetAt: Date.now(), enteredAt: Date.now() };
+  }
+
+  override async compact(process: ManagedProcess, opts?: { instructions?: string }) {
+    if (!await this.prepareInput(process)) throw new ProviderSubmitFailure("Claude API budget refused compaction", !this.held);
+    return super.compact(process, opts);
+  }
+
+  override async clearContext(process: ManagedProcess) {
+    if (!await this.prepareInput(process)) throw new ProviderSubmitFailure("Claude API budget refused context clear", !this.held);
+    const result = await super.clearContext(process);
+    this.nativeCostMicroUsd = 0;
+    this.rollover = true;
+    return result;
+  }
+
+  private queueReport() {
+    const managed = this.managed, reservation = this.reservation;
+    // Serialize reports so a later input cannot race the result's accounting/refusal.
+    this.budget.queue(async () => {
+      if (!reservation || managed !== this.managed || this.held || this.budget.settlement) return;
+      const decision = await this.reportBudget(reservation.sessionId, { costMicroUsd: this.costMicroUsd, ...(this.rollover ? { renew: true } : {}) });
+      if (managed !== this.managed) return;
+      if (!decision.allowed) this.stopForBudget(decision.reason ?? "budget-exhausted");
+    }, e => this.accountingFailed(e, managed));
+  }
+
+  private accountingFailed(error: unknown, managed?: ManagedProcess) {
+    if (managed !== this.managed) return;
+    // The native --max-budget-usd cap and the expiry timer bound spend to the reservation while the
+    // ledger is unreachable, so a transient failure never stops the provider; new input still needs a report (#3373).
+    if (isTransientBudgetFailure(error)) return;
+    this.stopForBudget("budget-accounting-unavailable");
+  }
+
+  private stopForBudget(reason: string) {
+    if (this.held) return;
+    this.held = true;
+    this.budgetState = { state: "blocked", reason: "rate_limit", kind: "usage_limit",
+      source: this.provider, label: "Claude API budget held", message: reason,
+      recommendedAction: "Check the shared API credit grant and restart after restoring headroom", enteredAt: Date.now() };
+    try { this.emitStatus({ status: "idle", clear: ["provider-turn"], providerState: this.budgetState }); }
+    finally { if (this.managed) void this.shutdown(this.managed, { graceful: false, timeoutMs: 1_000 }).catch(() => {}); }
+  }
+
+  override async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
+    if (process !== this.managed) return super.shutdown(process, opts);
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    this.rollover = false;
+    const result = await super.shutdown(process, opts);
+    if ((process.process as Bun.Subprocess).exitCode !== null) {
+      await process.meta?.nativeExit;
+      await this.settle(process);
+    }
+    return result;
+  }
+
+  protected override async onNativeExit(child: Bun.Subprocess, _code: number, retired: boolean) {
+    const managed = this.managed;
+    if (managed?.process === child && !(this.rollover && retired)) await this.settle(managed);
+  }
+
+  private async settle(managed: ManagedProcess) {
+    await this.accounting;
+    if (managed !== this.managed || !this.reservation) return;
+    // Exit observation and explicit shutdown share one idempotent settlement attempt.
+    try { await this.budget.settle(); } catch { this.held = true; }
+  }
+
+  /** The ledger's reservation is authoritative: adopt its window so a reconfigured grant reaches running sessions. */
+  private async reportBudget(sessionId: string, body: { costMicroUsd: number; renew?: boolean }): Promise<ApiBudgetDecision> {
+    return this.budget.report(body);
+  }
+
+  private rpc(action: "reserve" | "report", body: Record<string, unknown>): Promise<ApiBudgetDecision> {
+    return this.budget.transport(this.config!, action, body);
+  }
+}

package/src/adapters/claude-context-command.ts

@@ -0,0 +1,16 @@
+import { tmuxCommand } from "@humwick/sdk/tmux-utils";
+import { claudePaneIsBusy } from "./claude-status-detectors";
+import { claudeComposerText } from "./claude-submit-confirmation";
+import { captureTmuxVisiblePaneAsync, runTmuxInput } from "./tmux-offload";
+
+/** Slash commands must reach an idle, empty composer as literal keystrokes (#2794). */
+export async function submitClaudeContextCommand(session: string, command: "/compact" | "/clear" | `/effort ${string}`, socket?: string, signal?: AbortSignal, onSubmitted?: () => void): Promise<void> {
+  signal?.throwIfAborted();
+  const pane = await captureTmuxVisiblePaneAsync(session, socket, { styled: true });
+  signal?.throwIfAborted();
+  if (claudePaneIsBusy(pane) || claudeComposerText(pane) !== "") throw new Error("Claude context command requires an idle empty composer");
+  await runTmuxInput("tmux-context-command", tmuxCommand(socket, "send-keys", "-t", session, "-l", "--", command));
+  signal?.throwIfAborted();
+  onSubmitted?.();
+  await runTmuxInput("tmux-context-submit", tmuxCommand(socket, "send-keys", "-t", session, "C-m"));
+}

package/src/adapters/claude-credentials.ts

@@ -0,0 +1,22 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { CLAUDE_FAMILY_AMBIENT_CREDENTIAL_ENV_KEYS } from "@humwick/providers";
+import { resolveFileEnv } from "@humwick/sdk/child-env";
+
+/**
+ * #2513 — keep only the credentials this claude-family provider owns (claude-api owns the host paid-key
+ * file; other ids drop the primary subscription's ambient keys). A dropped key is also pushed to `envUnset`.
+ */
+export function scopeClaudeCredentialEnv(provider: string, providerEnv: Record<string, string | undefined>, env: Record<string, string>, envUnset: string[]): void {
+  const credentialKeys = provider === "claude"
+    ? (process.env.ANTHROPIC_API_KEY_FILE ? ["ANTHROPIC_API_KEY", "ANTHROPIC_API_KEY_FILE"] : [])
+    : CLAUDE_FAMILY_AMBIENT_CREDENTIAL_ENV_KEYS;
+  const scoped = resolveFileEnv(providerEnv, { keys: credentialKeys });
+  for (const key of credentialKeys) {
+    const providerScoped = scoped[key];
+    if (providerScoped) writeChildEnv(env, { [key]: providerScoped });
+    else {
+      writeChildEnv(env, {}, [key]);
+      envUnset.push(key);
+    }
+  }
+}

package/src/adapters/claude-delivery-lanes.ts

@@ -0,0 +1,28 @@
+import type { Message } from "@humwick/sdk";
+import { isHumanSenderMessage, type DeliverResult } from "../adapter";
+import { logger } from "../logger";
+
+/**
+ * #3415 — Claude Code labels Monitor events "NOT USER INPUT", so human senders go in as a tmux user turn,
+ * never Monitor, never stubbed; the rest stays on Monitor (all of it without a tmux pane). Kept out of
+ * claude-delivery.ts: the provisioned Monitor bundle imports it and the logger would pull the provider catalog in.
+ */
+export async function deliverClaudeByLane(messages: Message[], lanes: {
+  userTurn?: (batch: Message[]) => Promise<DeliverResult>;
+  monitor: (batch: Message[], reportsOffer: boolean) => Promise<DeliverResult>;
+  narrowTurnOpener?: (batch: Message[]) => () => void;
+}): Promise<DeliverResult> {
+  const userTurn = lanes.userTurn ? messages.filter(isHumanSenderMessage) : [];
+  const background = messages.filter((message) => !userTurn.includes(message));
+  if (userTurn.length === 0 || !lanes.userTurn) return lanes.monitor(background, true);
+  if (background.length === 0) return lanes.userTurn(userTurn);
+  // The typed turn answers only what it carried: a Monitor message may still fail, or fold into the turn as its own event.
+  const disarm = lanes.narrowTurnOpener?.(userTurn);
+  // The user turn goes first, so its throw (a #2664 submit fence) propagates before any Monitor event; it alone reports the input offer.
+  const typed = await lanes.userTurn(userTurn).catch((error: unknown) => { disarm?.(); throw error; });
+  const monitored = await lanes.monitor(background, false).catch((error: unknown): DeliverResult => {
+    logger.warn("claude", `monitor delivery failed after a user-turn submit; requeueing ${background.length} message(s): ${error}`);
+    return { acknowledgedIds: [] };
+  });
+  return { acknowledgedIds: [...typed.acknowledgedIds, ...monitored.acknowledgedIds] };
+}

package/src/adapters/claude-delivery.ts

@@ -0,0 +1,166 @@
+import type { Message } from "@humwick/sdk";
+import { dedupePersistedMessages, isMemoryInjection, isNotificationMessage, isPersistedRelayMessage, isReactionNotification, isSelfResumeInjection, NOTIFICATION_NUDGE, providerAttachmentText, providerSenderLabel } from "../adapter";
+import { receivesTurnResponseAutomatically } from "../response-routing";
+import { planClaudeMonitorDelivery, type MonitorDeliveryPlan } from "./claude-monitor-delivery-plan";
+
+interface ClaudeDeliveryTextOptions {
+  // Isolated profiles have no Relay surface, so omit claim instructions and notification nudges.
+  relaySurface?: boolean;
+  // #1935 — chars already emitted into the SAME batched monitor event ahead of this text (the
+  // once-per-session context/workspace block the plugin logs on first delivery). Counted against
+  // the per-event cap so the over-limit stub gate accounts for the prefix, not just the message.
+  reservedChars?: number;
+  // #1935 — enable the over-limit stub gate. Only the monitor delivery path is subject to the
+  // harness per-event/per-line caps; the tmux fallback pastes full text straight into the pane and
+  // must NOT stub (a monitorless agent may have no get-message surface). Defaults to off; the
+  // relay-monitor plugin opts in.
+  monitorLimited?: boolean;
+  // #2310 — directory to spill an over-cap must-keep (non-fetchable) section's full content to,
+  // in place of ever inlining a truncated copy. See planClaudeMonitorDelivery's spillDir doc.
+  spillDir?: string;
+}
+
+// Server-baked trailing line from taskMessageBody() in src/db.ts. Meaningless to an isolated
+// agent (sole claimant, no relay CLI), so drop it from delivered text when there's no surface.
+const TASK_CLAIM_INSTRUCTION = "Claim this task before working it, then update task status when finished.";
+
+function stripRelayScaffolding(body: string): string {
+  const bodyLines = body.split("\n");
+  const popTrailingBlanks = () => {
+    while (bodyLines.length && (bodyLines.at(-1) ?? "").trim() === "") bodyLines.pop();
+  };
+  popTrailingBlanks();
+  if (bodyLines.at(-1) === TASK_CLAIM_INSTRUCTION) {
+    bodyLines.pop();
+    popTrailingBlanks();
+  }
+  return bodyLines.join("\n");
+}
+
+function formatMessage(message: Message, relaySurface: boolean): string {
+  const subject = message.subject ? `Subject: ${message.subject}\n` : "";
+  const isMemoryContext = isMemoryInjection(message);
+  const rawBody = relaySurface ? message.body : stripRelayScaffolding(message.body);
+
+  if (isMemoryContext) {
+    return [
+      `[agent-relay ${isSelfResumeInjection(message) ? "self-resume continuation" : "context"} from ${message.from}]`,
+      providerAttachmentText(message),
+      `${subject}${rawBody}`,
+    ].filter(Boolean).join("\n");
+  }
+
+  return [
+    receivesTurnResponseAutomatically(message.from) ? undefined : `[relay message #${message.id} from ${providerSenderLabel(message)}]`,
+    providerAttachmentText(message),
+    `${subject}${rawBody}`,
+  ].filter(Boolean).join("\n");
+}
+
+// #1935 — a message whose full section would blow the monitor size limit is delivered as a minimal
+// stub: sender, a one-line gist (subject, else the first sentence of the body), thread, and the
+// fetch hint. Only persisted, fetchable, non-memory messages qualify (see isStubbable below) —
+// non-fetchable content is routed by the planner to a spill pointer or a truncation notice instead.
+const STUB_GIST_MAX_CHARS = 200;
+
+function clampToLine(text: string, max = STUB_GIST_MAX_CHARS): string {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > max ? `${collapsed.slice(0, max - 1).trimEnd()}…` : collapsed;
+}
+
+function firstSentence(body: string): string {
+  const trimmed = body.trim();
+  if (!trimmed) return "";
+  const match = trimmed.match(/^[\s\S]*?[.!?](?=\s|$)/);
+  return clampToLine(match ? match[0] : trimmed);
+}
+
+// #2310 — three sub-classes of over-limit section, each routed differently by the planner:
+//   fetchable   (isStubbable)  — persisted (id>0), retrievable via get-message → clean meta-only
+//                                 stub. Covers ordinary messages AND persisted reaction
+//                                 notifications (LOW-7: a persisted reaction must never be
+//                                 silently self-truncated with no way back to its content — it
+//                                 gets the same get-message pointer as any other message).
+//   must-keep   (everything     — no get-message path and no acceptable loss (memory context,
+//                else, default)   self-resume continuation) → spilled byte-exact to disk and
+//                                 replaced with a small pointer, never raw-emitted, never dropped.
+//   disposable  (isReactionNotification, — no get-message path but losing it is fine (an
+//                non-persisted only)       ephemeral, never-persisted reaction) → self-truncated
+//                                          to one event with an explicit notice.
+function isStubbable(message: Message): boolean {
+  return isPersistedRelayMessage(message) && !isMemoryInjection(message);
+}
+
+function nonStubbableSectionKind(message: Message): "must-keep" | "disposable" {
+  return isReactionNotification(message) ? "disposable" : "must-keep";
+}
+
+function nonStubbableSectionLabel(message: Message): string {
+  if (isSelfResumeInjection(message)) return "self-resume continuation";
+  if (isMemoryInjection(message)) return "memory injection";
+  if (isReactionNotification(message)) return "reaction notification";
+  return "content";
+}
+
+// #2844 — a task-delivery notice carries its actionable fields in the payload (see
+// notifyDelivery in src/services/task-delivery.ts), so the stub inlines them: disposition, head
+// sha, blocker count and next action. The coordinator can act without an extra get-message
+// round-trip; the full body stays behind the fetch hint.
+function taskDeliverableSummary(message: Message): string[] | undefined {
+  const payload = (message.payload ?? {}) as unknown as Record<string, unknown>;
+  if (payload.kind !== "task.deliverable") return undefined;
+  const lines: string[] = [];
+  const taskId = typeof payload.taskId === "number" ? payload.taskId : undefined;
+  const disposition = typeof payload.disposition === "string" && payload.disposition ? payload.disposition : undefined;
+  if (taskId !== undefined || disposition) {
+    lines.push(clampToLine(`Task${taskId !== undefined ? ` T${taskId}` : ""}${disposition ? ` · ${disposition}` : ""}`));
+  }
+  const headSha = typeof payload.headSha === "string" && payload.headSha ? payload.headSha : undefined;
+  const blockerCount = typeof payload.blockerCount === "number" ? payload.blockerCount : undefined;
+  if (headSha || blockerCount !== undefined) {
+    lines.push(clampToLine(`Head: ${headSha ?? "?"} · Blockers: ${blockerCount ?? "?"}`));
+  }
+  const nextAction = typeof payload.nextAction === "string" && payload.nextAction ? payload.nextAction : undefined;
+  if (nextAction) lines.push(clampToLine(`Next: ${nextAction}`));
+  return lines.length > 0 ? lines : undefined;
+}
+
+function stubMessage(message: Message): string {
+  const gist = message.subject ? `Subject: ${clampToLine(message.subject)}` : firstSentence(message.body);
+  const summary = taskDeliverableSummary(message);
+  const fetchTarget = message.messageType === "final-turn" && message.sourceMessageId ? message.sourceMessageId : message.id;
+  const finalTurn = message.messageType === "final-turn" ? " | final turn" : "";
+  return [
+    receivesTurnResponseAutomatically(message.from) ? undefined : `[relay message #${message.id} from ${providerSenderLabel(message)}${finalTurn}]`,
+    gist || undefined,
+    ...(summary ?? []),
+    message.threadId !== undefined ? `Thread: #${message.threadId}` : undefined,
+    `Over monitor size limit — full ${message.messageType === "final-turn" ? "turn" : "message"}: relay_get_message #${fetchTarget} (CLI: agent-relay get-message ${fetchTarget})`,
+  ].filter(Boolean).join("\n");
+}
+
+export function claudeMonitorDeliveryPlan(messages: Message[], options: ClaudeDeliveryTextOptions = {}): MonitorDeliveryPlan {
+  const relaySurface = options.relaySurface !== false;
+  const uniqueMessages = dedupePersistedMessages(messages);
+  const sections = uniqueMessages.map((message) => ({
+    id: isPersistedRelayMessage(message) ? message.id : undefined,
+    full: formatMessage(message, relaySurface),
+    ...(isStubbable(message)
+      ? { stub: stubMessage(message) }
+      : { kind: nonStubbableSectionKind(message), label: nonStubbableSectionLabel(message) }),
+  }));
+  if (relaySurface && uniqueMessages.length > 0 && uniqueMessages.every(message => isNotificationMessage(message) && !receivesTurnResponseAutomatically(message.from))) {
+    sections.push({ id: undefined, full: NOTIFICATION_NUDGE, kind: "disposable", label: "notification" });
+  }
+  if (!options.monitorLimited) {
+    return { events: [{ text: sections.map((section) => section.full).join("\n\n"), messageIds: sections.flatMap((section) => section.id === undefined ? [] : [section.id]) }] };
+  }
+  return planClaudeMonitorDelivery(sections, { reservedChars: options.reservedChars, spillDir: options.spillDir });
+}
+
+export function claudeProviderMessageText(messages: Message[], options: ClaudeDeliveryTextOptions = {}): string {
+  const plan = claudeMonitorDeliveryPlan(messages, options);
+  // Tmux is not Monitor-limited and retains its traditional single paste. The Monitor artifact
+  // consumes `claudeMonitorDeliveryPlan` directly so it can emit cap-compliant events.
+  return plan.events.map((event) => event.text).join("\n\n");
+}

package/src/adapters/claude-effort.ts

@@ -0,0 +1,94 @@
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
+import { findProviderCatalog, findProviderCatalogModel, type SpawnProvider } from "@humwick/sdk";
+import { tmuxCommand, tmuxHasSession } from "@humwick/sdk/tmux-utils";
+import type { ManagedProcess, RunnerSpawnConfig } from "../adapter";
+import { effortSwitchEnabledFromEnv } from "../config";
+import { providerHomePathFor } from "../profile-home";
+import { submitClaudeContextCommand } from "./claude-context-command";
+import { claudeProbeArgsFor, resolveManagedClaudeTranscriptPathAsync } from "./claude-session-probe";
+import { readIncrementalFileRange, statIncrementalFile } from "./incremental-file";
+import { captureTmuxVisiblePaneAsync, runTmuxInput } from "./tmux-offload";
+
+// #2950 — Claude keeps its prompt cache across an effort switch (docs/design/2950-effort-switch-slice.md).
+const EFFORT_CONFIRM_TIMEOUT_MS = 15_000;
+const EFFORT_CONFIRM_POLL_MS = 200;
+// CLAUDE_CODE_EFFORT_LEVEL pins the session: `/effort` then reports "overrides" and changes nothing.
+const CLAUDE_EFFORT_ENV = "CLAUDE_CODE_EFFORT_LEVEL";
+
+/** Launch effort as `--effort` while the slice flag is on (carrying an inherited pin over), else the legacy pinning env. */
+export function claudeEffortLaunch(effort: string | undefined, inheritedEnv: Record<string, string | undefined>): { args: string[]; env: Record<string, string>; unset: string[] } {
+  if (!effortSwitchEnabledFromEnv()) return { args: [], env: effort ? writeChildEnv({}, { [CLAUDE_EFFORT_ENV]: effort }) : {}, unset: [] };
+  const launchEffort = effort ?? relayEnv(inheritedEnv, CLAUDE_EFFORT_ENV)?.trim();
+  return { args: launchEffort ? ["--effort", launchEffort] : [], env: {}, unset: [CLAUDE_EFFORT_ENV] };
+}
+
+/** Persistent transports can switch effort. Host-base `/effort` would save into the human's own settings. */
+export function claudeEffortSwitchMeta(provider: SpawnProvider, config: RunnerSpawnConfig, oneShot: boolean): { effortSwitch?: true } {
+  const catalog = findProviderCatalog(provider);
+  const model = catalog && findProviderCatalogModel(catalog, config.model ?? catalog.defaultModel);
+  return effortSwitchEnabledFromEnv() && !oneShot && providerHomePathFor(provider, config) && model?.efforts.length ? { effortSwitch: true } : {};
+}
+
+interface ClaudeEffortOutcome { applied?: string; message: string }
+
+/** After a turn, the TUI asks before switching and warns of a full re-read; measured reuse is 0.999, so accept. */
+export function claudeEffortConfirmDialog(pane: string, effort: string): boolean {
+  return pane.includes("Change effort level?") && pane.includes(`1. Yes, switch to ${effort}`);
+}
+
+function entryText(entry: Record<string, unknown>): string {
+  const content = (entry.message as { content?: unknown } | undefined)?.content ?? entry.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => (typeof part?.text === "string" ? part.text : "")).join("");
+}
+
+/** The stdout `/effort <effort>` recorded in transcript lines written after the submit. */
+export function claudeEffortOutcome(jsonl: string, effort: string): ClaudeEffortOutcome | undefined {
+  let ours = false;
+  for (const line of jsonl.split("\n")) {
+    let entry: Record<string, unknown>;
+    try { entry = JSON.parse(line); } catch { continue; }
+    const text = entryText(entry);
+    if (text.includes("<command-name>/effort</command-name>")) {
+      ours = text.includes(`<command-args>${effort}</command-args>`);
+      continue;
+    }
+    const stdout = ours ? /<local-command-stdout>([\s\S]*?)<\/local-command-stdout>/.exec(text)?.[1]?.trim() : undefined;
+    if (stdout === undefined) continue;
+    const applied = /^Set effort level to ([a-z]+)/.exec(stdout)?.[1] ?? /set to '([a-z]+)' instead/.exec(stdout)?.[1];
+    return { ...(applied ? { applied } : {}), message: stdout };
+  }
+  return undefined;
+}
+
+export async function switchClaudeEffort(process: ManagedProcess, effort: string): Promise<{ effort: string; message: string; confirmedCacheDialog?: true }> {
+  const session = process.meta?.tmuxSession as string | undefined;
+  const socket = process.meta?.tmuxSocket as string | undefined;
+  if (!session || !tmuxHasSession(session, socket)) throw new Error("no active tmux session for effort");
+  const transcriptPath = await resolveManagedClaudeTranscriptPathAsync(claudeProbeArgsFor(process, session, socket));
+  if (!transcriptPath) throw new Error("Claude transcript is unavailable, so an effort change cannot be confirmed");
+  const start = await statIncrementalFile(transcriptPath).then((info) => info.size, () => 0);
+  await submitClaudeContextCommand(session, `/effort ${effort}`, socket);
+  const deadline = Date.now() + EFFORT_CONFIRM_TIMEOUT_MS;
+  let accepted = false;
+  while (Date.now() < deadline) {
+    await Bun.sleep(EFFORT_CONFIRM_POLL_MS);
+    const size = await statIncrementalFile(transcriptPath).then((info) => info.size, () => start);
+    const outcome = size > start ? claudeEffortOutcome(new TextDecoder().decode(await readIncrementalFileRange(transcriptPath, start, size)), effort) : undefined;
+    if (!outcome) {
+      if (!accepted && claudeEffortConfirmDialog(await captureTmuxVisiblePaneAsync(session, socket).catch(() => ""), effort)) {
+        await runTmuxInput("tmux-effort-confirm", tmuxCommand(socket, "send-keys", "-t", session, "1"));
+        accepted = true;
+      }
+      continue;
+    }
+    if (!outcome.applied) throw new Error(`Claude refused the effort change: ${outcome.message}`);
+    return { effort: outcome.applied, message: outcome.message, ...(accepted ? { confirmedCacheDialog: true } : {}) };
+  }
+  // Never leave the dialog up: the next delivery would type into it.
+  if ((await captureTmuxVisiblePaneAsync(session, socket).catch(() => "")).includes("Change effort level?")) {
+    await runTmuxInput("tmux-effort-cancel", tmuxCommand(socket, "send-keys", "-t", session, "Escape"));
+  }
+  throw new Error(`Claude did not confirm /effort ${effort} within ${EFFORT_CONFIRM_TIMEOUT_MS}ms`);
+}