ralphctl 0.7.0 → 0.7.1

package/dist/cli.mjs

@@ -2253,30 +2253,6 @@ var runSignalParsers = (text, timestamp, parsers = DEFAULT_SIGNAL_PARSERS) => {
 var parseHarnessSignals = (text, timestamp) => runSignalParsers(text, timestamp);
 
 // src/integration/ai/providers/claude/parse-stream.ts
-var parseClaudeJsonEnvelope = (stdout) => {
-  const trimmed = stdout.trim();
-  if (trimmed.length === 0) {
-    return { body: "", sessionId: void 0, model: void 0 };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch {
-    return { body: stdout, sessionId: void 0, model: void 0 };
-  }
-  if (typeof parsed !== "object" || parsed === null) {
-    return { body: stdout, sessionId: void 0, model: void 0 };
-  }
-  const obj = parsed;
-  const result = stringField(obj, "result");
-  const sessionId2 = stringField(obj, "session_id", "sessionId");
-  const model = stringField(obj, "model");
-  return {
-    body: result ?? stdout,
-    sessionId: sessionId2,
-    model
-  };
-};
 var stringField = (obj, ...names) => {
   for (const name of names) {
     const v = obj[name];
@@ -2284,6 +2260,63 @@ var stringField = (obj, ...names) => {
   }
   return void 0;
 };
+var createClaudeStreamParser = () => {
+  let buffer = "";
+  let body = "";
+  let sessionId2;
+  let model;
+  const emit = (raw, onLine) => {
+    if (raw.length === 0) return;
+    if (raw.startsWith("{") && raw.endsWith("}")) {
+      try {
+        const json = JSON.parse(raw);
+        onLine({ raw, json });
+        return;
+      } catch {
+      }
+    }
+    onLine({ raw });
+  };
+  const ingest = (line) => {
+    const json = line.json;
+    if (json === void 0) return;
+    if (sessionId2 === void 0) {
+      const seen = stringField(json, "session_id", "sessionId");
+      if (seen !== void 0) sessionId2 = seen;
+    }
+    const type = stringField(json, "type");
+    if (type === "system" && model === void 0) {
+      const m = stringField(json, "model");
+      if (m !== void 0) model = m;
+    }
+    if (type === "result") {
+      const r = stringField(json, "result");
+      if (r !== void 0) body = r;
+    }
+  };
+  return {
+    feed(chunk, onLine) {
+      buffer += chunk;
+      let nl = buffer.indexOf("\n");
+      while (nl !== -1) {
+        const line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        emit(line, onLine);
+        nl = buffer.indexOf("\n");
+      }
+    },
+    flush(onLine) {
+      if (buffer.length > 0) {
+        emit(buffer, onLine);
+        buffer = "";
+      }
+    },
+    ingest,
+    snapshot() {
+      return { body, sessionId: sessionId2, model };
+    }
+  };
+};
 
 // src/integration/ai/providers/_engine/idle-watchdog.ts
 var DEFAULT_IDLE_MS = 5 * 6e4;
@@ -2428,7 +2461,7 @@ var buildClaudeArgs = (session) => {
       })
     );
   }
-  const args = ["-p", "--output-format", "json", "--model", session.model];
+  const args = ["-p", "--verbose", "--output-format", "stream-json", "--model", session.model];
   args.push("--permission-mode", "bypassPermissions");
   const denied = disallowedToolsFor(session.permissions);
   if (denied.length > 0) {
@@ -2505,13 +2538,14 @@ var spawnAttempt = async (input) => {
   const child = spawnFn(command, args, {
     stdio: ["pipe", "pipe", "pipe"]
   });
-  let stdoutBuf = "";
+  const parser = createClaudeStreamParser();
   let stderrBuf = "";
+  const onLine = (line) => {
+    parser.ingest(line);
+  };
   const { code, signal } = await runHeadlessSpawn({
     child,
-    onStdout: (chunk) => {
-      stdoutBuf += chunk;
-    },
+    onStdout: (chunk) => parser.feed(chunk, onLine),
     onStderr: (chunk) => {
       stderrBuf += chunk;
     },
@@ -2530,6 +2564,7 @@ var spawnAttempt = async (input) => {
       });
     }
   });
+  parser.flush(onLine);
   if (signal === "SIGTERM") {
     return {
       kind: "error",
@@ -2541,9 +2576,8 @@ var spawnAttempt = async (input) => {
       })
     };
   }
