@flumecode/runner 0.3.1 → 0.5.0

package/dist/cli.js

@@ -40,6 +40,7 @@ function readVersion() {
 var RUNNER_VERSION = readVersion();
 var RUNNER_VERSION_HEADER = "x-flumecode-runner-version";
 var RUNNER_MIN_VERSION_HEADER = "x-flumecode-min-runner-version";
+var RUNNER_LATEST_VERSION_HEADER = "x-flumecode-latest-runner-version";
 function compareVersions(a, b) {
   const parse = (v) => (v.split("-")[0] ?? v).split(".").map((n) => Number.parseInt(n, 10) || 0);
   const pa = parse(a);
@@ -55,16 +56,29 @@ function compareVersions(a, b) {
 // src/api.ts
 var OUTDATED_WARN_INTERVAL_MS = 60 * 6e4;
 var lastOutdatedWarnAt = 0;
+var UPDATE_NUDGE_INTERVAL_MS = 60 * 6e4;
+var lastUpdateNudgeAt = 0;
 function noteServerVersion(res) {
   const min = res.headers.get(RUNNER_MIN_VERSION_HEADER)?.trim();
-  if (!min || RUNNER_VERSION === "unknown") return;
-  if (compareVersions(RUNNER_VERSION, min) >= 0) return;
-  const now = Date.now();
-  if (now - lastOutdatedWarnAt < OUTDATED_WARN_INTERVAL_MS) return;
-  lastOutdatedWarnAt = now;
-  console.warn(
-    `\u26A0\uFE0F  This runner (v${RUNNER_VERSION}) is outdated \u2014 the server expects v${min} or newer.
+  if (min && RUNNER_VERSION !== "unknown" && compareVersions(RUNNER_VERSION, min) < 0) {
+    const now2 = Date.now();
+    if (now2 - lastOutdatedWarnAt >= OUTDATED_WARN_INTERVAL_MS) {
+      lastOutdatedWarnAt = now2;
+      console.warn(
+        `\u26A0\uFE0F  This runner (v${RUNNER_VERSION}) is outdated \u2014 the server expects v${min} or newer.
    Update with: npm install -g @flumecode/runner@latest`
+      );
+    }
+    return;
+  }
+  const latest = res.headers.get(RUNNER_LATEST_VERSION_HEADER)?.trim();
+  if (!latest || RUNNER_VERSION === "unknown") return;
+  if (compareVersions(RUNNER_VERSION, latest) >= 0) return;
+  const now = Date.now();
+  if (now - lastUpdateNudgeAt < UPDATE_NUDGE_INTERVAL_MS) return;
+  lastUpdateNudgeAt = now;
+  console.log(
+    `\u2139\uFE0F  A newer runner is available (v${latest}; you have v${RUNNER_VERSION}). Update with: npm install -g @flumecode/runner@latest`
   );
 }
 async function claimJob(config) {
@@ -83,6 +97,19 @@ async function claimJob(config) {
   if (!res.ok) throw new Error(`claim failed: ${res.status} ${await safeText(res)}`);
   return await res.json();
 }
+async function pollJobCanceling(config, jobId) {
+  const res = await fetch(`${config.serverUrl}/api/runner/jobs/${jobId}/cancel`, {
+    method: "GET",
+    headers: {
+      authorization: `Bearer ${config.token}`,
+      [RUNNER_VERSION_HEADER]: RUNNER_VERSION
+    }
+  });
+  noteServerVersion(res);
+  if (!res.ok) return false;
+  const body = await res.json();
+  return body.canceling === true;
+}
 async function reportJob(config, jobId, result) {
   const res = await fetch(`${config.serverUrl}/api/runner/jobs/${jobId}/complete`, {
     method: "POST",
@@ -265,19 +292,30 @@ function renderPlan(plan) {
   lines.push(PLAN_MARKER);
   return lines.join("\n");
 }
+var submitPlanInputSchema = {
+  plans: z2.array(z2.object(planInputSchema)).min(1).refine(
+    (arr) => {
+      const titles = arr.map((p) => p.title.trim()).filter((t) => t.length > 0);
+      return new Set(titles).size === titles.length;
+    },
+    { message: "Each plan must have a distinct non-empty title" }
+  )
+};
+var submitPlanSchema = z2.object(submitPlanInputSchema);
 function createPlanTooling() {
-  let renderedPlan = null;
+  let renderedPlans = null;
   const submitPlan = tool2(
     SUBMIT_PLAN,
-    "Submit the finished plan. Call this \u2014 and only this \u2014 when the plan is complete and ready to post. The runner renders your structured fields into the canonical plan markdown and posts it as your comment. acceptanceCriteria is required and must contain at least 2 observable, verifiable conditions (behaviors, tests, or states you could check) that together define 'done'. After calling this, end your turn. The `title` field names this specific plan \u2014 make it concise and distinct from the request title.",
-    planInputSchema,
+    "Submit ALL your plans in a single call \u2014 one entry per plan; each becomes its own independently-acceptable Accept-as-plan draft. Do NOT call submit_plan more than once. acceptanceCriteria is required in each plan and must contain at least 2 observable, verifiable conditions. The 'title' field names each specific plan \u2014 make it concise and distinct from the request title and from sibling plan titles.",
+    submitPlanInputSchema,
     async (args) => {
-      renderedPlan = renderPlan(planSchema.parse(args));
+      const parsed = submitPlanSchema.parse(args);
+      renderedPlans = parsed.plans.map(renderPlan);
       return {
         content: [
           {
             type: "text",
-            text: "Plan submitted. The runner will render and post it as your comment. End your turn now."
+            text: "Plan(s) submitted. The runner will render and post them as your comment(s). End your turn now."
           }
         ]
       };
@@ -287,7 +325,7 @@ function createPlanTooling() {
     name: SERVER_NAME2,
     tools: [submitPlan]
   });
-  return { mcpServer, getPlan: () => renderedPlan };
+  return { mcpServer, getPlans: () => renderedPlans };
 }
 
 // src/executor.ts
@@ -295,7 +333,7 @@ var FLUME_PLUGIN_DIR = fileURLToPath2(new URL("../skills-plugin", import.meta.ur
 async function runClaudeCode(opts) {
   let finalText = "";
   const { mcpServer, collected } = createWidgetTooling();
-  const { mcpServer: planServer, getPlan } = createPlanTooling();
+  const { mcpServer: planServer, getPlans } = createPlanTooling();
   for await (const message of query({
     prompt: opts.prompt,
     options: {
@@ -303,6 +341,7 @@ async function runClaudeCode(opts) {
       permissionMode: opts.permissionMode,
       allowDangerouslySkipPermissions: opts.permissionMode === "bypassPermissions",
       ...opts.model ? { model: opts.model } : {},
+      ...opts.abortController ? { abortController: opts.abortController } : {},
       maxTurns: opts.maxTurns ?? 40,
       // Hermetic: ignore ALL config from the checked-out repo (CLAUDE.md,
       // .claude/settings.json, .claude/skills, …) and the runner owner's
@@ -333,7 +372,10 @@ async function runClaudeCode(opts) {
     }
   }
   process.stdout.write("\n");
-  return { text: finalText, widgets: collected, plan: getPlan() };
+  if (opts.abortController?.signal.aborted) {
+    throw new Error("Run canceled by user");
+  }
+  return { text: finalText, widgets: collected, plans: getPlans() };
 }
 
 // src/health.ts
@@ -399,6 +441,20 @@ function stripFrontMatter(raw) {
 }
 
 // src/prompt.ts
+function turnHeading(turn, agentName) {
+  if (turn.role === "user") return "User";
+  if (turn.failed) return `${agentName} (this run ended in an error)`;
+  if (turn.kind === "plan") return `${agentName} (proposed a plan)`;
+  if (turn.kind === "report") return `${agentName} (implementation report)`;
+  return agentName;
+}
+function appendThread(lines, ctx) {
+  if (!ctx.thread || ctx.thread.length === 0) return;
+  lines.push("", "# Conversation so far");
+  for (const turn of ctx.thread) {
+    lines.push("", `## ${turnHeading(turn, ctx.agentName)}`, turn.content);
+  }
+}
 function buildPrompt(ctx) {
   const task = ctx.permissionMode === "plan" ? `Use the \`flumecode:request-to-plan\` skill to handle this request. You are read-only and cannot modify files \u2014 clarify any ambiguity with the user first, then produce a concrete, actionable plan (the specific changes you would make and why). Cite the relevant files. Do NOT call ExitPlanMode or write the plan to a file. When the plan is ready, call the \`submit_plan\` tool with the structured plan fields; the runner renders it into the canonical plan markdown and posts it as your comment.` : `Use the \`flumecode:implement-plan\` skill to handle this request. You are the ORCHESTRATOR: do not implement, review, or write the report yourself \u2014 follow the skill to delegate each phase to subagents via the Task tool, picking the right model for each. Do not commit or push \u2014 the runner handles that.`;
   const orient = `Before investigating raw source, check for a FlumeCode wiki at \`.flumecode/wiki/\`. If it exists, read \`.flumecode/wiki/README.md\` first \u2014 it is the index \u2014 and follow its links to the pages and source paths relevant to this request. If there is no wiki, work from the code directly.`;
@@ -422,12 +478,7 @@ function buildPrompt(ctx) {
   if (ctx.request?.body) {
     lines.push("", ctx.request.body);
   }
-  if (ctx.thread && ctx.thread.length > 0) {
-    lines.push("", "# Conversation so far");
-    for (const turn of ctx.thread) {
-      lines.push("", `## ${turn.role === "agent" ? ctx.agentName : "User"}`, turn.content);
-    }
-  }
+  appendThread(lines, ctx);
   lines.push(
     "",
     ctx.permissionMode === "plan" ? "Your final reply is posted verbatim as your comment in the thread \u2014 if you called `submit_plan`, the rendered plan is posted automatically; for clarifying questions, your reply text is posted as-is." : "Your final reply is posted verbatim as your comment in the thread \u2014 make it the implementation report your report subagent produced, with nothing added. The runner appends the pull-request link."
@@ -435,7 +486,7 @@ function buildPrompt(ctx) {
   return lines.join("\n");
 }
 function buildRevisePrompt(ctx) {
-  const task = `Use the \`flumecode:revise-implementation\` skill to handle this turn. The plan below was already implemented (its report is included); the user is now asking to fine-tune that implementation. Decide how to respond to their latest message: if it's unclear, ask a clarifying question (as a widget); if it's a bad idea or not feasible, push back with your reasoning; if it warrants rethinking the plan, call \`submit_plan\` with a revised plan; otherwise implement the requested change. When you implement, you are the ORCHESTRATOR: delegate the work to subagents via the Task tool as the skill directs, and do not commit or push \u2014 the runner handles that, updating the existing pull request.`;
+  const task = `Use the \`flumecode:revise-implementation\` skill to handle this turn. The plan below was already implemented (its implementation report appears in the conversation below, tagged as such); the user is now asking to fine-tune that implementation. Decide how to respond to their latest message: if it's unclear, ask a clarifying question (as a widget); if it's a bad idea or not feasible, push back with your reasoning; if it warrants rethinking the plan, call \`submit_plan\` with a revised plan; otherwise implement the requested change. When you implement, you are the ORCHESTRATOR: delegate the work to subagents via the Task tool as the skill directs, and do not commit or push \u2014 the runner handles that, updating the existing pull request.`;
   const orient = `Before investigating raw source, check for a FlumeCode wiki at \`.flumecode/wiki/\`. If it exists, read \`.flumecode/wiki/README.md\` first \u2014 it is the index \u2014 and follow its links to the pages and source paths relevant to this change. If there is no wiki, work from the code directly.`;
   const widgets = `When you need the user to choose, ask it as a widget rather than writing the options as prose: call \`single_select\` for a one-of-N choice (radio buttons) or \`multi_select\` for a "select all that apply" choice (checkboxes). Don't add your own "Other" option \u2014 the UI always provides one. After calling a widget tool, end your turn \u2014 the user's answer comes back as their next message and starts a fresh run.`;
   const lines = [
@@ -454,21 +505,39 @@ function buildRevisePrompt(ctx) {
   if (ctx.request?.body) {
     lines.push("", ctx.request.body);
   }
-  if (ctx.priorReport) {
-    lines.push("", "# Latest implementation report", "", ctx.priorReport);
-  }
-  if (ctx.thread && ctx.thread.length > 0) {
-    lines.push("", "# Conversation so far");
-    for (const turn of ctx.thread) {
-      lines.push("", `## ${turn.role === "agent" ? ctx.agentName : "User"}`, turn.content);
-    }
-  }
+  appendThread(lines, ctx);
   lines.push(
     "",
     "The last message above is the user's request for this turn. Your final reply is posted verbatim as your comment in the plan thread: if you implemented a change, make it a short report of what you changed (the runner appends the pull-request link); if you asked a question, called `submit_plan`, or pushed back, your reply text is posted as-is."
   );
   return lines.join("\n");
 }
+function buildResolvePrompt(ctx) {
+  const mergeBranch = ctx.repo.mergeBranch ?? "the merge branch";
+  const task = `Use the \`flumecode:resolve-merge-conflict\` skill to handle this turn. A merge of \`${mergeBranch}\` into this branch is IN PROGRESS and has left conflict markers in your working tree. Resolve every conflicted file by correctly integrating BOTH sides \u2014 the change this session implemented (described below) and the incoming changes from \`${mergeBranch}\` \u2014 never blindly discard either side. Remove all conflict markers and verify the result builds and tests pass. Do NOT \`git add\`, commit, push, or open a pull request \u2014 the runner finalizes the merge commit and updates the existing pull request.`;
+  const orient = `Before investigating raw source, check for a FlumeCode wiki at \`.flumecode/wiki/\`. If it exists, read \`.flumecode/wiki/README.md\` first \u2014 it is the index \u2014 and follow its links to the pages and source paths relevant to the conflicting code. If there is no wiki, work from the code directly.`;
+  const lines = [
+    `You are "${ctx.agentName}", an autonomous coding agent resolving merge conflicts on an implemented FlumeCode plan.`,
+    `The repository ${ctx.repo.fullName} is checked out in your current working directory on the plan's implementation branch "${ctx.repo.checkoutBranch}" \u2014 the same branch its open pull request is built from \u2014 with an in-progress merge of "${mergeBranch}".`,
+    task,
+    orient,
+    "",
+    "These coding guidelines apply to all code produced in this run:",
+    "",
+    loadRule("coding-guideline"),
+    "",
+    `# Plan: ${ctx.request?.title ?? ""}`
+  ];
+  if (ctx.request?.body) {
+    lines.push("", ctx.request.body);
+  }
+  appendThread(lines, ctx);
+  lines.push(
+    "",
+    "Resolve the conflicts now. Your final reply is posted as a report in the plan thread: summarize which files conflicted and how you resolved each (the runner appends the pull-request link, so don't add one)."
+  );
+  return lines.join("\n");
+}
 function buildDocumentPrompt(ctx) {
   const lines = [
     `You are "${ctx.agentName}" maintaining the repository wiki for ${ctx.repo.fullName}.`,
@@ -480,12 +549,7 @@ function buildDocumentPrompt(ctx) {
   if (ctx.request?.body) {
     lines.push("", ctx.request.body);
   }
-  if (ctx.thread && ctx.thread.length > 0) {
-    lines.push("", "# Conversation so far");
-    for (const turn of ctx.thread) {
-      lines.push("", `## ${turn.role === "agent" ? ctx.agentName : "User"}`, turn.content);
-    }
-  }
+  appendThread(lines, ctx);
   lines.push("", "When done, reply with a one- or two-line summary of the wiki changes you made.");
   return lines.join("\n");
 }
@@ -589,6 +653,12 @@ async function discardWorkspace(key) {
     });
   }
 }
+async function resetWorkspace(dir) {
+  await git(["-C", dir, "reset", "--hard", "HEAD"]).catch(() => {
+  });
+  await git(["-C", dir, "clean", "-fd"]).catch(() => {
+  });
+}
 async function prepareAtSha(ctx, dir, reused) {
   if (!reused) {
     await cloneAtSha(ctx, dir);
@@ -702,6 +772,33 @@ async function rebaseOntoMergeBranch(ctx, dir) {
     throw new RebaseConflictError(mergeBranch, files);
   }
 }
+async function mergeInMergeBranch(ctx, dir) {
+  const { mergeBranch } = ctx.repo;
+  if (!mergeBranch) return { conflicted: false };
+  await git(["-C", dir, "fetch", "--quiet", "origin", mergeBranch]);
+  try {
+    await git([
+      "-C",
+      dir,
+      "-c",
+      "user.email=runner@flumecode.local",
+      "-c",
+      "user.name=FlumeCode Runner",
+      "merge",
+      "--no-edit",
+      "FETCH_HEAD"
+    ]);
+    return { conflicted: false };
+  } catch {
+    return { conflicted: true };
+  }
+}
+async function listUnmergedPaths(dir) {
+  const { stdout: stdout2 } = await git(["-C", dir, "diff", "--name-only", "--diff-filter=U"]).catch(() => ({
+    stdout: ""
+  }));
+  return stdout2.split("\n").map((line) => line.trim()).filter(Boolean);
+}
 async function openPullRequest(ctx) {
   const { owner, name, cloneToken, checkoutBranch, mergeBranch } = ctx.repo;
   if (!mergeBranch) return null;
@@ -747,21 +844,23 @@ async function cleanup(dir) {
 
 // src/run.ts
 var IDLE_MS = 5e3;
+var CANCEL_POLL_MS = 2500;
 var ORCHESTRATOR_MODEL = "sonnet";
 var ORCHESTRATOR_MAX_TURNS = 80;
 var MAX_COMMIT_REPAIRS = 2;
 var INIT_MAX_TURNS = 200;
 var DOCUMENT_MAX_TURNS = 120;
 var HEARTBEAT_MS = 5 * 6e4;
-async function pushAndOpenPr(ctx, dir, opts = { rebase: true }) {
-  const committed = await commitWithRepair(ctx, dir);
+async function pushAndOpenPr(ctx, dir, abort, opts = { rebase: true }) {
+  if (abort.signal.aborted) throw new Error("Run canceled by user");
+  const committed = await commitWithRepair(ctx, dir, abort);
   if (!committed) return { kind: "none" };
   if (opts.rebase) await rebaseOntoMergeBranch(ctx, dir);
   await pushBranch(ctx, dir);
   const pr = await openPullRequest(ctx);
   return pr ? { kind: "pr", pr } : { kind: "pushed" };
 }
-async function commitWithRepair(ctx, dir) {
+async function commitWithRepair(ctx, dir, abort) {
   for (let attempt = 1; ; attempt++) {
     try {
       return await commitChanges(ctx, dir);
@@ -775,7 +874,8 @@ async function commitWithRepair(ctx, dir) {
         prompt: buildRepairPrompt(ctx, err.log),
         permissionMode: ctx.permissionMode,
         model: ORCHESTRATOR_MODEL,
-        maxTurns: ORCHESTRATOR_MAX_TURNS
+        maxTurns: ORCHESTRATOR_MAX_TURNS,
+        abortController: abort
       });
     }
   }
@@ -800,51 +900,61 @@ function outcomeBanner(outcome, opts) {
 \u2139\uFE0F **No code changes were made** \u2014 ${opts.noChange ?? "there was nothing to open a pull request for."}`;
   }
 }
-async function processJob(ctx) {
+async function processJob(ctx, abort = new AbortController()) {
   const { dir, reused } = await acquireWorkspace(ctx.workspaceKey);
   let prepared = false;
   try {
     if (ctx.kind === "init") {
       await prepareAtSha(ctx, dir, reused);
       prepared = true;
-      return await processInitJob(ctx, dir);
+      return await processInitJob(ctx, dir, abort);
     }
     if (ctx.kind === "implement") {
       const { resumed } = await prepareResumingBranch(ctx, dir, reused);
       prepared = true;
-      return await processImplementJob(ctx, dir, resumed);
+      return await processImplementJob(ctx, dir, resumed, abort);
     }
     if (ctx.kind === "revise") {
       const { resumed } = await prepareResumingBranch(ctx, dir, reused);
       prepared = true;
-      return await processReviseJob(ctx, dir, resumed);
+      return await processReviseJob(ctx, dir, resumed, abort);
+    }
+    if (ctx.kind === "resolve") {
+      await prepareResumingBranch(ctx, dir, reused);
+      prepared = true;
+      return await processResolveJob(ctx, dir, abort);
     }
     await prepareAtSha(ctx, dir, reused);
     prepared = true;
-    return await processChatJob(ctx, dir);
+    return await processChatJob(ctx, dir, abort);
   } catch (err) {
-    if (!prepared) await discardWorkspace(ctx.workspaceKey);
+    if (abort.signal.aborted && prepared) {
+      await resetWorkspace(dir);
+    } else if (!prepared) {
+      await discardWorkspace(ctx.workspaceKey);
+    }
     throw err;
   }
 }
-async function processInitJob(ctx, dir) {
+async function processInitJob(ctx, dir, abort) {
   console.log(`
 \u25B6 Init ${ctx.jobId} \u2014 ${ctx.repo.fullName} on ${ctx.repo.checkoutBranch}`);
   const summary = (await runClaudeCode({
     cwd: dir,
     prompt: buildInitPrompt(ctx),
     permissionMode: ctx.permissionMode,
-    maxTurns: INIT_MAX_TURNS
+    maxTurns: INIT_MAX_TURNS,
+    abortController: abort
   })).text.trim();
   let reply = summary || "(the agent produced no summary)";
-  const outcome = await pushAndOpenPr(ctx, dir);
+  const outcome = await pushAndOpenPr(ctx, dir, abort);
   reply += outcomeBanner(outcome, {
     branch: ctx.repo.checkoutBranch,
     noChange: "no files were generated; the wiki may already exist."
   });
   return { text: reply, widgets: [] };
 }
-async function processChatJob(ctx, dir) {
+async function processChatJob(ctx, dir, abort) {
   console.log(`
 \u25B6 Job ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
   const orchestrating = ctx.permissionMode !== "plan";
@@ -853,18 +963,19 @@ async function processChatJob(ctx, dir) {
     cwd: dir,
     prompt: buildPrompt(ctx),
     permissionMode: ctx.permissionMode,
+    abortController: abort,
     ...orchestrating ? { model: ORCHESTRATOR_MODEL, maxTurns: ORCHESTRATOR_MAX_TURNS } : {}
   });
   const summary = result.text.trim();
   let reply = summary || "(the agent produced no summary)";
-  if (result.plan) {
-    reply = result.plan;
-  }
   if (installResult?.status === "failed") {
     reply += `
 
 > \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
   }
+  if (result.plans?.length) {
+    return { text: result.text.trim(), widgets: [], plans: result.plans };
+  }
   if (result.widgets.length > 0) {
     console.log(`  \u2026job ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
     return { text: reply, widgets: result.widgets };
@@ -877,18 +988,19 @@ async function processChatJob(ctx, dir) {
         cwd: dir,
         prompt: buildDocumentPrompt(ctx),
         permissionMode: ctx.permissionMode,
-        maxTurns: DOCUMENT_MAX_TURNS
+        maxTurns: DOCUMENT_MAX_TURNS,
+        abortController: abort
       });
       documented = true;
     } catch (err) {
       console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
     }
   }
-  const outcome = await pushAndOpenPr(ctx, dir);
+  const outcome = await pushAndOpenPr(ctx, dir, abort);
   reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
   return { text: reply, widgets: [] };
 }
-async function processImplementJob(ctx, dir, resumed) {
+async function processImplementJob(ctx, dir, resumed, abort) {
   console.log(`
 \u25B6 Implement ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
   const installResult = await installDependencies(dir);
@@ -897,7 +1009,8 @@ async function processImplementJob(ctx, dir, resumed) {
     prompt: buildPrompt(ctx),
     permissionMode: ctx.permissionMode,
     model: ORCHESTRATOR_MODEL,
-    maxTurns: ORCHESTRATOR_MAX_TURNS
+    maxTurns: ORCHESTRATOR_MAX_TURNS,
+    abortController: abort
   });
   let reply = result.text.trim() || "(the agent produced no report)";
   if (installResult.status === "failed") {
@@ -913,18 +1026,19 @@ async function processImplementJob(ctx, dir, resumed) {
         cwd: dir,
         prompt: buildDocumentPrompt(ctx),
         permissionMode: ctx.permissionMode,
-        maxTurns: DOCUMENT_MAX_TURNS
+        maxTurns: DOCUMENT_MAX_TURNS,
+        abortController: abort
       });
       documented = true;
     } catch (err) {
       console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
     }
   }
-  const outcome = await pushAndOpenPr(ctx, dir, { rebase: !resumed });
+  const outcome = await pushAndOpenPr(ctx, dir, abort, { rebase: !resumed });
   reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
   return { text: reply, widgets: [], ...outcome.kind === "pr" ? { pr: outcome.pr } : {} };
 }
-async function processReviseJob(ctx, dir, resumed) {
+async function processReviseJob(ctx, dir, resumed, abort) {
   console.log(`
 \u25B6 Revise ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
   const installResult = await installDependencies(dir);
@@ -933,11 +1047,12 @@ async function processReviseJob(ctx, dir, resumed) {
     prompt: buildRevisePrompt(ctx),
     permissionMode: ctx.permissionMode,
     model: ORCHESTRATOR_MODEL,
-    maxTurns: ORCHESTRATOR_MAX_TURNS
+    maxTurns: ORCHESTRATOR_MAX_TURNS,
+    abortController: abort
   });
   const summary = result.text.trim();
   let reply = summary || "(the agent produced no reply)";
-  if (result.plan) reply = result.plan;
+  if (result.plans?.length) reply = result.plans[0] ?? reply;
   if (installResult.status === "failed") {
     reply += `
 
@@ -955,18 +1070,62 @@ async function processReviseJob(ctx, dir, resumed) {
         cwd: dir,
         prompt: buildDocumentPrompt(ctx),
         permissionMode: ctx.permissionMode,
-        maxTurns: DOCUMENT_MAX_TURNS
+        maxTurns: DOCUMENT_MAX_TURNS,
+        abortController: abort
       });
       documented = true;
     } catch (err) {
       console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
     }
   }
-  const outcome = await pushAndOpenPr(ctx, dir, { rebase: !resumed });
+  const outcome = await pushAndOpenPr(ctx, dir, abort, { rebase: !resumed });
   if (outcome.kind !== "none") {
     reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
   }
-  return { text: reply, widgets: [], ...outcome.kind === "pr" ? { pr: outcome.pr } : {} };
+  return {
+    text: reply,
+    widgets: [],
+    ...outcome.kind === "pr" ? { pr: outcome.pr } : {},
+    ...result.plans?.length ? { plans: result.plans } : {}
+  };
+}
+async function processResolveJob(ctx, dir, abort) {
+  console.log(`
+\u25B6 Resolve ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
+  const installResult = await installDependencies(dir);
+  const { conflicted } = await mergeInMergeBranch(ctx, dir);
+  let reply;
+  if (conflicted) {
+    const result = await runClaudeCode({
+      cwd: dir,
+      prompt: buildResolvePrompt(ctx),
+      permissionMode: ctx.permissionMode,
+      model: ORCHESTRATOR_MODEL,
+      maxTurns: ORCHESTRATOR_MAX_TURNS,
+      abortController: abort
+    });
+    reply = result.text.trim() || "(the agent produced no report)";
+    const unresolved = await listUnmergedPaths(dir);
+    if (unresolved.length > 0) {
+      throw new Error(
+        `Could not fully resolve the merge \u2014 ${unresolved.length} file(s) still conflict: ${unresolved.join(", ")}`
+      );
+    }
+  } else {
+    reply = `Merged \`${ctx.repo.mergeBranch ?? "the merge branch"}\` into \`${ctx.repo.checkoutBranch}\` cleanly \u2014 there were no conflicts to resolve.`;
+  }
+  if (installResult.status === "failed") {
+    reply += `
+
+> \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
+  }
+  if (abort.signal.aborted) throw new Error("Run canceled by user");
+  await commitWithRepair(ctx, dir, abort);
+  await pushBranch(ctx, dir);
+  const pr = await openPullRequest(ctx);
+  const outcome = pr ? { kind: "pr", pr } : { kind: "pushed" };
+  reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch });
+  return { text: reply, widgets: [], ...pr ? { pr } : {} };
 }
 async function heartbeat(config) {
   const health = await checkClaudeCode();
@@ -986,37 +1145,78 @@ async function pollLoop(config) {
   const swept = await sweepWorkspaces();
   if (swept > 0) console.log(`Cleared ${swept} stale workspace${swept === 1 ? "" : "s"}.`);
   await heartbeat(config);
-  let nextHeartbeatAt = Date.now() + HEARTBEAT_MS;
-  for (; ; ) {
-    if (Date.now() >= nextHeartbeatAt) {
+  let heartbeatTimer;
+  const scheduleHeartbeat = () => {
+    heartbeatTimer = setTimeout(async () => {
       await heartbeat(config);
-      nextHeartbeatAt = Date.now() + HEARTBEAT_MS;
-    }
-    let ctx = null;
-    try {
-      ctx = await claimJob(config);
-    } catch (err) {
-      console.error(`Claim error: ${errorMessage2(err)}`);
-      await sleep(IDLE_MS);
-      continue;
-    }
-    if (!ctx) {
-      await sleep(IDLE_MS);
-      continue;
-    }
-    try {
-      const { text, widgets, pr } = await processJob(ctx);
-      await reportJob(config, ctx.jobId, { status: "done", text, widgets, pr });
-      console.log(`\u2713 Job ${ctx.jobId} done`);
-    } catch (err) {
-      const message = errorMessage2(err);
-      console.error(`\u2717 Job ${ctx.jobId} failed: ${message}`);
+      scheduleHeartbeat();
+    }, HEARTBEAT_MS);
+  };
+  scheduleHeartbeat();
+  try {
+    for (; ; ) {
+      let ctx = null;
+      try {
+        ctx = await claimJob(config);
+      } catch (err) {
+        console.error(`Claim error: ${errorMessage2(err)}`);
+        await sleep(IDLE_MS);
+        continue;
+      }
+      if (!ctx) {
+        await sleep(IDLE_MS);
+        continue;
+      }
+      const abort = new AbortController();
+      let stopPolling = false;
+      const scheduleCancelPoll = () => {
+        setTimeout(async () => {
+          if (stopPolling) return;
+          try {
+            if (await pollJobCanceling(config, ctx.jobId)) {
+              console.log(`\u23F9 Stop requested for job ${ctx.jobId} \u2014 aborting\u2026`);
+              abort.abort();
+              return;
+            }
+          } catch {
+          }
+          if (!stopPolling) scheduleCancelPoll();
+        }, CANCEL_POLL_MS);
+      };
+      scheduleCancelPoll();
       try {
-        await reportJob(config, ctx.jobId, { status: "error", error: message });
-      } catch (reportErr) {
-        console.error(`  (also failed to report the error: ${errorMessage2(reportErr)})`);
+        const { text, widgets, pr, plans } = await processJob(ctx, abort);
+        await reportJob(config, ctx.jobId, {
+          status: "done",
+          text,
+          widgets,
+          pr,
+          ...plans?.length ? { plans } : {}
+        });
+        console.log(`\u2713 Job ${ctx.jobId} done`);
+      } catch (err) {
+        if (abort.signal.aborted) {
+          console.log(`\u23F9 Job ${ctx.jobId} canceled`);
+          try {
+            await reportJob(config, ctx.jobId, { status: "canceled" });
+          } catch (reportErr) {
+            console.error(`  (failed to report the cancellation: ${errorMessage2(reportErr)})`);
+          }
+        } else {
+          const message = errorMessage2(err);
+          console.error(`\u2717 Job ${ctx.jobId} failed: ${message}`);
+          try {
+            await reportJob(config, ctx.jobId, { status: "error", error: message });
+          } catch (reportErr) {
+            console.error(`  (also failed to report the error: ${errorMessage2(reportErr)})`);
+          }
+        }
+      } finally {
+        stopPolling = true;
       }
     }
+  } finally {
+    if (heartbeatTimer) clearTimeout(heartbeatTimer);
   }
 }
 function sleep(ms) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumecode/runner",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "FlumeCode local runner — claims jobs and drives your local Claude Code against a real checkout.",
   "bin": {

package/skills-plugin/skills/request-to-plan/SKILL.md

@@ -84,13 +84,13 @@ plan without re-deriving it.
 
 ### Multiple plans per request
 
-A single request can yield **several** plans — one thread can be accepted into
-many. If the work naturally splits into independent pieces, or the user asks for
-more than one plan, call `submit_plan` once for each finished plan so each can
-be accepted into its own GitHub issue. Give each plan its own distinct `title`
-so sibling plans don't collide. After a plan is accepted the user may keep
-commenting to refine it; treat a later turn as a fresh **Plan** phase and call
-`submit_plan` again with the revised fields.
+A single request can yield **several** plans — one thread can be accepted into many. If the
+work naturally splits into independent pieces, or the user asks for more than one plan, make
+**ONE `submit_plan` call** with all of them in the `plans[]` array (one entry per plan, each
+with a distinct title). Do **not** call `submit_plan` more than once. Each entry becomes its
+own independently-acceptable "Accept as plan" draft. After a plan is accepted the user may
+keep commenting to refine it; treat a later turn as a fresh **Plan** phase and call
+`submit_plan` again with a `plans[]` array containing the revised fields.
 
 ## Always
 

package/skills-plugin/skills/resolve-merge-conflict/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: resolve-merge-conflict
+description: >-
+  Resolve the merge conflicts left by an in-progress merge of a coding session's
+  merge branch into its pull-request branch. Use in resolve-job runs. The working
+  tree already has conflict markers; integrate both sides of every conflict
+  correctly, verify the build/tests, and leave the resolved changes in the working
+  tree. Never `git add`, commit, push, or open a PR — the runner finalizes the merge.
+---
+
+# resolve-merge-conflict
+
+The plan in the context above was **already implemented** and has an open pull
+request. Its merge branch (e.g. `main`) has since advanced and now **conflicts** with
+the PR branch. The runner has already started a `git merge` of the merge branch into
+your current branch, so your working tree contains the **conflict markers**
+(`<<<<<<<`, `=======`, `>>>>>>>`). Your job is to resolve every conflict so the PR
+becomes mergeable again — without losing this session's work or the incoming changes.
+
+## You are stateless — orient yourself first
+
+You see the whole session thread (the plan and its implementation report) but keep
+**no memory** between turns. Read it first: the plan and report tell you what this
+branch was building, which is exactly the intent you must preserve when you choose how
+to integrate each conflict. Check the FlumeCode wiki (`.flumecode/wiki/README.md`) if
+one exists to understand the conflicting code.
+
+## Step 1 — Find every conflict
+
+- `git status` shows the unmerged paths; `git diff --diff-filter=U` shows the
+  conflicting hunks. Work through **all** of them — a single leftover marker fails the
+  run.
+
+## Step 2 — Resolve each conflict correctly
+
+For each conflicted file, understand **both** sides before editing:
+
+- **Ours** (the conflict's first side) is this session's implementation — the change
+  the plan/report describes.
+- **Theirs** (the second side) is what landed on the merge branch since.
+
+Integrate them so **both** intents survive. Do **not** blindly pick a side or delete
+one half to make the markers go away — that silently drops work. When the two changes
+are genuinely incompatible, prefer keeping this session's implementation intent while
+adapting it to the incoming code (e.g. a renamed function, a moved file, a new
+signature). Remove every conflict marker; the file must read as clean, correct code.
+
+You may delegate isolated, well-scoped resolutions to **Task** subagents, but give
+each a self-contained prompt (the conflicting file's content, both intents, and the
+coding guidelines verbatim) — subagents start blank.
+
+## Step 3 — Verify
+
+Run the project's build and tests to confirm the resolved tree is correct (the
+runner's commit will also run the repo's pre-commit hook, so failing checks would
+block the merge anyway). Fix anything the merge broke.
+
+## Never
+
+- Never `git add`, `git commit`, `git merge --continue`, `git push`, or open a PR —
+  the runner stages the resolved tree, finalizes the merge commit, and updates the
+  **existing** pull request. A new PR must never be created.
+- Never leave a conflict marker behind, and never resolve a conflict by discarding one
+  side's intent.
+
+## Your final reply
+
+Your last message **is** the report posted to the session thread. Write it for the
+user: list which files conflicted and, briefly, how you resolved each, plus how you
+verified (build/tests). The runner appends the pull-request link, so don't add one.

package/skills-plugin/skills/revise-implementation/SKILL.md

@@ -39,11 +39,11 @@ actual code. Pick exactly one:
   Explain why in plain prose, offer an alternative if you have one, and end your
   turn. Make no code changes.
 - **Re-plan** — the request meaningfully changes scope or direction, enough that a
-  fresh plan should be agreed before building. Call **`submit_plan`** with the
-  revised structured fields (same shape as the request-to-plan skill: `scope`,
-  `goal`, `assumptions`, `steps`, `acceptanceCriteria` — at least 2 —, `risks`,
-  `outOfScope`). The runner posts it as a revision the user can accept; make no
-  code changes this turn.
+  fresh plan should be agreed before building. Call **`submit_plan`** with a `plans[]` array
+  containing the revised structured fields (same per-plan shape as the request-to-plan skill:
+  `scope`, `goal`, `assumptions`, `steps`, `acceptanceCriteria` — at least 2 —, `risks`,
+  `outOfScope`). Include only one entry for a revise turn. The runner posts it as a revision
+  the user can accept; make no code changes this turn.
 - **Implement** — the request is clear and reasonable. Make the change (via
   subagents — see Step 2). This is the common case for small fine-tuning.