@applica-software-guru/sdd-core 1.8.2 → 1.8.3

package/dist/scaffold/templates.generated.js

@@ -228,13 +228,14 @@ name: sdd-remote
 description: >
   Remote sync workflow for Story Driven Development. Use when the user asks
   to update local state from remote changes, process remote drafts, and push
-  enriched items back.
+  enriched items back. Also applies when running a remote worker job (enrich
+  or sync).
 license: MIT
 compatibility: Requires sdd CLI (npm i -g @applica-software-guru/sdd)
 allowed-tools: Bash(sdd:*) Read Glob Grep
 metadata:
   author: applica-software-guru
-  version: "1.0"
+  version: "1.1"
 ---
 
 # SDD Remote - Pull, Enrich, Push
@@ -244,6 +245,9 @@ metadata:
 Use this skill to synchronize local SDD docs with remote updates, enrich draft content,
 and publish the enriched result to remote in active states.
 
+This skill also applies when a **remote worker job** is dispatched from SDD Flow, as the
+worker runs these same workflows on behalf of the user.
+
 ## Detection
 
 This workflow applies when:
@@ -251,79 +255,91 @@ This workflow applies when:
 - \`.sdd/config.yaml\` exists in the project root
 - The user asks to update local state from remote, pull pending CRs/bugs/docs,
   enrich drafts, or push pending remote updates
+- A remote worker job prompt instructs you to follow this workflow
 
-## Workflow
+## Workflows
+
+### Enrich Workflow (CR)
 
-Follow this sequence in order:
+Follow this sequence to enrich a draft Change Request:
 
-1. Verify remote configuration
+1. Pull remote updates:
 
 \`\`\`bash
-test -f .sdd/config.yaml && sdd remote status
+sdd pull --crs-only
 \`\`\`
 
-If remote is not configured or disconnected, run:
+3. Generate draft TODO list:
 
 \`\`\`bash
-sdd remote init
+sdd drafts
 \`\`\`
 
-Then stop and ask the user for URL/API key if needed.
+4. Enrich the draft with technical details, acceptance criteria, edge cases, and
+   any relevant information from the project documentation and comments.
 
-2. Pull remote updates (docs + CRs + bugs)
+5. Transition the enriched CR to pending:
 
 \`\`\`bash
-sdd pull
+sdd mark-drafts-enriched
 \`\`\`
 
-Optional scoped pulls:
+This performs: \`draft → pending\`
+
+6. Push the enriched content:
 
 \`\`\`bash
-sdd pull --docs-only
-sdd pull --crs-only
-sdd pull --bugs-only
+sdd push
 \`\`\`
 
-3. Generate draft TODO list for your coding agent
+### Enrich Workflow (Document)
+
+Follow this sequence to enrich a document:
+
+1. Pull remote updates:
 
 \`\`\`bash
-sdd drafts
+sdd pull --docs-only
 \`\`\`
 
-This command lists all local draft docs, CRs, and bugs and prints a minimal TODO-style prompt.
-Give that prompt to your coding agent. If additional context is needed, the agent can fetch it directly from project files.
+3. Locate the document file in \`product/\` or \`system/\` and update its content
+   with the enriched version.
 
-4. Transition enriched drafts to active states
+4. Push the enriched content:
 
 \`\`\`bash
-sdd mark-drafts-enriched
+sdd push
 \`\`\`
 
-This performs:
+If the document was in \`draft\` status, it will transition to \`new\` on the server.
+
+### Sync Workflow (Project-level)
 
-- Document: \`draft -> new\`
-- Change Request: \`draft -> pending\`
-- Bug: \`draft -> open\`
+Follow this sequence for a full project sync (all pending items):
 
-5. Push local pending updates to remote
+1. Pull the latest specs:
 
 \`\`\`bash
-sdd push
+sdd pull
 \`\`\`
 
-6. Verify final remote sync state
+3. Run the \`sdd\` skill — it handles the full loop: open bugs, pending CRs,
+   documentation sync, code implementation, mark-synced, and commit.
+
+4. Push:
 
 \`\`\`bash
-sdd remote status
+sdd push
 \`\`\`
 
 ## Rules
 
 1. Always check remote configuration before pull/push (\`sdd remote status\`)
-2. Do not use \`sdd push --all\` unless the user explicitly asks for a full reseed
-3. If pull reports conflicts, do not overwrite local files blindly; report conflicts and ask how to proceed
-4. Do not edit files inside \`.sdd/\` manually
-5. Keep status transitions explicit: enrich first, then \`sdd mark-drafts-enriched\`, then push
+3. Do not use \`sdd push --all\` unless the user explicitly asks for a full reseed
+4. If pull reports conflicts, do not overwrite local files blindly; report conflicts and ask how to proceed
+5. Do not edit files inside \`.sdd/\` manually
+6. Keep status transitions explicit: enrich first, then \`sdd mark-drafts-enriched\`, then push
+7. **Always commit before pushing** when the sync workflow makes code changes
 
 ## Related commands
 
@@ -332,6 +348,8 @@ sdd remote status
 - \`sdd pull\`
 - \`sdd drafts\`
 - \`sdd mark-drafts-enriched\`
+- \`sdd sync\`
+- \`sdd mark-synced\`
 - \`sdd push\`
 `;
 exports.FILE_FORMAT_REFERENCE = `# File Format and Status Lifecycle

package/dist/scaffold/templates.generated.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.generated.js","sourceRoot":"","sources":["../../src/scaffold/templates.generated.ts"],"names":[],"mappings":";AAAA,6DAA6D;AAC7D,qEAAqE;;;AAExD,QAAA,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyGhC,CAAC;AAEW,QAAA,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiHnC,CAAC;AAEW,QAAA,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8GvC,CAAC;AAEW,QAAA,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiEpC,CAAC;AAEW,QAAA,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BxC,CAAC;AAEW,QAAA,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6B7B,CAAC"}
+{"version":3,"file":"templates.generated.js","sourceRoot":"","sources":["../../src/scaffold/templates.generated.ts"],"names":[],"mappings":";AAAA,6DAA6D;AAC7D,qEAAqE;;;AAExD,QAAA,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyGhC,CAAC;AAEW,QAAA,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiHnC,CAAC;AAEW,QAAA,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgIvC,CAAC;AAEW,QAAA,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiEpC,CAAC;AAEW,QAAA,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BxC,CAAC;AAEW,QAAA,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6B7B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applica-software-guru/sdd-core",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "Core library for Story Driven Development",
   "author": "Bruno Fortunato <bruno.fortunato@applica.guru>",
   "main": "dist/index.js",

package/src/agent/agent-defaults.ts

@@ -1,6 +1,6 @@
 export const DEFAULT_AGENTS: Record<string, string> = {
-  claude: 'claude -p "$(cat $PROMPT_FILE)" --dangerously-skip-permissions --verbose',
-  codex: 'codex -q "$(cat $PROMPT_FILE)"',
+  claude: 'claude -p "$(cat $PROMPT_FILE)" --permission-mode auto --verbose --model $MODEL',
+  codex: 'codex -q "$(cat $PROMPT_FILE)" -m $MODEL',
   opencode: 'opencode -p "$(cat $PROMPT_FILE)"',
 };
 

package/src/agent/agent-runner.ts

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawn, type ChildProcess } from 'node:child_process';
 import { writeFile, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -9,38 +9,164 @@ export interface AgentRunnerOptions {
   root: string;
   prompt: string;
   agent: string;
+  model?: string;
   agents?: Record<string, string>;
   onOutput?: (data: string) => void;
 }
 
-export async function runAgent(options: AgentRunnerOptions): Promise<number> {
-  const { root, prompt, agent, agents, onOutput } = options;
+/** Handle returned by startAgent() for interactive worker mode. */
+export interface AgentRunnerHandle {
+  /** Resolves with the exit code when the agent process exits. */
+  exitPromise: Promise<number>;
+  /** Write data to the agent's stdin (for Q&A relay). */
+  writeStdin: (data: string) => void;
+  /** Kill the agent process. */
+  kill: () => void;
+  /** Path to the temp prompt file (cleaned up on exit). */
+  promptFile: string;
+}
+
+/**
+ * Extract human-readable text from a single stream-json NDJSON line.
+ * Returns the text to emit, or null if the line should be suppressed.
+ * Falls back to the raw line if it is not valid JSON (e.g. stderr noise).
+ */
+function extractStreamJsonText(line: string): string | null {
+  let event: unknown;
+  try {
+    event = JSON.parse(line);
+  } catch {
+    // Not JSON — pass raw (e.g. stderr lines from subprocesses)
+    return line;
+  }
+
+  if (typeof event !== 'object' || event === null || !('type' in event)) {
+    return null;
+  }
+
+  const { type } = event as Record<string, unknown>;
+
+  if (type === 'assistant') {
+    const message = (event as Record<string, unknown>).message;
+    if (typeof message === 'object' && message !== null && 'content' in message) {
+      const content = (message as Record<string, unknown>).content;
+      if (Array.isArray(content)) {
+        const texts = content
+          .filter((b): b is { type: string; text: string } => b?.type === 'text' && typeof b?.text === 'string')
+          .map((b) => b.text);
+        return texts.length > 0 ? texts.join('') : null;
+      }
+    }
+    return null;
+  }
+
+  if (type === 'result') {
+    const result = (event as Record<string, unknown>).result;
+    if (typeof result === 'string' && result.trim()) {
+      return result;
+    }
+    return null;
+  }
+
+  // Suppress system/init/tool events — not useful for display
+  return null;
+}
+
+/**
+ * Attach NDJSON-parsing stream handlers to a child process.
+ * Each complete JSON line is parsed and the extracted text forwarded to `sink`.
+ * stderr lines are forwarded raw (they are not stream-json).
+ */
+function pipeWithNdjsonParsing(
+  child: ChildProcess,
+  sink: (text: string) => void,
+): void {
+  if (child.stdout) {
+    let buf = '';
+    child.stdout.on('data', (data: Buffer) => {
+      buf += data.toString();
+      const lines = buf.split('\n');
+      buf = lines.pop() ?? '';
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        const text = extractStreamJsonText(line);
+        if (text) sink(text);
+      }
+    });
+    child.stdout.on('end', () => {
+      if (buf.trim()) {
+        const text = extractStreamJsonText(buf);
+        if (text) sink(text);
+      }
+    });
+  }
+
+  if (child.stderr) {
+    child.stderr.on('data', (data: Buffer) => sink(data.toString()));
+  }
+}
+
+async function prepareAgent(options: AgentRunnerOptions): Promise<{ command: string; tmpFile: string; isClaudeAgent: boolean }> {
+  const { prompt, agent, model, agents } = options;
 
   const template = resolveAgentCommand(agent, agents);
   if (!template) {
     throw new Error(`Unknown agent "${agent}". Available: ${Object.keys(agents ?? {}).join(', ') || 'claude, codex, opencode'}`);
   }
 
-  // Write prompt to temp file (too large for CLI arg)
   const tmpFile = join(tmpdir(), `sdd-prompt-${randomBytes(6).toString('hex')}.md`);
   await writeFile(tmpFile, prompt, 'utf-8');
 
-  // Replace $PROMPT_FILE with the temp file path in the command template
-  const command = template.replace(/\$PROMPT_FILE/g, tmpFile);
+  let command = template.replace(/\$PROMPT_FILE/g, tmpFile);
+  if (model) {
+    command = command.replace(/\$MODEL/g, model);
+    // If template doesn't have $MODEL but model is specified, inject --model flag
+    if (!template.includes('$MODEL')) {
+      command = command.replace(/^(\S+)/, `$1 --model ${model}`);
+    }
+  } else {
+    // Remove $MODEL placeholder and surrounding flags if not provided
+    command = command.replace(/--model\s+\$MODEL\s*/g, '');
+    command = command.replace(/\$MODEL\s*/g, '');
+  }
+
+  // For the claude CLI: switch to stream-json output for real-time streaming.
+  // --verbose is required alongside --output-format stream-json when using -p.
+  const isClaudeAgent = command.trimStart().startsWith('claude');
+  if (isClaudeAgent) {
+    // Ensure --verbose is present (required by stream-json in print mode)
+    if (!command.includes('--verbose')) {
+      command = command.trimEnd() + ' --verbose';
+    }
+    command = command.trimEnd() + ' --output-format stream-json';
+  }
+
+  return { command, tmpFile, isClaudeAgent };
+}
+
+export async function runAgent(options: AgentRunnerOptions): Promise<number> {
+  const { root, onOutput } = options;
+  const { command, tmpFile, isClaudeAgent } = await prepareAgent(options);
 
   try {
     const exitCode = await new Promise<number>((resolve, reject) => {
+      // For claude with stream-json we always pipe stdout so we can parse NDJSON.
+      // For other agents we inherit stdio when no onOutput is provided.
+      const usesPipe = isClaudeAgent || !!onOutput;
       const child = spawn(command, {
         cwd: root,
         shell: true,
-        stdio: onOutput ? ['inherit', 'pipe', 'pipe'] : 'inherit',
+        stdio: usesPipe ? ['inherit', 'pipe', 'pipe'] : 'inherit',
       });
 
-      if (onOutput && child.stdout) {
-        child.stdout.on('data', (data: Buffer) => onOutput(data.toString()));
-      }
-      if (onOutput && child.stderr) {
-        child.stderr.on('data', (data: Buffer) => onOutput(data.toString()));
+      if (usesPipe) {
+        const sink = onOutput ?? ((text: string) => process.stdout.write(text));
+        if (isClaudeAgent) {
+          pipeWithNdjsonParsing(child, sink);
+        } else {
+          if (child.stdout) child.stdout.on('data', (data: Buffer) => sink(data.toString()));
+          if (child.stderr) child.stderr.on('data', (data: Buffer) => sink(data.toString()));
+        }
       }
 
       child.on('error', reject);
@@ -52,3 +178,49 @@ export async function runAgent(options: AgentRunnerOptions): Promise<number> {
     await unlink(tmpFile).catch(() => {});
   }
 }
+
+/**
+ * Start an agent in interactive mode (stdin piped for Q&A).
+ * Returns a handle for writing to stdin, killing the process, and awaiting exit.
+ */
+export async function startAgent(options: AgentRunnerOptions): Promise<AgentRunnerHandle> {
+  const { root, onOutput } = options;
+  const { command, tmpFile, isClaudeAgent } = await prepareAgent(options);
+
+  const child: ChildProcess = spawn(command, {
+    cwd: root,
+    shell: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  const sink = onOutput ?? ((text: string) => process.stdout.write(text));
+  if (isClaudeAgent) {
+    pipeWithNdjsonParsing(child, sink);
+  } else {
+    if (child.stdout) child.stdout.on('data', (data: Buffer) => sink(data.toString()));
+    if (child.stderr) child.stderr.on('data', (data: Buffer) => sink(data.toString()));
+  }
+
+  const exitPromise = new Promise<number>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', (code) => {
+      unlink(tmpFile).catch(() => {});
+      resolve(code ?? 1);
+    });
+  });
+
+  return {
+    exitPromise,
+    writeStdin: (data: string) => {
+      if (child.stdin && !child.stdin.destroyed) {
+        child.stdin.write(data);
+      }
+    },
+    kill: () => {
+      if (!child.killed) {
+        child.kill('SIGTERM');
+      }
+    },
+    promptFile: tmpFile,
+  };
+}

package/src/agent/worker-daemon.ts

@@ -0,0 +1,254 @@
+import { hostname } from 'node:os';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { ApiClientConfig } from '../remote/api-client.js';
+import type { WorkerState, WorkerJobAssignment } from '../remote/worker-types.js';
+import {
+  registerWorker,
+  workerHeartbeat,
+  workerPoll,
+  workerJobStarted,
+  workerJobOutput,
+  workerJobQuestion,
+  workerJobAnswers,
+  workerJobCompleted,
+} from '../remote/worker-client.js';
+import { startAgent } from './agent-runner.js';
+import { checkoutBranch, getCurrentBranch, getCurrentCommit, getJobChangedFiles } from '../git/git.js';
+
+export interface WorkerDaemonOptions {
+  root: string;
+  name?: string;
+  agent: string;
+  agents?: Record<string, string>;
+  apiConfig: ApiClientConfig;
+  onLog?: (message: string) => void;
+  renderPrompt?: (prompt: string) => string;
+}
+
+const HEARTBEAT_INTERVAL_MS = 15_000;
+const OUTPUT_FLUSH_INTERVAL_MS = 2_000;
+const QA_POLL_INTERVAL_MS = 2_000;
+const WORKER_STATE_FILE = 'worker.json';
+
+export async function startWorkerDaemon(options: WorkerDaemonOptions): Promise<void> {
+  const { root, agent, agents, apiConfig, onLog, renderPrompt } = options;
+  const workerName = options.name ?? hostname();
+  const sddDir = join(root, '.sdd');
+  const stateFile = join(sddDir, WORKER_STATE_FILE);
+
+  const log = onLog ?? ((msg: string) => process.stderr.write(`[worker] ${msg}\n`));
+  const shortId = (id: string) => id.slice(0, 8);
+
+  // --- Read current branch (informational — no checkout) ---
+  const branch = getCurrentBranch(root) ?? undefined;
+
+  // --- Register ---
+  log(`Registering worker "${workerName}" with agent "${agent}"${branch ? ` (branch: ${branch})` : ''}...`);
+  const registration = await registerWorker(apiConfig, workerName, agent, branch, {
+    hostname: hostname(),
+    platform: process.platform,
+    arch: process.arch,
+  });
+
+  const state: WorkerState = {
+    workerId: registration.id,
+    name: workerName,
+    registeredAt: registration.registered_at,
+  };
+  await writeFile(stateFile, JSON.stringify(state, null, 2), 'utf-8');
+  log(`Registered as worker ${shortId(registration.id)}`);
+
+  let running = true;
+  let currentJobKill: (() => void) | null = null;
+
+  // --- Graceful shutdown ---
+  const shutdown = async () => {
+    log('Shutting down...');
+    running = false;
+    if (currentJobKill) {
+      currentJobKill();
+    }
+    try {
+      await workerHeartbeat(apiConfig, registration.id, 'online');
+    } catch {
+      // best effort
+    }
+  };
+
+  process.on('SIGINT', () => { shutdown(); });
+  process.on('SIGTERM', () => { shutdown(); });
+
+  // --- Heartbeat loop ---
+  const heartbeatLoop = async () => {
+    while (running) {
+      try {
+        await workerHeartbeat(apiConfig, registration.id, currentJobKill ? 'busy' : 'online');
+      } catch (err) {
+        const msg = (err as Error).message;
+        if (!msg.includes('abort')) {
+          log(`Heartbeat error: ${msg}`);
+        }
+      }
+      await sleep(HEARTBEAT_INTERVAL_MS);
+    }
+  };
+
+  // --- Poll & execute loop ---
+  const pollLoop = async () => {
+    while (running) {
+      try {
+        const job = await workerPoll(apiConfig, registration.id);
+        if (job && running) {
+          await executeJob(job);
+        }
+      } catch (err) {
+        if (!running) break;
+        const msg = (err as Error).message;
+        // Don't log abort errors during shutdown
+        if (!msg.includes('abort')) {
+          log(`Poll error: ${msg}`);
+        }
+        await sleep(3_000);
+      }
+    }
+  };
+
+  // --- Job execution ---
+  const executeJob = async (job: WorkerJobAssignment) => {
+    const jobDesc = job.entity_type ? `${job.entity_type}/${job.entity_id}` : 'sync';
+    const jid = shortId(job.job_id);
+    log(`┌─ Job ${jid} (${jobDesc})`);
+    log(`│  Agent: ${job.agent}${job.model ? `  Model: ${job.model}` : ''}${job.branch ? `  Branch: ${job.branch}` : ''}`);
+    const promptPreview = job.prompt.split('\n').find(l => l.trim().length > 0) ?? '';
+    log(`└─ ${promptPreview.length > 80 ? promptPreview.slice(0, 80) + '…' : promptPreview}`);
+
+    // Checkout branch if the job explicitly requests one different from the current
+    if (job.branch && job.branch !== getCurrentBranch(root)) {
+      log(`Checking out branch "${job.branch}" for job ${job.job_id}...`);
+      try {
+        checkoutBranch(root, job.branch);
+      } catch (err) {
+        log(`Warning: could not checkout branch "${job.branch}": ${(err as Error).message}`);
+      }
+    }
+
+    // Capture git state before the job starts so we can diff at the end
+    const baseCommit = getCurrentCommit(root);
+
+    try {
+      await workerJobStarted(apiConfig, job.job_id);
+    } catch (err) {
+      log(`Failed to notify job start: ${(err as Error).message}`);
+    }
+
+    // Buffer for batched output
+    let outputBuffer: string[] = [];
+    let lastFlush = Date.now();
+    let lastAnswerSequence = 0;
+    let waitingForAnswer = false;
+
+    const flushOutput = async () => {
+      if (outputBuffer.length === 0) return;
+      const lines = outputBuffer.splice(0);
+      try {
+        await workerJobOutput(apiConfig, job.job_id, lines);
+      } catch (err) {
+        log(`Output flush error: ${(err as Error).message}`);
+      }
+    };
+
+    // Start the agent with interactive mode
+    const handle = await startAgent({
+      root,
+      prompt: job.prompt,
+      agent: job.agent,
+      model: job.model,
+      agents,
+      onOutput: (data: string) => {
+        // Split into lines but preserve partial lines
+        const lines = data.split('\n');
+        for (const line of lines) {
+          // Suppress the Claude CLI stdin warning — prompt is passed via -p flag,
+          // stdin is kept open only for Q&A relay and does not need initial data.
+          if (line.includes('no stdin data received') || line.includes('redirect stdin explicitly')) {
+            continue;
+          }
+          if (line.length > 0) {
+            outputBuffer.push(line);
+          }
+        }
+
+        // Flush if enough time has passed
+        if (Date.now() - lastFlush >= OUTPUT_FLUSH_INTERVAL_MS) {
+          lastFlush = Date.now();
+          flushOutput();
+        }
+      },
+    });
+
+    currentJobKill = handle.kill;
+
+    // Periodic output flush + answer polling loop
+    const flushAndPollLoop = async () => {
+      while (running) {
+        // Flush pending output
+        await flushOutput();
+        lastFlush = Date.now();
+
+        // If we detected a question, poll for answers
+        if (waitingForAnswer) {
+          try {
+            const answers = await workerJobAnswers(apiConfig, job.job_id, lastAnswerSequence);
+            if (answers.length > 0) {
+              for (const ans of answers) {
+                handle.writeStdin(ans.content + '\n');
+                lastAnswerSequence = ans.sequence;
+              }
+              waitingForAnswer = false;
+            }
+          } catch (err) {
+            log(`Answer poll error: ${(err as Error).message}`);
+          }
+        }
+
+        await sleep(QA_POLL_INTERVAL_MS);
+      }
+    };
+
+    // Run the flush/poll loop concurrently with the agent
+    const flushPromise = flushAndPollLoop();
+
+    try {
+      const exitCode = await handle.exitPromise;
+
+      // Final flush
+      running = true; // temporarily re-enable to allow final flush
+      await flushOutput();
+
+      const changedFiles = getJobChangedFiles(root, baseCommit);
+      const filesMsg = changedFiles.length > 0 ? `, ${changedFiles.length} file(s) changed` : '';
+      log(`Job ${jid} done — exit ${exitCode}${filesMsg}`);
+      await workerJobCompleted(apiConfig, job.job_id, exitCode, changedFiles);
+    } catch (err) {
+      log(`Job ${jid} error: ${(err as Error).message}`);
+      try {
+        const changedFiles = getJobChangedFiles(root, baseCommit);
+        await workerJobCompleted(apiConfig, job.job_id, 1, changedFiles);
+      } catch {
+        // best effort
+      }
+    } finally {
+      currentJobKill = null;
+    }
+  };
+
+  // --- Start concurrent loops ---
+  log(`Worker "${workerName}" is online. Waiting for jobs… (id: ${shortId(registration.id)})`);
+  await Promise.all([heartbeatLoop(), pollLoop()]);
+  log('Worker stopped.');
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}