@humwick/runner 0.130.4 → 0.130.6

package/src/adapter.ts

@@ -1,3 +1,4 @@
+import { readHumwickRecord } from "@humwick/sdk/stored-names";
 import type { ServiceAccessHandoff } from "@humwick/sdk";
 import type { AgentProfile, InteractivePrompt, LivenessSignal, Message, MessageFinalityConfidence, MessageTurnEndReason, OperatorDecisionFileInput, ProviderState, ToolCallCategory } from "@humwick/sdk";
 // Leaf subpaths, not the barrel: the Claude monitor bundle imports this module and must stay small.
@@ -16,7 +17,7 @@ export { resolveRelayContext } from "./relay-instructions";
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
 
 /**
- * #1656 — the independent pane read is THREE-VALUED on its non-busy side, and collapsing it to a
+ * the independent pane read is THREE-VALUED on its non-busy side, and collapsing it to a
  * boolean was the defect. `false` used to mean both "captured the pane, no spinner" (evidence the
  * turn is over) and "could not read the pane at all" (no evidence of anything), and the busy
  * backstop's force-clear consumed the second as if it were the first: absence of evidence taken
@@ -51,7 +52,7 @@ export interface ProviderStatusEvent {
   label?: string;
   role?: string;
   parentId?: string;
-  // OS pids of the process(es) this busy work tracks (#650). When supplied, the
+  // OS pids of the process(es) this busy work tracks. When supplied, the
   // runner reconciles them against actual liveness and clears the busy marker if
   // every pid is dead — recovering from a tracked process killed out-of-band.
   pids?: number[];
@@ -62,7 +63,7 @@ export interface ProviderStatusEvent {
    */
   refusedInputIds?: number[];
   metadata?: Record<string, unknown>;
-  // #1235 — the live transcript path for a hookless (monitorless) provider turn. When an
+  // the live transcript path for a hookless (monitorless) provider turn. When an
   // adapter that learns turn boundaries WITHOUT Stop/UserPromptSubmit hooks (Claude's tmux
   // monitorless watch) supplies this on a `provider-turn` busy/idle event, the runner drives
   // the transcript reasoning tail natively: start on turn-start, capture the final response on
@@ -73,9 +74,9 @@ export interface ProviderStatusEvent {
 export type ProviderStatusUpdate = SemanticStatus | ProviderStatusEvent;
 
 /**
- * #1651 — pane evidence cannot end a turn, clear work, complete claims, decide a restart,
+ * pane evidence cannot end a turn, clear work, complete claims, decide a restart,
  * or send input. It carries no SemanticStatus or work-kind `clear`. The one display-only
- * exception is a startup-scoped bypass acceptance dialog (#2629): the runner may show a
+ * exception is a startup-scoped bypass acceptance dialog: the runner may show a
  * blocked badge and timeline alert until the modal disappears. This does not mutate work.
  *
  * A detector that wants to say something about the pane emits one of these via
@@ -122,17 +123,17 @@ export interface ProviderSessionEvent {
   replyToUserObligation?: boolean;
   /** Route captured with the submitted inbox turn; null means mirror only, undefined uses the runner cache. */
   replyRoute?: { to: string; replyToMessageId: number; channelTarget?: boolean; replyExpected?: boolean } | null;
-  /** #2840 — the turn opener, already resolved by the runner (a hookless capture finishing after its idle
+  /** the turn opener, already resolved by the runner (a hookless capture finishing after its idle
    *  edge); null = none. Absent ⇒ the runner resolves it from the final's turn id. */
   opener?: ProviderSessionEvent["replyRoute"];
   label?: string;
-  /** Provider-independent tool-call category (#1498), adapter-resolved; only set when type is "tool". */
+  /** Provider-independent tool-call category, adapter-resolved; only set when type is "tool". */
   category?: ToolCallCategory;
-  /** #3411 — absolute paths of the files a tool reads or edits, from its raw input (never `params`,
+  /** absolute paths of the files a tool reads or edits, from its raw input (never `params`,
    *  which is capped); only set when type is "tool". The runner matches them to path areas. */
   paths?: string[];
   /**
-   * Tool/step lifecycle status. `cancelled` (#2354) is the terminal outcome for a tool the
+   * Tool/step lifecycle status. `cancelled` is the terminal outcome for a tool the
    * provider interrupted before it finished (OpenCode's ToolPart error state with
    * `interrupted:true`), distinct from `failed` (ran and errored). Extended ONCE here for every
    * provider — see MessageSessionMeta.status.
@@ -144,16 +145,16 @@ export interface ProviderSessionEvent {
    * appending a duplicate (a tool's running→completed, a streamed reasoning row). */
   stepId?: string;
   /**
-   * #2397 round 3 — true only for a narration ABOUT the adapter's own retry/failure mechanics
+   * round 3 — true only for a narration ABOUT the adapter's own retry/failure mechanics
    * (e.g. "retrying in 4s…", "gave up after N retries"), never for anything the model itself
    * produced. `noteOutput` (empty-turn.ts) excludes these from empty-turn evidence the same way it
    * already excludes an echoed `prompt`: a retry storm that ends in terminal failure must not read
-   * as forward progress and cancel the #2389 input-armed escalation that wakes the spawn parent.
+   * as forward progress and cancel the input-armed escalation that wakes the spawn parent.
    * Distinct from `status: "failed"` on purpose — a failed TOOL call is still evidence the model is
    * alive and working; this is evidence only that the TRANSPORT is still failing.
    */
   diagnostic?: boolean;
-  /** #2437 — redacted, size-capped tool input/arguments, only set when type is "tool". Carried
+  /** redacted, size-capped tool input/arguments, only set when type is "tool". Carried
    * straight into MessageSessionMeta.params by the adapter-event→session-meta conversion. */
   params?: unknown;
 }