+  const envelope = parser.snapshot();
   if (code === 0) {
-    const envelope = parseClaudeJsonEnvelope(stdoutBuf);
-    stdoutBuf = "";
     if (envelope.sessionId !== void 0) {
       deps.eventBus.publish({
         type: "log",
@@ -2578,13 +2612,12 @@ var spawnAttempt = async (input) => {
     };
   }
   if (RATE_LIMIT_RE.test(stderrBuf)) {
-    const sessionIdOnFailure = parseClaudeJsonEnvelope(stdoutBuf).sessionId;
     return {
       kind: "rate-limit",
       error: new RateLimitError({
         subCode: "spawn-stderr",
         message: `claude-provider: rate-limit detected in stderr (exit ${String(code)})`,
-        ...sessionIdOnFailure !== void 0 ? { sessionId: sessionIdOnFailure } : {}
+        ...envelope.sessionId !== void 0 ? { sessionId: envelope.sessionId } : {}
       })
     };
   }
@@ -3211,6 +3244,7 @@ var stringifyError4 = (cause) => cause instanceof Error ? cause.message : String
 
 // src/integration/ai/providers/codex/interactive.ts
 import { spawn as nodeSpawn7 } from "child_process";
+import { dirname as dirname4 } from "path";
 var defaultSpawn7 = (command, args, options) => nodeSpawn7(command, [...args], { stdio: options.stdio, cwd: options.cwd });
 var createInteractiveCodexProvider = (deps) => {
   const spawnFn = deps.spawn ?? defaultSpawn7;
@@ -3227,10 +3261,23 @@ var createInteractiveCodexProvider = (deps) => {
           })
         );
       }
+      const allRoots = [
+        String(input.cwd),
+        ...input.additionalRoots?.map((r) => String(r)) ?? [],
+        dirname4(String(input.outputFile)),
+        dirname4(String(input.promptFile))
+      ];
+      const seen = /* @__PURE__ */ new Set();
+      const dirFlags = allRoots.filter((p) => {
+        if (seen.has(p)) return false;
+        seen.add(p);
+        return true;
+      }).flatMap((p) => ["--add-dir", shellQuote2(p)]);
       const inner = [
         "codex",
         "--cd",
         shellQuote2(String(input.cwd)),
+        ...dirFlags,
         "--model",
         shellQuote2(input.model),
         "-s",
@@ -3286,7 +3333,7 @@ var stringifyError5 = (cause) => cause instanceof Error ? cause.message : String
 // src/integration/ai/providers/copilot/interactive.ts
 import { promises as fs6 } from "fs";
 import { spawn as nodeSpawn8 } from "child_process";
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 var defaultSpawn8 = (command, args, options) => nodeSpawn8(command, [...args], { stdio: options.stdio, cwd: options.cwd });
 var defaultReadFile = (path) => fs6.readFile(path, "utf8");
 var createInteractiveCopilotProvider = (deps) => {
@@ -3320,8 +3367,8 @@ var createInteractiveCopilotProvider = (deps) => {
       const allRoots = [
         String(input.cwd),
         ...input.additionalRoots?.map((r) => String(r)) ?? [],
-        dirname4(String(input.outputFile)),
-        dirname4(String(input.promptFile))
+        dirname5(String(input.outputFile)),
+        dirname5(String(input.promptFile))
       ];
       const seen = /* @__PURE__ */ new Set();
       const dirFlags = allRoots.filter((p) => {
@@ -3864,7 +3911,7 @@ var createPullRequestCreator = (deps) => async (input) => {
 
 // src/integration/ai/prompts/_engine/fs-template-loader.ts
 import { promises as fs7 } from "fs";
-import { dirname as dirname5, join as join6 } from "path";
+import { dirname as dirname6, join as join6 } from "path";
 import { fileURLToPath } from "url";
 var createFsTemplateLoader = (templatesDir) => ({
   async load(name) {
@@ -3898,7 +3945,7 @@ var tryRead = async (path) => {
   }
 };
 var TEMPLATES_DIR = (() => {
-  const here = dirname5(fileURLToPath(import.meta.url));
+  const here = dirname6(fileURLToPath(import.meta.url));
   const isBundled = import.meta.url.endsWith("/cli.mjs") || import.meta.url.endsWith("\\cli.mjs");
   const path = isBundled ? join6(here, "prompts") : join6(here, "..");
   const parsed = AbsolutePath.parse(path);
@@ -4296,7 +4343,7 @@ var createNpmVersionChecker = (deps) => {
 // package.json
 var package_default = {
   name: "ralphctl",
-  version: "0.7.0",
+  version: "0.7.1",
   description: "Agent harness for long-running AI coding tasks \u2014 orchestrates Claude Code & GitHub Copilot across repositories",
   homepage: "https://github.com/lukas-grigis/ralphctl",
   type: "module",
@@ -4605,7 +4652,7 @@ var createSkillsAdapter = (deps) => {
 };
 
 // src/integration/ai/skills/bundled/source.ts
-import { dirname as dirname6, join as join12 } from "path";
+import { dirname as dirname7, join as join12 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { readFile } from "fs/promises";
 
@@ -4632,7 +4679,7 @@ var skillsForFlow = (flowId) => FLOW_SKILLS[flowId];
 
 // src/integration/ai/skills/bundled/source.ts
 var defaultBundledRoot = (() => {
-  const here = dirname6(fileURLToPath2(import.meta.url));
+  const here = dirname7(fileURLToPath2(import.meta.url));
   const isBundled = import.meta.url.endsWith("/cli.mjs") || import.meta.url.endsWith("\\cli.mjs");
   return isBundled ? join12(here, "skills") : here;
 })();
@@ -9350,7 +9397,7 @@ var refineTicketInteractiveLeaf = (deps, ticket) => leaf(`refine-ticket-${String
     execute: async (input) => {
       const session = await deps.runInTerminal(
         async () => deps.interactiveAi.run({
-          cwd: deps.cwd,
+          cwd: input.cwd,
           promptFile: input.promptFile,
           outputFile: input.outputFile,
           model: deps.model
@@ -9407,9 +9454,18 @@ var refineTicketInteractiveLeaf = (deps, ticket) => leaf(`refine-ticket-${String
         message: `refine-ticket-${String(ticket.id)}: prompt/output paths missing \u2014 render-prompt-to-file must run first`
       });
     }
+    if (ctx.currentUnitRoot === void 0) {
+      throw new InvalidStateError({
+        entity: "chain",
+        currentState: "pre-refine",
+        attemptedAction: `refine-ticket-${String(ticket.id)}`,
+        message: `refine-ticket-${String(ticket.id)}: unit root missing \u2014 build-refine-unit must run first`
+      });
+    }
     return {
       sprint: ctx.sprint,
       ticket,
+      cwd: ctx.currentUnitRoot,
       promptFile: ctx.currentPromptFile,
       outputFile: ctx.currentOutputFile
     };
@@ -9648,9 +9704,17 @@ var createRefineFlow = (deps, opts) => {
         {
           name: `install-skills-${String(ticket.id)}`,
           flowId: "refine",
-          // Skills land in the AI session's cwd (the repo) — the provider-native conventions
-          // only auto-discover skills from cwd, not from `--add-dir` roots.
-          cwdPicker: () => opts.cwd
+          // Skills land in the AI session's cwd — for refine that's the per-ticket unit root
+          // (`<sprintDir>/refinement/<ticket-slug>/`), not the user's repo. Refinement is
+          // implementation-agnostic, so we keep the AI out of the repo's auto-discovered context.
+          cwdPicker: (ctx) => {
+            if (ctx.currentUnitRoot === void 0) {
+              throw new Error(
+                `install-skills-${String(ticket.id)}: currentUnitRoot missing \u2014 build-refine-unit must run first`
+              );
+            }
+            return ctx.currentUnitRoot;
+          }
         }
       ),
       refineTicketInteractiveLeaf(
@@ -9658,7 +9722,6 @@ var createRefineFlow = (deps, opts) => {
           interactiveAi: deps.interactiveAi,
           runInTerminal: deps.runInTerminal,
           logger: deps.logger,
-          cwd: opts.cwd,
           model: opts.model,
           ...deps.reviewBeforeApprove !== void 0 ? { reviewBeforeApprove: deps.reviewBeforeApprove } : {},
           ...deps.issuePusher !== void 0 ? { issuePusher: deps.issuePusher } : {},
@@ -9668,7 +9731,17 @@ var createRefineFlow = (deps, opts) => {
       ),
       uninstallSkillsLeaf(
         { skillsAdapter: deps.skillsAdapter },
-        { name: `uninstall-skills-${String(ticket.id)}`, cwdPicker: () => opts.cwd }
+        {
+          name: `uninstall-skills-${String(ticket.id)}`,
+          cwdPicker: (ctx) => {
+            if (ctx.currentUnitRoot === void 0) {
+              throw new Error(
+                `uninstall-skills-${String(ticket.id)}: currentUnitRoot missing \u2014 build-refine-unit must run first`
+              );
+            }
+            return ctx.currentUnitRoot;
+          }
+        }
       ),
       saveSprintLeaf({ sprintRepo: deps.sprintRepo }, `save-after-${String(ticket.id)}`)
     ])
@@ -9691,9 +9764,8 @@ var deriveOriginFromGit = async (cwd, gitRunner) => {
   return parsed === null ? void 0 : parsed;
 };
 var launchRefine = async (ctx) => {
-  const { deps, snapshot, extras, settings, interactiveAi, skillsAdapter, skillSource, cwd, bridge, sessionId: sessionId2 } = ctx;
+  const { deps, snapshot, extras, settings, interactiveAi, skillsAdapter, skillSource, bridge, sessionId: sessionId2 } = ctx;
   if (!snapshot.sprint) return { ok: false, reason: "No sprint selected." };
-  if (!cwd) return { ok: false, reason: "No repository path resolvable from the project." };
   const pending = snapshot.sprint.tickets.filter((t) => t.status === "pending");
   const refinementRoot = AbsolutePath.parse(
     join15(String(deps.storage.dataRoot), "sprints", String(snapshot.sprint.id), "refinement")
@@ -9756,7 +9828,6 @@ ${body.trim()}`;
     {
       sprintId: snapshot.sprint.id,
       pendingTickets: pending,
-      cwd,
       model: extras.modelOverride ?? settings.ai.models.refine,
       refinementRoot: refinementRoot.value
     }
@@ -10214,6 +10285,13 @@ var markTaskBlocked = (task, reason) => {
   if (!guard2.ok) return Result.error(guard2.error);
   return Result.ok({ ...guard2.value, status: "blocked", blockedReason: reason });
 };
+var unblockTask = (task) => {
+  const guard2 = requireStatus("task", task, ["blocked"], "unblock");
+  if (!guard2.ok) return Result.error(guard2.error);
+  const { blockedReason: _ignored, ...rest } = guard2.value;
+  void _ignored;
+  return Result.ok({ ...rest, status: "todo" });
+};
 var latestCritique = (task) => {
   for (let i = task.attempts.length - 1; i >= 0; i--) {
     const att = task.attempts[i];
@@ -10394,7 +10472,7 @@ var callPlannerInteractiveLeaf = (deps) => leaf("call-planner-interactive", {
       const additionalRoots = deps.additionalRoots ?? [];
       const session = await deps.runInTerminal(
         async () => deps.interactiveAi.run({
-          cwd: deps.cwd,
+          cwd: input.cwd,
           promptFile: input.promptFile,
           outputFile: input.outputFile,
           model: deps.model,
@@ -10471,10 +10549,19 @@ var callPlannerInteractiveLeaf = (deps) => leaf("call-planner-interactive", {
         message: "call-planner-interactive: prompt/output paths missing \u2014 render-prompt-to-file must run first"
       });
     }
+    if (ctx.currentUnitRoot === void 0) {
+      throw new InvalidStateError({
+        entity: "chain",
+        currentState: "pre-plan",
+        attemptedAction: "call-planner-interactive",
+        message: "call-planner-interactive: unit root missing \u2014 build-plan-unit must run first"
+      });
+    }
     return {
       sprint: ctx.sprint,
       project: ctx.project,
       existingTasks: ctx.tasks ?? [],
+      cwd: ctx.currentUnitRoot,
       promptFile: ctx.currentPromptFile,
       outputFile: ctx.currentOutputFile
     };
@@ -10536,9 +10623,21 @@ var createPlanFlow = (deps, opts) => {
       { skillsAdapter: deps.skillsAdapter, skillSource: deps.skillSource },
       {
         flowId: "plan",
-        // Skills land in the AI session's cwd (the repo) — the provider-native conventions
-        // only auto-discover skills from cwd, not from `--add-dir` roots.
-        cwdPicker: () => opts.cwd
+        // Skills land in the AI session's cwd — for plan that's the per-sprint plan unit root
+        // (`<sprintDir>/plan/<run-slug>/`), not any project repo. Plan mounts every repo as an
+        // equal `--add-dir` source; rooting the session in any one repo would auto-load that
+        // repo's `CLAUDE.md` / agents / `.mcp.json` and bias the planner toward it.
+        cwdPicker: (ctx) => {
+          if (ctx.currentUnitRoot === void 0) {
+            throw new InvalidStateError({
+              entity: "chain",
+              currentState: "pre-plan",
+              attemptedAction: "install-skills",
+              message: "install-skills: currentUnitRoot missing \u2014 build-plan-unit must run first"
+            });
+          }
+          return ctx.currentUnitRoot;
+        }
       }
     ),
     callPlannerInteractiveLeaf({
@@ -10546,12 +10645,26 @@ var createPlanFlow = (deps, opts) => {
       runInTerminal: deps.runInTerminal,
       logger: deps.logger,
       clock: deps.clock,
-      cwd: opts.cwd,
       model: opts.model,
       ...opts.additionalRoots !== void 0 && opts.additionalRoots.length > 0 ? { additionalRoots: opts.additionalRoots } : {},
       ...deps.reviewBeforeApprove !== void 0 ? { reviewBeforeApprove: deps.reviewBeforeApprove } : {}
     }),
-    uninstallSkillsLeaf({ skillsAdapter: deps.skillsAdapter }, { cwdPicker: () => opts.cwd }),
+    uninstallSkillsLeaf(
+      { skillsAdapter: deps.skillsAdapter },
+      {
+        cwdPicker: (ctx) => {
+          if (ctx.currentUnitRoot === void 0) {
+            throw new InvalidStateError({
+              entity: "chain",
+              currentState: "pre-plan",
+              attemptedAction: "uninstall-skills",
+              message: "uninstall-skills: currentUnitRoot missing \u2014 build-plan-unit must run first"
+            });
+          }
+          return ctx.currentUnitRoot;
+        }
+      }
+    ),
     saveTasksLeaf({ taskRepo: deps.taskRepo }),
     saveSprintLeaf({ sprintRepo: deps.sprintRepo })
   ]);
@@ -10559,10 +10672,9 @@ var createPlanFlow = (deps, opts) => {
 
 // src/application/ui/shared/launch/plan.ts
 var launchPlan = (ctx) => {
-  const { deps, snapshot, extras, settings, interactiveAi, skillsAdapter, skillSource, cwd, bridge, sessionId: sessionId2 } = ctx;
+  const { deps, snapshot, extras, settings, interactiveAi, skillsAdapter, skillSource, bridge, sessionId: sessionId2 } = ctx;
   if (!snapshot.project) return { ok: false, reason: "No project loaded." };
   if (!snapshot.sprint) return { ok: false, reason: "No sprint selected." };
-  if (!cwd) return { ok: false, reason: "No repository path resolvable from the project." };
   const planRoot = AbsolutePath.parse(
     join17(String(deps.storage.dataRoot), "sprints", String(snapshot.sprint.id), "plan")
   );
@@ -10601,9 +10713,9 @@ ${summary}`;
     {
       sprintId: snapshot.sprint.id,
       projectId: snapshot.project.id,
-      cwd,
-      // Mount every repo on the project so the planner can navigate across them without per-file
-      // approval prompts. Duplicates with `cwd` are folded out by the adapter.
+      // Mount every repo on the project as an equal `--add-dir` source so the planner can
+      // navigate across them without per-file approval prompts. No repo enjoys cwd privilege —
+      // the session's cwd is the per-sprint plan unit root.
       additionalRoots: snapshot.project.repositories.map((r) => r.path),
       model: extras.modelOverride ?? settings.ai.models.plan,
       planRoot: planRoot.value
@@ -10675,7 +10787,7 @@ var loop = (name, body, opts = {}) => ({
 
 // src/integration/observability/sinks/progress-file-sink.ts
 import { promises as fs14 } from "fs";
-import { dirname as dirname7 } from "path";
+import { dirname as dirname8 } from "path";
 var MAX_QUEUE_DEPTH = 1e4;
 var createProgressFileSink = (deps) => {
   const queue = [];
@@ -10795,7 +10907,7 @@ var TEMPLATE = `${TITLE}
 ${HEADINGS.map((h) => `## ${h}
 `).join("\n")}`;
 var mergeSection = async (path, rendered) => {
-  await fs14.mkdir(dirname7(path), { recursive: true });
+  await fs14.mkdir(dirname8(path), { recursive: true });
   let current;
   try {
     current = await fs14.readFile(path, "utf8");
@@ -11017,6 +11129,45 @@ var gitCommitWithMessage = async (runner, cwd, message) => {
   if (!head.ok) return Result.error(head.error);
   return Result.ok({ committed: true, headSha: head.value });
 };
+var gitStashPush = async (runner, cwd, message) => {
+  const dirty = await gitHasUncommittedChanges(runner, cwd);
+  if (!dirty.ok) return Result.error(dirty.error);
+  if (!dirty.value) return Result.ok({ stashed: false });
+  const stash = await runner.run(cwd, ["stash", "push", "-u", "-m", message]);
+  if (!stash.ok) return Result.error(stash.error);
+  if (stash.value.exitCode !== 0) {
+    return Result.error(
+      new StorageError({
+        subCode: "io",
+        message: `git stash push failed: ${(stash.value.stderr || stash.value.stdout).trim()}`
+      })
+    );
+  }
+  return Result.ok({ stashed: true });
+};
+var gitResetHard = async (runner, cwd) => {
+  const reset = await runner.run(cwd, ["reset", "--hard", "HEAD"]);
+  if (!reset.ok) return Result.error(reset.error);
+  if (reset.value.exitCode !== 0) {
+    return Result.error(
+      new StorageError({
+        subCode: "io",
+        message: `git reset --hard failed: ${(reset.value.stderr || reset.value.stdout).trim()}`
+      })
+    );
+  }
+  const clean = await runner.run(cwd, ["clean", "-fd"]);
+  if (!clean.ok) return Result.error(clean.error);
+  if (clean.value.exitCode !== 0) {
+    return Result.error(
+      new StorageError({
+        subCode: "io",
+        message: `git clean -fd failed: ${(clean.value.stderr || clean.value.stdout).trim()}`
+      })
+    );
+  }
+  return Result.ok(void 0);
+};
 var gitGetCurrentBranch = async (runner, cwd) => {
   const result = await runner.run(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
   if (!result.ok) return Result.error(result.error);
@@ -12015,6 +12166,7 @@ var postTaskCheckLeaf = (deps, opts, taskId) => {
 };
 
 // src/business/task/preflight-task.ts
+var ELEMENT_NAME = "preflight-task";
 var preflightTaskUseCase = async (props) => {
   const log = props.logger.named("task.preflight");
   log.debug("checking working tree", { cwd: props.cwd });
@@ -12035,6 +12187,9 @@ var preflightTaskUseCase = async (props) => {
     });
     return Result.ok(void 0);
   }
+  if (policy === "prompt") {
+    return resolveViaPrompt(props, count.value);
+  }
   log.warn("refusing to start a task on a dirty tree", { cwd: props.cwd, dirtyEntries: count.value });
   return Result.error(
     new InvalidStateError({
@@ -12046,24 +12201,105 @@ var preflightTaskUseCase = async (props) => {
     })
   );
 };
+var resolveViaPrompt = async (props, dirtyEntries) => {
+  const log = props.logger.named("task.preflight");
+  if (props.askDirtyTreeChoice === void 0 || props.gitStash === void 0 || props.gitReset === void 0 || props.clock === void 0) {
+    throw new InvalidStateError({
+      entity: ELEMENT_NAME,
+      currentState: "prompt-without-deps",
+      attemptedAction: "configure-prompt-deps",
+      message: "preflight-task: dirtyTreePolicy='prompt' requires askDirtyTreeChoice, gitStash, gitReset, and clock dependencies"
+    });
+  }
+  const choice = await props.askDirtyTreeChoice({ cwd: props.cwd, dirtyEntries });
+  if (!choice.ok) {
+    return Result.error(choice.error);
+  }
+  switch (choice.value) {
+    case "keep":
+      log.info(`working tree dirty (${String(dirtyEntries)} entries) \u2014 proceeding (user chose 'keep')`, {
+        cwd: props.cwd,
+        dirtyEntries
+      });
+      return Result.ok(void 0);
+    case "stash": {
+      const sprintLabel = props.sprintId !== void 0 && props.sprintId.length > 0 ? props.sprintId : "unknown";
+      const message = `ralphctl preflight stash (sprint ${sprintLabel}, ${String(props.clock())})`;
+      const stashed = await props.gitStash(props.cwd, message);
+      if (!stashed.ok) return Result.error(stashed.error);
+      if (!stashed.value.stashed) {
+        log.warn("stash reported no changes despite dirty status \u2014 proceeding", { cwd: props.cwd });
+        return Result.ok(void 0);
+      }
+      log.info(`stashed working tree \u2014 recoverable as: ${message}`, { cwd: props.cwd, stashMessage: message });
+      return Result.ok(void 0);
+    }
+    case "reset": {
+      const reset = await props.gitReset(props.cwd);
+      if (!reset.ok) return Result.error(reset.error);
+      log.info("reset working tree \u2014 discarded uncommitted + untracked changes", { cwd: props.cwd });
+      return Result.ok(void 0);
+    }
+    case "cancel":
+      return Result.error(
+        new AbortError({ elementName: ELEMENT_NAME, reason: "user cancelled on dirty working tree" })
+      );
+  }
+};
 
 // src/application/flows/implement/leaves/preflight-task.ts
+var ELEMENT_NAME2 = "preflight-task";
 var preflightTaskLeaf = (deps, cwd, name = "preflight-task") => {
   const gitStatusEntryCount = async (path) => {
     const status = await gitStatusPorcelain(deps.gitRunner, path);
     if (!status.ok) return status;
     return { ok: true, value: status.value.length };
   };
+  const gitStash = (path, message) => gitStashPush(deps.gitRunner, path, message);
+  const gitReset = (path) => gitResetHard(deps.gitRunner, path);
+  const askDirtyTreeChoice = async ({
+    cwd: dirtyCwd,
+    dirtyEntries
+  }) => {
+    const choice = await deps.interactive.askChoice(
+      `Working tree at ${String(dirtyCwd)} has ${String(dirtyEntries)} uncommitted change(s). How do you want to handle it?`,
+      [
+        {
+          label: "Keep changes \u2014 proceed on the dirty tree",
+          value: "keep",
+          description: "AI may build on / overwrite the pending diff"
+        },
+        { label: "Stash \u2014 save changes to a recoverable stash, then proceed", value: "stash" },
+        {
+          label: "Reset \u2014 discard all uncommitted + untracked changes, then proceed",
+          value: "reset",
+          description: "git reset --hard && git clean -fd"
+        },
+        { label: "Cancel \u2014 abort the implement run", value: "cancel" }
+      ]
+    );
+    if (!choice.ok) {
+      return Result.error(
+        new AbortError({ elementName: ELEMENT_NAME2, reason: `dirty-tree prompt cancelled \u2014 ${choice.error.message}` })
+      );
+    }
+    return Result.ok(choice.value);
+  };
   return leaf(name, {
     useCase: {
-      execute: async () => preflightTaskUseCase({
+      execute: async (input) => preflightTaskUseCase({
         cwd,
         gitStatusEntryCount,
+        gitStash,
+        gitReset,
+        askDirtyTreeChoice,
+        clock: deps.clock,
+        sprintId: input.sprintId,
         logger: deps.logger,
         ...deps.dirtyTreePolicy !== void 0 ? { dirtyTreePolicy: deps.dirtyTreePolicy } : {}
       })
     },
-    input: () => void 0,
+    input: (ctx) => ({ sprintId: String(ctx.sprintId) }),
     output: (ctx) => ctx
   });
 };
@@ -12837,12 +13073,15 @@ var createImplementFlow = (deps, opts) => {
     path: r.path,
     ...r.setupScript !== void 0 ? { setupScript: r.setupScript } : {}
   }));
+  const dirtyTreePolicy = opts.dirtyTreePolicy ?? "prompt";
   const preflightLeaves = uniqueRepoCwds.map(
     (cwd, i) => preflightTaskLeaf(
       {
         gitRunner: deps.gitRunner,
+        interactive: deps.interactive,
+        clock: deps.clock,
         logger: deps.logger,
-        ...opts.dirtyTreePolicy !== void 0 ? { dirtyTreePolicy: opts.dirtyTreePolicy } : {}
+        dirtyTreePolicy
       },
       cwd,
       `preflight-task-${String(i + 1)}-${String(cwd)}`
@@ -12903,7 +13142,7 @@ var createImplementFlow = (deps, opts) => {
 
 // src/integration/observability/sinks/file-log-sink.ts
 import { promises as fs17 } from "fs";
-import { dirname as dirname8 } from "path";
+import { dirname as dirname9 } from "path";
 var startFileLogSink = (deps) => {
   const queue = [];
   let draining;
@@ -12915,7 +13154,7 @@ var startFileLogSink = (deps) => {
       if (next === void 0) continue;
       try {
         if (!dirEnsured) {
-          await fs17.mkdir(dirname8(String(deps.file)), { recursive: true });
+          await fs17.mkdir(dirname9(String(deps.file)), { recursive: true });
           dirEnsured = true;
         }
         await fs17.appendFile(String(deps.file), `${JSON.stringify(next)}
@@ -16704,6 +16943,39 @@ var createTicketRemoveFlow = (deps) => leaf("ticket-remove", {
   output: (c, o) => ({ ...c, output: o })
 });
 
+// src/business/task/unblock-task.ts
+var unblockTaskUseCase = async (props) => {
+  const log = props.logger.named("task.unblock");
+  if (props.task.status === "todo") {
+    log.debug("already todo, skipping", { taskId: props.task.id, sprintId: props.sprintId });
+    return Result.ok(props.task);
+  }
+  log.debug("unblocking task", {
+    taskId: props.task.id,
+    sprintId: props.sprintId,
+    from: props.task.status
+  });
+  const transitioned = unblockTask(props.task);
+  if (!transitioned.ok) {
+    log.warn("invalid state transition", {
+      taskId: props.task.id,
+      from: props.task.status,
+      error: transitioned.error.message
+    });
+    return Result.error(transitioned.error);
+  }
+  const persisted = await props.taskRepo.update(props.sprintId, transitioned.value);
+  if (!persisted.ok) {
+    log.error("persist failed", { taskId: transitioned.value.id, error: persisted.error.message });
+    return Result.error(persisted.error);
+  }
+  log.info(`unblocked task '${transitioned.value.name}'`, {
+    taskId: transitioned.value.id,
+    sprintId: props.sprintId
+  });
+  return Result.ok(transitioned.value);
+};
+
 // src/application/ui/tui/views/sprint-detail-view.tsx
 import { jsx as jsx41, jsxs as jsxs30 } from "react/jsx-runtime";
 var buildFocusList = (sprint, tasks) => [
@@ -16772,12 +17044,15 @@ var SprintDetailView = () => {
   const [feedback, setFeedback] = useState25(void 0);
   const ticketsEditable = sprint?.status === "draft";
   const inDetail = openIdx !== void 0;
+  const focusedNow = focusList[Math.min(cursorIdx, Math.max(0, focusList.length - 1))];
+  const focusedBlockedTask = focusedNow?.kind === "task" && focusedNow.task.status === "blocked" ? focusedNow.task : void 0;
   useViewHints(
     inDetail ? [{ keys: "esc", label: "back to list" }] : [
       { keys: "n", label: "flows" },
       { keys: "\u21B5/o", label: "open" },
       { keys: "a", label: "add ticket" },
-      { keys: "d", label: "remove ticket" }
+      { keys: "d", label: "remove ticket" },
+      ...focusedBlockedTask !== void 0 ? [{ keys: "u", label: "unblock" }] : []
     ]
   );
   useInput14((input, key) => {
@@ -16805,6 +17080,10 @@ var SprintDetailView = () => {
     if (input === "d" && ticketsEditable) {
       const focused = focusList[Math.min(cursorIdx, focusList.length - 1)];
       if (focused?.kind === "ticket") setConfirmRemove(focused.ticket);
+      return;
+    }
+    if (input === "u" && focusedBlockedTask !== void 0) {
+      void handleUnblock(focusedBlockedTask);
     }
   });
   useEffect17(() => confirmRemove !== void 0 ? ui.claimPrompt() : void 0, [confirmRemove, ui.claimPrompt]);
@@ -16820,6 +17099,21 @@ var SprintDetailView = () => {
     setFeedback(`\u2713 removed "${target.title}"`);
     reload();
   };
+  const handleUnblock = async (target) => {
+    if (sprint === void 0) return;
+    const r = await unblockTaskUseCase({
+      task: target,
+      sprintId: sprint.id,
+      taskRepo: deps.taskRepo,
+      logger: deps.logger
+    });
+    if (!r.ok) {
+      setFeedback(`\u2717 ${r.error.message}`);
+      return;
+    }
+    setFeedback(`\u2713 unblocked "${target.name}"`);
+    reload();
+  };
   return /* @__PURE__ */ jsx41(ViewShell, { title: "Sprint", subtitle: state.kind === "ok" ? state.value.sprint.name : "loading", children: ui.helpOpen ? /* @__PURE__ */ jsx41(HelpOverlay, {}) : state.kind === "loading" || state.kind === "idle" ? /* @__PURE__ */ jsx41(Box29, { paddingX: spacing.indent, children: /* @__PURE__ */ jsx41(Spinner, { label: "Loading\u2026" }) }) : state.kind === "error" ? /* @__PURE__ */ jsx41(Box29, { paddingX: spacing.indent, children: /* @__PURE__ */ jsx41(Text31, { children: "Failed to load sprint." }) }) : confirmRemove !== void 0 ? /* @__PURE__ */ jsxs30(Box29, { flexDirection: "column", paddingX: spacing.indent, children: [
     /* @__PURE__ */ jsxs30(Text31, { children: [
       "Remove ticket ",
@@ -19615,7 +19909,7 @@ import { basename as basename3, join as join33 } from "path";
 // src/application/ui/tui/prompts/path-picker-prompt.tsx
 import { useEffect as useEffect28, useState as useState35 } from "react";
 import { promises as fs24 } from "fs";
-import { dirname as dirname9, join as join32 } from "path";
+import { dirname as dirname10, join as join32 } from "path";
 import { homedir } from "os";
 import { Box as Box43, Text as Text45, useInput as useInput23 } from "ink";
 import { jsx as jsx55, jsxs as jsxs44 } from "react/jsx-runtime";
@@ -19675,7 +19969,7 @@ var PathPickerPrompt = ({
         return;
       }
       if (key.backspace || key.delete) {
-        const parent = dirname9(cwd);
+        const parent = dirname10(cwd);
         if (parent !== cwd) {
           setCwd(parent);
           setCursor(1);
@@ -19700,7 +19994,7 @@ var PathPickerPrompt = ({
         const row = rows[cursor];
         if (row === void 0) return;
         if (row.kind === "parent") {
-          const parent = dirname9(cwd);
+          const parent = dirname10(cwd);
           if (parent !== cwd) {
             setCwd(parent);
             setCursor(1);
@@ -21734,6 +22028,44 @@ var registerTaskCommand = (program) => {
       return;
     }
     process.stdout.write(`${JSON.stringify(result.value, null, 2)}
+`);
+  });
+  task.command("unblock <taskId>").description("flip a blocked task back to todo so the implement loop picks it up again").requiredOption("-s, --sprint <id>", "sprint id").action(async (rawTaskId, opts) => {
+    const sprintId = SprintId.parse(opts.sprint);
+    if (!sprintId.ok) {
+      process.stderr.write(`error: invalid sprint id: ${sprintId.error.message}
+`);
+      process.exit(1);
+      return;
+    }
+    const taskId = TaskId.parse(rawTaskId);
+    if (!taskId.ok) {
+      process.stderr.write(`error: invalid task id: ${taskId.error.message}
+`);
+      process.exit(1);
+      return;
+    }
+    const { deps } = await bootstrapCli();
+    const loaded = await deps.taskRepo.findById(sprintId.value, taskId.value);
+    if (!loaded.ok) {
+      process.stderr.write(`error: ${loaded.error.message}
+`);
+      process.exit(1);
+      return;
+    }
+    const result = await unblockTaskUseCase({
+      task: loaded.value,
+      sprintId: sprintId.value,
+      taskRepo: deps.taskRepo,
+      logger: deps.logger
+    });
+    if (!result.ok) {
+      process.stderr.write(`error: ${result.error.message}
+`);
+      process.exit(1);
+      return;
+    }
+    process.stdout.write(`unblocked task '${result.value.name}' (${String(result.value.id)})
 `);
   });
 };

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-05-18T19:45:23.510Z",
+  "generatedAt": "2026-05-19T05:25:59.916Z",
   "assets": [
     "prompts/_partials/harness-context.md",
     "prompts/_partials/signals-evaluation.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Agent harness for long-running AI coding tasks — orchestrates Claude Code & GitHub Copilot across repositories",
   "homepage": "https://github.com/lukas-grigis/ralphctl",
   "type": "module",