agent-relay-server 0.127.2 → 0.127.4

package/runner/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.127.2",
+  "version": "0.127.4",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/runner/plugins/claude/monitors/relay-monitor.provisioned.mjs

@@ -320,6 +320,9 @@ function shouldShowReplyReminder(deliveryCount) {
 function latestReplyableMessage(messages) {
   return messages.filter((message) => isPersistedRelayMessage2(message) && !isMemoryInjection(message) && !isReactionNotification(message) && !isSpawnObligationMessage(message) && message.replyExpected !== false).at(-1);
 }
+function isSelfResumeInjection(message) {
+  return isRecord(message.payload) && message.payload.resumeInjection === true;
+}
 function formatMessage(message, relaySurface) {
   const subject = message.subject ? `Subject: ${message.subject}
 ` : "";
@@ -331,7 +334,7 @@ function formatMessage(message, relaySurface) {
 `) : undefined;
   if (isMemoryContext) {
     return [
-      `[agent-relay context from ${message.from}]`,
+      `[agent-relay ${isSelfResumeInjection(message) ? "self-resume continuation" : "context"} from ${message.from}]`,
       providerAttachmentText(message),
       `${subject}${preview.body}`,
       truncationGuidance

package/runner/src/adapter.ts

@@ -327,6 +327,10 @@ function isMemoryInjection(message: Message): boolean {
   return isRecord(message.payload) && message.payload.memoryInjection === true;
 }
 
+function isSelfResumeInjection(message: Message): boolean {
+  return isRecord(message.payload) && message.payload.resumeInjection === true;
+}
+
 function isReactionNotification(message: Message): boolean {
   const event = isRecord(message.payload?.event) ? message.payload.event : undefined;
   return message.payload?.reactionNotification === true || event?.type === "message.reaction";
@@ -434,7 +438,7 @@ export function providerMessageText(messages: Message[]): string {
         : undefined;
       if (isMemoryContext) {
         return [
-          `[agent-relay context from ${message.from}]`,
+          `[agent-relay ${isSelfResumeInjection(message) ? "self-resume continuation" : "context"} from ${message.from}]`,
           "Guide: agent-relay /guide",
           providerAttachmentText(message),
           `${subject}${preview.body}`,

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

@@ -69,6 +69,10 @@ function latestReplyableMessage(messages: Message[]): Message | undefined {
     .at(-1);
 }
 
+function isSelfResumeInjection(message: Message): boolean {
+  return isRecord(message.payload) && message.payload.resumeInjection === true;
+}
+
 function formatMessage(message: Message, relaySurface: boolean): string {
   const subject = message.subject ? `Subject: ${message.subject}\n` : "";
   const isMemoryContext = isMemoryInjection(message);
@@ -81,7 +85,7 @@ function formatMessage(message: Message, relaySurface: boolean): string {
 
   if (isMemoryContext) {
     return [
-      `[agent-relay context from ${message.from}]`,
+      `[agent-relay ${isSelfResumeInjection(message) ? "self-resume continuation" : "context"} from ${message.from}]`,
       providerAttachmentText(message),
       `${subject}${preview.body}`,
       truncationGuidance,

package/runner/src/adapters/claude-transcript.ts

@@ -25,6 +25,7 @@ export interface TurnStep {
   type: "narration" | "reasoning" | "tool";
   text: string;
   label?: string;
+  occurredAt?: number;
 }
 
 interface TranscriptMessage {
@@ -35,6 +36,7 @@ interface TranscriptMessage {
 
 interface TranscriptEntry {
   type?: string;
+  timestamp?: string;
   message?: TranscriptMessage;
   // Claude Code stamps every transcript entry with `isSidechain`: true for
   // entries belonging to a Task (subagent) run, false for the root session.
@@ -225,6 +227,46 @@ export function countTranscriptEntries(jsonl: string): number {
   return count;
 }
 
+/** Key-order-independent structural equality, cheap enough for a small tool_input object. */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * True when the transcript already contains the exact assistant tool_use block that
+ * triggered a PreToolUse hook — the settle-poll anchor (#1116). The hook payload's own
+ * `tool_name`/`tool_input` are the precise call that fired it, so matching them against
+ * the transcript's tool_use blocks (name + structural input equality) is exact, unlike
+ * guessing from transcript shape alone. Claude's JSONL flush is async/bursty and can
+ * lag well behind the hook firing, so the entry backing the hook's own call may still be
+ * missing from disk the instant the hook runs — this is what the settle-poll waits for.
+ * #1086 should adopt this same anchor for its own turn-final settle marker rather than
+ * inventing a second one.
+ */
+export function transcriptHasToolUseAnchor(jsonl: string, toolName: string, toolInput: unknown): boolean {
+  const wantInput = canonicalJson(toolInput ?? {});
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "assistant" || isSidechainEntry(entry)) continue;
+    for (const block of blocks(entry.message)) {
+      if (block.type === "tool_use" && block.name === toolName && canonicalJson(block.input ?? {}) === wantInput) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Extract the ordered narration, reasoning, and tool steps for the most recent
  * turn (since the last real user prompt). Used by the reasoning tailer to stream
@@ -283,18 +325,25 @@ export class LatestTurnStepAccumulator {
       return;
     }
     if (entry.type !== "assistant") return;
+    const occurredAt = transcriptEntryOccurredAt(entry);
     for (const b of blocks(entry.message)) {
       if (b.type === "text" && typeof b.text === "string" && b.text.trim()) {
-        this.latestSteps.push({ type: "narration", text: b.text.trim() });
+        this.latestSteps.push({ type: "narration", text: b.text.trim(), ...(occurredAt ? { occurredAt } : {}) });
       } else if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.trim()) {
-        this.latestSteps.push({ type: "reasoning", text: b.thinking.trim() });
+        this.latestSteps.push({ type: "reasoning", text: b.thinking.trim(), ...(occurredAt ? { occurredAt } : {}) });
       } else if (b.type === "tool_use" && typeof b.name === "string" && b.name) {
-        this.latestSteps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input) });
+        this.latestSteps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input), ...(occurredAt ? { occurredAt } : {}) });
       }
     }
   }
 }
 
+function transcriptEntryOccurredAt(entry: TranscriptEntry): number | undefined {
+  if (typeof entry.timestamp !== "string" || !entry.timestamp) return undefined;
+  const parsed = Date.parse(entry.timestamp);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
 /**
  * Stable dedup keys for a turn's steps, in order. Each key is salted with how many
  * identical (type,label,text) steps preceded it in the same window — so running the

package/runner/src/control-server.ts

@@ -49,9 +49,13 @@ interface ControlServerOptions {
   // dashboard chat without the agent re-emitting it via /reply.
   // isPreFlush: true signals a mid-turn call from a PreToolUse hook — flush any
   // un-mirrored narrative before the interactive form appears in chat (#435).
+  // toolName/toolInput (#1116): the hook payload's own tool call — the exact anchor the
+  // runner settle-polls the transcript for before draining and returning. The resolved
+  // `reasoningSettled` reflects whether that anchor was actually found (vs a bounded
+  // timeout), so the interactive form can stamp an honest value instead of an assumed one.
   // promptId (#1086): Claude's native `prompt_id` from the Stop hook payload — the
   // stable, provider-native turn identifier used instead of a minted random UUID.
-  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean }): Promise<void>;
+  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean; toolName?: string; toolInput?: unknown }): Promise<{ reasoningSettled: boolean } | void>;
   onPermissionResolved?(input: ResolvedPermissionPrompt): Promise<void> | void;
   // A provider UserPromptSubmit hook hands over the prompt the human typed
   // directly into the session (web terminal / TUI) so the runner can mirror it
@@ -84,6 +88,8 @@ export interface ResolvedPermissionPrompt {
   approvalId: string;
   decision: ProviderPermissionDecisionInput["decision"];
   decisionLabel: string;
+  occurredAt: number;
+  resolvedAt: number;
   questions?: unknown[];
   answers?: Record<string, string>;
 }
@@ -264,18 +270,27 @@ async function handlePermissionRequest(
   options: ControlServerOptions,
   pendingPermissionRequests: Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>,
 ): Promise<Response> {
+  const occurredAt = Date.now();
   const body = await req.json().catch(() => null);
   if (!isRecord(body)) return Response.json({});
-  // #435: flush any un-mirrored narrative from the transcript before the form
-  // appears in chat — the transcript already has the assistant text block at
-  // PreToolUse time, but the Stop hook (which normally captures it) won't fire
-  // until after the user answers, so the form would otherwise arrive first.
+  // #435/#1116: flush any un-mirrored narrative from the transcript before the form
+  // appears in chat. The old comment here asserted the transcript already had the
+  // assistant text block at PreToolUse time — empirically false: Claude's JSONL flush is
+  // async/bursty and can lag the hook firing by a long margin. onSessionTurn now
+  // settle-polls for the exact tool_use entry that triggered this hook (toolName/
+  // toolInput below are that anchor) before draining, and honestly reports back whether
+  // it found the anchor or hit its bounded timeout — reasoningSettled reflects that,
+  // rather than an assumption nothing here confirmed.
   const transcriptPath = typeof body.transcript_path === "string" ? body.transcript_path : "";
+  const toolName = typeof body.tool_name === "string" ? body.tool_name : undefined;
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : undefined;
+  let reasoningSettled = true;
   if (transcriptPath && options.onSessionTurn) {
-    await options.onSessionTurn({ transcriptPath, isPreFlush: true }).catch(() => {});
+    const result = await options.onSessionTurn({ transcriptPath, isPreFlush: true, toolName, toolInput }).catch(() => undefined);
+    if (result && typeof result.reasoningSettled === "boolean") reasoningSettled = result.reasoningSettled;
   }
   const approvalId = crypto.randomUUID();
-  const view = claudePermissionApprovalView(approvalId, body);
+  const view = claudePermissionApprovalView(approvalId, body, reasoningSettled);
   options.onStatus({
     status: "busy",
     reason: "provider-turn",
@@ -299,18 +314,18 @@ async function handlePermissionRequest(
   });
 
   if (decision.reason !== PERMISSION_TIMEOUT_REASON && options.onPermissionResolved) {
-    await Promise.resolve(options.onPermissionResolved(claudeResolvedPermissionPrompt(view, decision, body))).catch(() => {});
+    await Promise.resolve(options.onPermissionResolved(claudeResolvedPermissionPrompt(view, decision, body, occurredAt))).catch(() => {});
   }
 
   return Response.json(claudePermissionHookResponse(decision, body));
 }
 
 // Build the normalized InteractivePrompt for a Claude PreToolUse permission/question hook.
-// reasoningSettled is stamped `true` because handlePermissionRequest pre-flushes the
-// transcript narrative (onSessionTurn isPreFlush) BEFORE this view is built and emitted, so
-// the turn's reasoning is already mirrored ahead of the form (#435/#723). No `provider` tag —
-// the server reads the typed contract, not provider identity.
-function claudePermissionApprovalView(id: string, body: Record<string, unknown>): InteractivePrompt {
+// reasoningSettled is the caller's settle-poll result (#435/#723/#1116): true when
+// handlePermissionRequest's pre-flush confirmed the turn's reasoning was drained before
+// this view was built, false when it hit its bounded timeout without confirming. No
+// `provider` tag — the server reads the typed contract, not provider identity.
+function claudePermissionApprovalView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt {
   const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
   const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
   // AskUserQuestion is not a yes/no gate — it asks the user to pick answers.
@@ -326,7 +341,7 @@ function claudePermissionApprovalView(id: string, body: Record<string, unknown>)
       body: "",
       questions: toolInput.questions as InteractivePrompt["questions"],
       choices: [],
-      reasoningSettled: true,
+      reasoningSettled,
     };
   }
   // ExitPlanMode arrives through the generic PermissionRequest hook (it doesn't
@@ -347,7 +362,7 @@ function claudePermissionApprovalView(id: string, body: Record<string, unknown>)
         { id: "approve", label: "Approve plan" },
         { id: "deny", label: "Keep planning" },
       ],
-      reasoningSettled: true,
+      reasoningSettled,
     };
   }
   const command = typeof toolInput.command === "string" ? toolInput.command : "";
@@ -368,7 +383,7 @@ function claudePermissionApprovalView(id: string, body: Record<string, unknown>)
       { id: "deny", label: "Deny" },
       { id: "abort", label: "Abort" },
     ],
-    reasoningSettled: true,
+    reasoningSettled,
   };
 }
 
@@ -437,7 +452,7 @@ function claudePermissionHookResponse(decision: ProviderPermissionDecisionInput,
   };
 }
 
-function claudeResolvedPermissionPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): ResolvedPermissionPrompt {
+function claudeResolvedPermissionPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>, occurredAt: number): ResolvedPermissionPrompt {
   const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
   const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
   const kind = view.kind === "questions" || view.kind === "plan" || view.kind === "command" || view.kind === "tool"
@@ -459,6 +474,8 @@ function claudeResolvedPermissionPrompt(view: InteractivePrompt, decision: Provi
     approvalId: decision.approvalId,
     decision: decision.decision,
     decisionLabel,
+    occurredAt,
+    resolvedAt: Date.now(),
     ...(questions ? { questions } : {}),
     ...(decision.answers ? { answers: decision.answers } : {}),
   };

package/runner/src/runner-core.ts

@@ -16,7 +16,7 @@ import { readRunnerContextProbeState } from "./context-probe-state";
 import { startControlServer, type ControlServer, type ResolvedPermissionPrompt } from "./control-server";
 import { ReplyObligationCache, obligationRequiresExplicitReply, responseCaptureReplyRoute } from "./reply-obligation-cache";
 import { Outbox, type OutboxRecord } from "./outbox";
-import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, extractAssistantTurnForPrompt, countTranscriptEntries, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
+import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, extractAssistantTurnForPrompt, countTranscriptEntries, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptHasToolUseAnchor, transcriptLooksComplete } from "./adapters/claude-transcript";
 import { IncrementalClaudeTranscriptTail } from "./adapters/claude-transcript-tail";
 import { getManifest } from "agent-relay-providers";
 import { profileUsesProviderHostGlobals } from "./profile-home";
@@ -153,6 +153,13 @@ const MAX_INITIAL_PROMPT_ATTEMPTS = 6;
 // transcript bytes.
 const REASONING_POLL_MS = 1_200;
 const SESSION_MIRROR_BATCH_MAX = 100;
+// #1116: bounded settle-poll for the PreToolUse pre-flush anchor. Claude's JSONL flush is
+// async/bursty and can lag the hook firing by a long margin, so a one-shot read (the old
+// #435/#499 behavior) often finds nothing. Poll at this cadence until the exact triggering
+// tool_use entry lands on disk, but never past the timeout — the question must never block
+// the user more than a few seconds waiting on a transcript write that might not be coming.
+const SETTLE_POLL_INTERVAL_MS = 250;
+const SETTLE_POLL_TIMEOUT_MS = 4_000;
 interface RunnerTimelineEvent {
   status: string;
   id?: string;
@@ -285,6 +292,10 @@ export class AgentRunner {
   // Reasoning tailer (item 5): streams the in-flight turn's reasoning/tool steps
   // from the Claude transcript into chat as discreet session events.
   private reasoningTail?: ReasoningTailState;
+  // Settle-poll cadence for the pre-flush anchor (#1116) — instance fields (not just the
+  // module constants) so tests can shrink them without waiting out the real bound.
+  private settlePollIntervalMs = SETTLE_POLL_INTERVAL_MS;
+  private settlePollTimeoutMs = SETTLE_POLL_TIMEOUT_MS;
   private scratch?: SessionScratchLayout;
   // #417: for non-claude providers, tracks how many times each spawner obligation has
   // been re-injected so a non-responsive agent can't spin in a re-injection loop.
@@ -424,7 +435,7 @@ export class AgentRunner {
       // Hot-path-safe: answered instantly from the local snapshot, never a server
       // round-trip. The snapshot is kept warm by the background refresh below (#196).
       onReplyObligations: () => Promise.resolve(this.obligationCache.get()),
-      onSessionTurn: (input) => this.publishSessionTurn(input), onPermissionResolved: (input) => this.publishSessionEvent({ from: this.agentId, to: "user", body: input.body, session: { type: "prompt-resolution", origin: "provider", label: input.decisionLabel, ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}), stepId: `prompt-resolution:${input.approvalId}`, promptResolution: input } }),
+      onSessionTurn: (input) => this.publishSessionTurn(input), onPermissionResolved: (input) => this.publishSessionEvent({ from: this.agentId, to: "user", body: input.body, occurredAt: input.occurredAt, session: { type: "prompt-resolution", origin: "provider", label: input.decisionLabel, ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}), stepId: `prompt-resolution:${input.approvalId}`, promptResolution: input } }),
       onUserPrompt: (input) => this.handleUserPrompt(input),
       onSessionBoundary: (input) => this.handleSessionBoundary(input),
       onHookFatal: (report) => this.reportHookFatal(report),
@@ -842,17 +853,24 @@ export class AgentRunner {
     const content = typeof params.content === "string" ? params.content.trim() : "";
     if (!content) throw new Error("content required");
     const memoryIds = Array.isArray(params.memoryIds) ? params.memoryIds.filter((id): id is string => typeof id === "string") : [];
+    const reason = typeof params.reason === "string" ? params.reason : undefined;
+    const selfResume = params.selfResume !== null && typeof params.selfResume === "object" && !Array.isArray(params.selfResume)
+      ? params.selfResume as Record<string, unknown>
+      : undefined;
+    const isSelfResumeContinuation = reason === "self-resume-continuation" || Boolean(selfResume);
     await this.options.adapter.deliver(this.process!, [{
       id: 0,
       from: "system",
       to: this.agentId,
       kind: "system",
-      subject: "Agent Relay memory context",
+      subject: isSelfResumeContinuation ? "Agent Relay self-resume continuation" : "Agent Relay memory context",
       body: content,
       payload: {
         memoryInjection: true,
-        reason: typeof params.reason === "string" ? params.reason : undefined,
+        reason,
         memoryIds,
+        ...(isSelfResumeContinuation ? { resumeInjection: true } : {}),
+        ...(selfResume ? { selfResume } : {}),
       },
       readBy: [],
       createdAt: Date.now(),
@@ -1428,17 +1446,21 @@ export class AgentRunner {
   // no relay message) are mirrored too. A reply obligation, when present, is still
   // used as replyTo so the Stop hook stops nagging the agent to /reply.
   //
-  // isPreFlush: true (#435/#499) — mid-turn PreToolUse boundary. Drain the live
-  // tail and force-flush session messages before showing the blocking control;
-  // the entry cursor lets Stop capture skip already-emitted text.
-  private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean }): Promise<void> {
+  // isPreFlush: true (#435/#499/#1116) — mid-turn PreToolUse boundary. Settle-polls the
+  // transcript for the exact tool_use entry that triggered the hook (toolName/toolInput,
+  // the hook payload's own anchor), then drains the live tail and force-flushes session
+  // messages before showing the blocking control; the entry cursor lets Stop capture skip
+  // already-emitted text. Returns whether the settle-poll actually found the anchor
+  // (reasoningSettled) — an honest `false` on timeout rather than a stamped `true` on a
+  // premise nothing here confirmed (#1116; see InteractivePrompt.reasoningSettled).
+  private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean; toolName?: string; toolInput?: unknown }): Promise<{ reasoningSettled: boolean } | void> {
     if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
 
     if (input.isPreFlush) {
-      if (!input.transcriptPath) return;
-      let jsonl: string | undefined;
-      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { return; }
-      if (!jsonl) return;
+      if (!input.transcriptPath) return { reasoningSettled: true };
+      const settled = await this.settlePollForToolUse(input.transcriptPath, input.toolName, input.toolInput);
+      const jsonl = settled.jsonl;
+      if (jsonl === undefined) return { reasoningSettled: false };
       const body = extractLastAssistantTurnAfterEntry(jsonl, this.narrativeFlushEntryCount);
       await this.drainReasoningTail();
       this.narrativeFlushEntryCount = countTranscriptEntries(jsonl);
@@ -1448,7 +1470,7 @@ export class AgentRunner {
         await this.publishSessionEvent({ from: this.agentId, to: "user", body, session: { type: "response", origin: "provider", ...(turnId ? { turnId } : {}) } });
       }
       await this.sessionOutbox.flush(2_000).then((ok) => { if (!ok) this.sessionLog(`pre-flush session outbox incomplete before blocking control (${this.sessionOutbox.pendingCount()} pending)`); }, (error) => this.sessionLog(`pre-flush session outbox failed before blocking control: ${errMessage(error)}`));
-      return;
+      return { reasoningSettled: settled.settled };
     }
 
     // Claude's Stop hook reports its own native `prompt_id` — the same UUID the
@@ -1458,6 +1480,11 @@ export class AgentRunner {
     // prompt_id at turn start — see setProviderStatus / handleUserPrompt), but this
     // prefers the freshest source so finalization is correct even if the two drift.
     const turnId = input.promptId ?? this.currentTurnId;
+    // #1116: drain whatever the tail hasn't polled yet BEFORE stopping it — stopping first
+    // (the old order) clears the poll/timer state, so any steps Claude flushed in the last
+    // window between the tail's previous tick and this Stop hook were silently dropped from
+    // the step lane instead of reaching chat.
+    await this.drainReasoningTail();
     this.stopReasoningTail();
     // Optional correlation for threading + obligation clearing — never a capture gate.
     let replyToMessageId: number | undefined, replyTarget = "user";
@@ -1543,22 +1570,18 @@ export class AgentRunner {
   // tool step) as a `kind: "session"` relay message tagged with payload.session so
   // the dashboard can render the live provider session faithfully. Display-only:
   // session messages are never delivered back into a provider.
-  private publishSessionEvent(input: {
-    from: string;
-    to: string;
-    body: string;
-    session: MessageSessionMeta;
-    replyTo?: number;
-  }): void {
-    // Durable, ordered, timestamped (#196): the actual POST happens in deliverOutboxEvent,
-    // retried until it lands. occurredAt is stamped now so a queued event reports when it
-    // truly happened, not when the server finally accepted it. Routed through the fast-lane
-    // sessionOutbox (#332) so a transient trace failure can't head-of-line block real messages.
+  private publishSessionEvent(input: { from: string; to: string; body: string; session: MessageSessionMeta; replyTo?: number; occurredAt?: number }): void {
+    // Durable, ordered, timestamped (#196/#1115): the actual POST happens in
+    // deliverOutboxEvent, retried until it lands. An explicit occurredAt preserves the
+    // provider-native event time; otherwise the outbox stamps enqueue time. Routed through
+    // the fast-lane sessionOutbox (#332) so a transient trace failure can't head-of-line
+    // block real messages.
     // A stepId-bearing step (Codex tool running→completed, streamed reasoning/response) uses a
     // STABLE idempotency key so the server upserts the row in place instead of appending a dup.
     const stepId = input.session.stepId;
     this.sessionOutbox.enqueue({
       kind: "session-message",
+      ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}),
       ...(stepId ? { idempotencyKey: `session-step:${input.from}:${input.session.turnId ?? ""}:${stepId}` } : {}),
       payload: {
         from: input.from,
@@ -1571,13 +1594,7 @@ export class AgentRunner {
     });
   }
 
-  private publishSessionEventsBatch(inputs: Array<{
-    from: string;
-    to: string;
-    body: string;
-    session: MessageSessionMeta;
-    replyTo?: number;
-  }>): void {
+  private publishSessionEventsBatch(inputs: Array<{ from: string; to: string; body: string; session: MessageSessionMeta; replyTo?: number; occurredAt?: number }>): void {
     for (let i = 0; i < inputs.length; i += SESSION_MIRROR_BATCH_MAX) {
       const chunk = inputs.slice(i, i + SESSION_MIRROR_BATCH_MAX);
       if (chunk.length === 1) {
@@ -1592,6 +1609,7 @@ export class AgentRunner {
           ...(input.replyTo ? { replyTo: input.replyTo } : {}),
           kind: "session",
           body: input.body,
+          ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}),
           ...(stepId ? { idempotencyKey: `session-step:${input.from}:${input.session.turnId ?? ""}:${stepId}` } : {}),
           payload: { session: { provider: this.options.provider, ...input.session } },
         } satisfies SendMessageInput;
@@ -1933,7 +1951,7 @@ export class AgentRunner {
       }
       const turnId = this.currentTurnId ?? turnIdAtStart;
       let emitted = 0;
-      const batch: Array<{ from: string; to: string; body: string; session: MessageSessionMeta }> = [];
+      const batch: Array<{ from: string; to: string; body: string; session: MessageSessionMeta; occurredAt?: number }> = [];
       for (const { sig, step } of keyed) {
         if (seen.has(sig)) continue;
         seen.add(sig);
@@ -1942,6 +1960,7 @@ export class AgentRunner {
           from: this.agentId,
           to: "user",
           body: step.text,
+          ...(step.occurredAt ? { occurredAt: step.occurredAt } : {}),
           session: { type: step.type, origin: "provider", ...(turnId ? { turnId } : {}), ...(step.label ? { label: step.label } : {}) },
         });
         if (step.type === "narration") emittedNarrationKeys.add(sig);
@@ -1964,6 +1983,28 @@ export class AgentRunner {
     await this.reasoningTail?.poll();
   }
 
+  // #1116: bounded settle-poll for the PreToolUse pre-flush anchor. The old pre-flush read
+  // the transcript exactly once and, on the false premise that Claude's JSONL write is
+  // synchronous with the hook firing, treated whatever it found (often nothing) as complete.
+  // Claude's flush is actually async/bursty — sometimes gated on the hook's own resolution —
+  // so this polls at settlePollIntervalMs until the transcript contains the EXACT tool_use
+  // entry that triggered the hook (toolName/toolInput from the hook payload is the precise
+  // anchor), then returns the freshest read. Never polls past settlePollTimeoutMs — the
+  // question must ship regardless, just honestly flagged as `settled: false` when it does.
+  // No toolName (a caller that can't identify an anchor) skips straight to a single read,
+  // matching the old one-shot behavior.
+  private async settlePollForToolUse(transcriptPath: string, toolName?: string, toolInput?: unknown): Promise<{ settled: boolean; jsonl?: string }> {
+    const deadline = Date.now() + this.settlePollTimeoutMs;
+    for (;;) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (!toolName) return { settled: Boolean(jsonl), jsonl };
+      if (jsonl !== undefined && transcriptHasToolUseAnchor(jsonl, toolName, toolInput)) return { settled: true, jsonl };
+      if (Date.now() >= deadline) return { settled: false, jsonl };
+      await Bun.sleep(this.settlePollIntervalMs);
+    }
+  }
+
   private preFlushBodyAlreadyMirroredByReasoningTail(jsonl: string, body: string): boolean {
     const tail = this.reasoningTail;
     if (!tail || !tail.emittedNarrationKeys.size) return false;

package/scripts/orchestrator-spawn-smoke.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { spawnSync } from "node:child_process";
 import { hostname } from "node:os";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 type Orchestrator = {
@@ -33,14 +34,16 @@ let cwd = process.env.AGENT_RELAY_SMOKE_CWD || "";
 let timeoutMs = Number(process.env.AGENT_RELAY_SMOKE_TIMEOUT_MS || 90_000);
 let providers = (process.env.AGENT_RELAY_SMOKE_PROVIDERS || "codex,claude").split(",").filter(Boolean);
 
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i]!;
-  if (arg === "--relay-url" && args[i + 1]) relayUrl = args[++i]!;
-  else if (arg === "--orchestrator" && args[i + 1]) orchestratorId = args[++i]!;
-  else if (arg === "--cwd" && args[i + 1]) cwd = args[++i]!;
-  else if (arg === "--timeout" && args[i + 1]) timeoutMs = Number(args[++i]);
-  else if (arg === "--providers" && args[i + 1]) providers = args[++i]!.split(",").map((p) => p.trim()).filter(Boolean);
-  else throw new Error(`Unknown option: ${arg}`);
+function parseArgs(): void {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--relay-url" && args[i + 1]) relayUrl = args[++i]!;
+    else if (arg === "--orchestrator" && args[i + 1]) orchestratorId = args[++i]!;
+    else if (arg === "--cwd" && args[i + 1]) cwd = args[++i]!;
+    else if (arg === "--timeout" && args[i + 1]) timeoutMs = Number(args[++i]);
+    else if (arg === "--providers" && args[i + 1]) providers = args[++i]!.split(",").map((p) => p.trim()).filter(Boolean);
+    else throw new Error(`Unknown option: ${arg}`);
+  }
 }
 
 relayUrl = relayUrl.replace(/\/+$/, "");
@@ -92,6 +95,68 @@ function localRepoRoot(): string | null {
   return result.stdout.trim() || null;
 }
 
+function localRepoName(): string | null {
+  const result = spawnSync("git", ["config", "--get", "remote.origin.url"], {
+    cwd: process.cwd(),
+    encoding: "utf8",
+  });
+  if (result.status !== 0) return null;
+  const remote = result.stdout.trim();
+  if (!remote) return null;
+  const name = basename(remote.replace(/\.git$/, ""));
+  return name || null;
+}
+
+function pathContainedBy(path: string, parent: string): boolean {
+  const rel = relative(resolve(parent), resolve(path));
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function isGitRepo(path: string): boolean {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: path,
+    encoding: "utf8",
+  });
+  return result.status === 0;
+}
+
+export function resolveDefaultSpawnCwd(
+  orchestrator: Pick<Orchestrator, "id" | "baseDir">,
+  deps: {
+    hostname?: () => string;
+    localRepoRoot?: () => string | null;
+    localRepoName?: () => string | null;
+    isGitRepo?: (path: string) => boolean;
+  } = {},
+): string {
+  const host = deps.hostname ?? hostname;
+  if (orchestrator.id !== host()) {
+    throw new Error(`orchestrator ${orchestrator.id} is remote; pass --cwd or set AGENT_RELAY_SMOKE_CWD to a git repo on that host`);
+  }
+  if (!orchestrator.baseDir) {
+    throw new Error(`orchestrator ${orchestrator.id} did not report a baseDir; pass --cwd or set AGENT_RELAY_SMOKE_CWD`);
+  }
+
+  const gitRoot = (deps.localRepoRoot ?? localRepoRoot)();
+  if (gitRoot && pathContainedBy(gitRoot, orchestrator.baseDir)) return gitRoot;
+
+  const repoName = (deps.localRepoName ?? localRepoName)();
+  const gitCheck = deps.isGitRepo ?? isGitRepo;
+  const candidates = [
+    repoName ? join(orchestrator.baseDir, "oss", repoName) : "",
+    repoName ? join(orchestrator.baseDir, repoName) : "",
+    orchestrator.baseDir,
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    if (pathContainedBy(candidate, orchestrator.baseDir) && gitCheck(candidate)) return candidate;
+  }
+
+  throw new Error(
+    `could not resolve a git repo inside orchestrator ${orchestrator.id} base dir ${orchestrator.baseDir}; ` +
+    "pass --cwd or set AGENT_RELAY_SMOKE_CWD",
+  );
+}
+
 function findSpawnedAgent(agents: Agent[], provider: string, label: string, startedAt: number): Agent | null {
   return agents
     .filter((agent) => agent.ready && agent.status !== "offline")
@@ -127,6 +192,8 @@ function promptForCase(provider: string, approvalMode: ApprovalMode, label: stri
   };
 }
 
+async function main(): Promise<void> {
+parseArgs();
 const orchestrators = await api<Orchestrator[]>("GET", "/orchestrators");
 // Default selection prefers the orchestrator on the same host as the relay (the
 // gate runs there): a local spawn is faster and avoids cross-host teardown
@@ -146,13 +213,7 @@ if (orchestrator.status !== "online") throw new Error(`orchestrator ${orchestrat
 // An explicit --cwd / env override still wins (and is subject to the
 // orchestrator's containment check).
 if (!cwd) {
-  if (orchestrator.id !== hostname()) {
-    throw new Error(`orchestrator ${orchestrator.id} is remote; pass --cwd or set AGENT_RELAY_SMOKE_CWD to a git repo on that host`);
-  }
-  cwd = localRepoRoot() || "";
-  if (!cwd) {
-    throw new Error("could not resolve the local git repo root; pass --cwd or set AGENT_RELAY_SMOKE_CWD");
-  }
+  cwd = resolveDefaultSpawnCwd(orchestrator);
 }
 console.log(`using cwd ${cwd} on ${orchestrator.id} (base ${orchestrator.baseDir})`);
 
@@ -239,3 +300,8 @@ for (const provider of providers) {
 }
 
 console.log("spawn smoke passed");
+}
+
+if (import.meta.main) {
+  await main();
+}