@controlflow-ai/daemon 0.1.2 → 0.1.3

package/src/agent-runtime.ts

@@ -1,6 +1,10 @@
-import type { Message, RoomParticipant, RunAction } from './types.js';
-import { join } from 'node:path';
+import type { AgentActivityKind, AgentRoomSubscription, DeliveryContext, EnabledSkill, Message, RoomMode, RoomParticipant, RoomSavedMessage, RunAction } from './types.js';
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { createWriteStream, existsSync, mkdirSync, type WriteStream } from 'node:fs';
+import { delimiter, join, win32 as pathWin32 } from 'node:path';
+import { homeDir, privatePalCliExecutableName } from './config.js';
 import { sanitizeProviderIds } from './provider-identity.js';
+import { buildRuntimeLaunchContext, runtimeLaunchRoot as permissionRuntimeLaunchRoot, runtimeStateHome as permissionRuntimeStateHome, selectAcpPermissionOption, effectivePermissionProfile, type AgentPermissionProfile, type RuntimeLaunchContext } from './agent-permissions.js';
 
 export interface AgentRuntimeRunInput {
   agent: string;
@@ -9,6 +13,8 @@ export interface AgentRuntimeRunInput {
   cwd: string;
   agentHome?: string;
   projectCwd?: string;
+  permissionProfile?: AgentPermissionProfile;
+  launchContext?: RuntimeLaunchContext;
   projectContext?: {
     id: string;
     name: string;
@@ -23,15 +29,38 @@ export interface AgentRuntimeRunInput {
   localDaemonToken?: string;
   runtimeSessionId?: string | null;
   roomParticipants?: RoomParticipant[];
+  roomAgentSubscriptions?: AgentRoomSubscription[];
+  roomMode?: RoomMode;
+  enabledSkills?: EnabledSkill[];
   recentMessages?: Message[];
+  deliveryContext?: DeliveryContext;
+  runtimeAttachments?: RuntimeAttachment[];
   dryRun?: boolean;
   privateCliBinDir?: string;
   palCliCommand?: string;
+  runtimeEnv?: NodeJS.ProcessEnv;
   signal?: AbortSignal;
   onStart?: (pid: number | null) => Promise<void>;
+  onActivity?: (event: AgentRuntimeActivityEvent) => Promise<void>;
   getAction?: () => Promise<RunAction | null>;
 }
 
+export interface RuntimeAttachment {
+  id: string;
+  messageId: number;
+  kind: 'image' | 'file';
+  mimeType: string;
+  filename: string;
+  path: string;
+}
+
+export interface AgentRuntimeActivityEvent {
+  kind: AgentActivityKind;
+  title: string;
+  detail?: string;
+  metadata?: Record<string, unknown>;
+}
+
 export function formatRoomParticipantContext(participants: RoomParticipant[] | undefined): string {
   if (!participants || participants.length === 0) {
     return '\nRoom participants: no local participant snapshot is available yet.';
@@ -39,12 +68,58 @@ export function formatRoomParticipantContext(participants: RoomParticipant[] | u
   const lines = participants.slice(0, 50).map((p) => {
     const participant = sanitizeProviderIds(p.participant_id);
     const name = p.display_name ? ` (${sanitizeProviderIds(p.display_name)})` : '';
-    return `- ${p.kind}: ${participant}${name}, source=${p.source}`;
+    const mentionKey = p.kind === 'agent' ? `, mention_key=${participant}` : '';
+    return `- ${p.kind}: ${participant}${name}${mentionKey}, source=${p.source}`;
   });
   const suffix = participants.length > 50 ? `\n- ... ${participants.length - 50} more participants omitted` : '';
   return `\nRoom participants:\n${lines.join('\n')}${suffix}`;
 }
 
+export function formatRoomDeliveryPolicyContext(input: {
+  agent: string;
+  subscriptions?: AgentRoomSubscription[];
+}): string {
+  const modes = new Map((input.subscriptions ?? [])
+    .filter((subscription) => subscription.channel_id === null)
+    .map((subscription) => [subscription.agent, subscription.mode]));
+  const currentMode = modes.get(input.agent) ?? 'mentions';
+  const strategyLines = [...modes.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .slice(0, 50)
+    .map(([agent, mode]) => {
+      const current = agent === input.agent ? ' (you)' : '';
+      return `- @${sanitizeProviderIds(agent)}${current}: ${mode}`;
+    });
+  const strategyBlock = strategyLines.length > 0
+    ? `\nCurrent agent receive strategies in this room:\n${strategyLines.join('\n')}`
+    : '\nCurrent agent receive strategies in this room: no subscription snapshot is available; assume agents default to mentions mode unless a direct mention succeeds.';
+  return `\nRoom delivery and mention semantics:
+  - A direct mention (\`--mention <mention_key>\` or a message addressed to @agent) wakes that agent even when ordinary room messages would not.
+  - For agent participants, use the exact \`mention_key\` shown in Room participants.
+  - An explicit @all/@_all/所有人 mention is a room-wide handoff: every active room agent that can participate may receive it. Use it only when all agents should inspect the request.
+  - A plain room message without a direct recipient is shared context. Agents in \`all\` mode receive it immediately; agents in \`mentions\` mode usually do not wake unless directly mentioned or included by @all.
+  - \`periodic\` means pull/batched attention: do not rely on an immediate wakeup from ordinary chatter. Directly mention the agent when you need timely action.
+  - \`muted\` or \`off\` means the agent should not be expected to react unless the system explicitly delivers a direct task.
+  - Your current receive strategy here is \`${currentMode}\`. When coordinating, decide whether the other agent will naturally see the room message or needs a direct \`--mention <mention_key>\` send.${strategyBlock}`;
+}
+
+export function formatRoomModeAndSkillContext(input: {
+  roomMode?: RoomMode;
+  enabledSkills?: EnabledSkill[];
+}): string {
+  const mode = input.roomMode ?? 'standard';
+  const modeDescription = mode === 'idea_development'
+    ? 'This room is for developing ideas through conversation and .pal docs before implementation handoff.'
+    : 'This is an ordinary PAL room. Do not apply special Idea Development workflow unless the user explicitly asks for it.';
+  const skills = input.enabledSkills ?? [];
+  const skillBlock = skills.length === 0
+    ? 'Enabled skills: none.'
+    : `Enabled skills:\n${skills.map((skill) => (
+      `- ${sanitizeProviderIds(skill.key)} (${sanitizeProviderIds(skill.binding_scope)} priority ${skill.binding_priority}): ${sanitizeProviderIds(skill.name)}\n${sanitizeProviderIds(skill.instruction_content)}`
+    )).join('\n')}`;
+  return `\nRoom mode and skills:\n- Current room mode: ${mode}\n- ${modeDescription}\n${skillBlock}`;
+}
+
 export function formatRecentMessageContext(messages: Message[] | undefined, currentMessageId: number): string {
   if (!messages || messages.length === 0) {
     return '\nRecent room history: no local message history is available yet.';
@@ -55,35 +130,119 @@ export function formatRecentMessageContext(messages: Message[] | undefined, curr
     const recipient = message.recipient ? ` to=@${sanitizeProviderIds(message.recipient)}` : '';
     const sender = sanitizeProviderIds(message.sender);
     const content = sanitizeProviderIds(message.content).replace(/\s+/g, ' ').trim().slice(0, 500);
-    return `- [${message.id}${marker}] @${sender}${recipient}${parent}: ${content}`;
+    const attachments = formatMessageAttachmentSummary(message);
+    return `- [${message.id}${marker}] @${sender}${recipient}${parent}: ${content}${attachments}`;
   });
   const omitted = messages.length > 12 ? `\n- ... ${messages.length - 12} older messages omitted` : '';
   return `\nRecent room history:\n${lines.join('\n')}${omitted}`;
 }
 
+function formatMessageLines(messages: Message[], currentMessageId: number): string {
+  return messages.map((message) => {
+    const marker = message.id === currentMessageId ? ' current' : '';
+    const parent = message.parent_id === null ? '' : ` parent=${message.parent_id}`;
+    const recipient = message.recipient ? ` to=@${sanitizeProviderIds(message.recipient)}` : '';
+    const sender = sanitizeProviderIds(message.sender);
+    const content = sanitizeProviderIds(message.content).replace(/\s+/g, ' ').trim().slice(0, 500);
+    const attachments = formatMessageAttachmentSummary(message);
+    return `- [${message.id}${marker}] @${sender}${recipient}${parent}: ${content}${attachments}`;
+  }).join('\n');
+}
+
+function formatMessageAttachmentSummary(message: Message): string {
+  if (!message.attachments || message.attachments.length === 0) return '';
+  const items = message.attachments.map((attachment) => (
+    `${attachment.kind} ${sanitizeProviderIds(attachment.filename || attachment.id)} (${attachment.mime_type}, ${attachment.size_bytes} bytes, path=${attachment.path})`
+  ));
+  return ` [attachments: ${items.join('; ')}]`;
+}
+
+function formatSavedRoomContext(savedMessages: RoomSavedMessage[] | undefined): string {
+  if (!savedMessages || savedMessages.length === 0) return '';
+  const lines = savedMessages.slice(0, 10).map((saved) => {
+    const id = sanitizeProviderIds(saved.id);
+    const sender = sanitizeProviderIds(saved.message_sender);
+    const savedBy = sanitizeProviderIds(saved.saved_by);
+    const note = saved.note?.trim()
+      ? ` note="${sanitizeProviderIds(saved.note).replace(/\s+/g, ' ').trim().slice(0, 240)}"`
+      : '';
+    const content = sanitizeProviderIds(saved.message_content).replace(/\s+/g, ' ').trim().slice(0, 500);
+    return `- [saved ${id} msg #${saved.message_id}] saved by @${savedBy}${note}; original @${sender}: ${content}`;
+  });
+  const omitted = savedMessages.length > 10 ? `\n- ... ${savedMessages.length - 10} older saved messages omitted` : '';
+  return `\nSaved room context:\nThese are room messages and notes humans or agents saved as durable collaboration context.\n${lines.join('\n')}${omitted}`;
+}
+
+function formatRuntimeAttachments(attachments: RuntimeAttachment[] | undefined): string {
+  if (!attachments || attachments.length === 0) return '';
+  const imageCount = attachments.filter((attachment) => attachment.kind === 'image').length;
+  const fileCount = attachments.length - imageCount;
+  const lines = attachments.map((attachment) => (
+    `- ${attachment.kind} #${sanitizeProviderIds(attachment.id)} from message ${attachment.messageId}: ${sanitizeProviderIds(attachment.filename)}, ${attachment.mimeType}, local path: ${attachment.path}`
+  ));
+  const summary = imageCount === attachments.length
+    ? `The triggering message includes ${imageCount} image attachment${imageCount === 1 ? '' : 's'}.`
+    : `The triggering message includes ${attachments.length} attachment${attachments.length === 1 ? '' : 's'}, including ${imageCount} image attachment${imageCount === 1 ? '' : 's'} and ${fileCount} file attachment${fileCount === 1 ? '' : 's'}.`;
+  return `\nMessage attachments:\n${summary}\nThese files are stored under the PAL room directory and are visible to agents participating in this room. Use the listed local paths if you need to inspect them.\n${lines.join('\n')}`;
+}
+
+export function formatDeliveredRoomContext(context: DeliveryContext | undefined, currentMessageId: number, chatId: string): string {
+  if (!context) return formatRecentMessageContext(undefined, currentMessageId);
+  const header = '\nDelivered room context:\nThis context contains the newest 50 messages since your previous delivery or room-join cursor.';
+  const omitted = context.omittedCount > 0
+    ? `\nThere are ${context.omittedCount} earlier unread/context messages not shown. Use \`pal messages list --chat-id ${chatId} --after ${context.startMessageId} --limit 50\` to inspect them.`
+    : '';
+  const lines = context.messages.length > 0
+    ? `\n${formatMessageLines(context.messages, currentMessageId)}`
+    : '\nNo delivered room context messages are available.';
+  return `${header}${omitted}${lines}`;
+}
+
+function formatAllMentionOnlyHandoff(content: string, contextLabel: string): string {
+  if (!/^\s*@(?:_all|all|所有人)\s*$/iu.test(content)) return '';
+  return `\nAll-agents handoff:
+- The current message contains only an @all mention. Treat it as a broadcast trigger for the most recent prior message in ${contextLabel} from the same sender in this chat/topic.
+- If that prior message contains a concrete request, act on it and send a useful reply; do not dismiss this as acknowledgment-only just because the trigger content is only @all.
+- If no prior concrete request is visible, explain that you need the task details.`;
+}
+
 export function runtimeCwd(input: AgentRuntimeRunInput): string {
-  return input.agentHome ?? input.cwd;
+  return permissionRuntimeStateHome(input);
 }
 
 export function runtimeProjectCwd(input: AgentRuntimeRunInput): string {
   return input.projectCwd ?? input.cwd;
 }
 
+export function runtimeLaunchRoot(input: AgentRuntimeRunInput): string {
+  return permissionRuntimeLaunchRoot(input);
+}
+
 export function buildPalPrompt(input: AgentRuntimeRunInput): string {
   const palCli = input.palCliCommand ?? 'pal';
   const thread = input.message.parent_id === null ? '' : `\nTopic parent message id: ${input.message.parent_id}`;
   const recipient = input.message.recipient ? `\nRecipient: @${sanitizeProviderIds(input.message.recipient)}` : '';
   const agentHome = runtimeCwd(input);
   const projectCwd = runtimeProjectCwd(input);
+  const launchContext = input.launchContext ?? buildRuntimeLaunchContext(input);
   const chatName = sanitizeProviderIds(input.message.chat_name);
+  const chatRef = input.message.chat_id;
   const sender = sanitizeProviderIds(input.message.sender);
   const content = sanitizeProviderIds(input.message.content);
+  const freshnessFlags = `--base-message-id ${input.message.id} --hold-if-stale`;
   const projectContext = input.projectContext
     ? input.projectContext.accessible
       ? `\nProject context:\n- You are working in project: ${sanitizeProviderIds(input.projectContext.name)}\n- Project computer: ${sanitizeProviderIds(input.projectContext.computerName || input.projectContext.computerId)}\n- Project path: ${input.projectContext.rootPath}\n- This agent is running on the project computer and can use the project workspace path above.`
       : `\nProject context:\n- This room belongs to project: ${sanitizeProviderIds(input.projectContext.name)}\n- Project computer: ${sanitizeProviderIds(input.projectContext.computerName || input.projectContext.computerId)}\n- Project path: ${input.projectContext.rootPath}\n- This agent is currently running on computer: ${sanitizeProviderIds(input.projectContext.currentComputerId || 'unknown')}\n- The computers differ, so the project path is temporarily not accessible from this agent run. Do not claim to inspect or change that path unless access is restored.`
     : '';
 
+  const messageContext = input.deliveryContext
+    ? formatDeliveredRoomContext(input.deliveryContext, input.message.id, chatRef)
+    : formatRecentMessageContext(input.recentMessages, input.message.id);
+  const savedRoomContext = input.deliveryContext ? formatSavedRoomContext(input.deliveryContext.savedMessages) : '';
+  const runtimeAttachments = formatRuntimeAttachments(input.runtimeAttachments);
+  const messageContextLabel = input.deliveryContext ? 'Delivered room context' : 'Recent room history';
+
   return `You are ${input.agent}, a long-running PAL coding agent connected to the pal chat server.
 
 PAL is a multi-agent chat platform where humans and agents collaborate through rooms and topics.
@@ -91,14 +250,14 @@ PAL is a multi-agent chat platform where humans and agents collaborate through r
 Workspace contract:
 - Your current working directory is your persistent PAL agent home: ${agentHome}
 - Your cwd is for identity, memory, recovery state, scratch files, and durable local notes.
-- Your cwd is not the project repository.
+- The runtime process starts from your persistent PAL agent home: ${launchContext.runtimeRoot}
 - The project workspace for source inspection, code changes, tests, and Git work is: ${projectCwd}
+- Keep durable agent memory in your agent home, not in the project repository.
 ${projectContext}
 
 Startup recovery:
-- Read MEMORY.md in your cwd first when it exists.
+- Read ${agentHome}/MEMORY.md first when it exists.
 - Follow its recovery order and read only the referenced state/kb files you need.
-- Keep durable agent memory in your agent home, not in the project repository.
 
 A new chat message arrived.
 
@@ -106,7 +265,12 @@ Message id: ${input.message.id}
 Chat: #${chatName}${thread}
 Sender: @${sender}${recipient}
 ${formatRoomParticipantContext(input.roomParticipants)}
-${formatRecentMessageContext(input.recentMessages, input.message.id)}
+${formatRoomDeliveryPolicyContext({ agent: input.agent, subscriptions: input.roomAgentSubscriptions })}
+${formatRoomModeAndSkillContext({ roomMode: input.roomMode, enabledSkills: input.enabledSkills })}
+${messageContext}
+${savedRoomContext}
+${runtimeAttachments}
+${formatAllMentionOnlyHandoff(content, messageContextLabel)}
 Content:
 ${content}
 
@@ -118,13 +282,37 @@ Communication rules:
 - Store PAL handles such as user:pal_user_ab12cd34 in durable memory. Never store provider-native IDs such as Feishu/Lark open_id, chat_id, message_id, or app_id values.
 
 Commands:
-- Send a reply to the same chat: ${palCli} send --chat ${chatName} --from ${input.agent} <message>
-- Send a message to another agent and trigger that agent's runtime: ${palCli} send --chat ${chatName} --from ${input.agent} --to <agent-key> <message>
-- Reply in this topic: ${palCli} send --chat ${chatName} --parent ${input.message.parent_id ?? input.message.id} --from ${input.agent} <message>
+- Send a reply to the same chat: ${palCli} send --chat-id ${chatRef} ${freshnessFlags} --from ${input.agent} <message>
+- Send a message to one or more agents and trigger their runtimes: ${palCli} send --chat-id ${chatRef} ${freshnessFlags} --from ${input.agent} --mention <mention_key> [--mention <mention_key> ...] <message>
+  Use the exact mention_key shown for agent participants above, for example \`--mention 逻辑尖子生\`.
+- Reply in this topic: ${palCli} send --chat-id ${chatRef} --parent ${input.message.parent_id ?? input.message.id} ${freshnessFlags} --from ${input.agent} <message>
 - List rooms: ${palCli} rooms list
-- View room members: ${palCli} rooms members --room ${chatName}
-- Read recent chat messages: ${palCli} messages list --room ${chatName}
+- View room members: ${palCli} rooms members --room ${chatRef}
+- Read recent chat messages: ${palCli} messages list --chat-id ${chatRef}
 - Show one message: ${palCli} messages show <message-id>
+- List room tasks: ${palCli} tasks list --chat-id ${chatRef}
+- Create room tasks: ${palCli} tasks create --chat-id ${chatRef} --from ${input.agent} <title> [title...]
+- Claim room tasks: ${palCli} tasks claim --chat-id ${chatRef} --tasks <task-number>[,<task-number>]
+- Update a task: ${palCli} tasks status --chat-id ${chatRef} --task <task-number> --status in_review|done|closed
+- Schedule a reminder from this message: ${palCli} reminders schedule --msg-id ${input.message.id} --delay-seconds <seconds> --title <title> [--repeat daily|weekly|every:2h]
+- List scheduled reminders: ${palCli} reminders list --status scheduled
+- Save this message for later: ${palCli} saved save --msg-id ${input.message.id} --note <note>
+- List saved messages: ${palCli} saved list --chat-id ${chatRef}
+- List held drafts: ${palCli} drafts list
+- Revise a held draft after reading intervening messages: ${palCli} drafts revise <draft-id> <revised message>
+- Stay silent on an obsolete held draft: ${palCli} drafts stay-silent <draft-id>
+- Send an unchanged held draft anyway: ${palCli} drafts send-anyway <draft-id>
+
+Markdown-safe sending:
+- For Markdown or any message with special shell characters such as quotes, backticks, dollar signs, command substitutions, or multiple lines, pipe a single-quoted heredoc into \`${palCli} send --stdin\`.
+- Use this pattern for ordinary replies: \`cat << 'PAL_MESSAGE' | ${palCli} send --chat-id ${chatRef} ${freshnessFlags} --from ${input.agent} --stdin\`, then the raw Markdown body, then \`PAL_MESSAGE\`.
+- For topic replies, keep the same pattern and include the parent flag: \`cat << 'PAL_MESSAGE' | ${palCli} send --chat-id ${chatRef} --parent ${input.message.parent_id ?? input.message.id} ${freshnessFlags} --from ${input.agent} --stdin\`.
+- This avoids shared temp files entirely; each send process reads its own stdin stream.
+
+Freshness rule:
+- Keep the freshness flags on visible replies. If \`${palCli} send\` reports a held draft, the room changed after the context you saw. Inspect the returned intervening messages before doing anything else.
+- Use \`${palCli} drafts revise <draft-id> <revised message>\` if a reply is still useful, \`${palCli} drafts stay-silent <draft-id>\` if the draft is obsolete, and \`${palCli} drafts send-anyway <draft-id>\` only when the unchanged content is still correct.
+- Do not leave held drafts unresolved after deciding.
 
 Finish naturally when the task is done. There is no fixed timeout for this run.`;
 }
@@ -136,6 +324,23 @@ export interface AgentRuntimeRunResult {
   runtimeSessionId?: string | null;
 }
 
+export interface AgentRuntimeSteerInput {
+  agent: string;
+  serverUrl: string;
+  runId: string;
+  sessionId: string;
+  runtimeSessionId?: string | null;
+  message: Message;
+  cwd: string;
+  agentHome?: string;
+  projectCwd?: string;
+  localDaemonUrl?: string;
+  localDaemonToken?: string;
+  privateCliBinDir?: string;
+  palCliCommand?: string;
+  runtimeEnv?: NodeJS.ProcessEnv;
+}
+
 export type AgentRuntimeProtocol = 'json-stream' | 'acp';
 
 export interface AgentRuntimeCapabilities {
@@ -143,6 +348,7 @@ export interface AgentRuntimeCapabilities {
   resume: 'runtime-session-id' | 'adapter-session-id' | 'none';
   busyDeliveryMode: 'queue' | 'direct' | 'notification' | 'none';
   supportsMcp: boolean;
+  supportsSteer: boolean;
 }
 
 export interface AgentRuntime {
@@ -156,24 +362,166 @@ export interface AgentRuntime {
   readonly command: string;
   /** Return the working directory for the agent process. Defaults to input.agentHome ?? input.cwd. */
   buildCwd?(input: AgentRuntimeRunInput): string;
+  /** Return additional environment variables for the agent process. */
+  buildEnv?(input: AgentRuntimeRunInput): Record<string, string>;
   /** Parse stdout/stderr from the agent process. Defaults to trimmed stdout + stderr. */
   parseOutput?(input: { stdout: string; stderr: string; input: AgentRuntimeRunInput }): { output: string; runtimeSessionId?: string | null };
+  /** Inject a message into an already running runtime session when supported. */
+  steerActiveRun?(input: AgentRuntimeSteerInput): Promise<void>;
+}
+
+export interface PrivateCliEnvOptions {
+  platform?: NodeJS.Platform;
+  pathDelimiter?: string;
+}
+
+export function buildPrivateCliEnv(
+  privateCliBinDir: string,
+  basePath = '',
+  options: PrivateCliEnvOptions = {},
+): { PAL_CLI: string; PATH: string } {
+  const platform = options.platform ?? process.platform;
+  const cliName = privatePalCliExecutableName(platform);
+  const palCli = platform === 'win32' ? pathWin32.join(privateCliBinDir, cliName) : join(privateCliBinDir, cliName);
+  return {
+    PAL_CLI: palCli,
+    PATH: `${privateCliBinDir}${options.pathDelimiter ?? delimiter}${basePath}`,
+  };
+}
+
+function runtimeDebugEnabled(): boolean {
+  return /^(1|true|yes|on)$/i.test(process.env.PAL_RUNTIME_DEBUG ?? '');
+}
+
+function runtimeDebugLogDir(): string {
+  return process.env.PAL_RUNTIME_LOG_DIR?.trim() || join(homeDir(), 'runtime-logs');
+}
+
+function safeFileSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'unknown';
+}
+
+function jsonSafe(value: unknown): unknown {
+  if (value instanceof Error) return { name: value.name, message: value.message, stack: value.stack };
+  return value;
+}
+
+class RuntimeDebugLogger {
+  readonly path: string;
+  private stream: WriteStream;
+  private closed = false;
+
+  private constructor(path: string, stream: WriteStream) {
+    this.path = path;
+    this.stream = stream;
+  }
+
+  static create(runtime: AgentRuntime, input: AgentRuntimeRunInput, prompt: string, args: string[], procCwd: string): RuntimeDebugLogger | null {
+    if (!runtimeDebugEnabled()) return null;
+    const dir = runtimeDebugLogDir();
+    mkdirSync(dir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const file = [
+      timestamp,
+      safeFileSegment(runtime.name),
+      safeFileSegment(input.agent),
+      `message-${input.message.id}`,
+    ].join('_');
+    const logger = new RuntimeDebugLogger(join(dir, `${file}.jsonl`), createWriteStream(join(dir, `${file}.jsonl`), { flags: 'a', mode: 0o600 }));
+    logger.write('runtime.start', {
+      runtime: runtime.name,
+      command: runtime.command,
+      args,
+      cwd: procCwd,
+      projectCwd: runtimeProjectCwd(input),
+      agent: input.agent,
+      chat: input.message.chat_name,
+      messageId: input.message.id,
+      runtimeSessionId: input.runtimeSessionId ?? null,
+      prompt,
+    });
+    console.log(`[${runtime.name}] debug log=${logger.path}`);
+    return logger;
+  }
+
+  write(event: string, data: Record<string, unknown> = {}): void {
+    if (this.closed) return;
+    const safeData = jsonSafe(data);
+    const record = safeData && typeof safeData === 'object' ? safeData as Record<string, unknown> : { value: safeData };
+    this.stream.write(`${JSON.stringify({ ts: new Date().toISOString(), event, ...record })}\n`);
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.stream.end();
+  }
 }
 
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function processGroupSignal(pid: number, signal: NodeJS.Signals): void {
+export interface ProcessTreeSignalOptions {
+  platform?: NodeJS.Platform;
+  killPid?: (pid: number, signal?: NodeJS.Signals | number) => void;
+  taskkill?: (pid: number, force: boolean) => Promise<void>;
+}
+
+function runTaskkill(pid: number, force: boolean): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const args = ['/pid', String(pid), '/t'];
+    if (force) args.push('/f');
+    const taskkill = spawn('taskkill.exe', args, { windowsHide: true });
+    let stderr = '';
+    taskkill.stderr.on('data', (chunk) => {
+      stderr += String(chunk);
+    });
+    taskkill.once('error', reject);
+    taskkill.once('exit', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`taskkill exited ${code}${stderr.trim() ? `: ${stderr.trim()}` : ''}`));
+    });
+  });
+}
+
+export async function signalProcessTree(
+  pid: number,
+  signal: NodeJS.Signals,
+  options: ProcessTreeSignalOptions = {},
+): Promise<void> {
+  const platform = options.platform ?? process.platform;
+  const killPid = options.killPid ?? process.kill;
+  if (platform === 'win32') {
+    try {
+      await (options.taskkill ?? runTaskkill)(pid, signal === 'SIGKILL');
+    } catch {
+      try { killPid(pid, signal); } catch { /* already exited */ }
+    }
+    return;
+  }
   try {
-    process.kill(-pid, signal);
+    killPid(-pid, signal);
   } catch {
-    try { process.kill(pid, signal); } catch { /* already exited */ }
+    try { killPid(pid, signal); } catch { /* already exited */ }
   }
 }
 
+function stopNodeProcess(proc: ChildProcessWithoutNullStreams): void {
+  if (!proc.pid) return;
+  void signalProcessTree(proc.pid, 'SIGTERM');
+  setTimeout(() => {
+    if (proc.exitCode === null && proc.signalCode === null && proc.pid) {
+      void signalProcessTree(proc.pid, 'SIGKILL');
+    }
+  }, 2000).unref();
+}
+
 async function stopProcess(proc: ReturnType<typeof Bun.spawn>): Promise<number | null> {
-  processGroupSignal(proc.pid, 'SIGTERM');
+  await signalProcessTree(proc.pid, 'SIGTERM');
   const graceful = await Promise.race([
     proc.exited.then((exitCode) => ({ exited: true as const, exitCode })),
     sleep(2000).then(() => ({ exited: false as const })),
@@ -181,14 +529,376 @@ async function stopProcess(proc: ReturnType<typeof Bun.spawn>): Promise<number |
 
   if (graceful.exited) return graceful.exitCode;
 
-  processGroupSignal(proc.pid, 'SIGKILL');
-  proc.kill('SIGKILL');
+  await signalProcessTree(proc.pid, 'SIGKILL');
+  try { proc.kill('SIGKILL'); } catch { /* already exited */ }
   return await Promise.race([
     proc.exited,
     sleep(500).then(() => null),
   ]);
 }
 
+interface JsonRpcMessage {
+  jsonrpc?: string;
+  id?: number | string | null;
+  method?: string;
+  params?: Record<string, unknown>;
+  result?: unknown;
+  error?: unknown;
+}
+
+function textFromAcpContent(content: unknown): string {
+  if (!content || typeof content !== 'object') return '';
+  const record = content as Record<string, unknown>;
+  if (record.type === 'text' && typeof record.text === 'string') return record.text;
+  if (record.type === 'content') return textFromAcpContent(record.content);
+  return '';
+}
+
+function redactRuntimeLog(value: string): string {
+  return value
+    .replace(/(api[-_]?key|token|secret|authorization|password)(["'\s:=]+)([^\s"']+)/gi, '$1$2<redacted>')
+    .replace(/Bearer\s+[^\s"']+/gi, 'Bearer <redacted>')
+    .replace(/sk-[A-Za-z0-9_-]+/g, 'sk-<redacted>');
+}
+
+function tailLines(lines: string[], count = 8): string[] {
+  return lines.slice(Math.max(0, lines.length - count)).map((line) => redactRuntimeLog(line));
+}
+
+function truncateActivityText(value: string, max = 1200): string {
+  const compact = redactRuntimeLog(value).replace(/\s+/g, ' ').trim();
+  return compact.length > max ? `${compact.slice(0, max - 1)}...` : compact;
+}
+
+function stringField(record: Record<string, unknown>, key: string): string {
+  const value = record[key];
+  return typeof value === 'string' ? value : '';
+}
+
+function activityFromRuntimeJson(line: string): AgentRuntimeActivityEvent | null {
+  let event: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(line) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    event = parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  const type = stringField(event, 'type') || stringField(event, 'method') || 'runtime.event';
+  const item = event.item && typeof event.item === 'object' && !Array.isArray(event.item) ? event.item as Record<string, unknown> : {};
+  const itemType = stringField(item, 'type');
+  const text = stringField(event, 'text') || stringField(item, 'text') || stringField(event, 'message');
+  const command = stringField(event, 'command') || stringField(item, 'command');
+  const detail = truncateActivityText(text || command || line);
+  const metadata = { runtimeEventType: type, itemType: itemType || undefined };
+
+  if (type === 'thread.started') return { kind: 'lifecycle', title: 'Runtime thread started', detail: stringField(event, 'thread_id'), metadata };
+  if (type.includes('error') || stringField(event, 'level') === 'error') return { kind: 'error', title: 'Runtime error', detail, metadata };
+  if (itemType.includes('command') || itemType.includes('tool') || type.includes('exec') || type.includes('tool')) return { kind: 'tool', title: command ? 'Tool call' : 'Using tool', detail, metadata };
+  if (itemType === 'agent_message' || type.includes('message') || text) return { kind: 'output', title: 'Output', detail, metadata };
+  if (type.includes('completed')) return { kind: 'lifecycle', title: 'Step completed', detail, metadata };
+  if (type.includes('started')) return { kind: 'working', title: 'Working', detail, metadata };
+  return { kind: 'thinking', title: 'Thinking', detail, metadata };
+}
+
+async function emitActivity(input: AgentRuntimeRunInput, event: AgentRuntimeActivityEvent): Promise<void> {
+  try {
+    await input.onActivity?.(event);
+  } catch (error) {
+    console.warn(`[runtime] activity write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function commandPath(command: string, env: Record<string, string | undefined>): string | null {
+  if (command.includes('/')) return existsSync(command) ? command : null;
+  for (const dir of (env.PATH ?? '').split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, command);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function runtimeEnvSummary(command: string, env: Record<string, string | undefined>): Record<string, unknown> {
+  const krb5 = env.KRB5CCNAME;
+  const krb5Path = krb5?.replace(/^FILE:/, '');
+  const pathParts = (env.PATH ?? '').split(delimiter).filter(Boolean);
+  return {
+    commandPath: commandPath(command, env) ?? '<not found in PATH>',
+    home: env.HOME ? 'set' : 'missing',
+    user: env.USER ? 'set' : 'missing',
+    krb5ccname: krb5 ? `${krb5}${krb5Path && existsSync(krb5Path) ? ' exists' : ' missing-file'}` : 'missing',
+    lang: env.LANG ?? null,
+    lcAll: env.LC_ALL ?? null,
+    term: env.TERM ?? null,
+    httpsProxy: env.HTTPS_PROXY || env.https_proxy ? 'set' : 'missing',
+    httpProxy: env.HTTP_PROXY || env.http_proxy ? 'set' : 'missing',
+    noProxy: env.NO_PROXY || env.no_proxy ? 'set' : 'missing',
+    palCli: env.PAL_CLI ? 'set' : 'missing',
+    pathEntries: pathParts.length,
+    pathHead: pathParts.slice(0, 5),
+  };
+}
+
+async function runAcpAgentRuntime(
+  runtime: AgentRuntime,
+  input: AgentRuntimeRunInput,
+  prompt: string,
+  args: string[],
+  procCwd: string,
+  env: Record<string, string | undefined>,
+  debugLog: RuntimeDebugLogger | null,
+): Promise<AgentRuntimeRunResult> {
+  const envSummary = runtimeEnvSummary(runtime.command, env);
+  console.log(`[${runtime.name}] acp env ${JSON.stringify(envSummary)}`);
+  await emitActivity(input, { kind: 'working', title: 'Starting ACP runtime', detail: `${runtime.command} ${args[0] ?? ''}`.trim() });
+  debugLog?.write('process.env_summary', envSummary);
+  const proc = spawn(runtime.command, args, {
+    cwd: procCwd,
+    detached: true,
+    env: env as NodeJS.ProcessEnv,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  console.log(`[${runtime.name}] spawned pid=${proc.pid ?? '-'}`);
+  debugLog?.write('process.spawned', { pid: proc.pid ?? null });
+  await input.onStart?.(proc.pid ?? null);
+  await emitActivity(input, { kind: 'working', title: 'Runtime process started', detail: proc.pid ? `pid ${proc.pid}` : 'pid unavailable' });
+
+  let nextId = 1;
+  const pending = new Map<number, {
+    method: string;
+    resolve: (value: unknown) => void;
+    reject: (error: Error) => void;
+  }>();
+  const outputChunks: string[] = [];
+  const stderrChunks: string[] = [];
+  let sessionId = input.runtimeSessionId ?? null;
+  let stoppedByAction: RunAction | null = null;
+  let completed = false;
+  let childExit: { code: number | null; signal: NodeJS.Signals | null } | null = null;
+  let childError: string | null = null;
+  const rejectPendingRequests = (reason: string): void => {
+    if (pending.size === 0) return;
+    const diagnostics = {
+      reason,
+      pending: Array.from(pending.values()).map((request) => request.method),
+      childExit,
+      childError,
+      stdinDestroyed: proc.stdin.destroyed,
+      stdoutTail: tailLines(outputChunks),
+      stderrTail: tailLines(stderrChunks),
+    };
+    console.warn(`[${runtime.name}] acp pending requests failed ${JSON.stringify(diagnostics)}`);
+    debugLog?.write('acp.pending_failed', diagnostics);
+    for (const [id, request] of Array.from(pending.entries())) {
+      pending.delete(id);
+      request.reject(new Error(`${reason} before ${request.method} response; childExit=${JSON.stringify(childExit)} stderrTail=${JSON.stringify(diagnostics.stderrTail)}`));
+    }
+  };
+  proc.once('exit', (code, signal) => {
+    childExit = { code, signal };
+    console.log(`[${runtime.name}] process exit observed code=${code ?? '-'} signal=${signal ?? '-'}`);
+    debugLog?.write('process.exit_observed', childExit);
+    rejectPendingRequests('ACP child process exited');
+  });
+  proc.once('error', (error) => {
+    childError = error.message;
+    console.warn(`[${runtime.name}] process error ${redactRuntimeLog(error.message)}`);
+    debugLog?.write('process.error', { message: redactRuntimeLog(error.message) });
+    rejectPendingRequests('ACP child process error');
+  });
+
+  const send = (method: string, params: Record<string, unknown>): Promise<unknown> => {
+    const id = nextId;
+    nextId += 1;
+    const request = { jsonrpc: '2.0', id, method, params };
+    const startedAt = Date.now();
+    console.log(`[${runtime.name}] acp request id=${id} method=${method}`);
+    debugLog?.write('acp.send', request);
+    proc.stdin.write(`${JSON.stringify(request)}\n`);
+    return new Promise((resolve, reject) => {
+      pending.set(id, {
+        method,
+        resolve: (value) => {
+          const elapsedMs = Date.now() - startedAt;
+          console.log(`[${runtime.name}] acp response id=${id} method=${method} elapsedMs=${elapsedMs}`);
+          resolve(value);
+        },
+        reject: (error) => {
+          const elapsedMs = Date.now() - startedAt;
+          console.warn(`[${runtime.name}] acp error id=${id} method=${method} elapsedMs=${elapsedMs} error=${redactRuntimeLog(error.message)}`);
+          reject(error);
+        },
+      });
+    });
+  };
+
+  const reply = (id: number | string, result: unknown): void => {
+    const response = { jsonrpc: '2.0', id, result };
+    debugLog?.write('acp.client_response', response);
+    proc.stdin.write(`${JSON.stringify(response)}\n`);
+  };
+
+  const rejectClientRequest = (id: number | string, method: string): void => {
+    const response = { jsonrpc: '2.0', id, error: { code: -32601, message: `Unsupported ACP client method: ${method}` } };
+    debugLog?.write('acp.client_response', response);
+    proc.stdin.write(`${JSON.stringify(response)}\n`);
+  };
+
+  const handleMessage = (message: JsonRpcMessage): void => {
+    if (message.id !== undefined && message.id !== null && !message.method) {
+      const pendingRequest = pending.get(Number(message.id));
+      if (!pendingRequest) {
+        console.warn(`[${runtime.name}] acp response id=${String(message.id)} has no pending request`);
+        return;
+      }
+      pending.delete(Number(message.id));
+      if (message.error) {
+        pendingRequest.reject(new Error(`${pendingRequest.method} failed: ${JSON.stringify(message.error)}`));
+      } else {
+        pendingRequest.resolve(message.result);
+      }
+      return;
+    }
+
+    if (message.method === 'session/update') {
+      const update = (message.params?.update ?? {}) as Record<string, unknown>;
+      if (typeof message.params?.sessionId === 'string') sessionId = message.params.sessionId;
+      if (update.sessionUpdate === 'agent_message_chunk') {
+        const text = textFromAcpContent(update.content);
+        if (text) {
+          outputChunks.push(text);
+          void emitActivity(input, { kind: 'output', title: 'Output', detail: truncateActivityText(text), metadata: { protocol: 'acp', sessionId } });
+        }
+      } else if (typeof update.sessionUpdate === 'string') {
+        void emitActivity(input, { kind: 'thinking', title: 'Thinking', detail: update.sessionUpdate, metadata: { protocol: 'acp', sessionId } });
+      }
+      return;
+    }
+
+    if (message.id !== undefined && message.id !== null && message.method) {
+      if (message.method === 'session/request_permission') {
+        reply(message.id, {
+          outcome: {
+            outcome: 'selected',
+            optionId: selectAcpPermissionOption({
+              params: message.params,
+              profile: effectivePermissionProfile(input),
+              context: input.launchContext ?? buildRuntimeLaunchContext(input),
+            }),
+          },
+        });
+      } else {
+        rejectClientRequest(message.id, message.method);
+      }
+    }
+  };
+
+  const readLines = async (stream: NodeJS.ReadableStream, onLine: (line: string) => void): Promise<void> => {
+    let buffer = '';
+    for await (const chunk of stream) {
+      buffer += String(chunk);
+      let newline = buffer.indexOf('\n');
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line) onLine(line);
+        newline = buffer.indexOf('\n');
+      }
+    }
+    const rest = buffer.trim();
+    if (rest) onLine(rest);
+  };
+
+  const stdoutTask = readLines(proc.stdout, (line) => {
+    debugLog?.write('process.stdout', { line });
+    try {
+      const message = JSON.parse(line) as JsonRpcMessage;
+      debugLog?.write('acp.receive', { message });
+      handleMessage(message);
+    } catch {
+      const redacted = redactRuntimeLog(line);
+      console.warn(`[${runtime.name}] acp non-json stdout: ${redacted}`);
+      outputChunks.push(line);
+    }
+  });
+  const stderrTask = readLines(proc.stderr, (line) => {
+    debugLog?.write('process.stderr', { line });
+    stderrChunks.push(line);
+    console.warn(`[${runtime.name}] stderr: ${redactRuntimeLog(line)}`);
+  });
+
+  const actionTimer = setInterval(() => {
+    void input.getAction?.().then((action) => {
+      if (!action || completed || stoppedByAction) return;
+      stoppedByAction = action;
+      if (sessionId) {
+        proc.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'session/cancel', params: { sessionId } })}\n`);
+      }
+      stopNodeProcess(proc);
+    }).catch(() => {});
+  }, 1000);
+
+  try {
+    console.log(`[${runtime.name}] acp initialize start`);
+    await emitActivity(input, { kind: 'working', title: 'Initializing runtime', detail: 'ACP initialize' });
+    const initialized = await send('initialize', {
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo: { name: 'pal', version: '0.1.0' },
+    }) as Record<string, unknown>;
+    const capabilities = (initialized.agentCapabilities ?? {}) as Record<string, unknown>;
+    const sessionCapabilities = (capabilities.sessionCapabilities ?? {}) as Record<string, unknown>;
+    console.log(`[${runtime.name}] acp initialize ok capabilities=${JSON.stringify({ resume: Boolean(sessionCapabilities.resume), loadSession: Boolean(capabilities.loadSession) })}`);
+    const sessionParams = { cwd: procCwd, mcpServers: [] };
+    let session: Record<string, unknown>;
+    if (input.runtimeSessionId && sessionCapabilities.resume) {
+      console.log(`[${runtime.name}] acp session/resume start sessionId=${input.runtimeSessionId}`);
+      session = await send('session/resume', { sessionId: input.runtimeSessionId, ...sessionParams }) as Record<string, unknown>;
+      sessionId = input.runtimeSessionId;
+    } else if (input.runtimeSessionId && capabilities.loadSession) {
+      console.log(`[${runtime.name}] acp session/load start sessionId=${input.runtimeSessionId}`);
+      session = await send('session/load', { sessionId: input.runtimeSessionId, ...sessionParams }) as Record<string, unknown>;
+      sessionId = input.runtimeSessionId;
+    } else {
+      console.log(`[${runtime.name}] acp session/new start cwd=${procCwd}`);
+      session = await send('session/new', sessionParams) as Record<string, unknown>;
+      if (typeof session.sessionId === 'string') sessionId = session.sessionId;
+    }
+    if (!sessionId) throw new Error('ACP session did not provide a sessionId');
+    console.log(`[${runtime.name}] acp session ready sessionId=${sessionId}`);
+    await emitActivity(input, { kind: 'lifecycle', title: 'Runtime session ready', detail: sessionId, metadata: { protocol: 'acp' } });
+
+    console.log(`[${runtime.name}] acp session/prompt start promptChars=${prompt.length}`);
+    await emitActivity(input, { kind: 'working', title: 'Prompt sent', detail: `${prompt.length} chars` });
+    await send('session/prompt', {
+      sessionId,
+      prompt: [{ type: 'text', text: prompt }],
+    });
+    completed = true;
+    console.log(`[${runtime.name}] acp session/prompt completed outputChunks=${outputChunks.length} stderrLines=${stderrChunks.length}`);
+    await emitActivity(input, { kind: 'lifecycle', title: 'Runtime completed', detail: `${outputChunks.length} output chunks` });
+  } finally {
+    clearInterval(actionTimer);
+    proc.stdin.end();
+    stopNodeProcess(proc);
+  }
+
+  const exitCode = await Promise.race([
+    new Promise<number | null>((resolve) => proc.once('exit', (code) => resolve(code))),
+    sleep(3000).then(() => null),
+  ]);
+  debugLog?.write('process.exit', { exitCode, stoppedByAction });
+  await Promise.allSettled([stdoutTask, stderrTask]);
+  const output = [outputChunks.join(''), stderrChunks.join('\n')].filter(Boolean).join('\n');
+  console.log(`[${runtime.name}] output length=${output.length}`);
+  const result = { output, runtimeSessionId: sessionId, exitCode: stoppedByAction ? exitCode : 0, stoppedByAction };
+  debugLog?.write('runtime.result', result);
+  debugLog?.close();
+  return result;
+}
+
 async function waitForExitOrAction(
   proc: ReturnType<typeof Bun.spawn>,
   input: AgentRuntimeRunInput,
@@ -233,33 +943,47 @@ export async function runAgentRuntime(
   const prompt = runtime.buildPrompt(input);
   const args = runtime.buildArgs(input);
   const procCwd = runtime.buildCwd?.(input) ?? runtimeCwd(input);
+  const debugLog = RuntimeDebugLogger.create(runtime, input, prompt, args, procCwd);
   console.log(`[${runtime.name}] run agent=${input.agent} chat=${input.message.chat_name} message=${input.message.id} cwd=${procCwd} projectCwd=${runtimeProjectCwd(input)} dryRun=${input.dryRun} extraArgs=[${input.extraArgs.join(', ')}]`);
+  await emitActivity(input, { kind: 'working', title: 'Run accepted', detail: `${runtime.name} runtime starting in ${procCwd}` });
 
   if (input.dryRun) {
     console.log(`[${runtime.name}] dry-run mode, skipping spawn`);
+    await emitActivity(input, { kind: 'lifecycle', title: 'Dry run', detail: 'Runtime spawn skipped' });
     const [subcommand, ...restArgs] = args;
     const renderedArgs = [
       subcommand,
       ...restArgs.map((arg) => JSON.stringify(arg)),
     ].filter(Boolean).join(' ');
     await input.onStart?.(null);
-    return {
+    const result = {
       output: `[dry-run] ${runtime.command}${renderedArgs ? ` ${renderedArgs}` : ''}`,
       exitCode: 0,
       stoppedByAction: null,
       runtimeSessionId: input.runtimeSessionId ?? null,
     };
+    debugLog?.write('runtime.result', result);
+    debugLog?.close();
+    return result;
   }
 
+  const baseEnv = input.runtimeEnv ?? process.env;
   const env = {
-    ...process.env,
+    ...baseEnv,
     PAL_SERVER: input.serverUrl,
     PAL_AGENT: input.agent,
     ...(input.localDaemonUrl ? { LOCK_DAEMON_URL: input.localDaemonUrl } : {}),
     ...(input.localDaemonToken ? { LOCK_DAEMON_TOKEN: input.localDaemonToken } : {}),
-    ...(input.privateCliBinDir ? { PAL_CLI: join(input.privateCliBinDir, 'pal'), PATH: `${input.privateCliBinDir}:${process.env.PATH ?? ''}` } : {}),
+    ...(input.privateCliBinDir ? buildPrivateCliEnv(input.privateCliBinDir, baseEnv.PATH ?? '') : {}),
+    ...(runtime.buildEnv?.(input) ?? {}),
   };
   console.log(`[${runtime.name}] spawning: ${runtime.command} ${args.map((a) => JSON.stringify(a)).join(' ')}`);
+  if (runtime.capabilities.protocol === 'acp') {
+    return runAcpAgentRuntime(runtime, input, prompt, args, procCwd, env, debugLog);
+  }
+  const envSummary = runtimeEnvSummary(runtime.command, env);
+  console.log(`[${runtime.name}] env ${JSON.stringify(envSummary)}`);
+  debugLog?.write('process.env_summary', envSummary);
   const proc = Bun.spawn([runtime.command, ...args], {
     cwd: procCwd,
     stdout: 'pipe',
@@ -269,14 +993,49 @@ export async function runAgentRuntime(
   });
 
   console.log(`[${runtime.name}] spawned pid=${proc.pid}`);
+  debugLog?.write('process.spawned', { pid: proc.pid });
   await input.onStart?.(proc.pid);
+  await emitActivity(input, { kind: 'working', title: 'Runtime process started', detail: `pid ${proc.pid}` });
+
+  const stdoutLines: string[] = [];
+  const stderrLines: string[] = [];
+  const collectLines = async (stream: ReadableStream<Uint8Array>, onLine: (line: string) => void): Promise<string> => {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let text = '';
+    for await (const chunk of stream) {
+      const part = decoder.decode(chunk, { stream: true });
+      text += part;
+      buffer += part;
+      let newline = buffer.indexOf('\n');
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line) onLine(line);
+        newline = buffer.indexOf('\n');
+      }
+    }
+    const rest = `${buffer}${decoder.decode()}`.trim();
+    if (rest) onLine(rest);
+    return text;
+  };
+  const stdoutTask = collectLines(proc.stdout, (line) => {
+    stdoutLines.push(line);
+    const activity = activityFromRuntimeJson(line);
+    if (activity) void emitActivity(input, activity);
+  });
+  const stderrTask = collectLines(proc.stderr, (line) => {
+    stderrLines.push(line);
+    void emitActivity(input, { kind: 'error', title: 'Runtime stderr', detail: truncateActivityText(line) });
+  });
+
   const status = await waitForExitOrAction(proc, input);
   console.log(`[${runtime.name}] process exited exitCode=${status.exitCode} stoppedByAction=${status.stoppedByAction ?? '-'}`);
+  debugLog?.write('process.exit', status);
 
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
+  const [stdout, stderr] = await Promise.all([stdoutTask, stderrTask]);
+  debugLog?.write('process.stdout', { text: stdout });
+  debugLog?.write('process.stderr', { text: stderr });
 
   const parsed = runtime.parseOutput?.({ stdout, stderr, input }) ?? {
     output: [stdout.trim(), stderr.trim()].filter(Boolean).join('\n'),
@@ -284,7 +1043,15 @@ export async function runAgentRuntime(
   };
   const output = parsed.output;
   console.log(`[${runtime.name}] output length=${output.length}`);
-  return { output, runtimeSessionId: parsed.runtimeSessionId ?? input.runtimeSessionId ?? null, ...status };
+  const result = { output, runtimeSessionId: parsed.runtimeSessionId ?? input.runtimeSessionId ?? null, ...status };
+  await emitActivity(input, {
+    kind: status.stoppedByAction ? 'lifecycle' : status.exitCode === 0 ? 'lifecycle' : 'error',
+    title: status.stoppedByAction ? `Run ${status.stoppedByAction}` : status.exitCode === 0 ? 'Run completed' : 'Run failed',
+    detail: `${stdoutLines.length} stdout events · ${stderrLines.length} stderr lines`,
+  });
+  debugLog?.write('runtime.result', result);
+  debugLog?.close();
+  return result;
 }
 
 export type RuntimeDriver = AgentRuntime;