agent-relay-runner 0.10.21 → 0.10.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.10.21",
+  "version": "0.10.22",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

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.10.21",
+  "version": "0.10.22",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/hooks/relay-status.sh

@@ -35,6 +35,20 @@ relay_post_timeline_status() {
   relay_post_status "$1" "${2:-provider-turn}" "" "" "" "" "${3:-}" "$4"
 }
 
+relay_post_session_turn() {
+  # Phase 1 live-session lane: hand the transcript path to the runner so it can
+  # capture the assistant turn for the dashboard chat. Synchronous on purpose —
+  # the captured turn clears the reply obligation before the stop decision check
+  # below, so the agent is not nagged to /reply (and does not re-emit).
+  local transcript_path="${1:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  [ -z "$transcript_path" ] && return 0
+  curl -fsS -X POST "http://127.0.0.1:${port}/session-turn" \
+    -H 'Content-Type: application/json' \
+    -d "{\"transcriptPath\":\"$(relay_json_escape "$transcript_path")\"}" >/dev/null 2>&1 || true
+}
+
 relay_pending_reply_stop_decision() {
   local port="${AGENT_RELAY_RUNNER_PORT:-}"
   [ -z "$port" ] && return 0

package/plugins/claude/hooks/stop.sh

@@ -5,6 +5,7 @@ source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/
 payload="$(cat || true)"
 stop_hook_active="$(relay_json_bool_field stop_hook_active "$payload")"
 if [ "$stop_hook_active" != "true" ]; then
+  relay_post_session_turn "$(relay_json_string_field transcript_path "$payload")"
   stop_decision="$(relay_pending_reply_stop_decision)"
   if [ -n "$stop_decision" ]; then
     printf '%s\n' "$stop_decision"

package/plugins/claude/skills/reply/SKILL.md

@@ -20,10 +20,12 @@ Examples:
 ```bash
 agent-relay /reply 206 "Sounds good, I'll take a look"
 agent-relay /reply 42 "Done — the fix is in commit abc123"
-agent-relay /reply 42 --stdin < response.md
+agent-relay /reply 42 --stdin < .agent-relay/sessions/$AGENT_RELAY_ID/tmp/reply.md
 agent-relay /reply 42 --body-file response.md
 ```
 
 Use `--stdin` or `--body-file` for long replies so shell quoting does not mangle the body. Oversized replies are automatically uploaded as an Agent Relay artifact and sent as an attached concise reply.
 
+The relay creates this per-session scratch dir for you (it is git-ignored locally), so staging there never pollutes the working tree and never collides with other agents. No cleanup needed — the dir is reaped when your session ends.
+
 Do not send a separate Relay follow-up that only confirms the reply was sent. The CLI output is enough local confirmation.

package/plugins/codex/skills/reply/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: reply
-description: Reply to an Agent Relay message by ID. Auto-routes to the sender and inherits channel context, so no target is needed. Use when the user invokes /reply or asks to reply to a specific relay message, especially with stdin/file for long replies.
+description: Reply to an Agent Relay message by ID. Auto-routes to the sender and inherits channel context — no target needed. Use when the user invokes /reply or asks to reply to a specific relay message, especially with stdin/file for long replies.
 argument-hint: "<messageId> <message|--stdin|--body-file PATH>"
+allowed-tools: [Bash]
 ---
 
 # Agent Relay Reply
@@ -12,17 +13,19 @@ Run:
 agent-relay /reply $ARGUMENTS
 ```
 
-The server auto-routes the reply to the original sender and inherits the channel if applicable. No target or channel ID is needed.
+The server auto-routes the reply to the original sender and inherits the channel (Telegram, Slack, etc.) if applicable. No target or channel ID needed.
 
 Examples:
 
 ```bash
 agent-relay /reply 206 "Sounds good, I'll take a look"
-agent-relay /reply 42 "Done; the fix is in commit abc123"
-agent-relay /reply 42 --stdin < response.md
+agent-relay /reply 42 "Done — the fix is in commit abc123"
+agent-relay /reply 42 --stdin < .agent-relay/sessions/$AGENT_RELAY_ID/tmp/reply.md
 agent-relay /reply 42 --body-file response.md
 ```
 
 Use `--stdin` or `--body-file` for long replies so shell quoting does not mangle the body. Oversized replies are automatically uploaded as an Agent Relay artifact and sent as an attached concise reply.
 
-Report the sent message id and resolved target briefly.
+The relay creates this per-session scratch dir for you (it is git-ignored locally), so staging there never pollutes the working tree and never collides with other agents. No cleanup needed — the dir is reaped when your session ends.
+
+Do not send a separate Relay follow-up that only confirms the reply was sent. The CLI output is enough local confirmation.

package/src/adapters/claude-delivery.ts

@@ -7,6 +7,27 @@ const REMINDER_EVERY_DELIVERIES = 5;
 interface ClaudeDeliveryTextOptions {
   deliveryCount: number;
   readOnly?: boolean;
+  // false = isolated profile with no relay plugin/CLI surface. The agent cannot /reply or
+  // /claim, so strip the reply-reminder block and the server-baked claim-task instruction —
+  // it's just confusing noise in a clean-room run. Defaults to true (relay-aware agents).
+  relaySurface?: boolean;
+}
+
+// Server-baked trailing line from taskMessageBody() in src/db.ts. Meaningless to an isolated
+// agent (sole claimant, no relay CLI), so drop it from delivered text when there's no surface.
+const TASK_CLAIM_INSTRUCTION = "Claim this task before working it, then update task status when finished.";
+
+function stripRelayScaffolding(body: string): string {
+  const lines = body.split("\n");
+  const popTrailingBlanks = () => {
+    while (lines.length && (lines.at(-1) ?? "").trim() === "") lines.pop();
+  };
+  popTrailingBlanks();
+  if (lines.at(-1) === TASK_CLAIM_INSTRUCTION) {
+    lines.pop();
+    popTrailingBlanks();
+  }
+  return lines.join("\n");
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -47,23 +68,24 @@ function latestReplyableMessage(messages: Message[]): Message | undefined {
     .at(-1);
 }
 
-function formatMessage(message: Message): string {
+function formatMessage(message: Message, relaySurface: boolean): string {
   const subject = message.subject ? `Subject: ${message.subject}\n` : "";
   const isMemoryContext = isMemoryInjection(message);
   const canFetchMessage = isPersistedRelayMessage(message);
-  const shouldPreview = canFetchMessage && message.body.length > PROVIDER_MESSAGE_BODY_PREVIEW_CHARS;
+  const rawBody = relaySurface ? message.body : stripRelayScaffolding(message.body);
+  const shouldPreview = canFetchMessage && rawBody.length > PROVIDER_MESSAGE_BODY_PREVIEW_CHARS;
   const preview = shouldPreview
     ? {
-      body: message.body.slice(0, PROVIDER_MESSAGE_BODY_PREVIEW_CHARS),
+      body: rawBody.slice(0, PROVIDER_MESSAGE_BODY_PREVIEW_CHARS),
       truncated: true,
     }
     : {
-      body: message.body,
+      body: rawBody,
       truncated: false,
     };
   const truncationGuidance = preview.truncated
     ? [
-      `[truncated: showing first ${PROVIDER_MESSAGE_BODY_PREVIEW_CHARS} of ${message.body.length} chars]`,
+      `[truncated: showing first ${PROVIDER_MESSAGE_BODY_PREVIEW_CHARS} of ${rawBody.length} chars]`,
       `Read full: agent-relay get-message ${message.id}`,
       `Body only: agent-relay get-message ${message.id} --body`,
     ].join("\n")
@@ -99,9 +121,11 @@ function replyReminder(message: Message, readOnly: boolean): string {
 }
 
 export function claudeProviderMessageText(messages: Message[], options: ClaudeDeliveryTextOptions): string {
-  const sections = messages.map(formatMessage);
+  const relaySurface = options.relaySurface !== false;
+  const sections = messages.map((message) => formatMessage(message, relaySurface));
   const replyable = latestReplyableMessage(messages);
-  if (replyable && shouldShowReplyReminder(options.deliveryCount)) {
+  // Isolated agents have no way to reply through Relay — never append the reminder.
+  if (relaySurface && replyable && shouldShowReplyReminder(options.deliveryCount)) {
     sections.push(replyReminder(replyable, options.readOnly === true));
   }
   return sections.join("\n\n");

package/src/adapters/claude-transcript.ts

@@ -0,0 +1,76 @@
+// Phase 1 live-session lane: extract the user-visible assistant turn from a
+// Claude Code transcript JSONL so it can be surfaced in the dashboard chat
+// without the agent re-emitting it via /reply (zero agent tokens).
+//
+// Transcript shape (one JSON object per line):
+//   { type: "user", message: { content: "..." | [{type:"text"|"tool_result", ...}] } }
+//   { type: "assistant", message: { content: [{type:"thinking"|"text"|"tool_use", ...}], stop_reason } }
+//
+// The "current turn" is everything after the last *real* user prompt (a user
+// entry carrying text, not just tool_result blocks). We collect the assistant
+// `text` blocks from that turn — thinking and tool_use are dropped.
+
+interface TranscriptBlock {
+  type?: string;
+  text?: string;
+}
+
+interface TranscriptMessage {
+  role?: string;
+  content?: string | TranscriptBlock[];
+  stop_reason?: string;
+}
+
+interface TranscriptEntry {
+  type?: string;
+  message?: TranscriptMessage;
+}
+
+function blocks(message: TranscriptMessage | undefined): TranscriptBlock[] {
+  if (!message || !Array.isArray(message.content)) return [];
+  return message.content.filter((b): b is TranscriptBlock => Boolean(b) && typeof b === "object");
+}
+
+function isRealUserPrompt(entry: TranscriptEntry): boolean {
+  if (entry.type !== "user") return false;
+  const content = entry.message?.content;
+  if (typeof content === "string") return content.trim().length > 0;
+  // An array user entry is a real prompt only if it carries a text block;
+  // pure tool_result entries are mid-turn plumbing, not a new prompt.
+  return blocks(entry.message).some((b) => b.type === "text" && Boolean(b.text?.trim()));
+}
+
+function assistantText(entry: TranscriptEntry): string {
+  if (entry.type !== "assistant") return "";
+  return blocks(entry.message)
+    .filter((b) => b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text!.trim())
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+/**
+ * Returns the concatenated assistant `text` for the most recent turn (since the
+ * last real user prompt), or "" if there is nothing user-visible to surface.
+ */
+export function extractLastAssistantTurn(jsonl: string): string {
+  const lines = jsonl.split("\n");
+  let collected: string[] = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (isRealUserPrompt(entry)) {
+      collected = [];
+      continue;
+    }
+    const text = assistantText(entry);
+    if (text) collected.push(text);
+  }
+  return collected.join("\n\n").trim();
+}

package/src/adapters/claude.ts

@@ -1,9 +1,10 @@
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import type { Message } from "agent-relay-sdk";
 import { profileAllowsRelayFeature, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
 import { prepareClaudeProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
+import { claudeProviderMessageText } from "./claude-delivery";
 
 export class ClaudeAdapter implements ProviderAdapter {
   readonly provider = "claude";
@@ -58,10 +59,35 @@ export class ClaudeAdapter implements ProviderAdapter {
     return { method: "tmux-inject", command: "/clear" };
   }
 
-  async deliver(_process: ManagedProcess, messages: Message[]): Promise<void> {
-    const monitor = _process.meta?.monitor as { deliver?(messages: Message[]): Promise<number[]> } | undefined;
-    if (!monitor?.deliver) throw new Error("Claude monitor delivery is unavailable");
-    await monitor.deliver(messages);
+  async deliver(process: ManagedProcess, messages: Message[]): Promise<void> {
+    const monitor = process.meta?.monitor as { deliver?(messages: Message[]): Promise<number[]> } | undefined;
+    // A monitor object always exists for headless claude (it proxies to the runner
+    // control server), so its presence says nothing about whether a monitor process
+    // is actually connected. `monitorless` is set at spawn when the profile disables
+    // the relay plugin — then no monitor will ever connect, so we must not route
+    // through it (it would throw "no Claude monitor connected" forever); we inject via
+    // tmux instead. For monitored profiles we keep the monitor path (and its retry on
+    // transient startup races) to avoid double-delivering against a late monitor.
+    const monitorless = process.meta?.monitorless === true;
+    if (!monitorless && monitor?.deliver) {
+      await monitor.deliver(messages);
+      return;
+    }
+    // Inject straight into the interactive tmux session via send-keys — the same
+    // transport deliverInitialPrompt uses. Keeps the agent on interactive Claude (the
+    // user's Max quota), never `claude -p`/API, and lets isolated automation agents
+    // receive their task (a claimable message) and any mid-session messages (e.g. the
+    // budget "wrap up" warning) that a launch --prompt can't carry.
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    if (!session || !tmuxHasSession(session, socket)) {
+      throw new Error("Claude monitor delivery is unavailable and no tmux session for fallback");
+    }
+    await waitForClaudeInputReady(session, CLAUDE_TMUX_READY_TIMEOUT_MS, socket);
+    // Monitorless = isolated profile with no relay plugin/CLI surface. Strip relay
+    // interaction scaffolding (reply reminder, claim-task instruction) — the agent has
+    // no way to /reply or /claim, so it's just confusing noise in a clean-room run.
+    await submitTextToTmux(session, claudeProviderMessageText(messages, { deliveryCount: 1, relaySurface: !monitorless }), socket);
   }
 
   async deliverInitialPrompt(process: ManagedProcess, prompt: string): Promise<void> {
@@ -78,9 +104,13 @@ export class ClaudeAdapter implements ProviderAdapter {
     const defaultArgs = profileUsesHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
     const pluginDirs = profileAllowsRelayFeature(config, "plugins") ? [...new Set([pluginRoot, ...providerConfig.pluginDirs])] : [];
     const isClaudeRig = /claude-rig/.test(providerConfig.command);
-    const bypassRigDefaults = config.headless && isClaudeRig && config.approvalMode !== "open";
-    const rigPrefix = isClaudeRig && !bypassRigDefaults && config.rig ? ["launch", config.rig] : [];
-    const command = bypassRigDefaults || (isClaudeRig && !config.rig && !findClaudeRigRC(config.cwd))
+    // Isolated profiles run their own CLAUDE_CONFIG_DIR and must never route through
+    // claude-rig — claude-rig resolves host rig config (and a bare `claude-rig` with no
+    // rig key just errors out). Only host-base profiles may use claude-rig.
+    const usesClaudeRig = isClaudeRig && profileUsesHostProviderGlobals(config);
+    const bypassRigDefaults = config.headless && usesClaudeRig && config.approvalMode !== "open";
+    const rigPrefix = usesClaudeRig && !bypassRigDefaults && config.rig ? ["launch", config.rig] : [];
+    const command = !usesClaudeRig || bypassRigDefaults || (!config.rig && !findClaudeRigRC(config.cwd))
       ? "claude"
       : providerConfig.command;
     const providerArgs = config.headless
@@ -102,13 +132,22 @@ export class ClaudeAdapter implements ProviderAdapter {
       env: {
         ...config.env,
         ...(profileHome ? { CLAUDE_CONFIG_DIR: profileHome.path } : {}),
+        // Plain `claude` (isolated profiles) runs its own CLAUDE_CONFIG_DIR and never
+        // routes through claude-rig, so it never inherits the host's long-lived
+        // CLAUDE_CODE_OAUTH_TOKEN. Without it, claude falls back to the (often stale)
+        // file-based .credentials.json and bails to /login (401). claude-rig launches
+        // inject their own token, so only thread it for the plain-claude path, and
+        // never override an explicit per-launch value.
+        ...(command === "claude" && process.env.CLAUDE_CODE_OAUTH_TOKEN && !config.env?.CLAUDE_CODE_OAUTH_TOKEN
+          ? { CLAUDE_CODE_OAUTH_TOKEN: process.env.CLAUDE_CODE_OAUTH_TOKEN }
+          : {}),
         AGENT_RELAY_PROVIDER: "claude",
         ...(config.effort ? { CLAUDE_CODE_EFFORT_LEVEL: config.effort } : {}),
       },
     };
   }
 
-  buildTmuxArgs(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): { sessionName: string; socketName: string; args: string[] } {
+  buildTmuxArgs(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): { sessionName: string; socketName: string; args: string[]; launcherScript?: string } {
     const sessionName = config.tmuxSession || tmuxSessionName(config.providerConfig.headless.tmuxPrefix, config.instanceId, config.label);
     const socketName = tmuxSocketName(sessionName);
     const shellCmd = [spawnArgs.command, ...spawnArgs.args].map(shellQuote).join(" ");
@@ -121,8 +160,18 @@ export class ClaudeAdapter implements ProviderAdapter {
       }
     }
 
-    tmuxArgs.push("-c", spawnArgs.cwd, shellCmd);
-    return { sessionName, socketName, args: tmuxArgs };
+    // tmux new-session has a hard limit on command length. When the inline shell
+    // command is too long (e.g. fork with conversation history in --append-system-prompt),
+    // externalize it to a launcher script that tmux executes instead.
+    const MAX_TMUX_CMD_LEN = 2000;
+    let launcherScript: string | undefined;
+    if (shellCmd.length > MAX_TMUX_CMD_LEN) {
+      launcherScript = writeLauncherScript(sessionName, shellCmd);
+      tmuxArgs.push("-c", spawnArgs.cwd, `bash ${shellQuote(launcherScript)}`);
+    } else {
+      tmuxArgs.push("-c", spawnArgs.cwd, shellCmd);
+    }
+    return { sessionName, socketName, args: tmuxArgs, launcherScript };
   }
 
   private async spawnHeadless(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): Promise<ManagedProcess> {
@@ -158,6 +207,9 @@ export class ClaudeAdapter implements ProviderAdapter {
       process: undefined,
       meta: {
         monitor: config.monitor,
+        // When the profile disables the relay plugin, the bundled monitor never
+        // loads, so no monitor will ever connect — deliver() must use tmux injection.
+        monitorless: !profileAllowsRelayFeature(config, "plugins"),
         tmuxSession: sessionName,
         tmuxSocket: socketName,
       },
@@ -294,13 +346,18 @@ function captureTmuxPane(sessionName: string, socketName?: string): string {
 }
 
 export function claudePaneLooksReady(text: string): boolean {
-  return text.includes("Claude Code")
-    && (
-      text.includes("bypass permissions")
-      || text.includes("/effort")
-      || text.includes("What's new")
-      || text.includes("Welcome back")
-    );
+  // Claude's startup banner ("Claude Code" / "Welcome back") scrolls off the pane once the
+  // conversation fills it, so a mid-session delivery (e.g. the budget warning, minutes into
+  // a run) must detect readiness from the PERSISTENT input-box footer that Claude always
+  // renders at the prompt. Requiring the banner made every delivery after the first screen
+  // of output time out as "input not ready". Any one of these strong, Claude-specific
+  // markers means the TUI is up and the input box exists.
+  return text.includes("bypass permissions")   // footer in --dangerously-skip-permissions mode
+    || text.includes("shift+tab to cycle")       // mode-cycle footer hint (persistent)
+    || text.includes("? for shortcuts")          // default footer hint (persistent)
+    || text.includes("/effort")
+    || text.includes("Welcome back")
+    || text.includes("Claude Code");
 }
 
 async function waitForClaudeInputReady(sessionName: string, timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS, socketName?: string): Promise<void> {
@@ -349,6 +406,16 @@ async function submitTextToTmux(sessionName: string, text: string, socketName?:
   }
 }
 
+const LAUNCHER_DIR = join(tmpdir(), "agent-relay-launchers");
+
+function writeLauncherScript(sessionName: string, shellCmd: string): string {
+  mkdirSync(LAUNCHER_DIR, { recursive: true });
+  const sanitized = sessionName.replace(/[^a-zA-Z0-9._-]/g, "-");
+  const scriptPath = join(LAUNCHER_DIR, `${sanitized}.sh`);
+  writeFileSync(scriptPath, `#!/usr/bin/env bash\nexec ${shellCmd}\n`, { mode: 0o755 });
+  return scriptPath;
+}
+
 export function tmuxEnvKeys(env: Record<string, string>, providerEnv: Record<string, string>): string[] {
   const keys = new Set<string>();
   for (const key of Object.keys(env)) {
@@ -372,10 +439,14 @@ export function findClaudeRigRC(cwd: string): string | null {
   const home = homedir();
   let dir = resolve(cwd);
   while (true) {
+    // Stop at $HOME without inspecting it: ~/.claude-rig is the claude-rig tool's
+    // own config home, not a per-project rc marker. Matching it would make every
+    // project under $HOME look like a claude-rig project.
+    if (dir === home) return null;
     const rc = join(dir, ".claude-rig");
     if (existsSync(rc)) return rc;
     const parent = resolve(dir, "..");
-    if (parent === dir || dir === home) return null;
+    if (parent === dir) return null;
     dir = parent;
   }
 }

package/src/control-server.ts

@@ -20,6 +20,10 @@ interface ControlServerOptions {
   onStatus(status: ProviderStatusEvent): void;
   onTerminalAttachSpec?(): Promise<TerminalAttachSpec>;
   onReplyObligations?(): Promise<ReplyObligation[]>;
+  // Phase 1 live-session lane: a provider Stop hook hands over its transcript
+  // path so the runner can capture the assistant turn and surface it in the
+  // dashboard chat without the agent re-emitting it via /reply.
+  onSessionTurn?(input: { transcriptPath: string }): Promise<void>;
 }
 
 export function startControlServer(options: ControlServerOptions): ControlServer {
@@ -59,6 +63,9 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       if (url.pathname === "/permissions/request" && req.method === "POST") {
         return handlePermissionRequest(req, options, pendingPermissionRequests);
       }
+      if (url.pathname === "/session-turn" && req.method === "POST") {
+        return handleSessionTurn(req, options);
+      }
       if (url.pathname === "/monitor") {
         const upgraded = srv.upgrade(req, { data: { kind: "monitor" } });
         return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
@@ -241,6 +248,22 @@ function claudePermissionHookResponse(decision: ProviderPermissionDecisionInput,
   };
 }
 
+async function handleSessionTurn(req: Request, options: ControlServerOptions): Promise<Response> {
+  if (!options.onSessionTurn) return Response.json({ ok: false, reason: "session capture unavailable" });
+  const body = await req.json().catch(() => null);
+  const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : "";
+  if (!transcriptPath) return Response.json({ ok: false, reason: "transcriptPath required" }, { status: 400 });
+  // Awaited on purpose: the Stop hook posts this synchronously before its
+  // reply-obligation check, so the captured turn must be persisted (and the
+  // obligation cleared) before this response returns.
+  try {
+    await options.onSessionTurn({ transcriptPath });
+    return Response.json({ ok: true });
+  } catch (error) {
+    return Response.json({ ok: false, reason: error instanceof Error ? error.message : String(error) }, { status: 500 });
+  }
+}
+
 async function handleStatus(req: Request, options: ControlServerOptions): Promise<Response> {
   const body = await req.json().catch(() => null) as Partial<ProviderStatusEvent> | null;
   const status = body?.status;

package/src/profile-home.ts

@@ -17,14 +17,35 @@ function profileRequiresIsolatedHome(config: RunnerSpawnConfig): boolean {
   return Boolean(config.agentProfile && config.agentProfile.base !== "host");
 }
 
+// First-run bootstrap (provider layer)
+// -------------------------------------
+// Isolated profile homes are keyed by instanceId, so every spawn gets a brand
+// new CLAUDE_CONFIG_DIR / CODEX_HOME — to the provider it always looks like the
+// first time it has ever run, even in a repo we've used before. Without
+// bootstrapping, the CLI stalls on first-run gates (theme/onboarding picker,
+// "do you trust this folder?") and the agent never starts; the runner then sees
+// repeated ~2s exits and gives up. bootstrap<Provider>FirstRun makes a fresh
+// home launch-ready non-interactively, guaranteeing three things:
+//   1. host auth is linked in,
+//   2. first-run / onboarding flags are pre-accepted (where the provider has them),
+//   3. the cwd workspace is trusted.
+// Workspace trust is independent of repoInstructions: "ignore" means don't load
+// the repo's CLAUDE.md / AGENTS.md as behavioral instructions, NOT "don't
+// operate here" — an isolated agent must still read/edit/execute in its own cwd.
+// (claude-rig / host-base launches dodge all of this via onboarded host config +
+// --dangerously-skip-permissions; only isolated homes need the bootstrap.)
+
 export function prepareCodexProfileHome(config: RunnerSpawnConfig): ProviderHome | undefined {
   if (!profileRequiresIsolatedHome(config)) return undefined;
   const target = providerHomePath("codex", config);
   mkdirSync(target, { recursive: true });
-  trustCodexProjectIfAllowed(target, config);
+  return { path: target, authLinked: bootstrapCodexFirstRun(target, config) };
+}
+
+function bootstrapCodexFirstRun(codexHome: string, config: RunnerSpawnConfig): string[] {
+  trustWorkspaceForCodex(codexHome, config);
   const sourceHome = process.env.CODEX_HOME || join(homedir(), ".codex");
-  const authLinked = linkExistingAuthItems(sourceHome, target, ["auth.json", "installation_id"]);
-  return { path: target, authLinked };
+  return linkExistingAuthItems(sourceHome, codexHome, ["auth.json", "installation_id"]);
 }
 
 export function prepareClaudeProfileHome(config: RunnerSpawnConfig): ProviderHome | undefined {
@@ -35,9 +56,44 @@ export function prepareClaudeProfileHome(config: RunnerSpawnConfig): ProviderHom
   // surface. An isolated-research profile (relay.context disabled) must not get
   // agent-relay communication instructions written into its config home.
   if (profileAllowsRelayFeature(config, "context")) writeClaudeRelayManual(target);
+  return { path: target, authLinked: bootstrapClaudeFirstRun(target, config) };
+}
+
+function bootstrapClaudeFirstRun(claudeHome: string, config: RunnerSpawnConfig): string[] {
+  seedClaudeConfigIfMissing(claudeHome, config);
   const sourceHome = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
-  const authLinked = linkExistingAuthItems(sourceHome, target, [".credentials.json", "statsig"]);
-  return { path: target, authLinked };
+  return linkExistingAuthItems(sourceHome, claudeHome, [".credentials.json", "statsig"]);
+}
+
+function seedClaudeConfigIfMissing(claudeHome: string, config: RunnerSpawnConfig): void {
+  const path = join(claudeHome, ".claude.json");
+  if (existsSync(path)) return;
+  const host = readHostClaudeConfig();
+  const seed: Record<string, unknown> = {
+    hasCompletedOnboarding: true,
+    theme: typeof host?.theme === "string" ? host.theme : "dark",
+  };
+  if (typeof host?.lastOnboardingVersion === "string") seed.lastOnboardingVersion = host.lastOnboardingVersion;
+  // Open approval = headless launch adds --dangerously-skip-permissions, which has
+  // its OWN first-run gate ("Bypass Permissions mode" accept/exit). Pre-accept it,
+  // or the agent stalls there exactly like the onboarding/trust gates.
+  if (config.approvalMode === "open") seed.bypassPermissionsModeAccepted = true;
+  if (config.cwd) {
+    seed.projects = {
+      [resolve(config.cwd)]: { hasTrustDialogAccepted: true, hasCompletedProjectOnboarding: true },
+    };
+  }
+  writeFileSync(path, JSON.stringify(seed, null, 2), { mode: 0o600 });
+}
+
+function readHostClaudeConfig(): Record<string, unknown> | undefined {
+  try {
+    const hostPath = join(homedir(), ".claude.json");
+    if (!existsSync(hostPath)) return undefined;
+    return JSON.parse(readFileSync(hostPath, "utf8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
 }
 
 function providerHomePath(provider: "claude" | "codex", config: RunnerSpawnConfig): string {
@@ -63,8 +119,8 @@ function linkExistingAuthItems(sourceHome: string, targetHome: string, items: st
   return linked;
 }
 
-function trustCodexProjectIfAllowed(codexHome: string, config: RunnerSpawnConfig): void {
-  if (config.agentProfile?.instructions.repoInstructions === "ignore") return;
+function trustWorkspaceForCodex(codexHome: string, config: RunnerSpawnConfig): void {
+  if (!config.cwd) return;
   const path = join(codexHome, "config.toml");
   const project = tomlBasicString(resolve(config.cwd));
   const section = `[projects.${project}]`;

package/src/runner.ts

@@ -1,5 +1,6 @@
 import { hostname } from "node:os";
 import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { AgentProfile, ContextState, Message, ProviderCapabilities, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
 import { RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
@@ -8,9 +9,11 @@ import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissio
 import { messagesWithCachedAttachments } from "./attachment-cache";
 import { ClaimTracker } from "./claim-tracker";
 import { startControlServer, type ControlServer } from "./control-server";
+import { extractLastAssistantTurn } from "./adapters/claude-transcript";
 import { agentProfileProjectionReport } from "./profile-projection";
 import { profileUsesHostProviderGlobals } from "./profile-home";
 import { runtimeMetadata } from "./version";
+import { ensureSessionScratch, reapSessionScratch, sweepStaleSessions, type SessionScratchLayout } from "./session-scratch";
 
 interface RunnerOptions {
   provider: string;
@@ -99,6 +102,8 @@ export class AgentRunner {
   private readonly pendingMessages = new Map<number, Message>();
   private readonly activeTaskClaims = new Map<number, ActiveTaskClaim>();
   private pendingTimelineEvent?: { status: string; id?: string; timestamp: number };
+  private pendingPromptMessageId?: number;
+  private scratch?: SessionScratchLayout;
 
   constructor(private readonly options: RunnerOptions) {
     this.agentId = options.agentId ?? options.runnerId;
@@ -177,6 +182,7 @@ export class AgentRunner {
       onStatus: (status) => this.setProviderStatus(status),
       onTerminalAttachSpec: () => this.terminalAttachSpec(),
       onReplyObligations: () => this.http.listReplyObligations(this.agentId),
+      onSessionTurn: (input) => this.publishSessionTurn(input),
     });
     this.writeRunnerInfoFile();
     this.options.adapter.onStatusChange((status) => {
@@ -195,6 +201,8 @@ export class AgentRunner {
     });
     this.bus.on("error", (code, message) => this.handleBusError(String(code), String(message)));
     await this.bus.connect();
+    this.ensureScratch();
+    void this.sweepStaleScratch();
     this.process = await this.spawnProvider();
     this.writeRunnerInfoFile();
     this.processStartedAt = Date.now();
@@ -210,6 +218,11 @@ export class AgentRunner {
   async stop(): Promise<void> {
     const alreadyStopped = this.stopped;
     this.stopped = true;
+    reapSessionScratch({
+      agentId: this.agentId,
+      cwd: this.options.cwd,
+      fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
+    });
     if (!alreadyStopped) await this.bus.statusAsync({ agentStatus: "offline", ready: false });
     if (this.process && !alreadyStopped) {
       await this.options.adapter.shutdown(this.process, {
@@ -239,6 +252,7 @@ export class AgentRunner {
       AGENT_RELAY_RUNNER_ID: this.options.runnerId,
       AGENT_RELAY_PROVIDER_SESSION_ID: this.providerSessionId,
       AGENT_RELAY_ID: this.agentId,
+      ...(this.scratch ? { AGENT_RELAY_SCRATCH_DIR: this.scratch.tmpDir } : {}),
       AGENT_RELAY_URL: this.options.relayUrl,
       AGENT_RELAY_APPROVAL: this.options.approvalMode,
       ...(this.currentToken ? { AGENT_RELAY_TOKEN: this.currentToken } : {}),
@@ -397,7 +411,7 @@ export class AgentRunner {
   private async handleCommand(type: string, params: Record<string, unknown>, commandId: string, command?: Record<string, unknown>): Promise<void> {
     const target = typeof command?.target === "string" ? command.target : this.agentId;
     if (target !== this.agentId && target !== this.options.runnerId) return;
-    if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.reconnect" && type !== "agent.kill" && type !== "agent.compact" && type !== "agent.clearContext" && type !== "agent.injectContext" && type !== "agent.permissionDecision") return;
+    if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.reconnect" && type !== "agent.kill" && type !== "agent.compact" && type !== "agent.clearContext" && type !== "agent.injectContext" && type !== "agent.permissionDecision" && type !== "prompt.inject") return;
 
     const exitAfterCommand = type === "agent.shutdown" || type === "agent.kill";
     if (exitAfterCommand) {
@@ -425,6 +439,8 @@ export class AgentRunner {
         providerResult = await this.injectContext(params);
       } else if (type === "agent.permissionDecision") {
         providerResult = await this.respondToPermissionDecision(params);
+      } else if (type === "prompt.inject") {
+        providerResult = await this.injectPrompt(params);
       } else await this.shutdownProvider(type === "agent.kill", commandTimeoutMs(params));
       await this.updateCommand(commandId, "succeeded", {
         action: type,
@@ -496,6 +512,17 @@ export class AgentRunner {
     return { approvalId, decision, ...(result ? { providerResult: result } : {}) };
   }
 
+  private async injectPrompt(params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const body = typeof params.body === "string" ? params.body : "";
+    if (!body) throw new Error("body required");
+    if (!this.process) throw new Error("provider process is unavailable");
+    if (!this.options.adapter.deliverInitialPrompt) throw new Error("provider does not support prompt injection");
+    const messageId = typeof params.messageId === "number" ? params.messageId : undefined;
+    if (messageId) this.pendingPromptMessageId = messageId;
+    await this.options.adapter.deliverInitialPrompt(this.process, body);
+    return { injected: true, messageId };
+  }
+
   private async restartProvider(): Promise<void> {
     this.restartInProgress = true;
     try {
@@ -632,6 +659,52 @@ export class AgentRunner {
     this.publishStatus();
   }
 
+  // Phase 1 live-session lane: capture the assistant turn from the Claude
+  // transcript and post it as an observed "session" message so it shows in the
+  // dashboard chat with zero agent tokens. Posting it as a reply to the
+  // triggering message also clears the reply obligation, so the Stop hook no
+  // longer nags the agent to /reply — which is what made it re-emit before.
+  private async publishSessionTurn(input: { transcriptPath: string }): Promise<void> {
+    // Find the triggering message to reply to: either a pending prompt injection
+    // (Phase 2 direct lane) or a reply obligation from the dashboard human.
+    let replyToMessageId: number | undefined;
+    const pendingPrompt = this.pendingPromptMessageId;
+    if (pendingPrompt) {
+      replyToMessageId = pendingPrompt;
+      this.pendingPromptMessageId = undefined;
+    } else {
+      try {
+        const obligations = await this.http.listReplyObligations(this.agentId);
+        const obligation = [...obligations].reverse().find((o) => o.from === "user");
+        replyToMessageId = obligation?.messageId;
+      } catch {
+        return;
+      }
+    }
+    if (!replyToMessageId) return;
+
+    let jsonl: string;
+    try {
+      jsonl = await readFile(input.transcriptPath, "utf8");
+    } catch {
+      return;
+    }
+    const body = extractLastAssistantTurn(jsonl);
+    if (!body) return;
+
+    try {
+      await this.http.sendMessage({
+        from: this.agentId,
+        to: "user",
+        replyTo: replyToMessageId,
+        kind: "session",
+        body,
+      });
+    } catch (error) {
+      this.logRunnerDiagnostic(`session turn capture failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
   private publishStatus(): void {
     const status = this.claims.currentStatus();
     const agentStatus = runnerAgentStatus(status);
@@ -735,6 +808,33 @@ export class AgentRunner {
     }
   }
 
+  private ensureScratch(): void {
+    try {
+      this.scratch = ensureSessionScratch({
+        agentId: this.agentId,
+        cwd: this.options.cwd,
+        fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
+      });
+    } catch (error) {
+      this.logRunnerDiagnostic(`session scratch setup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  private async sweepStaleScratch(): Promise<void> {
+    try {
+      const agents = await this.http.listAgents().catch(() => [] as Awaited<ReturnType<RelayHttpClient["listAgents"]>>);
+      const keep = new Set(agents.map((a) => a.id));
+      keep.add(this.agentId);
+      const removed = sweepStaleSessions({
+        cwd: this.options.cwd,
+        fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
+        keepAgentIds: keep,
+        now: Date.now(),
+      });
+      if (removed.length) this.logRunnerDiagnostic(`swept ${removed.length} stale session scratch dir(s)`);
+    } catch {}
+  }
+
   private scheduleRuntimeTokenRenewal(delayMs?: number): void {
     if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
     this.tokenRenewTimer = undefined;
@@ -1069,6 +1169,10 @@ function runtimeProviderCapabilities(options: RunnerOptions, contextStats?: { so
     },
     ...runtimeProviderContextCapabilities(options, contextStats),
     ...runtimeProviderTerminalCapabilities(options),
+    liveSession: {
+      capture: true,
+      inject: Boolean(options.adapter.deliverInitialPrompt),
+    },
     source: "runtime",
     confidence: "reported",
     lastUpdatedAt: options.startedAt,

package/src/session-scratch.ts

@@ -0,0 +1,169 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, appendFileSync, constants, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+export const SCRATCH_DIR_NAME = ".agent-relay";
+// The local-ignore entry. Leading + trailing slash scopes it to the dir at the
+// base, matching git's gitignore semantics.
+const EXCLUDE_ENTRY = "/.agent-relay/";
+
+export interface SessionScratchLayout {
+  baseDir: string; // dir that contains .agent-relay (cwd, or fallback base dir)
+  rootDir: string; // <base>/.agent-relay
+  sessionsDir: string; // <base>/.agent-relay/sessions
+  sessionDir: string; // <base>/.agent-relay/sessions/<id>
+  tmpDir: string; // <base>/.agent-relay/sessions/<id>/tmp
+  replyFile: string; // <tmp>/reply.md
+}
+
+export interface SessionScratchTarget {
+  agentId: string;
+  cwd: string;
+  // Orchestrator base dir, used only when cwd is not writable. NEVER home — a
+  // home fallback would place scratch above the orchestrator base dir and break
+  // cwd containment.
+  fallbackBaseDir?: string;
+}
+
+function isWritableDir(dir: string): boolean {
+  try {
+    if (!statSync(dir).isDirectory()) return false;
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Prefer cwd; fall back to the orchestrator base dir only when cwd is not a
+// writable dir. Returns cwd as a last resort so callers can still attempt mkdir
+// (and surface the real error) rather than silently picking an unrelated path.
+export function resolveScratchBase(cwd: string, fallbackBaseDir?: string): string {
+  if (isWritableDir(cwd)) return cwd;
+  if (fallbackBaseDir && isWritableDir(fallbackBaseDir)) return fallbackBaseDir;
+  return cwd;
+}
+
+export function sessionScratchLayout(baseDir: string, agentId: string): SessionScratchLayout {
+  const rootDir = join(baseDir, SCRATCH_DIR_NAME);
+  const sessionsDir = join(rootDir, "sessions");
+  const sessionDir = join(sessionsDir, agentId);
+  const tmpDir = join(sessionDir, "tmp");
+  return { baseDir, rootDir, sessionsDir, sessionDir, tmpDir, replyFile: join(tmpDir, "reply.md") };
+}
+
+// Resolve git's exclude file for baseDir, correctly handling plain repos,
+// worktrees, and submodules (git rev-parse returns the shared commondir's
+// info/exclude). Returns null when baseDir is not inside a git work tree.
+function gitExcludePath(baseDir: string): string | null {
+  try {
+    const out = execFileSync("git", ["-C", baseDir, "rev-parse", "--git-path", "info/exclude"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!out) return null;
+    return isAbsolute(out) ? out : resolve(baseDir, out);
+  } catch {
+    return null;
+  }
+}
+
+// Idempotently append EXCLUDE_ENTRY to an ignore file (grep-before-write).
+function appendIgnoreEntry(file: string): void {
+  let existing = "";
+  try {
+    existing = readFileSync(file, "utf8");
+  } catch {}
+  const wanted = EXCLUDE_ENTRY.trim();
+  if (existing.split("\n").some((line) => line.trim() === wanted)) return;
+  mkdirSync(dirname(file), { recursive: true });
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  appendFileSync(file, `${prefix}${EXCLUDE_ENTRY}\n`);
+}
+
+// Ensure `.agent-relay/` is locally ignored. Prefers .git/info/exclude (git's
+// local, uncommitted ignore list) so no tracked file is ever modified; falls
+// back to .gitignore only when baseDir is not a git repo. Returns which file was
+// used (for logging/tests).
+export function ensureScratchIgnored(baseDir: string): "exclude" | "gitignore" {
+  const excludePath = gitExcludePath(baseDir);
+  if (excludePath) {
+    appendIgnoreEntry(excludePath);
+    return "exclude";
+  }
+  appendIgnoreEntry(join(baseDir, ".gitignore"));
+  return "gitignore";
+}
+
+// SessionStart: create the session tmp dir and ensure local ignore. Dir
+// creation is the load-bearing part; ignore setup is best-effort.
+export function ensureSessionScratch(target: SessionScratchTarget): SessionScratchLayout {
+  const base = resolveScratchBase(target.cwd, target.fallbackBaseDir);
+  const layout = sessionScratchLayout(base, target.agentId);
+  mkdirSync(layout.tmpDir, { recursive: true });
+  try {
+    ensureScratchIgnored(base);
+  } catch {
+    // best-effort: a missing ignore entry never pollutes git because the dir is
+    // already created and the entry is the only thing at risk.
+  }
+  return layout;
+}
+
+function dedupeBases(bases: Array<string | undefined>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const b of bases) {
+    if (!b || seen.has(b)) continue;
+    seen.add(b);
+    out.push(b);
+  }
+  return out;
+}
+
+// SessionEnd: remove this session's dir from every candidate base.
+export function reapSessionScratch(target: SessionScratchTarget): void {
+  for (const base of dedupeBases([target.cwd, target.fallbackBaseDir])) {
+    const { sessionDir } = sessionScratchLayout(base, target.agentId);
+    try {
+      rmSync(sessionDir, { recursive: true, force: true });
+    } catch {}
+  }
+}
+
+export interface SweepOptions {
+  cwd: string;
+  fallbackBaseDir?: string;
+  // Agent ids to keep (currently-known agents + self). Any session dir whose id
+  // is not in this set AND older than minAgeMs is removed.
+  keepAgentIds: Set<string>;
+  now: number;
+  minAgeMs?: number;
+}
+
+// Periodic sweep of leftover session dirs from agents no longer known to the
+// relay. The minAgeMs grace avoids racing a peer that just created its dir but
+// has not yet appeared in the agent list.
+export function sweepStaleSessions(opts: SweepOptions): string[] {
+  const minAge = opts.minAgeMs ?? 60 * 60 * 1000;
+  const removed: string[] = [];
+  for (const base of dedupeBases([opts.cwd, opts.fallbackBaseDir])) {
+    const sessionsDir = join(base, SCRATCH_DIR_NAME, "sessions");
+    let ids: string[];
+    try {
+      ids = readdirSync(sessionsDir);
+    } catch {
+      continue;
+    }
+    for (const id of ids) {
+      if (opts.keepAgentIds.has(id)) continue;
+      const dir = join(sessionsDir, id);
+      try {
+        if (opts.now - statSync(dir).mtimeMs < minAge) continue;
+        rmSync(dir, { recursive: true, force: true });
+        removed.push(dir);
+      } catch {}
+    }
+  }
+  return removed;
+}