agent-relay-runner 0.63.0 → 0.63.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.63.0",
+  "version": "0.63.2",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.41"
+    "agent-relay-sdk": "0.2.42"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/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.63.0",
+  "version": "0.63.2",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -1,6 +1,7 @@
 import type { AgentProfile, Message } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk";
 import type { SessionEvent } from "./session-insights";
+import { messageBodyMaxCharsFromEnv } from "./config";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
 type ProviderWorkKind = "provider-turn" | "subagent";
@@ -202,7 +203,7 @@ export const DEFAULT_PROVIDER_MESSAGE_BODY_MAX_CHARS = 24_000;
 // Resolve the delivered-body cap. Deployment-dependent (the right ceiling tracks the host's
 // context budget), so it's overridable via env — set on the orchestrator/host that spawns runners.
 export function providerMessageBodyMaxChars(): number {
-  const raw = process.env.AGENT_RELAY_MESSAGE_BODY_MAX_CHARS;
+  const raw = messageBodyMaxCharsFromEnv();
   if (raw !== undefined) {
     const parsed = Number.parseInt(raw.trim(), 10);
     if (Number.isFinite(parsed) && parsed > 0) return parsed;

package/src/adapters/claude-transcript.ts

@@ -202,6 +202,40 @@ export function extractFinalAssistantMessage(jsonl: string): string {
   return lastText.trim();
 }
 
+/**
+ * Like extractFinalAssistantMessage but skips the first `afterEntry` valid JSON
+ * entries. Used when a PreToolUse pre-flush already emitted the text before a
+ * blocking control, so final-mode Stop capture only sees later assistant text.
+ */
+export function extractFinalAssistantMessageAfterEntry(jsonl: string, afterEntry: number): string {
+  const lines = jsonl.split("\n");
+  let lastText = "";
+  let pastLastUserPrompt = afterEntry > 0;
+  let entryIndex = 0;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    entryIndex++;
+    if (isSidechainEntry(entry)) continue;
+    if (entryIndex <= afterEntry) continue;
+    if (isRealUserPrompt(entry)) {
+      pastLastUserPrompt = true;
+      lastText = "";
+      continue;
+    }
+    if (!pastLastUserPrompt) continue;
+    const text = assistantText(entry);
+    if (text) lastText = text;
+  }
+  return lastText.trim();
+}
+
 /**
  * Extract text from the `last_assistant_message` field in the Stop hook
  * payload. This is the content of the final assistant message — either a plain

package/src/attachment-cache.ts

@@ -4,6 +4,7 @@ import { basename, join } from "node:path";
 import type { Artifact, Message } from "agent-relay-sdk";
 import { errMessage, isRecord } from "agent-relay-sdk";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { attachmentCacheDirFromEnv } from "./config";
 
 const DEFAULT_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -34,11 +35,11 @@ function attachmentRefs(message: Message): Record<string, unknown>[] {
   return refs.filter(isRecord);
 }
 
-function attachmentCacheRoot(agentId: string, rootDir = process.env.AGENT_RELAY_ATTACHMENT_CACHE_DIR): string {
+function attachmentCacheRoot(agentId: string, rootDir = attachmentCacheDirFromEnv()): string {
   return join(attachmentCacheBase(rootDir), safePathPart(agentId));
 }
 
-function attachmentCacheBase(rootDir = process.env.AGENT_RELAY_ATTACHMENT_CACHE_DIR): string {
+function attachmentCacheBase(rootDir = attachmentCacheDirFromEnv()): string {
   return rootDir || join(homedir(), ".agent-relay", "attachments");
 }
 
@@ -147,7 +148,7 @@ function withCacheError(ref: Record<string, unknown>, error: unknown): Record<st
 
 export function pruneAttachmentCache(
   agentId: string,
-  rootDir = process.env.AGENT_RELAY_ATTACHMENT_CACHE_DIR,
+  rootDir = attachmentCacheDirFromEnv(),
   maxAgeMs = DEFAULT_CACHE_MAX_AGE_MS,
   now = Date.now(),
 ): void {

package/src/config.ts

@@ -1,11 +1,26 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { DEFAULT_RELAY_URL, RELAY_TOKEN_HEADER, errMessage, stringValue } from "agent-relay-sdk";
 import type { SettingEntry, WorkspaceMetadata } from "agent-relay-sdk";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
-import type { ProviderConfig } from "./adapter";
+
+interface ProviderConfig {
+  command: string;
+  defaultArgs: string[];
+  env: Record<string, string>;
+  pluginDirs: string[];
+  defaultCapabilities: string[];
+  defaultApprovalMode: string;
+  defaultTags: string[];
+  chatCaptureMode: "final" | "full";
+  reasoningCapture?: boolean;
+  headless: {
+    tmuxPrefix: string;
+    shutdownTimeoutMs: number;
+  };
+}
 
 interface GlobalRunnerConfig {
   relayUrl: string;
@@ -17,7 +32,7 @@ interface LoadedProviderConfig extends ProviderConfig {
   path: string;
 }
 
-function agentRelayHome(): string {
+export function agentRelayHome(): string {
   return process.env.AGENT_RELAY_HOME || join(homedir(), ".agent-relay");
 }
 
@@ -48,12 +63,135 @@ export function loadGlobalConfig(home = agentRelayHome()): GlobalRunnerConfig {
   const path = join(home, "config.json");
   const parsed = readJson(path);
   return {
-    relayUrl: stringValue(parsed.relayUrl) ?? process.env.AGENT_RELAY_URL ?? DEFAULT_RELAY_URL,
-    token: stringValue(parsed.token) ?? process.env.AGENT_RELAY_TOKEN,
+    relayUrl: stringValue(parsed.relayUrl) ?? relayUrlFromEnv() ?? DEFAULT_RELAY_URL,
+    token: stringValue(parsed.token) ?? relayTokenFromEnv(),
     defaultCwd: stringValue(parsed.defaultCwd) ?? process.cwd(),
   };
 }
 
+function relayUrlFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_URL;
+}
+
+export function relayTokenFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN;
+}
+
+export function runtimeTokenProfileFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN_PROFILE;
+}
+
+export function runtimeTokenJtiFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN_JTI;
+}
+
+export function runtimeTokenExpiresAtFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN_EXPIRES_AT;
+}
+
+export function agentProfileNameFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_AGENT_PROFILE;
+}
+
+export function agentProfileJsonFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_AGENT_PROFILE_JSON;
+}
+
+export function workspaceJsonFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_WORKSPACE_JSON;
+}
+
+export function tmuxSessionFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TMUX_SESSION;
+}
+
+export function policyNameFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_POLICY;
+}
+
+export function spawnRequestIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_SPAWN_REQUEST_ID;
+}
+
+export function automationIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_AUTOMATION_ID;
+}
+
+export function automationRunIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_AUTOMATION_RUN_ID;
+}
+
+export function lifecycleFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_LIFECYCLE;
+}
+
+export function sessionDebugEnabled(): boolean {
+  return process.env.AGENT_RELAY_SESSION_DEBUG === "1";
+}
+
+export function logLevelFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_LOG_LEVEL;
+}
+
+export function mcpProxyEnabledFromEnv(): boolean {
+  return !["0", "false", "off"].includes((process.env.AGENT_RELAY_MCP_PROXY ?? "").trim().toLowerCase());
+}
+
+export function runnerInfoFileFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_RUNNER_INFO_FILE;
+}
+
+export function runnerOutboxDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_RUNNER_OUTBOX_DIR;
+}
+
+export function runnerOutboxDirWithInfoFallback(): string | undefined {
+  const dir = runnerOutboxDirFromEnv();
+  if (dir) return dir;
+  const infoFile = runnerInfoFileFromEnv();
+  return infoFile ? join(dirname(infoFile), "outbox") : undefined;
+}
+
+export function capsFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CAPS;
+}
+
+export function tagsFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TAGS;
+}
+
+export function workspaceModeFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_WORKSPACE_MODE;
+}
+
+export function orchestratorBaseDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR;
+}
+
+export function runnerLogFileFromEnv(): string | undefined {
+  return typeof process.env.AGENT_RELAY_LOG_FILE === "string" ? process.env.AGENT_RELAY_LOG_FILE : undefined;
+}
+
+export function orchestratorUrlFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_ORCHESTRATOR_URL;
+}
+
+export function contextStateDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CONTEXT_STATE_DIR;
+}
+
+export function attachmentCacheDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_ATTACHMENT_CACHE_DIR;
+}
+
+export function providerHomeRootFromEnv(): string {
+  return process.env.AGENT_RELAY_PROVIDER_HOME_ROOT || join(homedir(), ".agent-relay", "provider-homes");
+}
+
+export function messageBodyMaxCharsFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_MESSAGE_BODY_MAX_CHARS;
+}
+
 export function loadProviderConfig(provider: string, home = agentRelayHome()): LoadedProviderConfig {
   const path = join(providersDir(home), `${provider}.json`);
   const raw = readJson(path);

package/src/index.ts

@@ -3,7 +3,24 @@ import { hostname } from "node:os";
 import { basename } from "node:path";
 import { isatty } from "node:tty";
 import { AgentRunner } from "./runner";
-import { loadGlobalConfig, loadProviderConfigFromRelay, resolveCwd, runnerId } from "./config";
+import {
+  agentProfileJsonFromEnv,
+  agentProfileNameFromEnv,
+  automationIdFromEnv,
+  automationRunIdFromEnv,
+  lifecycleFromEnv,
+  loadGlobalConfig,
+  loadProviderConfigFromRelay,
+  policyNameFromEnv,
+  resolveCwd,
+  runnerId,
+  runtimeTokenExpiresAtFromEnv,
+  runtimeTokenJtiFromEnv,
+  runtimeTokenProfileFromEnv,
+  spawnRequestIdFromEnv,
+  tmuxSessionFromEnv,
+  workspaceJsonFromEnv,
+} from "./config";
 import { createProviderAdapter } from "./providers";
 import { VERSION } from "./version";
 import type { AgentProfile, SpawnProvider, WorkspaceMetadata } from "agent-relay-sdk";
@@ -49,9 +66,9 @@ export async function main(argv = process.argv): Promise<void> {
     interactive: opts.interactive,
     relayUrl,
     token: opts.token ?? globalConfig.token,
-    runtimeTokenProfile: process.env.AGENT_RELAY_TOKEN_PROFILE,
-    runtimeTokenJti: process.env.AGENT_RELAY_TOKEN_JTI,
-    runtimeTokenExpiresAt: parseTokenExpiresAt(process.env.AGENT_RELAY_TOKEN_EXPIRES_AT),
+    runtimeTokenProfile: runtimeTokenProfileFromEnv(),
+    runtimeTokenJti: runtimeTokenJtiFromEnv(),
+    runtimeTokenExpiresAt: parseTokenExpiresAt(runtimeTokenExpiresAtFromEnv()),
     provider: opts.provider,
     cwd,
     runnerId: id,
@@ -84,20 +101,20 @@ export async function main(argv = process.argv): Promise<void> {
     approvalMode,
     label: opts.label,
     rig: opts.rig,
-    profile: opts.profile ?? process.env.AGENT_RELAY_AGENT_PROFILE,
-    agentProfile: parseAgentProfileEnv(process.env.AGENT_RELAY_AGENT_PROFILE_JSON),
-    workspace: parseWorkspaceEnv(process.env.AGENT_RELAY_WORKSPACE_JSON),
+    profile: opts.profile ?? agentProfileNameFromEnv(),
+    agentProfile: parseAgentProfileEnv(agentProfileJsonFromEnv()),
+    workspace: parseWorkspaceEnv(workspaceJsonFromEnv()),
     prompt: opts.prompt,
     systemPromptAppend: opts.systemPromptAppend,
-    tmuxSession: process.env.AGENT_RELAY_TMUX_SESSION,
+    tmuxSession: tmuxSessionFromEnv(),
     tags: opts.tags,
     capabilities: opts.caps,
     providerArgs: opts.providerArgs,
-    policyName: process.env.AGENT_RELAY_POLICY,
-    spawnRequestId: process.env.AGENT_RELAY_SPAWN_REQUEST_ID,
-    automationId: process.env.AGENT_RELAY_AUTOMATION_ID,
-    automationRunId: process.env.AGENT_RELAY_AUTOMATION_RUN_ID,
-    lifecycle: normalizeAgentLifecycle(process.env.AGENT_RELAY_LIFECYCLE) ?? "persistent",
+    policyName: policyNameFromEnv(),
+    spawnRequestId: spawnRequestIdFromEnv(),
+    automationId: automationIdFromEnv(),
+    automationRunId: automationRunIdFromEnv(),
+    lifecycle: normalizeAgentLifecycle(lifecycleFromEnv()) ?? "persistent",
     startedAt: Date.now(),
     providerConfig,
     adapter,

package/src/logger.ts

@@ -1,6 +1,7 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { logLevelFromEnv } from "./config";
 
 // Phase 1 observability (#198): one leveled, runtime-togglable logger for the
 // Runner and the provider adapters below it. Replaces the ad-hoc scatter of
@@ -47,7 +48,7 @@ export class Logger {
   private logDir: string;
 
   constructor(config: LoggerConfig = {}) {
-    this.level = config.level ?? parseLogLevel(process.env.AGENT_RELAY_LOG_LEVEL) ?? "info";
+    this.level = config.level ?? parseLogLevel(logLevelFromEnv()) ?? "info";
     this.agentId = config.agentId ?? "runner";
     this.headless = config.headless ?? false;
     this.logDir = config.logDir ?? join(process.env.HOME || ".", ".agent-relay", "logs");

package/src/outbox.ts

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { errMessage } from "agent-relay-sdk";
 import { logger } from "./logger";
+import { runnerOutboxDirFromEnv } from "./config";
 
 // Phase 2 (#196) — the "nothing is ever lost" half. Runner→server events that used to be
 // fire-and-forget over HTTP (session turns, reasoning/tool traces, prompt echoes, insights,
@@ -112,7 +113,7 @@ export class Outbox {
     this.maxBackoffMs = options.maxBackoffMs ?? DEFAULTS.maxBackoffMs;
     this.pollMs = options.pollMs ?? DEFAULTS.pollMs;
 
-    const dir = options.dir ?? process.env.AGENT_RELAY_RUNNER_OUTBOX_DIR ?? join(tmpdir(), "agent-relay-outbox");
+    const dir = options.dir ?? runnerOutboxDirFromEnv() ?? join(tmpdir(), "agent-relay-outbox");
     this.path = options.dir === ":memory:" ? ":memory:" : join(dir, `outbox-${safeName(this.agentId)}.sqlite`);
     if (this.path !== ":memory:") mkdirSync(dirname(this.path), { recursive: true });
 

package/src/profile-home.ts

@@ -4,6 +4,7 @@ import { join, resolve } from "node:path";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
 import { CLAUDE_RELAY_MANUAL } from "./relay-instructions";
+import { providerHomeRootFromEnv } from "./config";
 
 type ProviderHome = {
   path: string;
@@ -105,7 +106,7 @@ function readHostClaudeConfig(): Record<string, unknown> | undefined {
 }
 
 function providerHomePath(provider: "claude" | "codex", config: RunnerSpawnConfig): string {
-  const root = process.env.AGENT_RELAY_PROVIDER_HOME_ROOT || join(homedir(), ".agent-relay", "provider-homes");
+  const root = providerHomeRootFromEnv();
   const profileName = sanitizePathPart(config.agentProfile?.name || config.profile || "profile");
   const instance = sanitizePathPart(config.instanceId || config.runnerId);
   return join(root, provider, profileName, instance);

package/src/runner-core.ts

@@ -12,7 +12,7 @@ import { ClaimTracker } from "./claim-tracker";
 import { startControlServer, type ControlServer } from "./control-server";
 import { ReplyObligationCache, obligationRequiresExplicitReply } from "./reply-obligation-cache";
 import { Outbox, type OutboxRecord } from "./outbox";
-import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, countTranscriptEntries, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
+import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, countTranscriptEntries, extractFinalAssistantMessage, extractFinalAssistantMessageAfterEntry, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
 import { profileUsesHostProviderGlobals } from "./profile-home";
 import { RELAY_MCP_TOKEN_ENV, relayMcpEndpoint } from "./relay-mcp";
 import { RelayMcpProxy } from "./relay-mcp-proxy";
@@ -22,6 +22,7 @@ import { ensureSessionScratch, reapSessionScratch, sweepStaleSessions, type Sess
 import { deliverBufferedMcpCall as deliverBufferedMcpOutboxCall, deliverRunnerOutboxEvent } from "./mcp-outbox";
 import { RunnerInsights } from "./runner-insights";
 import { BusyReconciler } from "./busy-reconciler";
+import { capsFromEnv, contextStateDirFromEnv, logLevelFromEnv, mcpProxyEnabledFromEnv, orchestratorBaseDirFromEnv, orchestratorUrlFromEnv, runnerInfoFileFromEnv, runnerLogFileFromEnv, runnerOutboxDirWithInfoFallback, sessionDebugEnabled, tagsFromEnv, workspaceModeFromEnv } from "./config";
 import {
   appliedAgentProfileMetadata,
   commandTimeoutMs,
@@ -272,7 +273,7 @@ export class AgentRunner {
   private injectedPrompts: Array<{ text: string; at: number }> = [];
   // Verbose session-mirror diagnostics (turn lifecycle, reconciler probes, tail
   // emits) → a dedicated clean log. Always on for key transitions; AGENT_RELAY_SESSION_DEBUG=1 adds the high-frequency probe/emit lines.
-  private readonly sessionDebugVerbose = process.env.AGENT_RELAY_SESSION_DEBUG === "1";
+  private readonly sessionDebugVerbose = sessionDebugEnabled();
   // Tracks whether the provider is in a legitimate blocked/approval state, so the
   // busy reconciler doesn't mistake a permission prompt for a stuck-busy turn.
   private providerBlocked = false;
@@ -299,21 +300,20 @@ export class AgentRunner {
     logger.configure({
       agentId: this.agentId,
       headless: options.headless,
-      ...(this.sessionDebugVerbose && !parseLogLevel(process.env.AGENT_RELAY_LOG_LEVEL) ? { level: "debug" as const } : {}),
+      ...(this.sessionDebugVerbose && !parseLogLevel(logLevelFromEnv()) ? { level: "debug" as const } : {}),
     });
     this.currentToken = options.token;
     this.currentTokenJti = options.tokenJti;
     this.currentTokenProfileId = options.tokenProfileId;
     this.currentTokenExpiresAt = options.tokenExpiresAt;
-    this.mcpProxyEnabled = !["0", "false", "off"].includes((process.env.AGENT_RELAY_MCP_PROXY ?? "").trim().toLowerCase());
+    this.mcpProxyEnabled = mcpProxyEnabledFromEnv();
     this.mcpProxySecret = crypto.randomUUID();
     const runtime = runtimeMetadata(options.provider);
     this.http = new RelayHttpClient({ baseUrl: options.relayUrl, token: this.currentToken });
     this.obligationCache = new ReplyObligationCache({ fetch: () => this.http.listReplyObligations(this.agentId) });
     // Co-locate the durable outbox with the runner's runtime state (survives reboot) when the
     // orchestrator told us where that is; otherwise the Outbox falls back to a temp dir.
-    const outboxDir = process.env.AGENT_RELAY_RUNNER_OUTBOX_DIR
-      ?? (process.env.AGENT_RELAY_RUNNER_INFO_FILE ? join(dirname(process.env.AGENT_RELAY_RUNNER_INFO_FILE), "outbox") : undefined);
+    const outboxDir = runnerOutboxDirWithInfoFallback();
     this.outbox = new Outbox({ agentId: this.agentId, dir: outboxDir, send: (record) => this.deliverOutboxEvent(record) });
     this.sessionOutbox = new Outbox({
       agentId: `${this.agentId}-session`,
@@ -359,7 +359,7 @@ export class AgentRunner {
         ...new Set([
           ...options.providerConfig.defaultCapabilities,
           ...options.capabilities,
-          ...csvTags(process.env.AGENT_RELAY_CAPS),
+          ...csvTags(capsFromEnv()),
           "lifecycle.shutdown.hard",
           "lifecycle.restart.hard",
           "lifecycle.status.semantic",
@@ -369,7 +369,7 @@ export class AgentRunner {
           "capabilities.report",
         ]),
       ],
-      tags: [...new Set([options.provider, ...csvTags(process.env.AGENT_RELAY_TAGS), ...options.tags, ...options.providerConfig.defaultTags, ...(options.headless ? ["headless"] : [])])],
+      tags: [...new Set([options.provider, ...csvTags(tagsFromEnv()), ...options.tags, ...options.providerConfig.defaultTags, ...(options.headless ? ["headless"] : [])])],
       meta: {
         ...runtime,
         version: runtime.package.version,
@@ -388,7 +388,7 @@ export class AgentRunner {
         automationRunId: options.automationRunId ?? null,
         workspace: options.workspace ?? null,
         lifecycle: options.lifecycle ?? "persistent",
-        workspaceMode: options.workspace?.requestedMode ?? options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE ?? null,
+        workspaceMode: options.workspace?.requestedMode ?? options.workspace?.mode ?? workspaceModeFromEnv() ?? null,
         runnerManaged: true,
         cwd: options.cwd,
         approvalMode: options.approvalMode,
@@ -471,7 +471,7 @@ export class AgentRunner {
     reapSessionScratch({
       agentId: this.agentId,
       cwd: this.options.cwd,
-      fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
+      fallbackBaseDir: orchestratorBaseDirFromEnv(),
     });
     if (!alreadyStopped) await this.bus.statusAsync({ agentStatus: "offline", ready: false });
     if (this.process && !alreadyStopped) {
@@ -528,7 +528,7 @@ export class AgentRunner {
   }
 
   private ownsIsolatedWorktree(): boolean {
-    const mode = this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE;
+    const mode = this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? workspaceModeFromEnv();
     return mode === "isolated";
   }
 
@@ -607,7 +607,7 @@ export class AgentRunner {
   }
 
   private writeRunnerInfoFile(): void {
-    const file = process.env.AGENT_RELAY_RUNNER_INFO_FILE;
+    const file = runnerInfoFileFromEnv();
     if (!file || !this.control) return;
     try {
       mkdirSync(dirname(file), { recursive: true });
@@ -1101,7 +1101,7 @@ export class AgentRunner {
     const tmuxSession = typeof this.process?.meta?.tmuxSession === "string" ? this.process.meta.tmuxSession : undefined;
     const tmuxSocket = typeof this.process?.meta?.tmuxSocket === "string" ? this.process.meta.tmuxSocket : undefined;
     const exitSource = tmuxSession ? "tmux-session-ended" : this.process?.process ? "process-exit" : "provider-status";
-    const logFile = typeof process.env.AGENT_RELAY_LOG_FILE === "string" ? process.env.AGENT_RELAY_LOG_FILE : undefined;
+    const logFile = runnerLogFileFromEnv();
     const claudeResumeId = this.options.provider === "claude" && logFile ? latestClaudeResumeIdFromLogFile(logFile) : undefined;
     return {
       status,
@@ -1306,10 +1306,9 @@ 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) — mid-turn call from a PreToolUse hook (AskUserQuestion /
-  // ExitPlanMode / permission). Emits any un-mirrored narrative from the transcript
-  // tail immediately, before the interactive form appears in chat, then updates the
-  // entry-count cursor so the eventual Stop-hook call (full mode) skips it.
+  // 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; isPreFlush?: boolean }): Promise<void> {
     if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
 
@@ -1321,15 +1320,12 @@ export class AgentRunner {
       const body = extractLastAssistantTurnAfterEntry(jsonl, this.narrativeFlushEntryCount);
       await this.drainReasoningTail();
       this.narrativeFlushEntryCount = countTranscriptEntries(jsonl);
-      if (!body || this.preFlushBodyAlreadyMirroredByReasoningTail(jsonl, body)) return;
-      const turnId = this.currentTurnId;
-      this.sessionLog(`pre-flush narrative for turn ${turnId ?? "?"} (${body.length} chars)`);
-      await this.publishSessionEvent({
-        from: this.agentId,
-        to: "user",
-        body,
-        session: { type: "response", origin: "provider", ...(turnId ? { turnId } : {}) },
-      });
+      if (body && !this.preFlushBodyAlreadyMirroredByReasoningTail(jsonl, body)) {
+        const turnId = this.currentTurnId;
+        this.sessionLog(`pre-flush narrative for turn ${turnId ?? "?"} (${body.length} chars)`);
+        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;
     }
 
@@ -1368,11 +1364,10 @@ export class AgentRunner {
           try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { break; }
         }
         if (!transcriptLooksComplete(jsonl)) continue;
-        // Full mode: if a pre-flush already emitted entries 1..flushCount, only
-        // collect text from entries after that mark to avoid double-emit (#435).
+        // If a pre-flush already emitted entries 1..flushCount, resume after that mark to avoid double-emit (#435/#499).
         const extract = this.options.providerConfig.chatCaptureMode === "full"
           ? (j: string) => (flushCount > 0 ? extractLastAssistantTurnAfterEntry(j, flushCount) : extractLastAssistantTurn(j))
-          : extractFinalAssistantMessage;
+          : (j: string) => (flushCount > 0 ? extractFinalAssistantMessageAfterEntry(j, flushCount) : extractFinalAssistantMessage(j));
         body = extract(jsonl);
         if (body) break;
       }
@@ -1820,7 +1815,7 @@ export class AgentRunner {
         automationId: this.options.automationId ?? null,
         automationRunId: this.options.automationRunId ?? null,
         workspace: this.options.workspace ?? null,
-        lifecycle: this.options.lifecycle ?? "persistent", workspaceMode: this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE ?? null,
+        lifecycle: this.options.lifecycle ?? "persistent", workspaceMode: this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? workspaceModeFromEnv() ?? null,
         lifecycleAction: this.lifecycleAction ?? null,
         profile: this.options.profile ?? null,
         ...(status === "error" ? { terminalStatus: "error" } : {}),
@@ -1938,7 +1933,7 @@ export class AgentRunner {
       this.scratch = ensureSessionScratch({
         agentId: this.agentId,
         cwd: this.options.cwd,
-        fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
+        fallbackBaseDir: orchestratorBaseDirFromEnv(),
       });
     } catch (error) {
       this.logRunnerDiagnostic(`session scratch setup failed: ${errMessage(error)}`);
@@ -1952,7 +1947,7 @@ export class AgentRunner {
       keep.add(this.agentId);
       const removed = sweepStaleSessions({
         cwd: this.options.cwd,
-        fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
+        fallbackBaseDir: orchestratorBaseDirFromEnv(),
         keepAgentIds: keep,
         now: Date.now(),
       });
@@ -2004,7 +1999,7 @@ export class AgentRunner {
   // is already expired — the orchestrator's standing credential is the authority.
   private canRemintViaOrchestrator(): boolean {
     return Boolean(
-      process.env.AGENT_RELAY_ORCHESTRATOR_URL &&
+      orchestratorUrlFromEnv() &&
       this.currentToken &&
       (this.currentTokenProfileId === "provider-agent" || this.currentTokenProfileId === "provider-interactive"),
     );
@@ -2079,7 +2074,7 @@ export class AgentRunner {
   // (possibly expired) token; the orchestrator re-mints it via the relay using its
   // standing credential. Returns true on success.
   private async remintViaOrchestrator(): Promise<boolean> {
-    const orchUrl = process.env.AGENT_RELAY_ORCHESTRATOR_URL;
+    const orchUrl = orchestratorUrlFromEnv();
     if (!orchUrl || !this.currentToken) return false;
     try {
       const res = await fetch(`${orchUrl.replace(/\/+$/, "")}/api/runtime-tokens/runner-renew`, {
@@ -2153,7 +2148,7 @@ export class AgentRunner {
   }
 
   private latestProbeMetrics() {
-    const stateDir = process.env.AGENT_RELAY_CONTEXT_STATE_DIR;
+    const stateDir = contextStateDirFromEnv();
     return readContextProbeState(this.agentId, stateDir);
   }