@humwick/runner 0.130.4 → 0.130.6

package/src/adapters/claude-api.ts

@@ -46,10 +46,7 @@ export class ClaudeApiAdapter extends ClaudeHeadlessAdapter {
     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",
-      }, config.env) };
+      env: resolveProviderApiAuth(this.provider, built.env, providerConfig.env, config.env) };
   }
 
   override async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
@@ -59,10 +56,10 @@ export class ClaudeApiAdapter extends ClaudeHeadlessAdapter {
     // 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" });
+        ?? "~/.config/humwick/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);
+    const decision = await this.budget.reserve(relayEnv(config.env, "HUMWICK_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;
@@ -84,7 +81,7 @@ export class ClaudeApiAdapter extends ClaudeHeadlessAdapter {
     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). */
+  /** One incarnation-owned expiry timer; re-read the window on every arm so a moved endsAt takes effect immediately. */
   private armExpiry() {
     clearTimeout(this.expiry);
     const managed = this.managed, reservation = this.reservation;
@@ -121,7 +118,7 @@ export class ClaudeApiAdapter extends ClaudeHeadlessAdapter {
     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).
+        // Park the input under a transient hold: the relay's bounded resume backoff retries it, no operator step.
         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" } });
@@ -162,7 +159,7 @@ export class ClaudeApiAdapter extends ClaudeHeadlessAdapter {
     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,
+    return { state: "blocked", reason: "rate_limit", kind: "usage_limit", usageLimitScope: "session", source: this.provider,
       label: "Claude API allowance reached; renewing reservation", resetAt: Date.now(), enteredAt: Date.now() };
   }
 
@@ -193,7 +190,7 @@ export class ClaudeApiAdapter extends ClaudeHeadlessAdapter {
   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).
+    // ledger is unreachable, so a transient failure never stops the provider; new input still needs a report.
     if (isTransientBudgetFailure(error)) return;
     this.stopForBudget("budget-accounting-unavailable");
   }
@@ -201,7 +198,7 @@ export class ClaudeApiAdapter extends ClaudeHeadlessAdapter {
   private stopForBudget(reason: string) {
     if (this.held) return;
     this.held = true;
-    this.budgetState = { state: "blocked", reason: "rate_limit", kind: "usage_limit",
+    this.budgetState = { state: "blocked", reason: "rate_limit", kind: "usage_limit", usageLimitScope: "session",
       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 }); }

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

@@ -3,7 +3,7 @@ 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). */
+/** Slash commands must reach an idle, empty composer as literal keystrokes. */
 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 });

package/src/adapters/claude-credentials.ts

@@ -1,9 +1,9 @@
-import { writeChildEnv } from "@humwick/sdk/env";
+import { relayEnv, 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
+ * 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 {
@@ -13,10 +13,14 @@ export function scopeClaudeCredentialEnv(provider: string, providerEnv: Record<s
   const scoped = resolveFileEnv(providerEnv, { keys: credentialKeys });
   for (const key of credentialKeys) {
     const providerScoped = scoped[key];
-    if (providerScoped) writeChildEnv(env, { [key]: providerScoped });
+    if (providerScoped) writeChildEnv(env, { [key]: providerScoped }, []);
     else {
       writeChildEnv(env, {}, [key]);
       envUnset.push(key);
     }
   }
+  // tmux must not resurrect credentials absent from the probed child environment.
+  for (const key of CLAUDE_FAMILY_AMBIENT_CREDENTIAL_ENV_KEYS) {
+    if (!relayEnv(env, key) && !envUnset.includes(key)) envUnset.push(key);
+  }
 }

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

@@ -3,7 +3,7 @@ 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,
+ * 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.
  */
@@ -18,7 +18,7 @@ export async function deliverClaudeByLane(messages: Message[], lanes: {
   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.
+  // The user turn goes first, so its throw 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}`);

package/src/adapters/claude-delivery.ts

@@ -1,21 +1,21 @@
 import type { Message } from "@humwick/sdk";
-import { dedupePersistedMessages, isMemoryInjection, isNotificationMessage, isPersistedRelayMessage, isReactionNotification, isSelfResumeInjection, NOTIFICATION_NUDGE, providerAttachmentText, providerSenderLabel } from "../adapter";
+import { dedupePersistedMessages, isMemoryInjection, isNotificationMessage, isPersistedRelayMessage, isReactionNotification, isSelfResumeInjection, monitorDeliveryLineMaxChars, NOTIFICATION_NUDGE, providerAttachmentText, providerSenderLabel } from "../adapter";
 import { receivesTurnResponseAutomatically } from "../response-routing";
-import { planClaudeMonitorDelivery, type MonitorDeliveryPlan } from "./claude-monitor-delivery-plan";
+import { planClaudeMonitorDelivery, truncateToCaps, 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
+  // 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
+  // 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,
+  // 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;
 }
@@ -44,7 +44,7 @@ function formatMessage(message: Message, relaySurface: boolean): string {
 
   if (isMemoryContext) {
     return [
-      `[agent-relay ${isSelfResumeInjection(message) ? "self-resume continuation" : "context"} from ${message.from}]`,
+      `[humwick ${isSelfResumeInjection(message) ? "self-resume continuation" : "context"} from ${message.from}]`,
       providerAttachmentText(message),
       `${subject}${rawBody}`,
     ].filter(Boolean).join("\n");
@@ -57,10 +57,8 @@ function formatMessage(message: Message, relaySurface: boolean): string {
   ].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.
+// over-cap messages get a body preview plus retrieval guidance when space permits.
+// Compact stubs preserve batch admission under tight caps; non-fetchable content uses spill files.
 const STUB_GIST_MAX_CHARS = 200;
 
 function clampToLine(text: string, max = STUB_GIST_MAX_CHARS): string {
@@ -75,7 +73,7 @@ function firstSentence(body: string): string {
   return clampToLine(match ? match[0] : trimmed);
 }
 
-// #2310 — three sub-classes of over-limit section, each routed differently by the planner:
+// 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
@@ -102,7 +100,7 @@ function nonStubbableSectionLabel(message: Message): string {
   return "content";
 }
 
-// #2844 — a task-delivery notice carries its actionable fields in the payload (see
+// 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.
@@ -125,17 +123,19 @@ function taskDeliverableSummary(message: Message): string[] | undefined {
   return lines.length > 0 ? lines : undefined;
 }
 
-function stubMessage(message: Message): string {
+function stubMessage(message: Message, includePreview = false): string {
   const gist = message.subject ? `Subject: ${clampToLine(message.subject)}` : firstSentence(message.body);
+  const preview = includePreview ? truncateToCaps(message.body, 400, monitorDeliveryLineMaxChars()) : "";
   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,
+    message.subject || !preview ? gist || undefined : 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})`,
+    preview ? `Body preview (${preview.length} of ${message.body.length} chars):\n${preview}` : undefined,
+    `Over monitor size limit — full ${message.messageType === "final-turn" ? "turn" : "message"}: humwick_get_message #${fetchTarget} (CLI: humwick get-message ${fetchTarget})`,
   ].filter(Boolean).join("\n");
 }
 
@@ -146,7 +146,7 @@ export function claudeMonitorDeliveryPlan(messages: Message[], options: ClaudeDe
     id: isPersistedRelayMessage(message) ? message.id : undefined,
     full: formatMessage(message, relaySurface),
     ...(isStubbable(message)
-      ? { stub: stubMessage(message) }
+      ? { stub: stubMessage(message), preview: stubMessage(message, true) }
       : { kind: nonStubbableSectionKind(message), label: nonStubbableSectionLabel(message) }),
   }));
   if (relaySurface && uniqueMessages.length > 0 && uniqueMessages.every(message => isNotificationMessage(message) && !receivesTurnResponseAutomatically(message.from))) {

package/src/adapters/claude-effort.ts

@@ -9,7 +9,7 @@ import { claudeProbeArgsFor, resolveManagedClaudeTranscriptPathAsync } from "./c
 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).
+// 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.
@@ -17,7 +17,7 @@ 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: [] };
+  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] };
 }

