From 7daec1baee20066d2ffdd204463cfa2000b3e86f Mon Sep 17 00:00:00 2001 From: arielarevalo <71473451+arielarevalo@users.noreply.github.com> Date: Mon, 17 Aug 2026 08:02:33 -0600 Subject: [PATCH] Resume an interrupted run from the entry command The pilot run died at step 12 of about 21 because the account hit a session limit. Its state was intact and pointed at the step it was about to take, ninety minutes and $28 of work sat on disk, and nothing could pick it up. Getting back there meant paying it again. The mechanism was already built and the specification already assumed it. SPEC section 3.5: one static command serves both a fresh run and a run resumed at any node, which is why the command body tells the runner to stand by instead of naming a step. Gate resume has always used that. Nothing was wired to it for a run whose session simply went away. Resuming is the default, since the expensive mistake is redoing work rather than continuing it. --new starts fresh and leaves the stopped run alone. The auto flag is carried rather than re-read: a run cannot change its mind halfway about whether a human is behind it, and the answers already recorded were given under whichever mode was in force. Three refusals, all of them cases where guessing is worse than asking. A graph that moved underneath the run is refused rather than resumed against nodes that may no longer exist. Several stopped runs are named rather than picked between. A run stopped mid-ask needs its answers, not a resume past them, since its node already points at the destination. The entry command's argument hint is now always present, because every workflow can be interrupted and so every workflow can be resumed. Two tests had baked in the old shape: a frontmatter field count, and a key pattern that never allowed a hyphen even though argument-hint has always had one. --- CHANGELOG.md | 27 +++++- README.md | 24 ++++- package-lock.json | 4 +- package.json | 2 +- src/emit/claude-code.ts | 171 +++++++++++++++++++++++++++++++-- src/index.ts | 2 +- tests/emit-claude-code.test.ts | 148 +++++++++++++++++++++++++++- 7 files changed, 361 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a50a9b..e54c478 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.0] - 2026-08-17 + +### Added + +- **A run interrupted mid-flight can be resumed from the entry command.** A long + workflow will be interrupted: a session limit, a closed laptop, a crash. Its + state was already intact and already pointed at the step it was about to take, + and SPEC section 3.5 already said "one static command therefore serves both a + fresh run and a run resumed at any node", which is how gate resume has always + worked. Nothing was wired to it for an interrupted run, so the work was simply + lost. Running the entry command again now picks the run up where it stopped and + reports what it resumed. + + Resuming is the default, because the expensive mistake is redoing work rather + than continuing it. `--new` starts a fresh run and leaves the stopped one + alone. The auto flag is carried rather than re-read, so a run cannot change + halfway about whether a human is behind it. A run whose graph hash no longer + matches is refused rather than resumed against nodes that may have moved, and + several stopped runs are named rather than guessed between. A run stopped + mid-ask is reported as needing its answers, not resumed past them. + +- The entry command now always carries an `argument-hint`, since every workflow + can be interrupted and therefore resumed. + ## [0.1.4] - 2026-08-17 ### Fixed @@ -168,7 +192,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 Vitest test suite, and GitHub Actions for CI and publishing. - Placeholder release reserving the `minflow` package name on npm. -[Unreleased]: https://github.com/minlayer/minflow/compare/v0.1.4...HEAD +[Unreleased]: https://github.com/minlayer/minflow/compare/v0.2.0...HEAD +[0.2.0]: https://github.com/minlayer/minflow/compare/v0.1.4...v0.2.0 [0.1.4]: https://github.com/minlayer/minflow/compare/v0.1.3...v0.1.4 [0.1.3]: https://github.com/minlayer/minflow/compare/v0.1.2...v0.1.3 [0.1.2]: https://github.com/minlayer/minflow/compare/v0.1.1...v0.1.2 diff --git a/README.md b/README.md index 5636696..a9c7d74 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,23 @@ Every compiled workflow also accepts `--auto` on its entry command, which answer its own questions and runs unattended. It is the same mechanism either way, so an unattended run exercises the real ask path rather than a mode that skips it. +### A run you can pick back up + +A long workflow will be interrupted. A session limit, a closed laptop, a crash. +Running the entry command again **resumes where it stopped** and says so, rather +than starting over: + +``` +resuming run run-20260817045146-b71a96 at step "draft-findings", 12 steps in. +Everything already finished is kept. Pass --new to start over instead. +``` + +Resuming is the default because the expensive mistake is redoing work, not +continuing it. `--new` starts fresh and leaves the stopped run alone. A run whose +graph has changed underneath it is refused rather than resumed against nodes that +may have moved, and when several runs are stopped it names them instead of +guessing. + ### Sign-off that actually blocks `wf.gate()` parks the run and waits for a human to release it, across sessions if @@ -205,9 +222,10 @@ registrations are scoped so that nothing fires during unrelated work. ## Status Working: the builder, the IR, the graph lint, the transition evaluator, run -context interpolation, command nodes, interactive asks, auto mode, skills shipped -inside the plugin, skill validation, Mermaid output, generated tests, and the -Claude Code backend. 640 tests, none of which need a model. +context interpolation, command nodes, interactive asks, auto mode, resuming an +interrupted run, skills shipped inside the plugin, skill validation, Mermaid +output, generated tests, and the Claude Code backend. 646 tests, none of which +need a model. A compiled workflow runs: the transition cycle, a judge verdict, a gate parked in one session and released in another, a retry to its limit, a command node routing diff --git a/package-lock.json b/package-lock.json index 2a10a82..ee35ae9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "minflow", - "version": "0.1.4", + "version": "0.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "minflow", - "version": "0.1.4", + "version": "0.2.0", "license": "MIT", "dependencies": { "randexp": "^0.5.3", diff --git a/package.json b/package.json index 7952d1e..28ebca8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "minflow", - "version": "0.1.4", + "version": "0.2.0", "description": "A workflow compiler for coding agents. Describe a graph of steps in TypeScript; get a plugin the agent installs and runs.", "keywords": [ "minflow", diff --git a/src/emit/claude-code.ts b/src/emit/claude-code.ts index b9f650b..f391028 100644 --- a/src/emit/claude-code.ts +++ b/src/emit/claude-code.ts @@ -990,16 +990,23 @@ function askProtocolSection(pluginName: string): string { } function runCommandFile(ir: Graph, pluginName: string): string { + // `--new` is always offered, unlike `--auto`: every workflow can be + // interrupted, so every workflow can be resumed, and the flag is how you say + // you meant to start over rather than continue. + const hints = graphAsks(ir) + ? "[--auto to answer the run's own questions instead of asking you] [--new to start over " + + "instead of resuming]" + : "[--new to start over instead of resuming]"; return commandFor( - `Start the "${ir.name}" workflow.`, + `Start or resume the "${ir.name}" workflow.`, spawnRunnerBody( pluginName, - `Start the **${oneLine(ir.name)}** workflow, which begins at \`${ir.entry}\`.`, + `Start the **${oneLine(ir.name)}** workflow, which begins at \`${ir.entry}\`.\n\n` + + "If a previous run stopped part way through, this picks it up where it left off " + + "instead of starting again, and says so. Everything already finished is kept.", graphAsks(ir), ), - // Only offered when there is something to answer. A flag advertised on a - // workflow that never asks is a flag that does nothing. - graphAsks(ir) ? "[--auto to answer the run's own questions instead of asking you]" : undefined, + hints, ); } @@ -2107,6 +2114,10 @@ const ASK_MARKER = "MINFLOW-ASK"; // answers nobody is coming to give. const AUTO_FLAG = /(^|\s)--auto\b/; +// Forces a fresh run when one is sitting there half finished. The default is to +// resume, because the expensive mistake is redoing work, not continuing it. +const NEW_FLAG = /(^|\s)--new\b/; + // A test seam, and the only one in this file. // // Set to a path, it answers observations from that file instead of resolving @@ -2262,6 +2273,83 @@ function linkSession(sessionId, runId) { // Every run parked at a gate, which is how a resume finds its run from a session // that never started it. Reading a directory of small JSON files is the whole // index: there is no second one to keep consistent with the state files. +// Runs whose session went away mid-flight. +// +// The state is intact and its node already points at the step the run was about to +// take, so such a run is exactly as resumable as one parked at a gate. Nothing +// was ever wired to pick it up, which is how ninety minutes of work became +// unrecoverable the first time a session limit was hit. +// +// Only "running" is claimed here. "awaiting" is a gate and has its own command. +// "asking" put questions in front of a session that is now gone, and resuming it +// means asking again rather than continuing, so it is reported rather than +// silently resumed into a destination whose answers never arrived. +function resumableRuns() { + let entries = []; + try { + entries = fs.readdirSync(path.join(DATA, "runs")); + } catch (error) { + return []; + } + const found = []; + for (const entry of entries) { + if (entry.slice(-5) !== ".json") continue; + const state = readJson(path.join(DATA, "runs", entry)); + if (state === null || state.status !== "running") continue; + found.push(state); + } + return found; +} + +/** Runs stalled mid-ask, which need answers rather than a resume. */ +function askingRuns() { + let entries = []; + try { + entries = fs.readdirSync(path.join(DATA, "runs")); + } catch (error) { + return []; + } + const found = []; + for (const entry of entries) { + if (entry.slice(-5) !== ".json") continue; + const state = readJson(path.join(DATA, "runs", entry)); + if (state === null || state.status !== "asking") continue; + found.push(state); + } + return found; +} + +/** + * Which stalled run the entry command meant, when it meant one at all. + * + * The same order of preference gate resume uses, and for the same reason: + * resuming the wrong run is worse than asking which. + */ +function resumableRunFor(event, sessionId) { + const named = commandArgument(event).replace(AUTO_FLAG, "").replace(NEW_FLAG, "").trim(); + const candidates = resumableRuns(); + if (candidates.length === 0) return { none: true }; + if (named !== "") { + for (const state of candidates) { + if (state.runId === named) return { state: state }; + } + return { none: true }; + } + const linked = runIdForSession(sessionId); + for (const state of candidates) { + if (state.runId === linked) return { state: state }; + } + if (candidates.length === 1) return { state: candidates[0] }; + const ids = candidates.map(function (state) { + return state.runId + ' at step "' + state.node + '"'; + }); + return { + error: + candidates.length + " runs stopped part way through: " + ids.join(", ") + + ". Name the one to resume, or pass --new to start a fresh run.", + }; +} + function parkedRuns(gate) { let entries = []; try { @@ -3137,11 +3225,40 @@ function startRun(event, sessionId) { ); return; } + const argument = commandArgument(event); + + // SPEC section 3.5: one static command serves both a fresh run and a run + // resumed at any node, which is why the command body tells the runner to stand + // by rather than naming a step. Gate resume has always used that. A run whose + // session died mid-flight can use it too, and until now nothing did, so the + // work was simply lost. + if (!NEW_FLAG.test(argument)) { + const stalled = askingRuns(); + if (stalled.length > 0 && resumableRuns().length === 0) { + const one = stalled[0]; + report( + "run " + one.runId + ' is waiting on answers before step "' + one.node + + '", so it needs those answers rather than a resume. Answer it, or pass --new to start ' + + "a fresh run.", + ); + return; + } + const found = resumableRunFor(event, sessionId); + if (found.error) { + report(found.error); + return; + } + if (found.state) { + resumeRun(found.state, graph, sessionId); + return; + } + } + const runId = mintRunId(); // Read once, at the start, and carried for the life of the run. A run cannot // become unattended halfway through, and every later decision can see that the // answers behind it were invented. - const auto = AUTO_FLAG.test(commandArgument(event)); + const auto = AUTO_FLAG.test(argument); const state = { runId: runId, graphHash: PLUGIN.graphHash, @@ -3175,6 +3292,48 @@ function startRun(event, sessionId) { }); } +/** + * Pick a stalled run back up where it stopped. + * + * The same three steps gate resume takes, for the same reason: the state already + * names the node to continue into, so resuming is flipping the status and letting + * the command's own body spawn a fresh runner. + * + * The auto flag is carried, never re-read from the arguments. A run cannot change its + * mind halfway about whether a human is behind it, and the answers already + * recorded were given under whichever mode was in force. + */ +function resumeRun(parked, graph, sessionId) { + if (parked.graphHash !== graph.hash) { + report( + "run " + parked.runId + " started against graph " + parked.graphHash + ", but " + + PLUGIN.graphFile + " now hashes to " + graph.hash + + ". Refusing to resume it: its nodes may have moved. Pass --new to start a fresh run.", + ); + return; + } + if (needsAgent(parked.node) && typeof PLUGIN.agents[parked.node] !== "string") { + report('no agent is registered for node "' + parked.node + '". Regenerate the plugin.'); + return; + } + const state = Object.assign({}, parked, { status: "running" }); + delete state.host; + saveState(withScratch(state, startingScratch(state))); + linkSession(sessionId, state.runId); + appendTrace(state.runId, { + at: new Date().toISOString(), + decision: "resume", + session: sessionId, + run: state.runId, + node: state.node, + steps: state.steps, + }); + report( + "resuming run " + state.runId + ' at step "' + state.node + '", ' + state.steps + + " steps in. Everything already finished is kept. Pass --new to start over instead.", + ); +} + // A gate resume may arrive in a session that never started the run, which is the // whole point of parking on a run id rather than a session (SPEC D11). The run is // named explicitly if the user named it, then taken from this session, then from diff --git a/src/index.ts b/src/index.ts index 6b97316..47779e7 100644 --- a/src/index.ts +++ b/src/index.ts @@ -164,4 +164,4 @@ export type { export { isCommandNode } from "./ir.js"; /** The current package version. */ -export const VERSION = "0.1.4"; +export const VERSION = "0.2.0"; diff --git a/tests/emit-claude-code.test.ts b/tests/emit-claude-code.test.ts index 87f7cc6..7159229 100644 --- a/tests/emit-claude-code.test.ts +++ b/tests/emit-claude-code.test.ts @@ -1354,6 +1354,14 @@ interface Harness { trace(): Record[]; /** Rewrites the compiled graph, as an editor recompiling mid-run would. */ editGraph(change: (graph: Record) => void): void; + /** + * Edit a saved run's state in place. + * + * For the one thing no sequence of hook fires can produce: a run whose own + * recorded graph hash is stale while the plugin and the graph file agree, + * which is what regenerating a plugin under a stopped run leaves behind. + */ + patchRun(runId: string, change: (state: Record) => void): void; /** * Starts a run the way the platform actually starts one, in two beats. * @@ -1498,6 +1506,12 @@ async function withPlugin( change(graph); sync.writeFileSync(graphFile, JSON.stringify(graph, null, 2), "utf8"); }, + patchRun(runId, change) { + const file = path.join(dataDir, "runs", `${runId}.json`); + const state = JSON.parse(sync.readFileSync(file, "utf8")) as Record; + change(state); + sync.writeFileSync(file, JSON.stringify(state, null, 2), "utf8"); + }, }; body(harness); @@ -2042,6 +2056,128 @@ describe("a run, driven through the emitted dispatcher", () => { // Run context, interpolated at spawn time // --------------------------------------------------------------------------- +describe("a run whose session went away, resumed from the entry command", () => { + it("picks the run up where it stopped instead of starting a second one", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin(); + // One real step, then the session simply stops existing. Nothing marks the + // run as finished or parked: its status stays "running", which is exactly + // the state a session limit or a closed laptop leaves behind. + plugin.fire(stopped(reported({ done: true }))); + const stalled = plugin.onlyRun(); + expect(stalled.status).toBe("running"); + expect(stalled.node).toBe("build"); + expect(stalled.steps).toBe(1); + + // The entry command again, in a session that never started the run. SPEC + // section 3.5 always said one static command serves a fresh run and a + // resumed one; gate resume used that and this did not, so the work was + // simply lost. + const again = plugin.fire(typed("drivable:run-drivable", "session-2")); + expect(again.decision).toBeNull(); + expect(again.stderr).toContain("resuming run"); + expect(again.stderr).toContain('"build"'); + + // The same run, not a second one, and no work was rewound. + const resumed = plugin.onlyRun(); + expect(resumed.runId).toBe(stalled.runId); + expect(resumed.node).toBe("build"); + expect(resumed.steps).toBe(1); + expect(resumed.outputs).toEqual(stalled.outputs); + + // And it continues, rather than re-running the entry step. + const fired = plugin.fire(stopped("Standing by.", "session-2")); + expect(fired.reason).toContain("drivable:step-build"); + expect(plugin.trace().some((entry) => entry.decision === "resume")).toBe(true); + }); + }); + + it("carries the auto flag rather than re-reading it, so a run cannot change mode", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin("session-1", "--auto"); + plugin.fire(stopped(reported({ done: true }))); + expect(plugin.onlyRun().auto).toBe(true); + + // Resumed without the flag. The answers already recorded were given under + // auto, so quietly promoting the run to attended would misdescribe them. + plugin.fire(typed("drivable:run-drivable", "session-2")); + expect(plugin.onlyRun().auto).toBe(true); + }); + }); + + it("starts a fresh run when told to, leaving the stalled one alone", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin(); + plugin.fire(stopped(reported({ done: true }))); + const stalled = plugin.onlyRun(); + + plugin.fire(typed("drivable:run-drivable", "session-2", "--new")); + const runs = plugin.runs(); + expect(runs).toHaveLength(2); + const fresh = runs.find((run) => run.runId !== stalled.runId); + expect(fresh?.node).toBe("draft"); + expect(fresh?.steps).toBe(0); + // The old one is untouched, so nothing was destroyed by asking for a new run. + expect(runs.find((run) => run.runId === stalled.runId)?.node).toBe("build"); + }); + }); + + it("refuses to guess which of several stalled runs was meant, and names them", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin("session-1"); + plugin.fire(stopped(reported({ done: true }))); + plugin.fire(typed("drivable:run-drivable", "session-2", "--new")); + plugin.fire(stopped("Standing by.", "session-2")); + plugin.fire(stopped(reported({ done: true }), "session-2")); + expect(plugin.runs()).toHaveLength(2); + + // A third session knows about neither, so there is no link to fall back on. + const asked = plugin.fire(typed("drivable:run-drivable", "session-3")); + expect(asked.stderr).toContain("2 runs stopped part way through"); + expect(asked.stderr).toContain("--new"); + // Nothing was resumed and nothing was started. + expect(plugin.runs()).toHaveLength(2); + }); + }); + + it("resumes the run this session started, when several are stalled", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin("session-1"); + plugin.fire(stopped(reported({ done: true }))); + const mine = plugin.onlyRun().runId; + plugin.fire(typed("drivable:run-drivable", "session-2", "--new")); + plugin.fire(stopped("Standing by.", "session-2")); + plugin.fire(stopped(reported({ done: true }), "session-2")); + + const again = plugin.fire(typed("drivable:run-drivable", "session-1")); + expect(again.stderr).toContain(mine); + }); + }); + + it("refuses to resume a run whose graph moved underneath it", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin(); + plugin.fire(stopped(reported({ done: true }))); + const stalled = plugin.onlyRun(); + + // The plugin and the graph file still agree, so the dispatcher's own hash + // check passes and the resume path is actually reached. Only the stopped + // run remembers the older graph, which is what regenerating a plugin under + // a stopped run leaves behind. + plugin.patchRun(stalled.runId, (state) => { + state.graphHash = "0000000000000000"; + }); + + const again = plugin.fire(typed("drivable:run-drivable", "session-2")); + expect(again.stderr).toContain("Refusing to resume"); + expect(again.stderr).toContain("its nodes may have moved"); + // Not resumed, and not quietly replaced by a fresh run either. + expect(plugin.runs()).toHaveLength(1); + expect(plugin.onlyRun().node).toBe("build"); + }); + }); +}); + describe("a prompt's run context, resolved by the emitted dispatcher", () => { it("puts an earlier step's value into the next step's instruction", async () => { await withPlugin(interpolatingIr(), (plugin) => { @@ -2345,13 +2481,16 @@ describe("the step wrappers", () => { const described: [where: string, markdown: string, fields: number][] = [ ["the runner", fileOf(files, RUNNER_PATH), 3], ["the step wrapper", fileOf(files, "agents/step-first-second.md"), 3], - ["the run command", fileOf(files, `${COMMANDS_DIR}/run-multi-line.md`), 1], + // Two: a description, and the argument hint the run command always carries + // now that every workflow can be resumed. + ["the run command", fileOf(files, `${COMMANDS_DIR}/run-multi-line.md`), 2], ]; for (const [where, markdown, fields] of described) { // One physical line per field: nothing spilled into a line of its own. const lines = frontmatterLinesOf(markdown); expect(`${where}: ${lines.length}`).toBe(`${where}: ${fields}`); - for (const line of lines) expect(line).toMatch(/^[A-Za-z]+: \S/); + // Hyphens are legal in a key, and `argument-hint` is one of them. + for (const line of lines) expect(line).toMatch(/^[A-Za-z][A-Za-z-]*: \S/); // And the value the resolver hands back is a single line too. It arrives // double-quoted because the interpolated names carry quotes, and a @@ -2940,11 +3079,14 @@ describe("a small compiled workflow", () => { - End your final message with your JSON payload as a single fenced \`json\` block, with nothing after it. It is read from the message itself, so anything following it is noise the parser has to survive. ", "commands/run-tiny-flow.md": "--- - description: "Start the \\"tiny-flow\\" workflow." + description: "Start or resume the \\"tiny-flow\\" workflow." + argument-hint: "[--new to start over instead of resuming]" --- Start the **tiny-flow** workflow, which begins at \`draft\`. + If a previous run stopped part way through, this picks it up where it left off instead of starting again, and says so. Everything already finished is kept. + Spawn the subagent \`tiny-flow:runner\` with the Agent tool, and give it exactly this instruction, verbatim: