thepopebot 1.2.76-beta.0 → 1.2.76-beta.10

package/api/index.js

@@ -3,7 +3,7 @@ import { createAgentJob } from '../lib/tools/create-agent-job.js';
 import { setWebhook } from '../lib/tools/telegram.js';
 import { getAgentJobStatus, fetchAgentJobLog } from '../lib/tools/github.js';
 import { getTelegramAdapter } from '../lib/channels/index.js';
-import { chat, summarizeAgentJob } from '../lib/ai/index.js';
+import { chat, chatStream, summarizeAgentJob } from '../lib/ai/index.js';
 import { createNotification } from '../lib/db/notifications.js';
 import { loadTriggers } from '../lib/triggers.js';
 import { verifyApiKey } from '../lib/db/api-keys.js';
@@ -211,19 +211,33 @@ async function handleTelegramWebhook(request) {
 /**
  * Process a normalized message through the AI layer with channel UX.
  * Message persistence is handled centrally by the AI layer.
+ *
+ * Uses chatStream() for progressive tool-call rendering when the adapter
+ * supports it (Telegram: sends each tool call as a message, reacts on completion).
+ * Falls back to chat() for adapters without streamChatResponse.
  */
 async function processChannelMessage(adapter, normalized) {
   await adapter.acknowledge(normalized.metadata);
   const stopIndicator = adapter.startProcessingIndicator(normalized.metadata);
 
   try {
-    const response = await chat(
-      normalized.threadId,
-      normalized.text,
-      normalized.attachments,
-      { userId: 'telegram', chatTitle: 'Telegram' }
-    );
-    await adapter.sendResponse(normalized.threadId, response, normalized.metadata);
+    if (adapter.streamChatResponse) {
+      const chunks = chatStream(
+        normalized.threadId,
+        normalized.text,
+        normalized.attachments,
+        { userId: 'telegram', chatTitle: 'Telegram' }
+      );
+      await adapter.streamChatResponse(normalized.metadata.chatId, chunks);
+    } else {
+      const response = await chat(
+        normalized.threadId,
+        normalized.text,
+        normalized.attachments,
+        { userId: 'telegram', chatTitle: 'Telegram' }
+      );
+      await adapter.sendResponse(normalized.threadId, response, normalized.metadata);
+    }
   } catch (err) {
     console.error('Failed to process message with AI:', err);
     await adapter

package/bin/cli.js

@@ -305,6 +305,31 @@ async function init() {
     console.log('  Created .claude/skills → ../skills/active');
   }
 
+  // Create .codex/skills → ../skills/active symlink
+  const codexSkillsLink = path.join(cwd, '.codex', 'skills');
+  if (!fs.existsSync(codexSkillsLink)) {
+    fs.mkdirSync(path.dirname(codexSkillsLink), { recursive: true });
+    createDirLink('../skills/active', codexSkillsLink);
+    console.log('  Created .codex/skills → ../skills/active');
+  }
+
+  // Create .gemini/skills → ../skills/active symlink
+  const geminiSkillsLink = path.join(cwd, '.gemini', 'skills');
+  if (!fs.existsSync(geminiSkillsLink)) {
+    fs.mkdirSync(path.dirname(geminiSkillsLink), { recursive: true });
+    createDirLink('../skills/active', geminiSkillsLink);
+    console.log('  Created .gemini/skills → ../skills/active');
+  }
+
+  // Create .kimi/skills → ../skills/active symlink
+  const kimiSkillsLink = path.join(cwd, '.kimi', 'skills');
+  if (!fs.existsSync(kimiSkillsLink)) {
+    fs.mkdirSync(path.dirname(kimiSkillsLink), { recursive: true });
+    createDirLink('../skills/active', kimiSkillsLink);
+    console.log('  Created .kimi/skills → ../skills/active');
+  }
+
+
   // Report backed-up files
   if (backedUp.length > 0) {
     console.log(`\n  Backed up ${backedUp.length} file(s) to ${path.relative(cwd, backupDir)}/`);
@@ -420,7 +445,7 @@ function reset(filePath) {
       console.log(`  ${destPath(file)}`);
     }
     console.log('\nUsage: thepopebot reset <file>');
-    console.log('Example: thepopebot reset agent-job/SOUL.md\n');
+    console.log('Example: thepopebot reset agent-job/SYSTEM.md\n');
     return;
   }
 
@@ -502,7 +527,7 @@ function diff(filePath) {
       console.log('  All files match package templates.');
     }
     console.log('\nUsage: thepopebot diff <file>');
-    console.log('Example: thepopebot diff agent-job/SOUL.md\n');
+    console.log('Example: thepopebot diff agent-job/SYSTEM.md\n');
     return;
   }
 

package/drizzle/0021_coding_agent_workspace.sql

@@ -0,0 +1 @@
+ALTER TABLE `code_workspaces` ADD `coding_agent` text;

package/drizzle/meta/_journal.json

@@ -148,6 +148,13 @@
       "when": 1774327178886,
       "tag": "0020_natural_fabian_cortez",
       "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "6",
+      "when": 1775865600000,
+      "tag": "0021_coding_agent_workspace",
+      "breakpoints": true
     }
   ]
 }

package/lib/ai/index.js

@@ -4,8 +4,10 @@ import { z } from 'zod';
 import { getAgentChat, getCodeChat } from './agent.js';
 import { createModel } from './model.js';
 import path from 'path';
+import { existsSync } from 'fs';
 import { PROJECT_ROOT } from '../paths.js';
 import { render_md } from '../utils/render-md.js';
+import { buildCodingAgentSystemPrompt } from './system-prompt.js';
 import { getChatById, createChat, saveMessage, updateChatTitle, linkChatToWorkspace } from '../db/chats.js';
 import { getConfig } from '../config.js';
 import { getSdkAdapter } from './sdk-adapters/index.js';
@@ -171,35 +173,41 @@ async function* chatStream(threadId, message, attachments = [], options = {}) {
     const workspace = getCodeWorkspaceById(workspaceId);
     const featureBranch = workspace?.featureBranch;
 
+    const needsSetup = !existsSync(path.join(repoDir, '.git'));
     const setupToolCallId = `setup-${workspaceId.slice(0, 8)}`;
     const setupArgs = { repo, branch, featureBranch };
-    yield { type: 'tool-call', toolCallId: setupToolCallId, toolName: 'set_up_workspace', args: setupArgs };
+
+    if (needsSetup) {
+      yield { type: 'tool-call', toolCallId: setupToolCallId, toolName: 'workspace', args: setupArgs };
+    }
 
     try {
-      await ensureWorkspaceRepo({ workspaceDir: repoDir, repo, branch, featureBranch });
+      const setupOutput = await ensureWorkspaceRepo({ workspaceDir: repoDir, repo, branch, featureBranch });
       ensureSkills(repoDir, isCodeMode ? 'code' : 'agent');
-      yield { type: 'tool-result', toolCallId: setupToolCallId, result: JSON.stringify({ result: `Workspace ready on ${featureBranch || branch}` }) };
+      if (needsSetup) {
+        const result = setupOutput || `Workspace ready on ${featureBranch || branch}`;
+        yield { type: 'tool-result', toolCallId: setupToolCallId, result };
+        persistMessage(threadId, 'assistant', JSON.stringify({
+          type: 'tool-invocation',
+          toolCallId: setupToolCallId,
+          toolName: 'workspace',
+          state: 'output-available',
+          input: setupArgs,
+          output: result,
+        }), options);
+      }
     } catch (err) {
-      yield { type: 'tool-result', toolCallId: setupToolCallId, result: JSON.stringify({ result: `Setup failed: ${err.message}` }) };
+      if (needsSetup) {
+        yield { type: 'tool-result', toolCallId: setupToolCallId, result: `Setup failed: ${err.message}` };
+      }
       throw err;
     }
 
     // 2. Session continuity
     const sessionId = readSessionId(wsBaseDir);
 
-    // 3. System prompt (agent mode: SOUL.md + SYSTEM.md, code mode: none)
-    let systemPrompt = null;
-    if (!isCodeMode) {
-      const soulPath = path.join(PROJECT_ROOT, 'agent-job/SOUL.md');
-      const systemPath = path.join(PROJECT_ROOT, 'agent-job/SYSTEM.md');
-      try {
-        const soul = render_md(soulPath) || '';
-        const system = render_md(systemPath) || '';
-        systemPrompt = [soul, system].filter(Boolean).join('\n\n') || null;
-      } catch {
-        // Files may not exist — proceed without system prompt
-      }
-    }
+    // 3. System prompt
+    const systemPrompt = buildCodingAgentSystemPrompt(isCodeMode ? 'code' : 'agent');
 
     // 4. Stream from SDK adapter
     let pendingText = '';
@@ -213,6 +221,8 @@ async function* chatStream(threadId, message, attachments = [], options = {}) {
         sessionId,
         permissionMode: codeModeType,
         attachments,
+        workspaceId,
+        chatMode: isCodeMode ? 'code' : 'agent',
       })) {
         // Write session ID on first meta chunk
         if (chunk.type === 'meta' && chunk.sessionId) {

package/lib/ai/sdk-adapters/CLAUDE.md

@@ -0,0 +1,113 @@
+# lib/ai/sdk-adapters/ — SDK Adapter System
+
+In-process SDK adapters that replace the legacy LangGraph + Docker path for chat. Each adapter wraps a coding agent's SDK and yields a unified chunk stream consumed by `chatStream()` in `lib/ai/index.js`.
+
+## Architecture
+
+```
+Browser → POST /stream/chat (api.js)
+  → chatStream() (index.js)
+    → getSdkAdapter() returns adapter function or null
+    → if adapter: workspace setup → SDK adapter streaming → DB persistence
+    → if null: falls back to legacy LangGraph/Docker path
+```
+
+The adapter is a pure stream translator — it receives a prompt and options, calls the SDK, and yields normalized chunks. Everything else (workspace setup, DB persistence, session continuity, system prompts) is handled by `chatStream()` in `index.js`.
+
+## Existing Adapter
+
+| File | Agent | SDK |
+|------|-------|-----|
+| `claude-code.js` | `claude-code` | `@anthropic-ai/claude-agent-sdk` |
+
+## Adding a New SDK Adapter
+
+### 1. Create the adapter file
+
+Create `{agent-name}.js` in this directory. Export a single async generator function:
+
+```js
+export async function* myAgentStream({ prompt, workspaceDir, systemPrompt, sessionId, permissionMode, attachments }) {
+  // ... call the SDK, yield chunks
+}
+```
+
+### 2. Required chunk types to yield
+
+The adapter MUST yield these chunk types for `chatStream()` and `api.js` to work correctly:
+
+| Chunk | Shape | When | Purpose |
+|-------|-------|------|---------|
+| `meta` | `{ type: 'meta', sessionId: string }` | First event | Session ID for continuity across messages. `chatStream()` writes this to disk via `writeSessionId()` so subsequent messages resume the session. |
+| `text` | `{ type: 'text', text: string }` | Text output | Streamed to UI as deltas. Accumulated by `chatStream()` and flushed to DB as assistant messages at tool boundaries and stream end. |
+| `tool-call` | `{ type: 'tool-call', toolCallId: string, toolName: string, args: object }` | Tool invocation starts | Triggers tool UI in the browser. May be yielded twice: once at start with `args: {}`, once at `content_block_stop` with complete args. `chatStream()` tracks these in `pendingToolCalls` for pairing with results. |
+| `tool-result` | `{ type: 'tool-result', toolCallId: string, result: string }` | Tool completes | Paired with the matching `tool-call` by `toolCallId`. `chatStream()` persists the pair as a `tool-invocation` JSON message in the DB. |
+| `result` | `{ type: 'result', text: string, cost?: number, duration?: number, subtype?: string }` | Stream ends | Final summary. Logged by `chatStream()`, not persisted or sent to UI. |
+
+Optional:
+| `unknown` | `{ type: 'unknown', raw: any }` | Unrecognized events | `api.js` renders these as collapsible boxes in the UI. Use for debugging unhandled SDK events. |
+
+### 3. Register in index.js
+
+Add the import and mapping in `getSdkAdapter()`:
+
+```js
+import { myAgentStream } from './my-agent.js';
+
+export function getSdkAdapter(agentType) {
+  if (agentType === 'claude-code') return claudeCodeStream;
+  if (agentType === 'my-agent') return myAgentStream;
+  return null;
+}
+```
+
+The `agentType` string comes from the `CODING_AGENT` config value set in the admin UI.
+
+### 4. Auth resolution
+
+Use `buildAgentAuthEnv(agentType)` from `lib/tools/docker.js` to get credentials from the settings DB. This returns `{ env: string[], backendApi: string }` where `env` is an array of `KEY=value` strings. Parse them into an env object:
+
+```js
+import { buildAgentAuthEnv } from '../../tools/docker.js';
+
+const env = { ...process.env };
+const { env: authEnvPairs } = buildAgentAuthEnv('my-agent');
+for (const pair of authEnvPairs) {
+  const eqIdx = pair.indexOf('=');
+  if (eqIdx > 0) env[pair.slice(0, eqIdx)] = pair.slice(eqIdx + 1);
+}
+```
+
+The agent's auth config (API keys, OAuth tokens, provider selection) is managed in the admin UI at `/admin/event-handler/coding-agents` and stored in the settings DB. `buildAgentAuthEnv()` reads it — you don't need to access the settings DB directly.
+
+### 5. Function parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `prompt` | `string` | User message text |
+| `workspaceDir` | `string` | Absolute path to git repo root (the SDK should execute here) |
+| `systemPrompt` | `string\|null` | System prompt for agent mode (null in code mode) |
+| `sessionId` | `string\|null` | Previous session ID to resume (null on first message) |
+| `permissionMode` | `string` | `'plan'` (read-only) or `'code'` (read-write). Map to the SDK's equivalent permission concept. |
+| `attachments` | `Array` | Image attachments: `{ category: 'image', mimeType, dataUrl }` |
+
+### 6. Session continuity contract
+
+Multi-turn conversation works via session IDs:
+
+1. First message: `sessionId` param is `null`. Adapter yields `{ type: 'meta', sessionId: '<new-id>' }`.
+2. `chatStream()` writes the session ID to `{workspaceBaseDir}/.claude-ttyd-sessions/7681`.
+3. Next message: `sessionId` param contains the saved ID. Adapter passes it to the SDK's resume mechanism.
+
+If the SDK doesn't support session resume, the adapter can ignore `sessionId` — but multi-turn context will be lost between messages.
+
+## What the adapter does NOT handle
+
+These are managed by `chatStream()` in `index.js` — adapters should not duplicate them:
+
+- **Workspace git setup** — `ensureWorkspaceRepo()` clones/checkouts before the adapter is called
+- **DB persistence** — `chatStream()` saves user messages, assistant text, and tool invocations
+- **Chat creation** — `chatStream()` creates the chat and workspace DB records
+- **Auto-titling** — `chatStream()` generates a title after the first message
+- **System prompt loading** — `chatStream()` calls `buildCodingAgentSystemPrompt()` and passes the result as `systemPrompt`
+- **Skill activation** — `ensureSkills()` runs before the adapter is called

package/lib/ai/sdk-adapters/claude-code.js

@@ -1,6 +1,10 @@
+import path from 'path';
+import fs from 'fs';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { getConfig } from '../../config.js';
 import { buildAgentAuthEnv } from '../../tools/docker.js';
+import { createAgentJobApiKey } from '../../db/api-keys.js';
+import { getAllAgentJobSecrets } from '../../db/config.js';
 
 /**
  * Claude Agent SDK adapter. Wraps the SDK's query() and yields
@@ -15,10 +19,61 @@ import { buildAgentAuthEnv } from '../../tools/docker.js';
  * @param {Array} [opts.attachments] - Image attachments
  * @yields {{ type: 'text'|'tool-call'|'tool-result'|'meta'|'result'|'unknown', ... }}
  */
-export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, sessionId, permissionMode, attachments }) {
+/**
+ * Encode an absolute path the same way Claude Code encodes cwd for session storage.
+ * Non-alphanumeric characters are replaced with '-'.
+ */
+function encodeCwd(absolutePath) {
+  return absolutePath.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+/**
+ * Ensure the interactive container can find SDK-created sessions on the shared volume.
+ *
+ * The SDK stores sessions at $HOME/.claude/projects/<encoded-cwd>/. The interactive
+ * container uses cwd=/home/coding-agent/workspace, but the SDK adapter uses
+ * cwd=/app/data/workspaces/workspace-XXX/workspace — different encoded paths.
+ *
+ * Creates a symlink so the interactive container's encoded path resolves to the
+ * SDK adapter's encoded path, both on the same volume.
+ */
+function ensureSessionSymlink(wsBaseDir, workspaceDir) {
+  const projectsDir = path.join(wsBaseDir, '.claude', 'projects');
+  const sdkEncoded = encodeCwd(workspaceDir);
+  const interactiveEncoded = encodeCwd('/home/coding-agent/workspace');
+
+  // Both point to the same dir — no symlink needed
+  if (sdkEncoded === interactiveEncoded) return;
+
+  fs.mkdirSync(path.join(projectsDir, sdkEncoded), { recursive: true });
+
+  const symlinkPath = path.join(projectsDir, interactiveEncoded);
+  try {
+    const existing = fs.readlinkSync(symlinkPath);
+    if (existing === sdkEncoded) return; // already correct
+    fs.unlinkSync(symlinkPath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      // It's a real directory (not a symlink) — don't touch it
+      if (err.code === 'EINVAL') return;
+    }
+  }
+
+  try {
+    fs.symlinkSync(sdkEncoded, symlinkPath);
+  } catch {}
+}
+
+export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, sessionId, permissionMode, attachments, workspaceId, chatMode }) {
+  // Point HOME at the workspace volume so the SDK stores session data on the
+  // shared volume (not the EH container's ephemeral filesystem).
+  const wsBaseDir = path.dirname(workspaceDir);
+  ensureSessionSymlink(wsBaseDir, workspaceDir);
+
   // Build a local env object with auth credentials from the settings DB.
   // Passed via the SDK's `env` option — no process.env mutation needed.
   const env = { ...process.env };
+  env.HOME = wsBaseDir;
   try {
     const { env: authEnvPairs } = buildAgentAuthEnv('claude-code');
     for (const pair of authEnvPairs) {
@@ -41,16 +96,32 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
     // Fall through — env may already have the right vars from process.env
   }
 
+  // Inject agent job secrets when in agent chat mode
+  if (chatMode === 'agent') {
+    const shortId = (workspaceId || '').replace(/-/g, '').slice(0, 8);
+    const { key: agentJobToken } = createAgentJobApiKey(`claude-code-sdk-${shortId}`);
+    env.AGENT_JOB_TOKEN = agentJobToken;
+    const appUrl = getConfig('APP_URL');
+    if (appUrl) env.APP_URL = appUrl;
+
+    // Inject plain secrets as env vars (oauth types are null — agent fetches via skill)
+    const jobSecrets = getAllAgentJobSecrets();
+    for (const { key, value } of jobSecrets) {
+      if (value !== null && !env[key]) {
+        env[key] = value;
+      }
+    }
+  }
+
   const options = {
     cwd: workspaceDir,
     env,
     includePartialMessages: true,
+    model: getConfig('CODING_AGENT_CLAUDE_CODE_MODEL') || undefined,
   };
 
-  // Permission mode → allowed tools
-  if (permissionMode === 'code') {
-    options.permissionMode = 'bypassPermissions';
-  }
+  // Permission mode: plan = read-only, anything else = full write access
+  options.permissionMode = permissionMode === 'plan' ? 'plan' : 'bypassPermissions';
 
   if (sessionId) options.resume = sessionId;
   if (systemPrompt) {
@@ -80,6 +151,8 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
 
   // Track tool call state for mapping stream events
   const activeToolCalls = new Map(); // index → { id, name, argsJson }
+  const toolNamesById = new Map(); // toolCallId → toolName (persists for tool-result lookup)
+  const activeThinkingBlocks = new Set(); // indices of active thinking blocks
 
   try {
     for await (const message of query({ prompt: sdkPrompt, options })) {
@@ -102,9 +175,13 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
           const block = event.content_block;
           if (block.type === 'tool_use') {
             activeToolCalls.set(event.index, { id: block.id, name: block.name, argsJson: '' });
+            toolNamesById.set(block.id, block.name);
             yield { type: 'tool-call', toolCallId: block.id, toolName: block.name, args: {} };
+          } else if (block.type === 'thinking') {
+            activeThinkingBlocks.add(event.index);
+            yield { type: 'thinking-start' };
           }
-          // Skip 'thinking', 'text' start (deltas handle text)
+          // Skip 'text' start (deltas handle text)
           continue;
         }
 
@@ -114,11 +191,17 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
           } else if (event.delta.type === 'input_json_delta') {
             const tc = activeToolCalls.get(event.index);
             if (tc) tc.argsJson += event.delta.partial_json;
+          } else if (event.delta.type === 'thinking_delta') {
+            yield { type: 'thinking', delta: event.delta.thinking };
           }
           continue;
         }
 
         if (event.type === 'content_block_stop') {
+          if (activeThinkingBlocks.has(event.index)) {
+            activeThinkingBlocks.delete(event.index);
+            yield { type: 'thinking-end' };
+          }
           const tc = activeToolCalls.get(event.index);
           if (tc && tc.argsJson) {
             try {
@@ -144,14 +227,23 @@ export async function* claudeCodeStream({ prompt, workspaceDir, systemPrompt, se
               : Array.isArray(block.content)
                 ? block.content.map(b => b.type === 'text' ? b.text : JSON.stringify(b)).join('\n')
                 : JSON.stringify(block.content);
-            yield { type: 'tool-result', toolCallId: block.tool_use_id, result: content };
+            yield { type: 'tool-result', toolCallId: block.tool_use_id, toolName: toolNamesById.get(block.tool_use_id), result: content };
           }
         }
         continue;
       }
 
       // ── assistant messages — redundant with streaming, skip ──
-      if (message.type === 'assistant') continue;
+      // But extract tool names so resumed tool-results can carry them.
+      if (message.type === 'assistant') {
+        const blocks = message.message?.content || [];
+        for (const block of blocks) {
+          if (block.type === 'tool_use' && block.id && block.name) {
+            toolNamesById.set(block.id, block.name);
+          }
+        }
+        continue;
+      }
 
       // ── result ──
       if (message.type === 'result') {

package/lib/ai/system-prompt.js

@@ -0,0 +1,16 @@
+import path from 'path';
+import { PROJECT_ROOT } from '../paths.js';
+import { render_md } from '../utils/render-md.js';
+
+/**
+ * Build the system prompt for a coding agent.
+ * @param {'agent'|'code'} mode - Chat mode
+ * @returns {string|null} Rendered system prompt, or null if not configured
+ */
+export function buildCodingAgentSystemPrompt(mode) {
+  const file = mode === 'agent'
+    ? path.join(PROJECT_ROOT, 'agent-job/SYSTEM.md')
+    : path.join(PROJECT_ROOT, 'coding-workspace/SYSTEM.md');
+  const rendered = render_md(file);
+  return rendered?.trim() || null;
+}

package/lib/ai/tools.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { createAgentJob } from '../tools/create-agent-job.js';
 
 import { getConfig } from '../config.js';
+import { buildCodingAgentSystemPrompt } from './system-prompt.js';
 
 const agentJobTool = tool(
   async ({ prompt }) => {
@@ -63,6 +64,7 @@ const agentChatCodingTool = tool(
         workspaceId,
         taskPrompt: prompt,
         mode,
+        systemPrompt: buildCodingAgentSystemPrompt('agent'),
         injectSecrets: true,
       });
 
@@ -124,6 +126,7 @@ const codeChatCodingTool = tool(
         containerName, repo, branch, featureBranch, workspaceId,
         taskPrompt: prompt,
         mode,
+        systemPrompt: buildCodingAgentSystemPrompt('code'),
       });
 
       const chunks = [{ type: 'meta', codingAgent, backendApi }];

package/lib/ai/workspace-setup.js

@@ -32,20 +32,24 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
   if (ghToken) env.GH_TOKEN = ghToken;
 
   const execOpts = { cwd: workspaceDir, env };
+  const log = [];
 
   // 1. Create workspace directory
   mkdirSync(workspaceDir, { recursive: true });
 
   // 2. Configure git to use GH_TOKEN for GitHub HTTPS URLs (mirrors setup-git.sh)
   if (ghToken) {
-    await run('gh', ['auth', 'setup-git'], execOpts);
+    const out = await run('gh', ['auth', 'setup-git'], execOpts);
+    if (out) log.push(out);
   }
 
   // 3. Clone if not already a git repo
   const hasGit = existsSync(path.join(workspaceDir, '.git'));
   if (!hasGit) {
     if (!repo) throw new Error('ensureWorkspaceRepo: repo is required for initial clone');
-    await run('git', ['clone', '--branch', branch || 'main', `https://github.com/${repo}`, '.'], execOpts);
+    const out = await run('git', ['clone', '--branch', branch || 'main', `https://github.com/${repo}`, '.'], execOpts);
+    log.push(`Cloned ${repo} (branch: ${branch || 'main'})`);
+    if (out) log.push(out);
   }
 
   // 3. Git identity (only if not already configured)
@@ -61,6 +65,7 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
         const email = user.email || `${user.id}+${user.login}@users.noreply.github.com`;
         await run('git', ['config', 'user.name', name], execOpts);
         await run('git', ['config', 'user.email', email], execOpts);
+        log.push(`Git identity: ${name} <${email}>`);
       } catch (err) {
         console.error('[workspace-setup] Failed to set git identity:', err.message);
       }
@@ -68,7 +73,7 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
   }
 
   // 4. Feature branch checkout
-  if (!featureBranch) return;
+  if (!featureBranch) return log.join('\n');
 
   // Already on the right branch locally?
   try {
@@ -77,8 +82,11 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
     const current = await run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], execOpts);
     if (current !== featureBranch) {
       await run('git', ['checkout', featureBranch], execOpts);
+      log.push(`Checked out ${featureBranch}`);
+    } else {
+      log.push(`Already on ${featureBranch}`);
     }
-    return;
+    return log.join('\n');
   } catch {
     // Branch doesn't exist locally — check remote
   }
@@ -88,15 +96,20 @@ export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureB
     if (remoteCheck) {
       // Remote branch exists — checkout tracking it
       await run('git', ['checkout', '-B', featureBranch, `origin/${featureBranch}`], execOpts);
+      log.push(`Checked out ${featureBranch} (tracking origin)`);
     } else {
       // Create new branch and push
       await run('git', ['checkout', '-b', featureBranch], execOpts);
-      await run('git', ['push', '-u', 'origin', featureBranch], execOpts);
+      const pushOut = await run('git', ['push', '-u', 'origin', featureBranch], execOpts);
+      log.push(`Created and pushed ${featureBranch}`);
+      if (pushOut) log.push(pushOut);
     }
   } catch (err) {
     console.error('[workspace-setup] Feature branch error:', err.message);
     throw err;
   }
+
+  return log.join('\n');
 }
 
 /**