package/src/adapters/claude-exit.ts

@@ -1,4 +1,4 @@
-// #1647 — the ONE module allowed to type Claude's exit command, or the Enter that
+// the ONE module allowed to type Claude's exit command, or the Enter that
 // answers its exit-confirmation dialog, into a managed pane.
 //
 // A 13.4h coordinator was destroyed when the runner's graceful-shutdown path typed
@@ -171,7 +171,7 @@ export function decideClaudeGracefulExit(
   // session from its successor.
   if (observed.providerSessionId === null) return "provider-session-unknown";
   if (intent.providerSessionId !== null && intent.providerSessionId !== observed.providerSessionId) return "provider-session-mismatch";
-  // #1647's actual failure: the pane was mid-stream. Only POSITIVE end-of-turn
+  // actual failure: the pane was mid-stream. Only POSITIVE end-of-turn
   // evidence authorizes typing into it.
   if (observed.turn === "live") return "turn-live";
   if (observed.turn !== "ended") return "turn-unknown";

package/src/adapters/claude-headless-mirror.ts

@@ -4,7 +4,7 @@ import { freshContextState, providerContextState } from "../transcript-context";
 import { claudeAssistantSteps, claudeToolResults, sumUsageTokens, turnStepEvent, type TranscriptMessage, type TurnStep } from "./claude-transcript";
 
 /**
- * Turns the root session's stream-json events into session-mirror steps and context usage (#2771).
+ * Turns the root session's stream-json events into session-mirror steps and context usage.
  * A tool row opens `running` on its tool_use and settles in place (stepId = tool_use id) on its tool_result.
  */
 export class ClaudeHeadlessMirror {
@@ -12,6 +12,13 @@ export class ClaudeHeadlessMirror {
   private readonly contextWindows = new Map<string, number>();
   private usage?: { tokensUsed: number; model?: string; at: number };
   private clearedAt?: number;
+  // the result upgrades matching closing narration instead of appending its text again.
+  private closingNarration?: { body: string; turnId?: string; stepId: string };
+
+  responseStepId(body: string, turnId: string): string | undefined {
+    const closing = this.closingNarration;
+    return closing?.turnId === turnId && closing.body.trim() === body.trim() ? closing.stepId : undefined;
+  }
 
   observe(event: Record<string, unknown>, turnId: string | undefined): ProviderSessionEvent[] {
     // Subagent events carry their parent's tool_use id; like transcript sidechains they stay out of the root mirror.
@@ -22,13 +29,21 @@ export class ClaudeHeadlessMirror {
       this.noteUsage(message, occurredAt);
       // Claude's synthetic API-error message is a transcript row, not model output.
       const diagnostic = event.is_api_error_message === true;
-      return claudeAssistantSteps(message, occurredAt).map((step) => {
+      const entryId = typeof event.uuid === "string" ? event.uuid : crypto.randomUUID();
+      return claudeAssistantSteps(message, occurredAt).map((step, index) => {
+        this.closingNarration = undefined;
+        if (step.type === "narration" && !diagnostic) {
+          const stepId = `assistant:${entryId}:${index}`;
+          this.closingNarration = { body: step.text, turnId, stepId };
+          return { ...stepEvent(step, turnId), stepId };
+        }
         if (step.type !== "tool" || !step.toolUseId) return stepEvent(step, turnId, undefined, diagnostic);
         this.openTools.set(step.toolUseId, step);
         return stepEvent(step, turnId, "running");
       });
     }
     if (event.type === "user") {
+      this.closingNarration = undefined;
       return claudeToolResults(message).flatMap(({ toolUseId, isError }) => {
         const step = this.openTools.get(toolUseId);
         if (!step) return [];
@@ -56,6 +71,7 @@ export class ClaudeHeadlessMirror {
 
   /** After a clear the context is explicitly empty; omitting it would leave the card on the old usage. */
   clearContext(): void {
+    this.closingNarration = undefined;
     this.usage = undefined;
     this.clearedAt = Date.now();
   }

package/src/adapters/claude-headless-refusal.ts

@@ -1,7 +1,7 @@
 import type { ProviderState } from "@humwick/sdk";
 import { buildProviderRefusalHold, isProviderOverload, isProviderThrottle, isProviderUsageLimit, isProxyAuthFailure, parseClaudeRateLimitPane } from "../rate-limit";
 
-/** What Claude's native error result says about a refused turn (#2771). */
+/** What Claude's native error result says about a refused turn. */
 export interface ClaudeTurnError {
   /** The synthetic API-error assistant message's `error` class (rate_limit, overloaded, ...). */
   error?: string;
@@ -17,7 +17,7 @@ export function claudeApiErrorOf(event: Record<string, unknown>): string | undef
   return event.type === "assistant" && event.is_api_error_message === true && typeof event.error === "string" ? event.error : undefined;
 }
 
-/** Error text is authoritative even when Claude omits its API-error metadata (#3544). */
+/** Error text is authoritative even when Claude omits its API-error metadata. */
 export function claudeTurnError(result: Record<string, unknown>, error: string | undefined): ClaudeTurnError | undefined {
   if (result.is_error !== true && result.terminal_reason !== "api_error" && typeof result.api_error_status !== "number" && error === undefined) return undefined;
   const text = typeof result.result === "string" ? result.result : "";
@@ -40,7 +40,7 @@ export function claudeRefusalHold(turn: ClaudeTurnError, source: string): Provid
   return buildProviderRefusalHold({ message: turn.text, detail: turn.text || `Claude ${turn.error ?? turn.status}`, errorType: turn.error, statusCode: turn.status, source, ...(resetAt ? { resetAt } : {}) });
 }
 
-/** Preserve the provider's cause even when its error result has subtype=success (#3544). */
+/** Preserve the provider's cause even when its error result has subtype=success. */
 export function claudeResultFailure(result: Record<string, unknown>) {
   const text = typeof result.result === "string" ? result.result.trim() : "";
   const budget = result.subtype === "error_max_budget_usd" || /\b(?:budget|allowance)\b.*\b(?:exceeded|exhausted|reached)\b/i.test(text);

package/src/adapters/claude-headless.ts

@@ -45,7 +45,7 @@ interface HeadlessState {
   abandonedCommands: Set<string>;
   /** The live turn's API-error class, from the synthetic error message that precedes its error result. */
   apiError?: string;
-  /** Turn the provider refused under a rate-limit/quota/overload hold (#2771). */
+  /** Turn the provider refused under a rate-limit/quota/overload hold. */
   refusedTurnId?: string;
   /** Resolves a delivery waiting for the turn's first outcome: true if it was refused. */
   refusalWatch?: { turnId: string; settle(refused: boolean): void };
@@ -81,7 +81,7 @@ export function createClaudeTransportAdapter(provider: string, args: string[], l
   return streaming ? new ClaudeHeadlessAdapter(provider) : new ClaudeAdapter({ provider });
 }
 
-/** Persistent native Claude print-mode transport (#2754, #2771). */
+/** Persistent native Claude print-mode transport. */
 export class ClaudeHeadlessAdapter implements ProviderAdapter {
   readonly statusSourceId: string;
   readonly permissionPromptHandler = claudePermissionPromptHandler;
@@ -152,12 +152,12 @@ export class ClaudeHeadlessAdapter implements ProviderAdapter {
       transportArgs.push(arg);
     }
     return { ...args, args: [...transportArgs, "--print", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose", "--replay-user-messages"],
-      env: writeChildEnv({}, { ...args.env, AGENT_RELAY_CLAUDE_TRANSPORT: "stream-json" }) };
+      env: writeChildEnv({}, { ...args.env, HUMWICK_CLAUDE_TRANSPORT: "stream-json" }, []) };
   }
 
-  async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+  async spawn(config: RunnerSpawnConfig, preparedArgs?: SpawnArgs): Promise<ManagedProcess> {
     await verifyClaudeSubagentVersion(config);
-    const args = this.buildSpawnArgs(config, config.providerConfig);
+    const args = preparedArgs ?? this.buildSpawnArgs(config, config.providerConfig);
     this.watching = true;
     const child = Bun.spawn([args.command, ...args.args], {
       cwd: args.cwd,
@@ -234,7 +234,7 @@ export class ClaudeHeadlessAdapter implements ProviderAdapter {
           this.emitStatus({ status: "idle", reason: "provider-turn", clear: ["provider-turn"], id: turnId, ...this.transcriptStatus(state) });
           return;
         }
-        // A throttle, quota wall or overload refusal is neither delivered nor failed: hold, then resume (#2619).
+        // A throttle, quota wall or overload refusal is neither delivered nor failed: hold, then resume.
         const turnError = claudeTurnError(event, apiError);
         const hold = nativeHold ?? (turnError && claudeRefusalHold(turnError, this.statusSourceId));
         if (hold) {
@@ -254,7 +254,7 @@ export class ClaudeHeadlessAdapter implements ProviderAdapter {
       // Stopped watchers intentionally drop finals during teardown; resume cannot replay them.
       if (this.watching && typeof event.result === "string" && event.result.trim()) {
         this.response({ type: "response", body: event.result, origin: "provider", turnId, final: true,
-          confidence: "definitive", endedBy: "completed", replyToUserObligation: true, replyRoute });
+          confidence: "definitive", endedBy: "completed", replyToUserObligation: true, replyRoute, stepId: state.mirror.responseStepId(event.result, turnId), status: "completed" });
       }
       this.emitStatus({ status: "idle", reason: "provider-turn", clear: ["provider-turn"], id: turnId, ...this.transcriptStatus(state) });
     }).catch((error) => {
@@ -265,7 +265,7 @@ export class ClaudeHeadlessAdapter implements ProviderAdapter {
       child.kill("SIGKILL");
     });
     const nativeExit = child.exited.then(async (code) => {
-      // The final result can still be buffered when the process exits (#3314).
+      // The final result can still be buffered when the process exits.
       await stdout;
       await this.onNativeExit(child, code, state.stopping);
       this.abandonPending(state, "Claude exited");
@@ -295,7 +295,7 @@ export class ClaudeHeadlessAdapter implements ProviderAdapter {
     if (!messages.length) return [];
     state.replyRoute = deliveredBatchReplyRoute(messages);
     let outcome: void | "held";
-    try { outcome = await this.deliverInitialPrompt(process, claudeProviderMessageText(messages)); }
+    try { outcome = await this.deliverInitialPrompt(process, claudeProviderMessageText(messages), { inputObserver: ctx?.inputObserver }); }
     catch (error) { state.replyRoute = undefined; throw error; }
     const turnId = state.submittedTurnId;
     const ids = messages.map((message) => message.id);
@@ -315,6 +315,7 @@ export class ClaudeHeadlessAdapter implements ProviderAdapter {
     state.turnId = state.submittedTurnId = turnId;
     state.apiError = undefined;
     state.submitConfirmed = false;
+    options?.inputObserver?.offered(Date.now(), false);
     this.emitStatus({ status: "busy", reason: "provider-turn", id: turnId, pids: [state.child.pid], ...this.transcriptStatus(state) });
     let timer: ReturnType<typeof setTimeout> | undefined;
     let timeoutMs = state.initialized ? options?.readyTimeoutMs ?? 30_000 : Math.max(options?.readyTimeoutMs ?? 0, 120_000);
@@ -505,7 +506,7 @@ export class ClaudeHeadlessAdapter implements ProviderAdapter {
     }, this.contextTimeouts.recovery);
   }
 
-  /** #3398 — a reset no live command waits for (a timed-out or abandoned one, or Claude's own) is still a reset. */
+  /** a reset no live command waits for (a timed-out or abandoned one, or Claude's own) is still a reset. */
   private observeUnwaitedReset(state: HeadlessState, event: Record<string, unknown>): void {
     const compacted = event.type === "system" && event.subtype === "compact_boundary";
     if (!compacted && event.type !== "conversation_reset") return;

package/src/adapters/claude-launch-exit.ts

@@ -10,7 +10,7 @@ async function stderrTail(path: string): Promise<string> {
   } catch { return ""; }
 }
 
-// #3830 — a vanished pane is not evidence of a successful provider launch.
+// a vanished pane is not evidence of a successful provider launch.
 export async function claudeLaunchExitStatus(exitCodeFile: string | undefined, ready: boolean, oneShot: boolean, paneTail = ""): Promise<ProviderStatusUpdate> {
   const code = exitCodeFile ? await readOneShotExitCode(exitCodeFile) : undefined;
   // A successful interactive exec replaces the shell and its EXIT trap.

package/src/adapters/claude-monitor-delivery-plan.ts

@@ -7,7 +7,9 @@ export interface MonitorDeliverySection {
   id?: number;
   full: string;
   stub?: string;
-  // #2310 — how to represent `full` when it (or the section it's batched with) doesn't fit under
+  /** Body preview with retrieval guidance, preferred over a compact stub when space permits. */
+  preview?: string;
+  // how to represent `full` when it (or the section it's batched with) doesn't fit under
   // the Monitor's caps and there's no `stub` to fall back to. Only meaningful when `stub` is
   // absent (fetchable sections always resolve via their stub).
   //   "must-keep"  (default) — content with no get-message path and no acceptable loss (memory
@@ -29,12 +31,12 @@ export interface MonitorDeliveryPlan {
 
 export interface PlanClaudeMonitorDeliveryOptions {
   reservedChars?: number;
-  // #2310 — directory to spill an over-cap must-keep section's full content to (byte-exact),
+  // directory to spill an over-cap must-keep section's full content to (byte-exact),
   // replacing the delivered event with a small "read this file" pointer. There is no supported
   // way to emit more than one Monitor event per delivery cycle (the harness coalesces same-tick
   // stdout into one event), so a must-keep section that's too large to inline can never be
   // chunked across events — spilling to disk is the only loss-free route. Typically the agent's
-  // session scratch tmp dir (AGENT_RELAY_SCRATCH_DIR). When omitted, or the write fails, the
+  // session scratch tmp dir (HUMWICK_SCRATCH_DIR). When omitted, or the write fails, the
   // section gets an explicit "could not be delivered" notice — NEVER raw-emitted for the harness
   // to truncate mid-content, and never a bare/ambiguous truncation either.
   spillDir?: string;
@@ -51,7 +53,7 @@ const DISPOSABLE_TRUNCATION_NOTICE = "\n[…truncated]";
 // slice (never rearranges/rewraps), so the result is always a byte-exact prefix of `text` — except
 // that the cut point is nudged back by one UTF-16 code unit when it would otherwise land inside a
 // surrogate pair (e.g. an emoji), never emitting a lone unpaired surrogate.
-function truncateToCaps(text: string, budget: number, lineMaxChars: number): string {
+export function truncateToCaps(text: string, budget: number, lineMaxChars: number): string {
   let charCount = 0;
   let lineCount = 0;
   let cut = 0;
@@ -80,7 +82,7 @@ function selfTruncateDisposableSection(section: RenderedSection, reserved: numbe
   return body.length < section.text.length ? `${body}${DISPOSABLE_TRUNCATION_NOTICE}` : body;
 }
 
-// #2310 review round 4 P0-1 — bounds on the two places a caller-supplied `label` gets embedded so
+// review round 4 P0-1 — bounds on the two places a caller-supplied `label` gets embedded so
 // neither can blow a cap on its own: the filename component (unbounded here previously caused
 // ENAMETOOLONG on write, silently turning a usable spill into an undeliverable notice) and the
 // short display form used in notice/pointer text. The full uuid in the filename is NOT shortened —
@@ -100,7 +102,7 @@ function sanitizeForFilename(label: string): string {
   return cleaned.slice(0, MAX_FILENAME_LABEL_CHARS).replace(/-+$/g, "") || "content";
 }
 
-// #2310 P1 — the spilled file (and the dir it lands in) can hold sensitive content (memory
+// P1 — the spilled file (and the dir it lands in) can hold sensitive content (memory
 // context, self-resume continuation), so both are session-private: dir 0700, file 0600. `mode` on
 // mkdirSync/writeFileSync is still subject to umask, so re-assert both with chmodSync afterward —
 // best-effort (a chmod failure here shouldn't sacrifice the write; the caller's own try/catch
@@ -112,7 +114,7 @@ function writeSpillFileTight(dir: string, filePath: string, content: string): vo
   try { chmodSync(filePath, 0o600); } catch {}
 }
 
-// #2310 review round 3 P0 — a must-keep section must NEVER degrade to a bare disposable
+// review round 3 P0 — a must-keep section must NEVER degrade to a bare disposable
 // truncation ("[…truncated]" with no way back to the rest) — that's indistinguishable from
 // ordinary lossy content. When it genuinely can't be delivered in full this cycle, say so
 // explicitly and distinctly instead. `reason` names WHY (surfaced verbatim to the agent).
@@ -126,7 +128,7 @@ function writeSpillFileTight(dir: string, filePath: string, content: string): vo
 // injections a trackable identity and teaching that caller to retry on a missing ack — a genuine
 // architecture change, out of scope here. The explicit notice is the honest floor: it can't
 // silently vanish, even though it can't self-heal either.
-// #2310 review round 4 P0-1 — built as a cascade of progressively SHORTER, but always
+// review round 4 P0-1 — built as a cascade of progressively SHORTER, but always
 // independently-complete, candidates — never by truncating a single label-prefixed string (a huge
 // label pushed the classified marker text itself past the caps, so a raw prefix-truncation of the
 // old label-first shape could slice down to a bare "[LLLL…" containing none of "could NOT be
@@ -153,7 +155,7 @@ function mustKeepUndeliverableNotice(section: RenderedSection, reserved: number,
   return truncateToCaps(candidates[candidates.length - 1]!, Math.max(1, maxChars - reserved), lineMaxChars);
 }
 
-// #2310 — write the section's full, untouched content to disk and point at it instead of ever
+// write the section's full, untouched content to disk and point at it instead of ever
 // inlining a truncated/rewritten copy. The reference is built as a cascade of progressively
 // SHORTER but always independently-complete candidates, most useful first — never by truncating a
 // single label-prefixed string (review round 4 P0-1: a huge label must never cost us the file
@@ -190,7 +192,7 @@ function spillMustKeepSection(
   const bracket = `[${boundLabel(label, MAX_DISPLAY_LABEL_CHARS)} — spilled to disk, read it now]`;
   const references = [
     `Full content (byte-exact): ${filePath}`,
-    `File: ${fileName} — in your session scratch tmp dir ($AGENT_RELAY_SCRATCH_DIR)`,
+    `File: ${fileName} — in your session scratch tmp dir ($HUMWICK_SCRATCH_DIR)`,
     `File: ${fileName} (scratch dir)`,
     `File: ${fileName}`,
   ];
@@ -210,7 +212,26 @@ function spillMustKeepSection(
 
 type SpillResult = RenderedSection & { spilled: boolean };
 
-// #2310 review round 4 P0-2 — `items` is a mix of two DIFFERENT outcomes from spillMustKeepSection:
+// reserve room for every selected message before spending spare space on readable bodies.
+function readableEvent(items: RenderedSection[], reserved: number): MonitorDeliveryPlan {
+  const texts = items.map(item => item.text);
+  let totalChars = texts.reduce((sum, text) => sum + text.length, Math.max(0, texts.length - 1) * 2);
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]!;
+    if (!item.stub) continue;
+    for (const candidate of [item.full, item.preview]) {
+      if (candidate === undefined) continue;
+      const otherChars = totalChars - texts[i]!.length;
+      if (!fitsMonitorDelivery(candidate, { reserved: reserved + otherChars })) continue;
+      texts[i] = candidate;
+      totalChars = otherChars + candidate.length;
+      break;
+    }
+  }
+  return { events: items.length ? [{ text: join(texts), messageIds: idsOf(items) }] : [] };
+}
+
+// review round 4 P0-2 — `items` is a mix of two DIFFERENT outcomes from spillMustKeepSection:
 // truly spilled pointers (file exists, safe to defer into an aggregate "N more spilled" count) and
 // undeliverable notices (no spillDir / write failed — nothing exists to point at). The two must
 // never be conflated: deferring an undeliverable notice into the "spilled" count is a FALSE claim
@@ -240,12 +261,11 @@ function packWithDeferredNotice(items: SpillResult[], reserved: number): Rendere
  * Render each section once, then build ONE cap-compliant event (there is no supported way to emit
  * more than one Monitor event per delivery cycle — the harness coalesces same-tick stdout back
  * into a single event). No over-cap section is ever raw-emitted for the harness to truncate
- * (#2310):
  *
  * - Every "must-keep" section (no stub, no acceptable loss — memory context, self-resume
- *   continuation) is GUARANTEED a place in the event. #2310 P0 — with two or more oversized
+ *   continuation) is GUARANTEED a place in the event. P0 — with two or more oversized
  *   must-keep sections in one delivery, EACH is spilled to its own file and every pointer is
- *   included; none is ever silently replaced/dropped to make room for another (#2291-class: a
+ *   included; none is ever silently replaced/dropped to make room for another (class: a
  *   dropped must-keep section, unlike a dropped fetchable one, is unrecoverable — it has no
  *   persisted id to retry via).
  * - Fetchable (stubbed) and disposable sections are then greedily folded into whatever budget
@@ -267,7 +287,7 @@ export function planClaudeMonitorDelivery(
   const rendered: RenderedSection[] = sections.map((section) => ({ ...section, text: section.stub ?? section.full }));
   const allStubbed = join(rendered.map((section) => section.text));
   if (fitsMonitorDelivery(allStubbed, { reserved })) {
-    return { events: [{ text: allStubbed, messageIds: idsOf(rendered) }] };
+    return readableEvent(rendered, reserved);
   }
 
   const mustKeep = rendered.filter((section) => !section.stub && section.kind !== "disposable");
@@ -313,5 +333,5 @@ export function planClaudeMonitorDelivery(
       chunk = withSubstitute;
     }
   }
-  return { events: chunk.length ? [{ text: join(chunk.map((item) => item.text)), messageIds: idsOf(chunk) }] : [] };
+  return readableEvent(chunk, reserved);
 }