@@ -185,7 +186,7 @@ export interface ProviderTokenUsageRecord {
   reasoningOutputTokens?: number;
   dedupeKey: string;
   createdAt: number;
-  /** #3351 — the provider recorded usage without counts; buckets are zero and the ledger marks it unknown. */
+  /** the provider recorded usage without counts; buckets are zero and the ledger marks it unknown. */
   usageStatus?: "unknown";
 }
 
@@ -201,7 +202,7 @@ export interface ProviderTokenUsageReporter {
 export interface ProviderSessionTurnContext {
   turnId?: string;
   turnStartedAt?: number;
-  /** #2840 — set only on a hookless capture after the idle edge: the opener snapshotted there. */
+  /** set only on a hookless capture after the idle edge: the opener snapshotted there. */
   opener?: ProviderSessionEvent["opener"];
   chatCaptureMode: ProviderConfig["chatCaptureMode"];
   reasoningCapture?: boolean;
@@ -211,7 +212,7 @@ export interface ProviderSessionTurnContext {
   pendingSessionEventCount(): number;
   log(message: string): void;
   debug(message: string): void;
-  /** #2919 — set only on a turn-end capture: input the provider already accepted runs as the next turn
+  /** set only on a turn-end capture: input the provider already accepted runs as the next turn
    *  with no busy edge of its own, so the runner keeps a turn open across this end. */
   noteQueuedTurn?(): void;
 }
@@ -257,12 +258,12 @@ export interface ProviderPermissionPromptHandler {
   buildView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt;
   buildHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown>;
   buildResolvedPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>, occurredAt: number): ProviderPermissionResolvedPrompt;
-  // #1173: for prompt kinds whose PreToolUse hook is answered immediately (deny-then-hold —
+  // for prompt kinds whose PreToolUse hook is answered immediately (deny-then-hold —
   // see control-server.ts's AskUserQuestion branch) rather than held open for the decision,
   // this renders the eventual "answer" decision as the normal user-prompt text to inject back
   // into the session. Absent for prompt kinds that still ride the hook response directly.
   buildAnswerInjectionPrompt?(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): string;
-  // #2914: maps a "questions" prompt to a durable operator decision a coordinator files instead.
+  // maps a "questions" prompt to a durable operator decision a coordinator files instead.
   buildDecisionRequest?(body: Record<string, unknown>): OperatorDecisionFileInput | undefined;
 }
 
@@ -279,7 +280,7 @@ export interface ProviderConfig {
   // When false, the runner does not stream reasoning/tool steps into chat. Defaults
   // to enabled (steps render discreetly, never as chat bubbles).
   reasoningCapture?: boolean;
-  // #2539 Phase A — how a provider WITH a mid-turn steer channel treats an ordinary message
+  // Phase A — how a provider WITH a mid-turn steer channel treats an ordinary message
   // offered while a turn is active. Optional everywhere: absent resolves through the OWNING
   // adapter's default (see resolveActiveTurnMessageDelivery in mid-turn-delivery.ts — adapters
   // with a mid-turn steer channel, codex and opencode/zai, default to steer; adapters without
@@ -292,7 +293,7 @@ export interface ProviderConfig {
   };
 }
 
-/** #2539 Phase A — the mid-turn delivery policy. `"steer"` folds an ordinary message offered
+/** Phase A — the mid-turn delivery policy. `"steer"` folds an ordinary message offered
  *  mid-turn into the in-flight turn; `"defer"` keeps queue-until-turn-end. */
 export type ActiveTurnMessageDelivery = "steer" | "defer";
 
@@ -305,12 +306,12 @@ export interface RunnerSpawnConfig {
   provider: string;
   model?: string;
   effort?: string;
-  /** #2595 — effective-catalog context window from the spawn payload (incl. DB overrides);
+  /** effective-catalog context window from the spawn payload (incl. DB overrides);
    * adapters prefer it over their static manifest lookup. Absent ⇒ fall back to the manifest. */
   contextWindowTokens?: number;
-  /** #2599 — the full server-resolved model record (protocol ≥ 2). Precedence over the manifest
+  /** the full server-resolved model record (protocol ≥ 2). Precedence over the manifest
    * for window / qualified name / descriptor / threshold; absent ⇒ manifest (or the legacy
-   * #2595 `contextWindowTokens` above, which the adapter reads only when no record is present). */
+   * `contextWindowTokens` above, which the adapter reads only when no record is present). */
   modelRecord?: ResolvedModelRecord;
   runnerId: string;
   instanceId: string;
@@ -318,6 +319,8 @@ export interface RunnerSpawnConfig {
   relayUrl: string;
   /** Runner-owned live credential accessor for adapter accounting RPCs. */
   getRelayToken?: () => string | undefined;
+  /** Runner-local warning sink; published through the ordinary durable timeline audit. */
+  onLaunchWarning?: (event: import("./turn-reconcile-event").RunnerTimelineEvent) => void;
   cwd: string;
   headless: boolean;
   lifecycle?: "persistent" | "transient";
@@ -338,15 +341,15 @@ export interface RunnerSpawnConfig {
   hostClaudeSettings?: Record<string, unknown>;
   env: Record<string, string>;
   controlPort: number;
-  // Stage 2 (#215): the MCP endpoint the agent connects to — the runner-local proxy URL when the
+  // Stage 2: the MCP endpoint the agent connects to — the runner-local proxy URL when the
   // proxy is active. Undefined → the adapter targets the relay's MCP endpoint directly (Stage 1).
   relayMcpEndpoint?: string;
-  // #1450: the per-session proxy secret the agent authenticates to the runner-local proxy with (the
-  // same value exported as AGENT_RELAY_SESSION_TOKEN). Set only when the proxy is active; the Codex
+  // the per-session proxy secret the agent authenticates to the runner-local proxy with (the
+  // same value exported as HUMWICK_SESSION_TOKEN). Set only when the proxy is active; the Codex
   // per-agent metaOnly callmux uses it to reach the relay endpoint on-demand THROUGH the proxy, so
   // identity rides the proxy's live-token injection and no relay token is ever written to disk.
   mcpProxySecret?: string;
-  // #672: the shared host-listener URL the per-agent `callmux bridge` connects to, when the
+  // the shared host-listener URL the per-agent `callmux bridge` connects to, when the
   // profile/spawn opted into `agentProfile.sharedMcp`. Resolved runner-side (env → default);
   // the launch assembler only emits the bridge entry when sharedMcp is on.
   sharedMcpUrl?: string;
@@ -361,7 +364,7 @@ export interface SpawnArgs {
   args: string[];
   cwd: string;
   env: Record<string, string>;
-  /** #2513 — env keys that must be explicitly UNSET in the launch environment (the tmux
+  /** env keys that must be explicitly UNSET in the launch environment (the tmux
    * launcher script exports only whitelisted keys but still inherits the tmux server's
    * env, so deleting from `env` alone cannot scrub an ambient credential). */
   envUnset?: string[];
@@ -380,11 +383,11 @@ export interface ManagedProcess {
 }
 
 /**
- * #1746 — the terminal verdict of a provider shutdown. `killed` means the provider
+ * the terminal verdict of a provider shutdown. `killed` means the provider
  * process (tmux pane / pid tree) is POSITIVELY confirmed gone; `failed-to-kill` means it
  * survived even a SIGKILL of its process group (near-impossible on a same-user Linux host,
  * so it is the operator-visible safety surface, not the happy path). The runner uses this
- * to gate deregistration: a roster removal must imply the process is dead (#1746 ask 2), so
+ * to gate deregistration: a roster removal must imply the process is dead, so
  * a `failed-to-kill` keeps the agent visible rather than turning it into a silent zombie.
  */
 export type ShutdownOutcome = "killed" | "failed-to-kill";
@@ -395,7 +398,7 @@ export interface TerminalAttachSpec {
   cwd: string;
   command: string[];
   /**
-   * #2459 round 1 (review A) — REMOVED: a per-key env record let the guest credential ride
+   * round 1 (review A) — REMOVED: a per-key env record let the guest credential ride
    * the attach-spec HTTP response body and the orchestrator's process state. Credentials now
    * travel ONLY via {@link envFile}: the runner pre-stages a 0600 env file it owns and the
    * spec carries its PATH (never its contents); the orchestrator wraps the guest command in a
@@ -405,14 +408,14 @@ export interface TerminalAttachSpec {
   title?: string;
   ttlMs?: number;
   /**
-   * #2459 — absolute path to a 0600 env file written by the runner (same host + user), for
+   * absolute path to a 0600 env file written by the runner (same host + user), for
    * the orchestrator's guest wrapper to source into the guest process environment. The path
    * is not a secret; the file contents never travel through the control server, the
    * orchestrator's memory/persistence, logs, or any argv.
    */
   envFile?: string;
   /**
-   * #2459 — non-secret attachment generation, derived from the provider's ACTIVE session id
+   * non-secret attachment generation, derived from the provider's ACTIVE session id
    * (a one-way digest — never the session id itself, never a credential). The orchestrator
    * stores it with the guest tmux session and re-reads the runner's current generation before
    * terminal input and on stream connect/reconnect; a mismatch means clearContext()/retry
@@ -441,7 +444,7 @@ export interface ProviderPermissionDecisionReason {
 }
 
 // Fresh, per-turn context usage a transcript-backed adapter reads from its
-// session log (#1512). tokensUsed is the context-window token sum for the turn;
+// session log. tokensUsed is the context-window token sum for the turn;
 // occurredAt is the wall-clock ms of the turn when the log stamps one.
 export interface ProviderContextUsage {
   tokensUsed: number;
@@ -452,7 +455,7 @@ export interface ProviderContextUsage {
 /**
  * Runner-owned live turn state is sampled when the adapter offers input.
  *
- * #2539 Phase B — the SAME context carries the deferred-settlement handoff for a mid-turn steer whose
+ * Phase B — the SAME context carries the deferred-settlement handoff for a mid-turn steer whose
  * acceptance is not yet consumption (OpenCode/zai noReply persist: the provider row exists, the model
  * reads it at a LATER step). The callbacks are runner-owned implementations of the ONE settlement seam —
  * `settleMidTurnConsumed` completes an awaiting id's settlement exactly like an immediate ack (mark read,
@@ -469,23 +472,23 @@ export interface ProviderInputObserver {
 
 export interface ProviderDeliverContext {
   inputObserver?: ProviderInputObserver;
-  /** #2840 — for an adapter that runs one provider turn PER message: these messages open the next turn.
+  /** for an adapter that runs one provider turn PER message: these messages open the next turn.
    *  Returns a disarm for when they open none (failed, refused). Absent call ⇒ the whole batch opens one. */
   openTurnFor?: (messages: Message[]) => () => void;
-  /** #3415 — this offer's turn is opened by only these messages (a split batch); a no-op unless the offer armed an opener. Returns its disarm. */
+  /** this offer's turn is opened by only these messages (a split batch); a no-op unless the offer armed an opener. Returns its disarm. */
   narrowTurnOpener?: (messages: Message[]) => () => void;
   isRecipientMidTurn?: () => boolean;
   /** Text an adapter types as a provider user turn, so its prompt-hook echo is not mirrored as terminal input. */
   recordSubmittedPrompt?: (text: string, imagePaths?: readonly string[]) => void;
   /**
-   * #2539 Phase B — positively CONSUMED ids for a batch previously reported through
+   * Phase B — positively CONSUMED ids for a batch previously reported through
    * {@link DeliverResult.awaitingConsumptionIds}. Fires once per id when the model has read the
    * persisted row (SSE parentID correlation or the bounded idle-wake settle). Absent callback ⇒
    * the adapter must hold the ids in its ledger (fail-safe: never silently settled).
    */
   settleMidTurnConsumed?: (relayIds: number[]) => void;
   /**
-   * #2539 Phase B — ids to hand BACK to the normal queue (settled as undelivered, re-offered at
+   * Phase B — ids to hand BACK to the normal queue (settled as undelivered, re-offered at
    * the next boundary) because their persisted row can no longer be consumed where it lives.
    * Absent callback ⇒ hold in the ledger, same fail-safe as {@link settleMidTurnConsumed}.
    */
@@ -495,7 +498,7 @@ export interface ProviderDeliverContext {
 export interface DeliverResult {
   acknowledgedIds: number[];
   /**
-   * #2539 Phase B — ids the adapter positively accepted for the in-flight turn (or holds in
+   * Phase B — ids the adapter positively accepted for the in-flight turn (or holds in
    * ambiguous custody after ONE timed-out POST whose bounded exact-id reconcile was inconclusive)
    * but whose CONSUMPTION has not happened yet, so their settlement completes LATER through
    * {@link ProviderDeliverContext.settleMidTurnConsumed} / {@link ProviderDeliverContext.reofferMidTurnIds}.
@@ -505,7 +508,7 @@ export interface DeliverResult {
    */
   awaitingConsumptionIds?: number[];
   /**
-   * #2397 round 3 review (MED-3r) — ids the adapter positively knows failed a TERMINAL provider
+   * round 3 review (MED-3r) — ids the adapter positively knows failed a TERMINAL provider
    * error (e.g. OpenCode's retry+reroll budget exhausted against a rate-limited upstream), as
    * opposed to an ordinary un-acknowledged id (recipient mid-turn, transport busy). The runner
    * paces its re-drain of these with bounded exponential backoff instead of an immediate re-drain — without
@@ -514,7 +517,7 @@ export interface DeliverResult {
    */
   terminalFailureIds?: number[];
   /**
-   * #2619 — ids the provider REFUSED under a rate-limit/quota hold (the turn ended in the shared
+   * ids the provider REFUSED under a rate-limit/quota hold (the turn ended in the shared
    * `blocked/rate_limit` hold, not a terminal failure). Not delivered and not failed: the runner
    * parks them (never re-drained into the wall, claims released so no Task completes) until a
    * provider turn goes through again, then redelivers them. Must be disjoint from `acknowledgedIds`.
@@ -523,7 +526,7 @@ export interface DeliverResult {
 }
 
 /**
- * #2534 — thrown by a synchronous-endpoint adapter (OpenCode/zai) when its outbound prompt was
+ * thrown by a synchronous-endpoint adapter (OpenCode/zai) when its outbound prompt was
  * positively ACCEPTED and persisted by the provider, but the turn's COMPLETION await itself
  * failed afterwards (transport drop, turn-timeout abort). The provider is already working on the
  * prompt, so the caller must NOT requeue it: a requeue would run the same assignment a second
@@ -543,8 +546,8 @@ export interface ProviderAdapter {
   statusSourceId?: string;
   stopObligationPath?: string;
   permissionPromptHandler?: ProviderPermissionPromptHandler;
-  spawn(config: RunnerSpawnConfig): Promise<ManagedProcess>;
-  // #1746 — resolves once the provider is terminal. Returns the outcome so the runner can
+  spawn(config: RunnerSpawnConfig, preparedArgs?: SpawnArgs): Promise<ManagedProcess>;
+  // resolves once the provider is terminal. Returns the outcome so the runner can
   // gate deregistration on confirmed death; `void` from a legacy adapter is treated as
   // `killed` (best-effort back-compat), but both first-party adapters now report explicitly.
   shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome | void>;
@@ -555,51 +558,51 @@ export interface ProviderAdapter {
   compact?(process: ManagedProcess, opts?: { instructions?: string; signal?: AbortSignal; onSubmitted?: () => void }): Promise<Record<string, unknown> | void>;
   compactSupportsInstructions?: boolean;
   // Blind submits stamp onSubmitted and need a separate compacted/idle completion barrier.
-  /** #3398 — the adapter emits its own `compacted` / `context-cleared` timelines; hook copies are not reset facts. */
+  /** the adapter emits its own `compacted` / `context-cleared` timelines; hook copies are not reset facts. */
   reportsContextResets?: boolean;
   compactReportsSubmission?: boolean;
   clearContext?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
-  // #2950 — change effort in place. Resolves with the confirmed `effort`, throws when the provider
+  // change effort in place. Resolves with the confirmed `effort`, throws when the provider
   // refused or never confirmed it. Only processes whose meta.effortSwitch is true may receive it.
   setEffort?(process: ManagedProcess, effort: string): Promise<{ effort: string } & Record<string, unknown>>;
-  // #1588 — when true, the runner delivers a self-resume clear-inject continuation IN-PROCESS,
+  // when true, the runner delivers a self-resume clear-inject continuation IN-PROCESS,
   // coupled to the very same agent.clearContext command (deliverCoupledContinuationAfterClear),
   // rather than leaving it to the separate reactive agent.injectContext command, and only when
   // clearContext reports `clearConfirmed: true`. Set it when a separate inject could race the clear
-  // (Claude tmux's async `/clear`, the #1588 silent mind-wipe) or land after a queued inbox message
+  // (Claude tmux's async `/clear`, the silent mind-wipe) or land after a queued inbox message
   // (headless Claude, whose clear resolves on its native conversation_reset boundary). Codex leaves
   // it unset: its awaited threadStart is the barrier and the separate inject (backstopped by the
-  // server-side #1023 sweep) stays untouched.
+  // server-side sweep) stays untouched.
   couplesClearInjectContinuation?: boolean;
-  // #2043 F1 — when true, this provider's `/compact` // `/clear` must be submitted to an IDLE
+  // F1 — when true, this provider's `/compact` // `/clear` must be submitted to an IDLE
   // provider: Claude tmux keystrokes typed mid-turn dequeue as literal chat, and headless Claude
   // queues stream-json input behind the live turn. The runner therefore gates the submit on the
   // live provider turn CLEARING first (waitForProviderTurnClear). Providers whose compact/clear is an
   // awaited app-server handshake (Codex) leave this unset — a plain turn-clear wait would time out
   // on their in-turn compaction. Those providers fence the PREDECESSOR turn a different way
-  // instead — see interruptsTurnBeforeContextCommand below (#2569).
+  // instead — see interruptsTurnBeforeContextCommand below.
   awaitsIdleBeforeContextCommand?: boolean;
-  // #2569 — when true, the runner must INTERRUPT and SETTLE the predecessor provider turn before
+  // when true, the runner must INTERRUPT and SETTLE the predecessor provider turn before
   // this provider's compact/clearContext runs. Set for app-server providers (Codex) whose
   // clearContext starts a FRESH thread (and whose compact rewrites the current one) via an awaited
   // handshake: the await confirms the NEW generation is ready but does NOT settle the OLD turn.
-  // relay_compact_and_resume is called from within the model's own live turn, so that turn keeps
+  // humwick_compact_and_resume is called from within the model's own live turn, so that turn keeps
   // running on the previous thread while the successor generation is armed on the new one — two
-  // generations then write the single worktree and revert each other (the #2569 silent overlap).
+  // generations then write the single worktree and revert each other.
   // A plain wait would time out on the still-live in-turn compaction (why blind-submit providers
   // can't share this path), so the fence actively interrupts the turn, then waits for it to reach
   // a terminal state (interrupt-then-settle, mirroring the redirect path) before the destructive
   // step. Adapters that fence internally (OpenCode's turnQueue) or have no interrupt leave this unset.
   interruptsTurnBeforeContextCommand?: boolean;
   // Derive the current context-window token usage from a transcript-backed
-  // provider's session log (#1512). The runner calls this every heartbeat with the
+  // provider's session log. The runner calls this every heartbeat with the
   // latest transcript so context stats keep advancing per-turn even when a provider's
   // out-of-band probe (Claude's status-line command) goes silent after a
   // compact/clear/native-resume. Pure parse — no process state. Event-stream
   // providers (Codex) report context through `meta.getContext` instead and omit this.
   contextUsageFromTranscript?(jsonl: string): ProviderContextUsage | undefined;
   // Normalize the session so far into the provider-agnostic SessionEvent stream the
-  // Insights context-ratio signal (#183/#184) reduces. Called by the runner's
+  // Insights context-ratio signal reduces. Called by the runner's
   // pre-session-destroy seam before any compact/clear/restart/shutdown. The runner owns
   // the per-segment cursor (it slices events since the last capture), so this returns the
   // full ordered event list for the current process lifetime. `ctx.transcriptPath` is
@@ -621,7 +624,7 @@ export interface ProviderAdapter {
   // Whether the adapter supports additive input into a running provider turn.
   supportsMidTurnSteer?: boolean;
   /**
-   * #2539 Phase A — the shared mid-turn steer contract (Phase B: opencode/zai implement against
+   * Phase A — the shared mid-turn steer contract (Phase B: opencode/zai implement against
    * the same shape). Given a batch offered while the recipient is mid-turn, the adapter owns the
    * ONE eligibility decision: fold the steerable subset (ordinary persisted messages,
    * `partitionMidTurnDelivery`) into the in-flight turn and return/ack ONLY those ids;
@@ -633,7 +636,7 @@ export interface ProviderAdapter {
    * `supportsMidTurnSteer`; their `deliver` consults it at the paste instant, so the runner
    * keeps a single call path.
    *
-   * #2539 Phase B (OpenCode/zai) — the acceptance/consumption split: the ack for this adapter
+   * Phase B (OpenCode/zai) — the acceptance/consumption split: the ack for this adapter
    * means POSITIVE PERSISTENCE (POST /session/:id/message with a caller messageID +
    * noReply:true — a user row the active loop consumes at its next step; live-proven on pinned
    * 1.18.21), not consumption, so persisted/ambiguous ids are returned as
@@ -650,21 +653,21 @@ export interface ProviderAdapter {
   // turn was interrupted from the web terminal so no Stop hook fired). "unknown"
   // means the provider can't be cheaply probed and the reconciler should defer.
   probeActivity?(process: ManagedProcess): Promise<"busy" | "idle" | "unknown">;
-  // #769 P1-A: an independent "is the provider still visibly busy?" read, consulted by the
+  // P1-A: an independent "is the provider still visibly busy?" read, consulted by the
   // busy backstop — a probeActivity()=idle must not clear a live turn while this reads `busy`
   // (defense-in-depth when the primary probe can momentarily read idle mid-turn, e.g. a
-  // connection retry). #1656: three-valued on purpose. Only `not-busy` is evidence the turn
+  // connection retry).: three-valued on purpose. Only `not-busy` is evidence the turn
   // ended; `no-session`/`unreadable` are unknown and must never authorize a clear.
   probePaneBusy?(process: ManagedProcess): Promise<PaneBusyReading>;
-  // #1138: resolve a real OS pid for a busy provider-turn whose ManagedProcess carries
+  // resolve a real OS pid for a busy provider-turn whose ManagedProcess carries
   // none directly (e.g. Claude's tmux launch — process.pid is undefined, only a tmux
   // session/socket). The runner calls this as a fallback when a busy report supplies no
-  // explicit pids, so the #650 liveness reconcile (and the stale-turn backstop) has real
+  // explicit pids, so the liveness reconcile (and the stale-turn backstop) has real
   // proof-of-life instead of only an elapsed-time heuristic. Returning undefined leaves
   // the runner's existing process.pid fallback (or no pid at all) unchanged.
   resolveBusyPid?(process: ManagedProcess): number | undefined;
   terminalAttachSpec?(process: ManagedProcess): Promise<TerminalAttachSpec>;
-  // #2459 — the CURRENT non-secret attachment generation (see TerminalAttachSpec.generation).
+  // the CURRENT non-secret attachment generation (see TerminalAttachSpec.generation).
   // Read by the runner control server's GET /terminal/generation so the orchestrator can
   // detect a session rotation without ever learning the session id or any credential.
   // Absent ⇒ the provider's attach target cannot go stale (codex) and the endpoint reports
@@ -677,7 +680,7 @@ export interface ProviderAdapter {
   captureSubagentTokenUsage?(transcriptPath: string): Promise<void>;
   /**
    * Bounded final provider-native accounting pass before a session is torn down. `transcriptPath`
-   * is `undefined` for a provider with no transcript file to tail (#2484 round 2 review MED-1 —
+   * is `undefined` for a provider with no transcript file to tail (round 2 review MED-1 —
    * OpenCode's capture is event-sourced, not file-tailed); the adapter owns whatever precondition
    * it needs (a transcript-tailing adapter bails itself on a missing path, an event-sourced one
    * ignores the argument entirely).
@@ -686,9 +689,9 @@ export interface ProviderAdapter {
   /** Start the provider-owned lifecycle observation for a prompt seeded in the launch command. */
   startLaunchSeededTurn?(process: ManagedProcess): Promise<void>;
   handleUserPrompt?(input: ProviderUserPromptInput, ctx: ProviderSessionTurnContext): Promise<void>;
-  /** Whether a prompt the provider reports is one the runner submitted, through the provider's paste transport (#3081). */
+  /** Whether a prompt the provider reports is one the runner submitted, through the provider's paste transport. */
   matchesSubmittedPrompt?(providerPrompt: string, submitted: string, imagePaths?: readonly string[]): boolean;
-  /** A session-start hook's stamped check-in (#2664): the provider's hook path works. */
+  /** A session-start hook's stamped check-in: the provider's hook path works. */
   handleHookCheck?(input: { firedAt?: number }, ctx: ProviderSessionTurnContext): void;
   /** File paths from a synchronous provider tool hook; absent means transcript delivery. */
   toolHookPaths?(input: unknown): string[] | undefined;
@@ -697,29 +700,29 @@ export interface ProviderAdapter {
   stopSessionTrace?(): void;
   publishPassiveTelemetry?(): Promise<void>;
   // `options.readyTimeoutMs` lets the runner widen the provider-ready wait for the
-  // first (cold-start) delivery vs. a fast re-attempt after a ready signal (#329).
+  // first (cold-start) delivery vs. a fast re-attempt after a ready signal.
   // `options.isInitial` (default true) tells the adapter whether this delivery is the
   // agent's genuine first turn — the runner passes false from the dashboard
-  // prompt-injection / continue paths (#1228) so a mid-session nudge isn't mislabeled
+  // prompt-injection / continue paths so a mid-session nudge isn't mislabeled
   // as the initial prompt.
-  // Resolves "held" (#2619) when the provider REFUSED the prompt under a rate-limit/quota hold:
+  // Resolves "held" when the provider REFUSED the prompt under a rate-limit/quota hold:
   // not delivered, not failed — the runner parks it for redelivery (provider-hold.ts).
   deliverInitialPrompt?(process: ManagedProcess, prompt: string, options?: PromptOfferOptions): Promise<void | "held">;
   /** Confirm that a previously ambiguous input was consumed before the runner lifts its delivery hold. */
   confirmSubmitRecovery?(process: ManagedProcess, turnStarted: boolean): Promise<boolean>;
-  /** The operator released the runner's submit hold (#2664): drop any adapter-side submit fence. */
+  /** The operator released the runner's submit hold: drop any adapter-side submit fence. */
   releaseSubmitHold?(process: ManagedProcess): void;
   // When true, the adapter seeds the spawn-time initial prompt as a launch argument
   // (Claude's positional `claude "<prompt>"`), so it's already delivered the instant the
   // session starts. The runner must then NOT also deliver it post-launch via
   // deliverInitialPrompt — that would double-deliver and re-introduce the send-keys
-  // onboarding race (#352). deliverInitialPrompt stays available for mid-session injection
+  // onboarding race. deliverInitialPrompt stays available for mid-session injection
   // (dashboard chat box) and ongoing message delivery, which have no launch-arg equivalent.
   seedsInitialPromptAtLaunch?: boolean;
   /** Return accepted ids, plus consumption or failure outcomes when the transport reports them. */
   deliver(process: ManagedProcess, messages: Message[], ctx?: ProviderDeliverContext): Promise<void | number[] | DeliverResult>;
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void;
-  // #1651 — subscribe to pane-derived DIAGNOSTICS. Separate from onStatusChange on purpose:
+  // subscribe to pane-derived DIAGNOSTICS. Separate from onStatusChange on purpose:
   // this channel's payload cannot carry a status, a clear, or a providerState, so wiring a
   // detector here is a structural guarantee that it cannot mutate runner state. Optional;
   // adapters with no pane to scrape simply never call it.
@@ -728,7 +731,7 @@ export interface ProviderAdapter {
   // shared idempotency for multiple trace steps discovered in one provider poll.
   onSessionEvent?(cb: (event: ProviderSessionEvent) => void): void;
   onSessionEvents?(cb: (events: ProviderSessionEventBatch) => void): void;
-  // #2389 — "the model produced something in the current turn", for output an adapter can OBSERVE
+  // "the model produced something in the current turn", for output an adapter can OBSERVE
   // but cannot mirror. It exists because the runner has to tell a turn that did nothing at all from
   // one that finished work, and mirrored session events do not cover every provider: OpenCode's
   // wire carries tool parts whose internal shape we deliberately do not guess at, so they are
@@ -736,10 +739,10 @@ export interface ProviderAdapter {
   // — nothing is displayed, nothing is persisted. Optional; adapters whose output is fully mirrored
   // never need it.
   onTurnActivity?(cb: () => void): void;
-  // §4.1 of the Runner↔provider contract (#725 / #746): fold the runner-tracked raw
+  // §4.1 of the Runner↔provider contract: fold the runner-tracked raw
   // transport/timeline/token/work-kind signals into ONE normalized LivenessSignal the
   // server reads instead of six raw `meta` fields. Each adapter owns what counts as
-  // progress for its provider (Claude #713 timeline transitions; Codex #724 live
+  // progress for its provider (Claude timeline transitions; Codex live
   // subprocess work). Optional so test/mock adapters fall back to the shared
   // {@link computeLivenessSignal} fold — the runner always has a verdict to ship.
   liveness?(inputs: LivenessInputs): LivenessSignal;
@@ -756,7 +759,7 @@ export interface ProviderAdapter {
   buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs;
 }
 
-// #552 — the strictest base. Beyond the isolated provider home that every
+// the strictest base. Beyond the isolated provider home that every
 // non-host base already gets (fresh CLAUDE_CONFIG_DIR / CODEX_HOME, which drops
 // the GLOBAL instruction + host MCP/hooks/plugins cascade), "vanilla" actively
 // suppresses every remaining host customization channel at launch, including the
@@ -771,7 +774,7 @@ export function relayContext(): string {
   return resolveRelayContext({ slug: "relay.context.codex" }).text;
 }
 
-// #306 — deliver the FULL message body by default. Only a pathological body beyond this
+// deliver the FULL message body by default. Only a pathological body beyond this
 // high cap truncates (with a get-message hint) so it can't nuke an agent's context; the 99%
 // case (incl. multi-thousand-char handoffs/reports) arrives whole in one shot, no extra
 // round-trip. The mirror flow (user typing directly) already injects full text — this removes
@@ -789,7 +792,7 @@ export function providerMessageBodyMaxChars(): number {
   return DEFAULT_PROVIDER_MESSAGE_BODY_MAX_CHARS;
 }
 
-// #1935 — the Claude Code monitor surfaces each delivered event with a HARD cap on the content that
+// the Claude Code monitor surfaces each delivered event with a HARD cap on the content that
 // reaches the agent's context; beyond it the harness truncates the event and spills the tail to an
 // output file the agent must re-read (paying for the message ~twice, both copies persisting in
 // context). Two independent bounds, measured 2026-08-02 against the live harness:
@@ -842,7 +845,7 @@ export interface DeliveredBodyPreview {
   guidance: string[];
 }
 
-// #1058 — one home for the delivered-body cap. Head-only truncation silently ate the TAIL, which is
+// one home for the delivered-body cap. Head-only truncation silently ate the TAIL, which is
 // exactly where a report-up final puts its verdict / SHIP recommendation. Preserve BOTH ends: keep a
 // head slice for opening context and a tail slice for the conclusion, eliding the middle and pointing
 // at the untrimmed body. The tail is favored (it holds the verdict). Slices snap to whitespace so we
@@ -854,10 +857,10 @@ export function previewDeliveredBody(
 ): DeliveredBodyPreview {
   if (rawBody.length <= maxChars) return { body: rawBody, truncated: false, guidance: [] };
   const fetchLines = [
-    `Read full: agent-relay get-message ${messageId}`,
-    `Body only: agent-relay get-message ${messageId} --body`,
+    `Read full: humwick get-message ${messageId}`,
+    `Body only: humwick get-message ${messageId} --body`,
   ];
-  const marker = (elided: number) => `[… ${elided} chars elided from the middle — full report: relay_get_message #${messageId} …]`;
+  const marker = (elided: number) => `[… ${elided} chars elided from the middle — full report: humwick_get_message #${messageId} …]`;
   // Reserve room for the marker and its two blank-line joins; upper-bound the marker length by using
   // the (always-larger) full body length so the reserved budget can never underflow the real marker.
   const budget = maxChars - marker(rawBody.length).length - 4;
@@ -900,8 +903,8 @@ function attachmentLabel(ref: Record<string, unknown>): string {
 
 function attachmentCacheMetadata(ref: Record<string, unknown>): Record<string, unknown> | undefined {
   const metadata = isRecord(ref.metadata) ? ref.metadata : undefined;
-  const agentRelay = metadata && isRecord(metadata.agentRelay) ? metadata.agentRelay : undefined;
-  return agentRelay;
+  const humwick = readHumwickRecord(metadata);
+  return humwick;
 }
 
 export function isMemoryInjection(message: Message): boolean {
@@ -921,7 +924,7 @@ export function isPersistedRelayMessage(message: Message): boolean {
   return Number.isSafeInteger(message.id) && message.id > 0;
 }
 
-// #283 — one-line nudge that replaces the reply-scaffold footer for notification-class
+// one-line nudge that replaces the reply-scaffold footer for notification-class
 // (replyExpected:false) messages. Deliberately tiny so a bloated context can't drown the
 // no-reply rule established at session start. Shared with the Claude delivery path.
 export const NOTIFICATION_NUDGE = "↪ Notification — no reply needed.";
@@ -951,7 +954,7 @@ export function dedupePersistedMessages(messages: Message[]): Message[] {
   });
 }
 
-/** A human wrote it: a human address, or a prompt parked on a human's behalf (#3415). */
+/** A human wrote it: a human address, or a prompt parked on a human's behalf. */
 export function isHumanSenderMessage(message: Message): boolean {
   return isHumanAgentId(heldForSender(message) ?? message.from);
 }
@@ -969,10 +972,10 @@ export function providerSenderLabel(message: Message): string {
   return isHumanChannel ? `human user via ${message.from}` : message.from;
 }
 
-/** `imagePaths`: cached attachment paths the prompt text lists (#2664). */
+/** `imagePaths`: cached attachment paths the prompt text lists. */
 export interface PromptOfferOptions { readyTimeoutMs?: number; isInitial?: boolean; imagePaths?: string[]; inputObserver?: ProviderInputObserver }
 
-/** A parked prompt's attachment paths, carried on its inbox row so the redelivery keeps them (#2664). */
+/** A parked prompt's attachment paths, carried on its inbox row so the redelivery keeps them. */
 export const HELD_PROMPT_IMAGE_PATHS = "heldPromptImagePaths";
 
 /** Local cache paths of the messages' attachments, as providerAttachmentText lists them. */
@@ -1013,11 +1016,11 @@ export function providerAttachmentText(message: Message): string | undefined {
     : hasLocalPaths
     ? [
       "Use the local path above when inspecting the attachment.",
-      `Read attachment details: agent-relay get-message ${message.id} --json`,
+      `Read attachment details: humwick get-message ${message.id} --json`,
     ]
     : [
-      `Read attachment details: agent-relay get-message ${message.id} --json`,
-      `Fetch content: curl -fsS -H "X-Agent-Relay-Token: $AGENT_RELAY_TOKEN" "$AGENT_RELAY_URL/api/artifacts/<artifactId>/content" -o <filename>`,
+      `Read attachment details: humwick get-message ${message.id} --json`,
+      `Fetch content: curl -fsS -H "X-Humwick-Token: $HUMWICK_TOKEN" "$HUMWICK_URL/api/artifacts/<artifactId>/content" -o <filename>`,
     ];
   return [
     "Attachments:",
@@ -1042,7 +1045,7 @@ export function providerMessageText(messages: Message[]): string {
         : undefined;
       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}${preview.body}`,
         ].join("\n");