@delegoapp/runner 0.1.0 → 0.5.0

package/README.md

@@ -23,7 +23,7 @@ All flags also accept the matching `DELEGO_*` environment variable.
 | `--relay-url` | `DELEGO_RELAY_URL` | (required) | Relay base URL |
 | `--pairing-token` | `DELEGO_PAIRING_TOKEN` | — | Single-use bearer, first run only (`drs_pair_*`) |
 | `--profile` | `DELEGO_PROFILE` | `default` | Credentials profile name |
-| `--workspace-root` | `DELEGO_WORKSPACE_ROOT` | `process.cwd()` | Where to clone/worktree repos |
+| `--workspace-root` | `DELEGO_WORKSPACE_ROOT` | `~/delego-runner/workspace` | Where to clone/worktree repos |
 | `--git-clone-base-url` | `DELEGO_GIT_CLONE_BASE_URL` | `git@github.com:` | Base for `git clone` |
 | `--codex-command` | `DELEGO_CODEX_COMMAND` | `codex` | Codex CLI executable |
 | `--codex-args` | `DELEGO_CODEX_ARGS` | `exec --sandbox workspace-write` | Codex args before prompt |

package/dist/config.js

@@ -1,9 +1,12 @@
 import { ADAPTERS, ADAPTERS_BY_ID, SUPPORTED_EXECUTOR_IDS, } from './executor/adapters/index.js';
 import { createRequire } from 'node:module';
-import { resolve } from 'node:path';
-const defaultHeartbeatIntervalMs = 10_000;
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+const defaultHeartbeatIntervalMs = 300_000;
 const defaultPollIntervalMs = 10_000;
 const defaultCancellationPollIntervalMs = 5_000;
+const defaultSafetySyncIntervalMs = 300_000;
+const defaultFallbackPollIntervalMs = 30_000;
 const defaultExecutorTimeoutMs = 30 * 60_000;
 const PROFILE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const DEFAULT_PROFILE = 'default';
@@ -114,10 +117,12 @@ export function readConfig(args, env = process.env) {
     const heartbeatIntervalMs = readNumberOption(args, env, '--heartbeat-interval-ms', 'DELEGO_HEARTBEAT_INTERVAL_MS', defaultHeartbeatIntervalMs);
     const pollIntervalMs = readNumberOption(args, env, '--poll-interval-ms', 'DELEGO_POLL_INTERVAL_MS', defaultPollIntervalMs);
     const cancellationPollIntervalMs = readNumberOption(args, env, '--cancellation-poll-interval-ms', 'DELEGO_CANCELLATION_POLL_INTERVAL_MS', defaultCancellationPollIntervalMs);
+    const safetySyncIntervalMs = readNumberOption(args, env, '--safety-sync-interval-ms', 'DELEGO_SAFETY_SYNC_INTERVAL_MS', defaultSafetySyncIntervalMs);
+    const fallbackPollIntervalMs = readNumberOption(args, env, '--fallback-poll-interval-ms', 'DELEGO_FALLBACK_POLL_INTERVAL_MS', defaultFallbackPollIntervalMs);
     const executorTimeoutMs = readNumberOption(args, env, '--executor-timeout-ms', 'DELEGO_EXECUTOR_TIMEOUT_MS', defaultExecutorTimeoutMs);
     const workspaceRoot = readArg(args, '--workspace-root') ??
         env.DELEGO_WORKSPACE_ROOT ??
-        process.cwd();
+        join(homedir(), 'delego-runner', 'workspace');
     const gitCloneBaseUrl = (readArg(args, '--git-clone-base-url') ??
         env.DELEGO_GIT_CLONE_BASE_URL ??
         'git@github.com:').replace(/\/+$/, '');
@@ -129,6 +134,8 @@ export function readConfig(args, env = process.env) {
         ['--heartbeat-interval-ms', heartbeatIntervalMs, 1_000],
         ['--poll-interval-ms', pollIntervalMs, 1_000],
         ['--cancellation-poll-interval-ms', cancellationPollIntervalMs, 1_000],
+        ['--safety-sync-interval-ms', safetySyncIntervalMs, 30_000],
+        ['--fallback-poll-interval-ms', fallbackPollIntervalMs, 5_000],
         ['--executor-timeout-ms', executorTimeoutMs, 1_000],
     ]) {
         if (!Number.isFinite(value) || value < minimum) {
@@ -145,6 +152,8 @@ export function readConfig(args, env = process.env) {
         heartbeatIntervalMs,
         pollIntervalMs,
         cancellationPollIntervalMs,
+        safetySyncIntervalMs,
+        fallbackPollIntervalMs,
         workspaceRoot: resolve(workspaceRoot),
         gitCloneBaseUrl,
         executors,

package/dist/executor/adapters/claude.js

@@ -6,6 +6,13 @@ const defaultArgs = [
     'stream-json',
     '--dangerously-skip-permissions',
 ];
+// Claude Code surfaces fatal startup conditions (invalid/inaccessible model,
+// etc.) either as a bare stdout line or as the text of an assistant event,
+// then exits with a non-zero code while the JSON stream's final `result`
+// event still reads `subtype: success`. Both code paths must mark the run
+// as failed so the pipeline can surface the real reason instead of "exit
+// code 1".
+const FATAL_ERROR_PATTERN = /There's an issue with the selected model[^\n]*/;
 function summarizeToolInput(name, input) {
     if (!input || typeof input !== 'object')
         return '';
@@ -30,10 +37,48 @@ function summarizeToolInput(name, input) {
     }
     return '';
 }
+function parseAskUserQuestion(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const record = input;
+    const questions = record.questions;
+    if (!Array.isArray(questions) || questions.length === 0)
+        return null;
+    const first = questions[0];
+    if (!first || typeof first !== 'object')
+        return null;
+    const q = first;
+    if (typeof q.question !== 'string' || !q.question.trim())
+        return null;
+    const rawOptions = Array.isArray(q.options) ? q.options : [];
+    const options = rawOptions
+        .map((opt) => {
+        if (!opt || typeof opt !== 'object')
+            return null;
+        const o = opt;
+        if (typeof o.label !== 'string' || !o.label.trim())
+            return null;
+        const description = typeof o.description === 'string' ? o.description : undefined;
+        return description ? { label: o.label, description } : { label: o.label };
+    })
+        .filter((o) => o !== null);
+    const pending = {
+        question: q.question,
+        options,
+    };
+    if (typeof q.header === 'string')
+        pending.header = q.header;
+    if (typeof q.multiSelect === 'boolean')
+        pending.multiSelect = q.multiSelect;
+    return pending;
+}
 function formatAssistantContent(content) {
     const lines = [];
     const replyParts = [];
     let progress = null;
+    let askUserQuestion = null;
+    let toolUseId = null;
+    let fatalError = null;
     for (const block of content) {
         if (!block || typeof block !== 'object')
             continue;
@@ -45,6 +90,11 @@ function formatAssistantContent(content) {
             replyParts.push(entry.text);
             if (!progress)
                 progress = entry.text.split(/\r?\n/)[0]?.trim() ?? null;
+            if (!fatalError) {
+                const match = entry.text.match(FATAL_ERROR_PATTERN);
+                if (match)
+                    fatalError = match[0];
+            }
         }
         else if (entry.type === 'tool_use' && typeof entry.name === 'string') {
             const detail = summarizeToolInput(entry.name, entry.input);
@@ -52,33 +102,77 @@ function formatAssistantContent(content) {
             lines.push(formatted);
             if (!progress)
                 progress = `${entry.name}${detail}`;
+            if (entry.name === 'AskUserQuestion') {
+                const parsed = parseAskUserQuestion(entry.input);
+                if (parsed) {
+                    askUserQuestion = parsed;
+                    toolUseId = typeof entry.id === 'string' ? entry.id : null;
+                }
+            }
         }
     }
     return {
         display: lines.join('\n'),
         progress,
         replyText: replyParts.length ? replyParts.join('\n\n') : null,
+        askUserQuestion,
+        toolUseId,
+        fatalError,
     };
 }
+function extractToolResult(content) {
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const entry = block;
+        if (entry.type === 'tool_result' &&
+            typeof entry.tool_use_id === 'string' &&
+            entry.tool_use_id.length > 0) {
+            return {
+                id: entry.tool_use_id,
+                isError: entry.is_error === true,
+            };
+        }
+    }
+    return null;
+}
 function formatStreamEvent(event) {
     const type = typeof event.type === 'string' ? event.type : '';
     if (type === 'system' && event.subtype === 'init') {
-        return { display: null, progress: null };
+        const sessionId = typeof event.session_id === 'string' ? event.session_id : null;
+        return { display: null, progress: null, sessionId };
     }
     if (type === 'assistant' &&
         event.message &&
         typeof event.message === 'object') {
         const content = event.message.content;
         if (Array.isArray(content)) {
-            const { display, progress, replyText } = formatAssistantContent(content);
+            const { display, progress, replyText, askUserQuestion, toolUseId, fatalError, } = formatAssistantContent(content);
             return {
                 display: display.length ? display : null,
                 progress,
                 finalReply: replyText,
+                askUserQuestion,
+                toolUseId,
+                fatalError,
             };
         }
     }
     if (type === 'user') {
+        if (event.message && typeof event.message === 'object') {
+            const content = event.message.content;
+            if (Array.isArray(content)) {
+                const toolResult = extractToolResult(content);
+                if (toolResult) {
+                    return {
+                        display: null,
+                        progress: null,
+                        toolResultId: toolResult.id,
+                        toolResultIsError: toolResult.isError,
+                    };
+                }
+            }
+        }
         return { display: null, progress: null };
     }
     if (type === 'result') {
@@ -90,7 +184,37 @@ function formatStreamEvent(event) {
             parts.push(`${(ms / 1000).toFixed(1)}s`);
         if (cost !== null)
             parts.push(`$${cost.toFixed(4)}`);
-        return { display: parts.join(' · '), progress: null };
+        // Claude Code emits a `permission_denials` array on the final result
+        // event listing every tool call that was denied. In non-interactive
+        // mode (--print --dangerously-skip-permissions), AskUserQuestion is
+        // always denied because there's no human at the terminal — and that
+        // denial is exactly the signal we want: the agent needs the user to
+        // answer. This is the authoritative end-of-run source for pending
+        // questions; tracking tool_use/tool_result pairs in the stream is
+        // best-effort and can miss the signal when Claude pivots to a text
+        // response after the denial.
+        let askUserQuestion = null;
+        let toolUseId = null;
+        if (Array.isArray(event.permission_denials)) {
+            for (const denial of event.permission_denials) {
+                if (!denial || typeof denial !== 'object')
+                    continue;
+                const d = denial;
+                if (d.tool_name !== 'AskUserQuestion')
+                    continue;
+                const parsed = parseAskUserQuestion(d.tool_input);
+                if (parsed) {
+                    askUserQuestion = parsed;
+                    toolUseId = typeof d.tool_use_id === 'string' ? d.tool_use_id : null;
+                }
+            }
+        }
+        return {
+            display: parts.join(' · '),
+            progress: null,
+            askUserQuestion,
+            toolUseId,
+        };
     }
     return { display: null, progress: null };
 }
@@ -106,7 +230,13 @@ export const claudeAdapter = {
         if (job.executionPreferences.model) {
             out.push('--model', job.executionPreferences.model);
         }
-        out.push(promptForJob(job));
+        if (job.resumeContext?.claudeSessionId) {
+            out.push('--resume', job.resumeContext.claudeSessionId);
+            out.push(job.resumeContext.userReply);
+        }
+        else {
+            out.push(promptForJob(job));
+        }
         return { command, args: out, summaryLabel: 'Claude' };
     },
     formatStdoutLine(line) {
@@ -118,6 +248,9 @@ export const claudeAdapter = {
             return formatStreamEvent(event);
         }
         catch {
+            if (FATAL_ERROR_PATTERN.test(trimmed)) {
+                return { display: line, progress: null, fatalError: trimmed };
+            }
             return { display: line, progress: null };
         }
     },

package/dist/executor/process.js

@@ -24,7 +24,7 @@ function forceKillProcessGroup(child) {
         child.kill('SIGKILL');
     }
 }
-export async function runExecutor(config, job, repositoryPath) {
+export async function runExecutor(config, job, repositoryPath, isCancelled) {
     const executorId = job.executionPreferences.executor;
     const adapter = ADAPTERS_BY_ID[executorId];
     const options = config.executors[executorId];
@@ -60,23 +60,43 @@ export async function runExecutor(config, job, repositoryPath) {
             terminateProcessGroup(child);
             setTimeout(() => forceKillProcessGroup(child), 5_000).unref();
         }, config.executorTimeoutMs);
-        const cancellationPoll = setInterval(() => {
-            pollCancellation(config, job)
-                .then((requested) => {
-                if (!requested || settled || cancelled) {
+        const cancellationPoll = isCancelled
+            ? setInterval(() => {
+                if (!isCancelled() || settled || cancelled) {
                     return;
                 }
                 cancelled = true;
                 terminateProcessGroup(child);
                 setTimeout(() => forceKillProcessGroup(child), 5_000).unref();
-            })
-                .catch((error) => {
-                const message = error instanceof Error ? error.message : String(error);
-                console.error(`cancellation poll failed for ${job.id}: ${message}`);
-            });
-        }, config.cancellationPollIntervalMs);
+            }, 200)
+            : setInterval(() => {
+                pollCancellation(config, job)
+                    .then((requested) => {
+                    if (!requested || settled || cancelled) {
+                        return;
+                    }
+                    cancelled = true;
+                    terminateProcessGroup(child);
+                    setTimeout(() => forceKillProcessGroup(child), 5_000).unref();
+                })
+                    .catch((error) => {
+                    const message = error instanceof Error ? error.message : String(error);
+                    console.error(`cancellation poll failed for ${job.id}: ${message}`);
+                });
+            }, config.cancellationPollIntervalMs);
         let stdoutLineBuffer = '';
         let finalReply = null;
+        let sessionId = null;
+        let fatalError = null;
+        // Track unanswered AskUserQuestion tool_use ids. Cleared by paired
+        // tool_result events. Whatever remains at executor exit is the live
+        // pending question.
+        const pendingQuestions = new Map();
+        // Once we've captured the first AskUserQuestion + sessionId we have
+        // everything needed to resume later; killing the executor now skips
+        // Claude's 4-retry "tool dismissed" dance and the subsequent text
+        // fallback. Tracks whether we've already issued the kill.
+        let killedForQuestion = false;
         const sendProgress = (summary) => {
             void reportProgress(config, job, summary.slice(0, 240), {
                 stream: 'stdout',
@@ -100,6 +120,37 @@ export async function runExecutor(config, job, repositoryPath) {
                 formatted.finalReply.trim()) {
                 finalReply = formatted.finalReply;
             }
+            if (typeof formatted.sessionId === 'string' && formatted.sessionId) {
+                sessionId = formatted.sessionId;
+            }
+            if (typeof formatted.fatalError === 'string' && formatted.fatalError) {
+                fatalError = formatted.fatalError;
+            }
+            if (formatted.askUserQuestion && formatted.toolUseId) {
+                pendingQuestions.set(formatted.toolUseId, formatted.askUserQuestion);
+                // Short-circuit the run as soon as we have a usable pause point:
+                // a pending question + a session id we can `--resume` from later.
+                // Without this, Claude sees the synthetic "dismissed" tool_result
+                // (no human at the terminal), retries AskUserQuestion 3-4 times,
+                // then writes the question as text — burning ~1 minute and
+                // spamming the timeline. The close handler still fires and
+                // pipeline routes to /jobs/await as the happy path.
+                if (!killedForQuestion && sessionId !== null) {
+                    killedForQuestion = true;
+                    terminateProcessGroup(child);
+                    setTimeout(() => forceKillProcessGroup(child), 5_000).unref();
+                }
+            }
+            if (typeof formatted.toolResultId === 'string' &&
+                formatted.toolResultId) {
+                // Only clear the pending question when the tool_result was a real
+                // answer. `is_error: true` is what Claude Code injects when
+                // AskUserQuestion is called in non-interactive mode (no human at
+                // the terminal) — the question is effectively still unanswered.
+                if (!formatted.toolResultIsError) {
+                    pendingQuestions.delete(formatted.toolResultId);
+                }
+            }
         };
         child.stdout.on('data', (chunk) => {
             stdout = appendBoundedOutput(stdout, chunk);
@@ -138,6 +189,7 @@ export async function runExecutor(config, job, repositoryPath) {
                 stdoutLineBuffer = '';
             }
             console.log(`executor: exited for ${job.id} with code ${exitCode ?? 'null'} signal ${signal ?? 'none'}`);
+            const pending = Array.from(pendingQuestions.values());
             finish({
                 exitCode,
                 signal,
@@ -146,10 +198,36 @@ export async function runExecutor(config, job, repositoryPath) {
                 timedOut,
                 cancelled,
                 finalReply,
+                sessionId,
+                pendingQuestion: pending.length > 0 ? pending[pending.length - 1] : null,
+                fatalError,
             });
         });
     });
 }
+const FAILURE_TAIL_MAX_LINES = 5;
+const FAILURE_TAIL_MAX_BYTES = 1_024;
+function lastMeaningfulTail(text) {
+    if (!text)
+        return null;
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim().length > 0);
+    if (lines.length === 0)
+        return null;
+    const tail = lines.slice(-FAILURE_TAIL_MAX_LINES).join('\n');
+    if (Buffer.byteLength(tail, 'utf8') <= FAILURE_TAIL_MAX_BYTES) {
+        return tail;
+    }
+    return tail.slice(-FAILURE_TAIL_MAX_BYTES);
+}
+export function pickFailureDetail(result) {
+    const finalReply = result.finalReply?.trim();
+    if (finalReply)
+        return finalReply;
+    return lastMeaningfulTail(result.stderr) ?? lastMeaningfulTail(result.stdout);
+}
 export function summarizeExecutorFailure(result) {
     if (result.cancelled) {
         return 'Executor was cancelled by relay request.';
@@ -157,5 +235,10 @@ export function summarizeExecutorFailure(result) {
     if (result.timedOut) {
         return 'Executor timed out and was terminated.';
     }
-    return `Executor failed with exit code ${result.exitCode ?? 'unknown'}.`;
+    if (result.fatalError) {
+        return result.fatalError;
+    }
+    const header = `Executor failed with exit code ${result.exitCode ?? 'unknown'}.`;
+    const detail = pickFailureDetail(result);
+    return detail ? `${header}\n\n${detail}` : header;
 }

package/dist/executor/prompt.js

@@ -2,8 +2,24 @@ import { promptThinkingInstruction } from '../thinking.js';
 export function promptForJob(job) {
     const thinkingInstruction = promptThinkingInstruction(job.executionPreferences.thinking);
     return [
+        // This directive must come first — before task content — so Claude enters
+        // execution with the correct mental model. When placed at the end, Claude
+        // has already oriented itself toward completing the task and ignores it,
+        // phrasing questions as plain text (which ends the job immediately).
+        [
+            'OPERATING MODE — THIS OVERRIDES ALL OTHER INSTRUCTIONS INCLUDING CLAUDE.md, AGENTS.md, AND ANY SKILL INSTRUCTIONS:',
+            'This task runs through the Delego runner. There IS a real user waiting in Linear, but plain text replies end the job immediately — the user sees your text but CANNOT reply to it.',
+            'DO NOT invoke any skills (brainstorming, feature-dev, TDD, etc.). Skills communicate via plain text, which does not work here. Ignore all skill invocation rules from CLAUDE.md.',
+            'To pause and ask the user anything, you MUST call the AskUserQuestion tool:',
+            '  • With options: for structured A/B/C choices.',
+            '  • Without options: for open-ended questions or design proposals — put your full markdown in the question field.',
+            'NEVER write a question as plain text in your response. If you do, the job will be marked complete and the user will have no way to answer.',
+            'The AskUserQuestion call WILL return an `is_error: true` "dismissed" tool_result — this is expected. STOP immediately when you see it. Do not retry, do not restate the question as text, do not continue with any other work. The runner delivers your question to the user and resumes your session with their answer.',
+        ].join('\n'),
+        '',
         `Linear issue: ${job.linearIssue.identifier}${job.linearIssue.title ? ` - ${job.linearIssue.title}` : ''}`,
         job.linearIssue.url ? `URL: ${job.linearIssue.url}` : null,
+        `If you create a pull request, start the PR title with: ${job.linearIssue.identifier}:`,
         '',
         `Requested executor: ${job.executionPreferences.executor}`,
         job.executionPreferences.model

package/dist/git/commit.js

@@ -1,5 +1,6 @@
 import { runCommand } from './command.js';
 import { changedFilePaths } from './workspace.js';
+const HEAD_FILE_LIST_LIMIT = 200;
 async function readGitValue(path, args) {
     const result = await runCommand('git', args, path);
     if (result.code !== 0) {
@@ -47,6 +48,43 @@ function commitBodyForJob(job, changedFiles) {
         .filter((part) => part !== null)
         .join('\n');
 }
+/**
+ * Read CommitMetadata from the worktree's current HEAD. Used when the
+ * executor itself created commits inside the workspace (Codex defaults to
+ * git-committing as part of its workflow) — the runner did not author the
+ * commit, but still needs commit info to populate the PR body / activity log
+ * when it pushes the branch.
+ */
+export async function readHeadCommitMetadata(repositoryPath, branchName, startingSha) {
+    const [sha, subject, authorName, authorEmail, committedAt, diffNames] = await Promise.all([
+        readGitValue(repositoryPath, ['rev-parse', 'HEAD']),
+        readGitValue(repositoryPath, ['show', '-s', '--format=%s', 'HEAD']),
+        readGitValue(repositoryPath, ['show', '-s', '--format=%an', 'HEAD']),
+        readGitValue(repositoryPath, ['show', '-s', '--format=%ae', 'HEAD']),
+        readGitValue(repositoryPath, ['show', '-s', '--format=%cI', 'HEAD']),
+        readGitValue(repositoryPath, [
+            'diff',
+            '--name-only',
+            `${startingSha}..HEAD`,
+        ]),
+    ]);
+    const changedFiles = diffNames
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(0, HEAD_FILE_LIST_LIMIT);
+    return {
+        sha,
+        shortSha: sha.slice(0, 12),
+        subject,
+        branchName,
+        authorName,
+        authorEmail,
+        committedAt,
+        changedFileCount: changedFiles.length,
+        changedFiles,
+    };
+}
 export async function createLocalCommit(repositoryPath, job, branchName, statusLines) {
     const changedFiles = changedFilePaths(statusLines);
     if (changedFiles.length === 0) {

package/dist/git/workspace.js

@@ -142,6 +142,17 @@ async function currentBranch(path) {
     const branch = result.stdout.trim();
     return branch ? branch : null;
 }
+export async function readHeadSha(path) {
+    const result = await runCommand('git', ['rev-parse', 'HEAD'], path);
+    if (result.code !== 0) {
+        throw new Error(`Unable to read HEAD sha at ${path}: ${result.stderr || result.stdout || 'unknown git error'}`);
+    }
+    const sha = result.stdout.trim();
+    if (!sha) {
+        throw new Error(`Empty HEAD sha at ${path}`);
+    }
+    return sha;
+}
 async function branchExistsInBareRepo(sourceRepositoryPath, cwd, branchName) {
     const result = await runCommand('git', [
         '--git-dir',
@@ -166,7 +177,13 @@ export async function prepareWorkspace(config, job) {
             const head = await currentBranch(worktreePath);
             if (head === branchName) {
                 console.log(`workspace: reusing ${worktreePath} on ${branchName}`);
-                return { sourceRepositoryPath, worktreePath, branchName };
+                const startingSha = await readHeadSha(worktreePath);
+                return {
+                    sourceRepositoryPath,
+                    worktreePath,
+                    branchName,
+                    startingSha,
+                };
             }
         }
         catch {
@@ -208,6 +225,7 @@ export async function prepareWorkspace(config, job) {
     if (await isDirty(worktreePath)) {
         throw new Error(`Prepared worktree has uncommitted changes; refusing to run in ${worktreePath}`);
     }
+    const startingSha = await readHeadSha(worktreePath);
     console.log(`workspace: created ${worktreePath} from ${sourceRepositoryPath} on ${branchName}`);
-    return { sourceRepositoryPath, worktreePath, branchName };
+    return { sourceRepositoryPath, worktreePath, branchName, startingSha };
 }

package/dist/job-pipeline.js

@@ -2,10 +2,29 @@ import { validatePublishingPolicy } from './config.js';
 import { normalizeExecutionPreferences } from './execution-prefs.js';
 import { ADAPTERS_BY_ID } from './executor/adapters/index.js';
 import { runExecutor, summarizeExecutorFailure } from './executor/process.js';
-import { createLocalCommit } from './git/commit.js';
+import { createLocalCommit, readHeadCommitMetadata, } from './git/commit.js';
 import { publishBranchAndMaybePr, } from './git/publish.js';
-import { changedFilePaths, changedFiles, prepareWorkspace, } from './git/workspace.js';
-import { postJson, postRunnerEvent, reportCompletion, reportFailure, reportProgress, } from './relay-client.js';
+import { changedFilePaths, changedFiles, prepareWorkspace, readHeadSha, } from './git/workspace.js';
+import { postJson, postRunnerEvent, reportAwaitingUserInput, reportCompletion, reportFailure, reportProgress, } from './relay-client.js';
+export function createCancellationSignal(jobId) {
+    return { jobId, cancelled: false };
+}
+/**
+ * Wrap a relay status-report call so a transient relay failure (network blip,
+ * 5xx, rate-limit) never aborts the surrounding work or cascades to the
+ * outer-queue catch in run.ts. Status reporting is best-effort by design — the
+ * local commit and the git push are the load-bearing operations, not the
+ * Linear activity stream.
+ */
+async function safeReport(label, jobId, fn) {
+    try {
+        await fn();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`${label} failed for ${jobId}: ${message}`);
+    }
+}
 export async function pollOnce(config) {
     const poll = await postJson(config, '/api/runner/jobs/poll', {
         version: config.version,
@@ -20,18 +39,38 @@ export async function pollOnce(config) {
         executionPreferences: normalizeExecutionPreferences(poll.job),
     };
 }
-export async function runRealExecutionOnce(config) {
+export async function runRealExecutionOnce(config, externalSignal) {
     const job = await pollOnce(config);
     if (!job) {
         return false;
     }
-    console.log(`claimed ${job.id} for ${job.repositorySlug}`);
+    // Propagate the real job id into the external signal so that
+    // onCancellation(jobId) checks in run.ts can match correctly.
+    if (externalSignal) {
+        externalSignal.jobId = job.id;
+    }
+    console.log(`claimed ${job.id} for ${job.repositorySlug ?? '<no repository>'}`);
     await postRunnerEvent(config, '/api/runner/heartbeat', job.id);
     let workspace = null;
     let commitMetadata = null;
+    if (!job.repositorySlug) {
+        const message = "This job has no repository configured. Add a Repository Mapping (Linear → Repository) in delego for the issue's project, then re-trigger the agent session.";
+        await reportFailure(config, job, message, {
+            attemptId: job.attemptId,
+            repositorySlug: job.repositorySlug,
+        });
+        console.error(`failed ${job.id}: ${message}`);
+        await postRunnerEvent(config, '/api/runner/heartbeat', null);
+        return true;
+    }
+    // After the guard above the slug is non-null for the remainder of the function.
+    const executableJob = {
+        ...job,
+        repositorySlug: job.repositorySlug,
+    };
     try {
         validatePublishingPolicy(job.publishingPolicy);
-        workspace = await prepareWorkspace(config, job);
+        workspace = await prepareWorkspace(config, executableJob);
         await reportProgress(config, job, `Prepared local workspace for ${job.executionPreferences.executor} execution.`, {
             executor: job.executionPreferences.executor,
             model: job.executionPreferences.model,
@@ -41,31 +80,78 @@ export async function runRealExecutionOnce(config) {
             worktreePath: workspace.worktreePath,
             branchName: workspace.branchName,
         });
-        const result = await runExecutor(config, job, workspace.worktreePath);
+        const result = await runExecutor(config, job, workspace.worktreePath, externalSignal ? () => externalSignal.cancelled : undefined);
+        // Conversational mode: if Claude paused on an unanswered AskUserQuestion,
+        // route to /jobs/await (which posts the Linear elicitation and pauses
+        // the job in `awaiting_user_input`) instead of treating the silent exit
+        // as completion. The worktree is preserved for the resume claim.
+        //
+        // We do not require `exitCode === 0` here: the executor deliberately
+        // SIGTERMs the Claude subprocess as soon as it captures the first
+        // AskUserQuestion + session id (see process.ts), so a SIGTERM exit with
+        // a pending question is the normal happy path, not a failure.
+        if (!result.cancelled && !result.timedOut && result.pendingQuestion) {
+            if (!result.sessionId) {
+                await reportFailure(config, job, 'Claude returned a pending question without a session id; cannot resume.', {
+                    attemptId: job.attemptId,
+                    repositorySlug: job.repositorySlug,
+                    branchName: workspace.branchName,
+                    worktreePath: workspace.worktreePath,
+                });
+                return true;
+            }
+            await reportAwaitingUserInput(config, job, {
+                sessionId: result.sessionId,
+                question: result.pendingQuestion,
+                worktreePath: workspace.worktreePath,
+                branchName: workspace.branchName,
+                attemptId: job.attemptId,
+            });
+            console.log(`await: reported pending question for ${job.id}`);
+            return true;
+        }
         const changes = await changedFiles(workspace.worktreePath);
         let prMetadata = null;
         let pushed = false;
-        if (result.exitCode === 0 &&
+        const executorSucceeded = result.exitCode === 0 &&
             !result.cancelled &&
             !result.timedOut &&
-            changes.length > 0 &&
-            config.createCommit) {
+            !result.fatalError;
+        if (executorSucceeded && changes.length > 0 && config.createCommit) {
             commitMetadata = await createLocalCommit(workspace.worktreePath, job, workspace.branchName, changes);
             console.log(`commit: created ${commitMetadata.shortSha} on ${workspace.branchName}`);
-            if (job.publishingPolicy.autoPush) {
-                await reportProgress(config, job, 'Publishing branch with local git credentials.', {
-                    branchName: workspace.branchName,
-                    repositorySlug: job.repositorySlug,
-                    publishingPolicy: job.publishingPolicy,
-                });
-                prMetadata = await publishBranchAndMaybePr(workspace.worktreePath, job, workspace.branchName, commitMetadata);
-                pushed = true;
-                if (prMetadata) {
-                    console.log(`publish: created ${prMetadata.draft ? 'draft ' : ''}PR ${prMetadata.url}`);
-                }
-                else {
-                    console.log(`publish: pushed ${workspace.branchName} without creating a PR`);
-                }
+        }
+        // Codex (and other executors that script git) often commit changes inside
+        // the worktree on their own, so `changedFiles` returns empty but the
+        // branch still has new commits to publish. Detect that by comparing HEAD
+        // against the SHA captured before the executor ran, and publish whichever
+        // commits exist regardless of who authored them.
+        const headSha = await readHeadSha(workspace.worktreePath);
+        const branchHasNewCommits = headSha !== workspace.startingSha;
+        if (executorSucceeded && branchHasNewCommits && !commitMetadata) {
+            commitMetadata = await readHeadCommitMetadata(workspace.worktreePath, workspace.branchName, workspace.startingSha);
+            console.log(`commit: detected executor-created HEAD ${commitMetadata.shortSha} on ${workspace.branchName}`);
+        }
+        if (executorSucceeded &&
+            branchHasNewCommits &&
+            commitMetadata &&
+            job.publishingPolicy.autoPush) {
+            // Pre-publish progress is informational. Never let it block the actual
+            // git push — otherwise the executor's commits sit unpushed on the local
+            // branch with no path to recovery if the relay is unhappy.
+            const { branchName } = workspace;
+            await safeReport('progress report', job.id, () => reportProgress(config, job, 'Publishing branch with local git credentials.', {
+                branchName,
+                repositorySlug: job.repositorySlug,
+                publishingPolicy: job.publishingPolicy,
+            }));
+            prMetadata = await publishBranchAndMaybePr(workspace.worktreePath, executableJob, workspace.branchName, commitMetadata);
+            pushed = true;
+            if (prMetadata) {
+                console.log(`publish: created ${prMetadata.draft ? 'draft ' : ''}PR ${prMetadata.url}`);
+            }
+            else {
+                console.log(`publish: pushed ${workspace.branchName} without creating a PR`);
             }
         }
         const remainingChanges = await changedFiles(workspace.worktreePath);
@@ -87,6 +173,9 @@ export async function runRealExecutionOnce(config) {
             remainingChangeCount: remainingChanges.length,
             remainingChanges: changedFilePaths(remainingChanges).slice(0, 50),
             commitMetadata,
+            branchHasNewCommits,
+            startingSha: workspace.startingSha,
+            headSha,
             prMetadata,
             publishingPolicy: job.publishingPolicy,
             pushed,
@@ -94,10 +183,14 @@ export async function runRealExecutionOnce(config) {
             stdoutTail: result.stdout,
             stderrTail: result.stderr,
         };
-        if (result.exitCode === 0 && !result.cancelled && !result.timedOut) {
+        if (executorSucceeded) {
             const executorLabel = ADAPTERS_BY_ID[job.executionPreferences.executor].displayName;
-            if (changes.length === 0) {
-                await reportCompletion(config, job, `${executorLabel} executor completed successfully with no repository changes.`, metadata);
+            if (changes.length === 0 && !branchHasNewCommits) {
+                // Terminal status reports are best-effort: the underlying work is
+                // already finished (or in this branch, there was none). A relay
+                // failure here must not cascade into the catch block below and
+                // misreport a successful job as failed.
+                await safeReport('completion report', job.id, () => reportCompletion(config, job, `${executorLabel} executor completed successfully with no repository changes.`, metadata));
                 console.log(`complete: reported no-change success for ${job.id}`);
                 if (result.stdout.trim()) {
                     console.log(`executor stdout tail:\n${result.stdout.trim()}`);
@@ -111,23 +204,24 @@ export async function runRealExecutionOnce(config) {
                     ? `${executorLabel} executor completed successfully and created pull request ${prMetadata.url}.`
                     : commitMetadata
                         ? job.publishingPolicy.autoPush
-                            ? `${executorLabel} executor completed successfully, created local commit ${commitMetadata.shortSha}, and pushed ${workspace.branchName}.`
-                            : `${executorLabel} executor completed successfully and created local commit ${commitMetadata.shortSha}; publishing is manual.`
+                            ? `${executorLabel} executor completed successfully and pushed ${workspace.branchName} (HEAD ${commitMetadata.shortSha}).`
+                            : `${executorLabel} executor completed successfully with HEAD ${commitMetadata.shortSha} on ${workspace.branchName}; publishing is manual.`
                         : `${executorLabel} executor completed successfully with ${changes.length} changed file(s); local commit creation is disabled.`;
-                await reportCompletion(config, job, summary, metadata);
-                console.log(`changes: ${changes.join(', ')}`);
+                await safeReport('completion report', job.id, () => reportCompletion(config, job, summary, metadata));
+                const changedSummary = changes.length > 0 ? changes.join(', ') : '<committed by executor>';
+                console.log(`changes: ${changedSummary}`);
                 console.log(`complete: reported success for ${job.id}`);
             }
         }
         else {
             const summary = summarizeExecutorFailure(result);
-            await reportFailure(config, job, summary, metadata, result.cancelled);
+            await safeReport('failure report', job.id, () => reportFailure(config, job, summary, metadata, result.cancelled));
             console.log(`terminal: reported ${result.cancelled ? 'cancellation' : 'failure'} for ${job.id}`);
         }
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        await reportFailure(config, job, message, {
+        await safeReport('failure report', job.id, () => reportFailure(config, job, message, {
             attemptId: job.attemptId,
             repositorySlug: job.repositorySlug,
             branchName: workspace?.branchName,
@@ -136,11 +230,20 @@ export async function runRealExecutionOnce(config) {
             worktreePath: workspace?.worktreePath,
             commitMetadata,
             publishingPolicy: job.publishingPolicy,
-        });
+        }));
         console.error(`failed ${job.id}: ${message}`);
     }
     finally {
-        await postRunnerEvent(config, '/api/runner/heartbeat', null);
+        // The trailing heartbeat is purely informational ("I'm idle again"); it
+        // must not throw out of the finally block and replace any in-flight
+        // exception with an unrelated network/auth error.
+        try {
+            await postRunnerEvent(config, '/api/runner/heartbeat', null);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`post-job heartbeat failed: ${message}`);
+        }
     }
     return true;
 }

package/dist/realtime-subscriber.js

@@ -0,0 +1,91 @@
+import { createClient as defaultCreateClient, } from '@supabase/supabase-js';
+import { fetchRealtimeToken } from './relay-client.js';
+const REFRESH_LEAD_MS = 60_000;
+export function createRealtimeSubscriber(opts) {
+    const fetchToken = opts.fetchToken ?? fetchRealtimeToken;
+    const factory = opts.createClient ??
+        defaultCreateClient;
+    let client = null;
+    let channel = null;
+    let refreshTimer = null;
+    let connected = false;
+    let stopped = false;
+    async function refresh() {
+        const next = await fetchToken(opts.config);
+        if (client) {
+            client.realtime.setAuth(next.token);
+        }
+        scheduleRefresh(next.expiresAt);
+    }
+    function scheduleRefresh(expiresAtIso) {
+        if (refreshTimer)
+            clearTimeout(refreshTimer);
+        const delay = Math.max(1_000, new Date(expiresAtIso).getTime() - Date.now() - REFRESH_LEAD_MS);
+        refreshTimer = setTimeout(() => {
+            if (stopped)
+                return;
+            refresh().catch((err) => {
+                console.warn(`realtime: token refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+                // Retry in 30s; the existing JWT may still be valid for a while,
+                // and reconnect logic will take over once it expires.
+                scheduleRefresh(new Date(Date.now() + 30_000).toISOString());
+            });
+        }, delay);
+    }
+    return {
+        isConnected: () => connected,
+        async start() {
+            stopped = false;
+            const initial = await fetchToken(opts.config);
+            client = factory(initial.supabaseUrl, initial.token);
+            channel = client.channel(`runner-account-${opts.accountId}`);
+            channel.on('postgres_changes', {
+                event: '*',
+                schema: 'public',
+                table: 'jobs',
+                filter: `account_id=eq.${opts.accountId}`,
+            }, (payload) => {
+                if (payload.eventType === 'INSERT' ||
+                    payload.eventType === 'UPDATE') {
+                    opts.onJobReady();
+                }
+                if (payload.eventType === 'UPDATE') {
+                    const oldCancel = payload.old?.cancellation_requested;
+                    const newCancel = payload.new?.cancellation_requested;
+                    if (newCancel === true && oldCancel !== true) {
+                        const jobId = payload.new?.id;
+                        if (typeof jobId === 'string') {
+                            opts.onCancellation(jobId);
+                        }
+                    }
+                }
+            });
+            channel.subscribe((status) => {
+                if (status === 'SUBSCRIBED') {
+                    connected = true;
+                    opts.onJobReady();
+                }
+                else if (status === 'CHANNEL_ERROR' ||
+                    status === 'TIMED_OUT' ||
+                    status === 'CLOSED') {
+                    connected = false;
+                }
+            });
+            scheduleRefresh(initial.expiresAt);
+        },
+        async stop() {
+            stopped = true;
+            if (refreshTimer) {
+                clearTimeout(refreshTimer);
+                refreshTimer = null;
+            }
+            if (channel && client) {
+                await channel.unsubscribe();
+                client.removeChannel(channel);
+            }
+            channel = null;
+            client = null;
+            connected = false;
+        },
+    };
+}

package/dist/relay-client.js

@@ -76,9 +76,30 @@ export async function reportFailure(config, job, summary, metadata, cancelled =
         metadata,
     });
 }
+/**
+ * Conversational mode: report an unanswered AskUserQuestion. The relay
+ * transitions the job to `awaiting_user_input`, persists the question +
+ * Claude session id + worktree path, and posts a Linear elicitation
+ * activity so the user is prompted to answer.
+ */
+export async function reportAwaitingUserInput(config, job, body) {
+    await postJson(config, '/api/runner/jobs/await', {
+        jobId: job.id,
+        organizationId: job.organizationId,
+        agentSessionId: job.agentSessionId,
+        sessionId: body.sessionId,
+        question: body.question,
+        worktreePath: body.worktreePath,
+        branchName: body.branchName,
+        attemptId: body.attemptId,
+    });
+}
 export async function pollCancellation(config, job) {
     const status = await postJson(config, '/api/runner/jobs/status', {
         jobId: job.id,
     });
     return Boolean(status.job?.cancellationRequested);
 }
+export async function fetchRealtimeToken(config) {
+    return postJson(config, '/api/runner/realtime-token', {});
+}

package/dist/run.js

@@ -1,12 +1,51 @@
 import { readConfig, usageMessage, } from './config.js';
 import { getProfile, readStore, resolveCredentialsPath, } from './credentials-store.js';
-import { runMockExecutionOnce, runRealExecutionOnce } from './job-pipeline.js';
+import { createCancellationSignal, runMockExecutionOnce, runRealExecutionOnce, } from './job-pipeline.js';
 import { pairAndStore } from './pairing.js';
-import { describeRunnerResponse, postRunnerEvent, RelayUnauthorizedError, } from './relay-client.js';
-function sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
-    });
+import { describeRunnerResponse, fetchRealtimeToken, postRunnerEvent, RelayUnauthorizedError, } from './relay-client.js';
+function createKickableQueue(action) {
+    let running = false;
+    let kickedWhileRunning = false;
+    const runOnce = async () => {
+        if (running) {
+            kickedWhileRunning = true;
+            return;
+        }
+        running = true;
+        try {
+            do {
+                kickedWhileRunning = false;
+                try {
+                    await action();
+                }
+                catch (err) {
+                    console.warn(`job action failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            } while (kickedWhileRunning);
+        }
+        finally {
+            running = false;
+        }
+    };
+    return {
+        kick: (source) => {
+            console.log(`kick: ${source} at ${new Date().toISOString()}`);
+            runOnce().catch(() => {
+                /* swallowed in inner catch */
+            });
+        },
+    };
+}
+function decodeJwtSub(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts[1]) {
+        throw new Error('runtime: malformed realtime token');
+    }
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    if (typeof payload.sub !== 'string') {
+        throw new Error('runtime: realtime token missing sub claim');
+    }
+    return payload.sub;
 }
 export async function resolveRunnerConfig(input, env = process.env) {
     const credentialsPath = resolveCredentialsPath(env);
@@ -52,6 +91,8 @@ function buildRunnerConfig(input, relayUrl, bearer, runnerId) {
         heartbeatIntervalMs: input.heartbeatIntervalMs,
         pollIntervalMs: input.pollIntervalMs,
         cancellationPollIntervalMs: input.cancellationPollIntervalMs,
+        safetySyncIntervalMs: input.safetySyncIntervalMs,
+        fallbackPollIntervalMs: input.fallbackPollIntervalMs,
         workspaceRoot: input.workspaceRoot,
         gitCloneBaseUrl: input.gitCloneBaseUrl,
         executors: input.executors,
@@ -75,9 +116,6 @@ export async function run(args = process.argv.slice(2)) {
     }
     const input = readConfig(args);
     const config = await resolveRunnerConfig(input);
-    // In v0.3, /api/runner/register is the *pairing* endpoint and only accepts a
-    // pairing-token body. Pairing happens once inside resolveRunnerConfig (when
-    // --pairing-token is supplied); after that the runner just heartbeats.
     try {
         const heartbeat = await postRunnerEvent(config, '/api/runner/heartbeat');
         console.log(describeRunnerResponse('heartbeat', heartbeat));
@@ -92,33 +130,68 @@ export async function run(args = process.argv.slice(2)) {
         await runMockExecutionOnce(config);
         return;
     }
+    let activeSignal = null;
+    const queue = createKickableQueue(async () => {
+        const signal = createCancellationSignal('');
+        activeSignal = signal;
+        try {
+            return await runRealExecutionOnce(config, signal);
+        }
+        catch (error) {
+            if (error instanceof RelayUnauthorizedError) {
+                handleUnauthorized(error, config, input.profileName);
+            }
+            throw error;
+        }
+        finally {
+            activeSignal = null;
+        }
+    });
+    if (config.once) {
+        queue.kick('once');
+        return;
+    }
+    const initial = await fetchRealtimeToken(config);
+    const accountId = decodeJwtSub(initial.token);
+    const { createRealtimeSubscriber } = await import('./realtime-subscriber.js');
+    const subscriber = createRealtimeSubscriber({
+        config,
+        accountId,
+        onJobReady: () => queue.kick('realtime-push'),
+        onCancellation: (jobId) => {
+            if (activeSignal && activeSignal.jobId === jobId) {
+                activeSignal.cancelled = true;
+            }
+        },
+    });
+    await subscriber.start();
     const heartbeatTimer = startHeartbeatLoop(config, input.profileName);
-    try {
-        do {
-            let handled = false;
+    const safetySync = setInterval(() => queue.kick('safety-sync'), config.safetySyncIntervalMs);
+    const fallbackPoll = setInterval(() => {
+        if (!subscriber.isConnected()) {
+            queue.kick('fallback-poll');
+        }
+    }, config.fallbackPollIntervalMs);
+    // Keep the process alive until SIGTERM / SIGINT. The actual work is
+    // event-driven from this point on.
+    await new Promise((resolve) => {
+        const shutdown = async () => {
             try {
-                handled = await runRealExecutionOnce(config);
+                clearInterval(heartbeatTimer);
+                clearInterval(safetySync);
+                clearInterval(fallbackPoll);
+                await subscriber.stop();
             }
-            catch (error) {
-                if (error instanceof RelayUnauthorizedError) {
-                    handleUnauthorized(error, config, input.profileName);
-                }
-                const message = error instanceof Error ? error.message : String(error);
-                console.warn(`poll cycle failed: ${message}`);
-                if (config.once) {
-                    throw error;
-                }
+            catch (err) {
+                console.warn(`runner shutdown error: ${err instanceof Error ? err.message : String(err)}`);
             }
-            if (config.once) {
-                return;
+            finally {
+                resolve();
             }
-            await sleep(handled ? 1_000 : config.pollIntervalMs);
-            // oxlint-disable-next-line no-constant-condition
-        } while (true);
-    }
-    finally {
-        clearInterval(heartbeatTimer);
-    }
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
 }
 function startHeartbeatLoop(config, profileName) {
     let inFlight = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delegoapp/runner",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Delego runner — polls the Delego relay and executes Linear-delegated coding jobs via Codex CLI or Claude Code.",
   "keywords": [
@@ -30,20 +30,24 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
-    "@kit/tsconfig": "0.1.0"
-  },
-  "engines": {
-    "node": ">=20"
-  },
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/add-shebang.mjs",
     "prestart": "pnpm build",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
-    "clean": "rm -rf .turbo dist node_modules"
+    "clean": "rm -rf .turbo dist node_modules",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "catalog:"
+  },
+  "devDependencies": {
+    "@kit/tsconfig": "workspace:*",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=20"
   }
-}
+}