agentweaver 0.1.16 → 0.1.18

package/README.md

@@ -1,45 +1,64 @@
 # AgentWeaver
 
-`AgentWeaver` is a TypeScript/Node.js CLI for harness engineering around coding agents.
+`AgentWeaver` is a TypeScript/Node.js CLI for engineering durable workflows around coding agents.
 
-It is built around declarative workflow specs. A flow describes phases and steps in JSON, runtime nodes implement behavior in TypeScript, and artifacts on disk make runs resumable, inspectable, and operationally manageable from the TUI.
+It is built for teams that want agent work to behave less like one-off prompting and more like an inspectable engineering system: explicit workflows, durable artifacts, repeatable review gates, resumable execution, and repository-local guidance that evolves with the codebase.
 
 Typical usage looks like:
 
 `plan -> implement -> run-go-linter-loop -> run-go-tests-loop -> review -> review-fix`
 
-The important part is not that exact chain. The point is that AgentWeaver lets you design, operate, and evolve durable agent harnesses instead of accumulating one-off prompts and shell glue.
+Planning-heavy work can use:
 
-For planning-heavy work, a typical path can now include `plan -> design-review -> implement`, where `design-review` critiques planning artifacts before coding starts.
+`plan -> design-review -> implement -> review-loop`
 
-## What It Does
+The important part is not the exact chain. The point is that AgentWeaver lets you model, operate, and evolve the harness around the agent.
 
-- Fetches Jira issue context by issue key or browse URL
-- Fetches GitLab merge request diff and review data into reusable artifacts
-- Runs Codex-, OpenCode-, and process-backed stages through a common pipeline runtime
-- Persists artifacts and compact flow execution state under the current project scope
-- Supports both operator-driven work in a TUI and end-to-end automation flows
-- Resumes interrupted declarative flows when required artifacts and launch profile still match
+## Key Features
 
-## Harness Engineering Focus
+See [docs/features.md](docs/features.md) for the expanded feature overview.
+
+- **Declarative agent workflows**: flows are JSON specs with phases, steps, prompt bindings, params, expectations, and post-step actions. Workflow design stays declarative while runtime behavior lives in typed nodes and executors.
+- **Repository-local project playbook**: stable project conventions live under `.agentweaver/playbook/` as versioned rules, examples, and templates. Guided flows select relevant guidance before planning, implementation, review, and repair so repeated agent runs inherit the same project knowledge.
+- **Artifact-first execution**: each stage produces structured JSON and human-readable markdown artifacts on disk. Artifacts are the contract between stages, which makes runs inspectable, reviewable, and restartable.
+- **Planning and design-review gates**: planning flows produce design, implementation plan, and QA plan artifacts. `design-review` critiques those artifacts before coding starts, and `auto-common` can iterate through `plan-revise` before implementation.
+- **Review and repair loops**: review flows produce structured findings with severities. Repair flows can select blockers and critical findings, apply targeted fixes, and run follow-up checks.
+- **Resumable automation**: long-running flows persist compact execution state, support resume/continue/restart semantics, and can restart from selected phases when the artifacts and launch profile are compatible.
+- **Multiple execution backends**: Codex, OpenCode, shell/process checks, Jira, GitLab, Git commit, and Telegram notification integrations run through a common executor model.
+- **Interactive TUI and direct CLI**: the same workflow model works in an operator-driven terminal UI, direct CLI commands, and non-interactive automation.
+- **Custom flows**: built-in flows can be extended with global or project-local flow specs without changing AgentWeaver source code.
+- **Plugin SDK**: local plugins can add public-SDK-compatible nodes and executors, with manifest validation, version checks, and documented entrypoint rules.
+- **Operational diagnostics**: `doctor` checks system readiness, executor configuration, flow specs, node versions, and runtime environment shape before workflows fail mid-run.
+
+## Why Harness Engineering
 
 AgentWeaver is not positioned as a thin wrapper around one agent call. It is meant for harness engineering:
 
-- workflows are modeled explicitly as phases, steps, prompts, params, expectations, and artifacts
-- execution logic is isolated into reusable nodes and executors instead of being embedded in ad-hoc scripts
-- artifacts on disk are the contract between stages, which makes runs reviewable and restartable
-- the same workflow model can be used in direct CLI mode, interactive TUI mode, and resumable automation flows
+- The workflow is explicit instead of hidden in a long prompt.
+- The intermediate decisions are persisted instead of disappearing in chat history.
+- The agent receives project guidance from the repository instead of relying on memory or copy-pasted instructions.
+- Review, repair, checks, and restart behavior are first-class parts of the workflow.
+- The same model works in local CLI use, interactive operation, and automation.
 
 In practice, this means you can treat an agent workflow like an engineered system: versioned, inspectable, repeatable, and debuggable.
 
 ## Core Concepts
 
-- `flow spec`: declarative JSON under `src/pipeline/flow-specs/` or project-local `.agentweaver/.flows/`
+- `flow spec`: declarative JSON under `src/pipeline/flow-specs/`, global `~/.agentweaver/.flows/`, or project-local `.agentweaver/.flows/`
 - `node`: reusable runtime unit from `src/pipeline/nodes/`
 - `executor`: integration layer for Jira, Codex, OpenCode, GitLab, shell/process execution, Telegram notifications, and related actions
 - `scope`: isolated workspace key for artifacts and flow state; usually based on Jira task, otherwise derived from git context
 - `artifact`: file produced or consumed by flows, used as the stable contract between stages
 - `flow state`: compact persisted execution metadata used for resume/restart in long-running flows such as `auto-golang`
+- `project playbook`: local `.agentweaver/playbook/` directory with `manifest.yaml`, practices, examples, and templates; the format is described in [docs/playbook.md](docs/playbook.md)
+
+## Launch Semantics
+
+- `resume` only resumes a genuinely interrupted run and uses the saved execution state without rebuilding already completed steps
+- `continue` is intended for completed iterative cycles and starts the next iteration from the latest valid artifacts without deleting historical artifacts
+- `restart` is treated as a new run: the current active attempt is archived under `.agentweaver/scopes/<scope>/.artifacts/restart-archives/attempt-XXXX`, then a new active attempt is created
+- For ambiguous launches, the operator must choose the action explicitly: by confirmation in interactive mode, or with `--resume`, `--continue`, or `--restart` in non-interactive mode
+- This contract applies to `auto-common`, `auto-simple`, `auto-golang`, `instant-task`, `review-loop`, `run-go-linter-loop`, and `run-go-tests-loop`
 
 ## Declarative Workflow Model
 
@@ -54,6 +73,8 @@ The center of the system is the declarative flow spec:
 
 This keeps workflow design in JSON while keeping implementation details in typed runtime code.
 
+The full flow-spec reference now lives in [docs/declarative-workflows.md](docs/declarative-workflows.md).
+
 ## Repository Layout
 
 - `src/index.ts` — CLI entrypoint, interactive mode bootstrap, and top-level orchestration
@@ -101,6 +122,30 @@ There are also built-in nested/helper flows that are loaded declaratively but ar
 - `opencode` CLI if you use OpenCode-backed stages
 - access to Jira and/or GitLab when the selected flow needs them
 
+## Web UI
+
+The `agentweaver web [--no-open] [--host <host>|--listen-all] [<jira-browse-url|jira-issue-key>]` command starts interactive mode through the Web UI. By default, the server binds to `127.0.0.1`, asks the operating system for a random port, and prints the final address as `AgentWeaver Web UI: http://127.0.0.1:<port>/`.
+
+To open the Web UI from another machine on a trusted network, configure Web UI credentials first:
+
+```bash
+export AGENTWEAVER_WEB_USERNAME=operator
+export AGENTWEAVER_WEB_PASSWORD='choose-a-strong-password'
+agentweaver web --listen-all --no-open
+```
+
+External binding requires both `AGENTWEAVER_WEB_USERNAME` and `AGENTWEAVER_WEB_PASSWORD`. This applies to `agentweaver web --listen-all`, `agentweaver web --host 0.0.0.0`, `agentweaver web --host ::`, explicit non-loopback IP addresses such as `192.168.1.10` or `2001:db8::1`, and any hostname other than `localhost`. In this mode, the server listens on the requested interface; connect to the IP address or hostname of the machine running AgentWeaver and the assigned port.
+
+The default localhost bindings, including `127.0.0.1`, `::1`, and `localhost`, remain no-auth by default. If Web UI credentials are configured, the same Basic auth check also protects localhost Web UI requests.
+
+Web UI authentication uses HTTP Basic auth. Over plain HTTP, use it only on trusted networks because credentials are not encrypted in transit. For untrusted networks, put AgentWeaver behind TLS termination or an equivalent reverse proxy.
+
+By default, AgentWeaver tries to open the browser after the server starts successfully and the URL is printed. For CI, tests, and manual smoke checks, use `agentweaver web --no-open` or the `AGENTWEAVER_WEB_NO_OPEN=1` environment variable; the `--no-open` flag is supported only after the `web` command.
+
+The Web UI serves the operator console from the same local process, including `/`, `/static/app.js`, and `/static/styles.css`. Live browser interaction uses WebSocket on `/__agentweaver/ws`. Bounded checks can use `GET /__agentweaver/health`, and shutdown is available through `POST /__agentweaver/exit` or `SIGINT`/`SIGTERM`.
+
+Web UI state is process-local: it exists only while the AgentWeaver process is running and is not shared with other AgentWeaver processes. The Web UI is intended to match the interactive operator workflow for flow selection, launch confirmation, routing and user-input forms, progress and logs, and interrupt handling.
+
 ## Installation
 
 Local development:
@@ -118,6 +163,34 @@ node dist/index.js --help
 
 Global install after publishing:
 
+## Plugin SDK
+
+AgentWeaver supports local plugins and custom declarative flows from both global and project-local `.agentweaver` directories.
+
+Plugin authors must use only the public SDK subpath: `agentweaver/plugin-sdk`.
+The package root `agentweaver`, internal paths such as `agentweaver/dist/*` and `agentweaver/src/*`, and repository-relative source imports are not part of the supported SDK contract.
+
+Supported plugin manifest locations are:
+
+- `~/.agentweaver/.plugins/<plugin-id>/plugin.json`
+- `.agentweaver/.plugins/<plugin-id>/plugin.json`
+
+The plugin directory name and manifest `id` must match exactly.
+
+Use the dedicated guide at [docs/plugin-sdk.md](docs/plugin-sdk.md) for:
+
+- the executor versus node architecture
+- manifest and entrypoint rules
+- optional routing metadata for plugin LLM executors
+- runtime context APIs available to plugin code
+- global and project-local flow wiring under `~/.agentweaver/.flows/` and `.agentweaver/.flows/`
+- compatibility, testing, troubleshooting, and a complete end-to-end walkthrough
+
+Repository reference examples live under `docs/examples/`, for example:
+
+- `docs/examples/.plugins/claude-example-plugin/`
+- `docs/examples/.flows/claude-example.json`
+
 ```bash
 npm install -g agentweaver
 agentweaver --help
@@ -183,7 +256,7 @@ OPENCODE_MODEL=minimax-coding-plan/MiniMax-M2.7
 
 The full-screen TUI is not a cosmetic wrapper. It is the operator console for the harness:
 
-- browse built-in and project-local workflows
+- browse built-in, global, and project-local workflows
 - launch flows in the current scope
 - inspect progress by phase and step
 - follow activity, prompts, summaries, and statuses
@@ -259,7 +332,7 @@ Notes:
 - `--verbose` streams child process stdout/stderr in direct CLI mode
 - `--prompt <text>` appends extra instructions to the prompt
 - `--scope <name>` is supported by scope-flexible flows such as `implement`, `review`, `review-fix`, `review-loop`, `run-go-tests-loop`, `run-go-linter-loop`, `gitlab-review`, and `gitlab-diff-review`
-- `--md-lang <en|ru>` currently applies to `plan`
+- `--md-lang <en|ru>` applies only to generated workflow markdown artifacts, not repository source files or committed documentation
 - `--force` only affects interactive mode: it skips loading cached summary-pane content on startup so Jira-backed flows that regenerate summary artifacts can repopulate it during the run
 - Jira-backed flows ask for Jira input interactively when it is omitted
 - `task-describe` can also work from manual task description input without Jira
@@ -300,6 +373,7 @@ Artifacts and flow state are stored under the current project scope. In practice
 - Jira-backed runs usually use the Jira issue key as scope
 - non-Jira runs can fall back to a git-derived scope
 - `--scope <name>` lets you override the default for supported commands
+- interactive and web sessions automatically switch the branch-derived scope after the git branch changes, unless the session was started with an explicit Jira argument or `--scope`
 
 The runtime uses artifacts as the contract between stages, including markdown outputs and structured JSON files validated against schemas.
 
@@ -332,27 +406,31 @@ Current layout:
 Flow discovery behavior:
 
 - built-in flows are loaded from `src/pipeline/flow-specs/`
-- project-local flows are loaded from `.agentweaver/.flows/`
-- both built-in and project-local flow specs are validated at load time
-- duplicate flow ids fail fast
-- project-local flows are shown separately in the UI
+- global custom flows are loaded from `~/.agentweaver/.flows/`
+- project-local custom flows are loaded from `.agentweaver/.flows/`
+- all discovered flow specs are validated at load time
+- duplicate flow ids fail fast across built-in, global, and project-local sources
+- custom flows are shown separately in the UI as global and project-local groups
 
-## Project-Local Flows
+## Custom Flows
 
-You can add project-specific flow specs under:
+You can add custom flow specs under either:
 
 ```bash
+~/.agentweaver/.flows/**/*.json
 .agentweaver/.flows/**/*.json
 ```
 
-Project-local flows:
+Custom flows:
 
 - are discovered recursively
 - get their flow id from the relative path without `.json`
 - share the same validator and runtime as built-in flows
 - cannot conflict with an existing built-in or other discovered flow id
 
-Nested `flow-run` steps can reference built-in or project-local specs by file name, as long as the name resolves unambiguously.
+Use the global directory for reusable personal flows and plugins across repositories, and the project-local directory for repo-specific wiring.
+
+Nested `flow-run` steps can reference built-in, global, or project-local specs by file name, as long as the name resolves unambiguously.
 
 ## Development
 
@@ -387,7 +465,50 @@ Recommended smoke checks:
 node dist/index.js --help
 node dist/index.js auto-golang --help-phases
 node dist/index.js auto-common --help-phases
+node dist/index.js auto-common-guided --help-phases
 node dist/index.js plan --dry DEMO-1234
 node dist/index.js implement --dry DEMO-1234
 node dist/index.js review --dry DEMO-1234
 ```
+
+## Guided Project Guidance
+
+The project playbook is AgentWeaver's way to turn project-specific conventions into durable agent context. Instead of repeating the same instructions in every prompt, a repository can keep stable rules, examples, and templates under `.agentweaver/playbook/`. Guided flows validate that material, select the parts relevant to the current task and phase, and pass compact guidance into the model before planning, implementation, review, and repair.
+
+Typical playbook content includes:
+
+- engineering rules such as required test locations, documentation language, or runtime validation boundaries
+- examples that should be opened only when relevant, instead of pasted into every prompt
+- templates for recurring artifact shapes or implementation notes
+- repository context that should remain visible across tasks without overriding task-specific inputs
+
+The guided flow is `auto-common-guided`. It first runs the same Jira fetch and task normalization steps as `auto-common`, then validates `.agentweaver/playbook/manifest.yaml` and generates compact project guidance before the `plan`, `design-review`, `implement`, `review`, and `repair/review-fix` phases. JSON artifacts remain English and machine-readable; workflow markdown artifacts are generated in the workflow-selected language. The markdown language setting does not apply to repository source files, committed documentation, or playbook rules.
+
+The guidance is intentionally phase-aware. A rule can apply only to `plan`, `implement`, `review`, or another supported phase; it can also target languages, frameworks, glob patterns, and keywords. AgentWeaver writes both a structured `project-guidance/v1` JSON artifact and a derivative markdown file, then passes their paths into the phase prompt as supplemental project-local context.
+
+Initialize or refresh the playbook with:
+
+```bash
+agentweaver playbook-init
+agentweaver playbook-init --accept-playbook-draft
+```
+
+Use the guided flow with:
+
+```bash
+agentweaver auto-common-guided --help-phases
+agentweaver auto-common-guided --accept-playbook-draft DEMO-1234
+```
+
+The workflow does not read old `playbook.json` or `playbook.md` files as fallbacks. In non-interactive runs, a missing manifest stops the workflow before planning and reports the required action: run `agentweaver playbook-init --accept-playbook-draft` first, or rerun `agentweaver auto-common-guided --accept-playbook-draft <jira>`. The `--accept-playbook-draft` flag explicitly accepts the generated playbook without interactive review and allows AgentWeaver to write the manifest-based layout. An invalid manifest stops the guided phase before the LLM prompt.
+
+To inspect whether playbook guidance participated in a run, check the generated artifacts:
+
+```bash
+find .agentweaver/scopes -name 'project-guidance-*'
+rg -n "Project Guidance|practice\\." .agentweaver/scopes
+```
+
+Keep `.agentweaver/playbook/` in Git even when other AgentWeaver runtime state is ignored. The playbook format and maintenance workflow are documented in [docs/playbook.md](docs/playbook.md).
+
+Current limitations: skills integration is not available yet; the playbook generator must rely on repository evidence and clarification answers; guided prompts receive compact context and open full examples only when they are directly relevant to the current phase.

package/dist/artifacts.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { TaskRunnerError } from "./errors.js";
@@ -163,6 +163,20 @@ export function taskContextFile(taskKey, iteration) {
 export function taskContextJsonFile(taskKey, iteration) {
     return versionedJsonArtifactFile(taskKey, "task-context", iteration);
 }
+export function projectGuidanceArtifactStem(phase) {
+    switch (phase) {
+        case "repair/review-fix":
+            return "project-guidance-repair-review-fix";
+        default:
+            return `project-guidance-${phase}`;
+    }
+}
+export function projectGuidanceFile(taskKey, phase, iteration) {
+    return versionedMarkdownArtifactFile(taskKey, projectGuidanceArtifactStem(phase), iteration);
+}
+export function projectGuidanceJsonFile(taskKey, phase, iteration) {
+    return versionedJsonArtifactFile(taskKey, projectGuidanceArtifactStem(phase), iteration);
+}
 export function taskDescribeInputJsonFile(taskKey) {
     return taskArtifactsFile(taskKey, `task-describe-input-${taskKey}.json`);
 }
@@ -175,6 +189,33 @@ export function gitStatusJsonFile(taskKey) {
 export function gitDiffFile(taskKey) {
     return taskWorkspaceFile(taskKey, `git-diff-${taskKey}.txt`);
 }
+export function repoInventoryFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `repo-inventory-${taskKey}.md`);
+}
+export function repoInventoryJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `repo-inventory-${taskKey}.json`);
+}
+export function practiceCandidatesFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `practice-candidates-${taskKey}.md`);
+}
+export function practiceCandidatesJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `practice-candidates-${taskKey}.json`);
+}
+export function playbookQuestionsJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `playbook-questions-${taskKey}.json`);
+}
+export function playbookAnswersJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `playbook-answers-${taskKey}.json`);
+}
+export function playbookDraftFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `playbook-draft-${taskKey}.md`);
+}
+export function playbookDraftJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `playbook-draft-${taskKey}.json`);
+}
+export function playbookWriteResultJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `playbook-write-result-${taskKey}.json`);
+}
 export function gitCommitMessageJsonFile(taskKey) {
     return taskArtifactsFile(taskKey, `git-commit-message-${taskKey}.json`);
 }
@@ -214,8 +255,78 @@ export function gitlabDiffReviewInputJsonFile(taskKey) {
 export function flowStateFile(scopeKey, flowId) {
     return scopeArtifactsFile(scopeKey, `.agentweaver-flow-state-${encodeURIComponent(flowId)}.json`);
 }
-export function planArtifacts(taskKey) {
-    return [designFile(taskKey), designJsonFile(taskKey), planFile(taskKey), planJsonFile(taskKey), qaFile(taskKey), qaJsonFile(taskKey)];
+export function restartArchivesDir(scopeKey) {
+    return scopeArtifactsFile(scopeKey, "restart-archives");
+}
+function nextRestartArchiveName(scopeKey) {
+    const archiveRoot = restartArchivesDir(scopeKey);
+    if (!existsSync(archiveRoot)) {
+        return "attempt-0001";
+    }
+    const attemptNumbers = readdirSync(archiveRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => /^attempt-(\d{4})$/.exec(entry.name)?.[1] ?? null)
+        .filter((value) => value !== null)
+        .map((value) => Number.parseInt(value, 10));
+    const nextNumber = (attemptNumbers.length === 0 ? 0 : Math.max(...attemptNumbers)) + 1;
+    return `attempt-${String(nextNumber).padStart(4, "0")}`;
+}
+export function archiveActiveAttempt(scopeKey) {
+    const workspaceDir = scopeWorkspaceDir(scopeKey);
+    if (!existsSync(workspaceDir)) {
+        return null;
+    }
+    const workspaceEntries = readdirSync(workspaceDir, { withFileTypes: true })
+        .filter((entry) => entry.name !== ".artifacts");
+    const artifactEntries = readdirSync(scopeArtifactsDir(scopeKey), { withFileTypes: true })
+        .filter((entry) => entry.name !== "restart-archives");
+    if (workspaceEntries.length === 0 && artifactEntries.length === 0) {
+        return null;
+    }
+    const archiveRoot = restartArchivesDir(scopeKey);
+    mkdirSync(archiveRoot, { recursive: true });
+    const archiveDir = path.join(archiveRoot, nextRestartArchiveName(scopeKey));
+    const workspaceArchiveDir = path.join(archiveDir, "workspace");
+    const artifactsArchiveDir = path.join(archiveDir, "artifacts");
+    mkdirSync(workspaceArchiveDir, { recursive: true });
+    mkdirSync(artifactsArchiveDir, { recursive: true });
+    try {
+        for (const entry of workspaceEntries) {
+            cpSync(path.join(workspaceDir, entry.name), path.join(workspaceArchiveDir, entry.name), {
+                recursive: true,
+                errorOnExist: true,
+                force: false,
+            });
+        }
+        for (const entry of artifactEntries) {
+            cpSync(path.join(scopeArtifactsDir(scopeKey), entry.name), path.join(artifactsArchiveDir, entry.name), {
+                recursive: true,
+                errorOnExist: true,
+                force: false,
+            });
+        }
+    }
+    catch (error) {
+        rmSync(archiveDir, { recursive: true, force: true });
+        throw new TaskRunnerError(`Failed to archive active attempt for restart: ${error.message}`);
+    }
+    for (const entry of workspaceEntries) {
+        rmSync(path.join(workspaceDir, entry.name), { recursive: true, force: true });
+    }
+    for (const entry of artifactEntries) {
+        rmSync(path.join(scopeArtifactsDir(scopeKey), entry.name), { recursive: true, force: true });
+    }
+    return archiveDir;
+}
+export function planArtifacts(taskKey, iteration) {
+    return [
+        designFile(taskKey, iteration),
+        designJsonFile(taskKey, iteration),
+        planFile(taskKey, iteration),
+        planJsonFile(taskKey, iteration),
+        qaFile(taskKey, iteration),
+        qaJsonFile(taskKey, iteration),
+    ];
 }
 export function bugAnalyzeArtifacts(taskKey) {
     return [

package/dist/doctor/checks/executors.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { DoctorStatus } from "../types.js";
 import { CATEGORY } from "./category.js";
-import { ALLOWED_MODELS_BY_EXECUTOR } from "../../pipeline/launch-profile-config.js";
+import { allowedModelsForExecutor } from "../../pipeline/launch-profile-config.js";
 import { findCmdPath, isExecutable } from "../../runtime/command-resolution.js";
 function getEnvVarName(executorId) {
     return executorId === "codex" ? "CODEX_BIN" : "OPENCODE_BIN";
@@ -72,7 +72,7 @@ function checkExecutor(executorId) {
     if (versionOutput === null) {
         return createResult(executorId, DoctorStatus.Fail, `${executorId} --version check failed`, `${executorId} --version did not produce expected output`, `path: ${resolution.path}, source: ${resolution.source}`, resolution, null);
     }
-    const allowedModels = ALLOWED_MODELS_BY_EXECUTOR[executorId];
+    const allowedModels = allowedModelsForExecutor(executorId);
     const modelWarnings = [];
     for (const model of allowedModels) {
         const modelResult = spawnSync(resolution.path, ["--model", model, "--version"], { encoding: "utf8", stdio: "pipe" });

package/dist/flow-state.js

@@ -4,7 +4,25 @@ import { ensureScopeWorkspaceDir, flowStateFile } from "./artifacts.js";
 import { TaskRunnerError } from "./errors.js";
 import { isFlowRunResumeEnvelope } from "./pipeline/flow-run-resume.js";
 import { resolveStoredExecutionRoutingSnapshot, singleLaunchProfileExecutionRouting } from "./runtime/execution-routing.js";
-const FLOW_STATE_SCHEMA_VERSION = 2;
+const FLOW_STATE_SCHEMA_VERSION = 3;
+const CONTINUABLE_FLOW_KINDS = new Set([
+    "design-review-loop-flow",
+    "review-loop-flow",
+    "review-project-loop-flow",
+    "run-go-linter-loop-flow",
+    "run-go-tests-loop-flow",
+]);
+const CONTINUABLE_PARENT_FLOW_IDS = new Set([
+    "auto-common",
+    "auto-simple",
+    "auto-golang",
+    "instant-task",
+]);
+const CONTINUABLE_DIRECT_FLOW_IDS = new Set([
+    "review-loop",
+    "run-go-linter-loop",
+    "run-go-tests-loop",
+]);
 function nowIso8601() {
     return new Date().toISOString();
 }
@@ -45,6 +63,7 @@ export function createFlowRunState(scopeKey, flowId, executionState, jiraRef, la
     ensurePublicationRunId(executionState);
     const effectiveExecutionRouting = executionRouting ?? (launchProfile ? singleLaunchProfileExecutionRouting(launchProfile) : undefined);
     const effectiveLaunchProfile = launchProfile ?? effectiveExecutionRouting?.defaultRoute;
+    const continuation = inferContinuationMetadata(flowId, executionState);
     return {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         flowId,
@@ -56,6 +75,7 @@ export function createFlowRunState(scopeKey, flowId, executionState, jiraRef, la
         ...(effectiveLaunchProfile ? { launchProfile: effectiveLaunchProfile } : {}),
         ...(effectiveExecutionRouting ? { executionRouting: effectiveExecutionRouting, routingFingerprint: effectiveExecutionRouting.fingerprint } : {}),
         ...(selectedRoutingPreset ? { selectedRoutingPreset } : {}),
+        continuation,
         executionState: stripExecutionStatePayload(executionState),
     };
 }
@@ -66,6 +86,43 @@ function upgradeFlowRunStateV1(state) {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         ...(executionRouting ? { executionRouting, routingFingerprint: executionRouting.fingerprint } : {}),
         ...(executionRouting ? { selectedRoutingPreset: { kind: "custom", label: "Legacy launch profile" } } : {}),
+        continuation: {
+            continueEligible: false,
+        },
+    };
+}
+function upgradeFlowRunStateV2(state) {
+    return {
+        ...state,
+        schemaVersion: FLOW_STATE_SCHEMA_VERSION,
+        continuation: {
+            continueEligible: false,
+        },
+    };
+}
+function parseTerminationLocation(terminationReason) {
+    if (typeof terminationReason !== "string") {
+        return {};
+    }
+    const match = /^Stopped by ([^:]+):(.+)$/.exec(terminationReason.trim());
+    if (!match) {
+        return {};
+    }
+    const stopPhaseId = match[1];
+    const stopStepId = match[2];
+    return {
+        ...(stopPhaseId ? { stopPhaseId } : {}),
+        ...(stopStepId ? { stopStepId } : {}),
+    };
+}
+function inferContinuationMetadata(flowId, executionState) {
+    const stopLocation = parseTerminationLocation(executionState.terminationReason);
+    const continueEligible = CONTINUABLE_FLOW_KINDS.has(executionState.flowKind)
+        || (CONTINUABLE_PARENT_FLOW_IDS.has(flowId) && Boolean(stopLocation.stopPhaseId && stopLocation.stopStepId));
+    return {
+        continueEligible,
+        ...(stopLocation.stopPhaseId ? { stopPhaseId: stopLocation.stopPhaseId } : {}),
+        ...(stopLocation.stopStepId ? { stopStepId: stopLocation.stopStepId } : {}),
     };
 }
 function normalizeFlowRunState(raw, flowId, filePath) {
@@ -77,6 +134,9 @@ function normalizeFlowRunState(raw, flowId, filePath) {
     if (schemaVersion === 1) {
         state = upgradeFlowRunStateV1(raw);
     }
+    else if (schemaVersion === 2) {
+        state = upgradeFlowRunStateV2(raw);
+    }
     else if (schemaVersion === FLOW_STATE_SCHEMA_VERSION) {
         state = raw;
     }
@@ -97,6 +157,11 @@ function normalizeFlowRunState(raw, flowId, filePath) {
         state.executionRouting = executionRouting;
         state.routingFingerprint = executionRouting.fingerprint;
     }
+    const inferredContinuation = inferContinuationMetadata(state.flowId, state.executionState);
+    state.continuation = {
+        ...inferredContinuation,
+        continueEligible: inferredContinuation.continueEligible && state.continuation?.continueEligible !== false,
+    };
     return state;
 }
 export function loadFlowRunState(scopeKey, flowId) {
@@ -125,6 +190,7 @@ export function saveFlowRunState(state) {
         state.executionRouting = singleLaunchProfileExecutionRouting(state.launchProfile);
         state.routingFingerprint = state.executionRouting.fingerprint;
     }
+    state.continuation = inferContinuationMetadata(state.flowId, state.executionState);
     ensureScopeWorkspaceDir(state.scopeKey);
     writeFileSync(flowStateFile(state.scopeKey, state.flowId), `${JSON.stringify({
         ...state,
@@ -154,6 +220,53 @@ export function hasResumableFlowState(state) {
     }
     return state.executionState.phases.some((phase) => phase.steps.some((step) => step.status === "done" || step.status === "running"));
 }
+function hasContinuableFlowState(state) {
+    if (!state) {
+        return false;
+    }
+    if (!state.executionState.terminated && state.status !== "completed") {
+        return false;
+    }
+    return state.continuation?.continueEligible === true;
+}
+export function classifyFlowLaunchAvailability(state) {
+    if (!state) {
+        return {
+            hasExistingState: false,
+            requiresExplicitChoice: false,
+            resume: { available: false, reason: "No saved state found." },
+            continue: { available: false, reason: "No saved state found." },
+            restart: { available: true, reason: "Start a fresh attempt." },
+        };
+    }
+    const resumeAvailable = hasResumableFlowState(state);
+    const continueAvailable = hasContinuableFlowState(state);
+    const availability = {
+        hasExistingState: true,
+        requiresExplicitChoice: resumeAvailable || continueAvailable,
+        resume: resumeAvailable
+            ? { available: true, reason: "Continue the interrupted execution state." }
+            : {
+                available: false,
+                reason: state.executionState.terminated || state.status === "completed"
+                    ? "The saved run already terminated and cannot be resumed."
+                    : "The saved state is not resumable.",
+            },
+        continue: continueAvailable
+            ? { available: true, reason: "Start the next iteration from the latest active artifacts." }
+            : {
+                available: false,
+                reason: state.schemaVersion < FLOW_STATE_SCHEMA_VERSION
+                    ? "Legacy flow state lacks safe continuation metadata."
+                    : "The saved run does not expose a continuable loop boundary.",
+            },
+        restart: {
+            available: true,
+            reason: "Archive the active attempt and start a fresh run.",
+        },
+    };
+    return availability;
+}
 function normalizeStepState(step) {
     if (step.status !== "running") {
         return step;
@@ -237,3 +350,27 @@ export function prepareFlowStateForResume(state) {
     delete state.executionState.terminationReason;
     return state;
 }
+export function prepareFlowStateForContinue(state, orderedPhases) {
+    state.status = "pending";
+    state.lastError = null;
+    state.currentStep = null;
+    const flowKind = state.executionState.flowKind;
+    if (CONTINUABLE_FLOW_KINDS.has(flowKind) || CONTINUABLE_DIRECT_FLOW_IDS.has(state.flowId)) {
+        state.executionState = {
+            ...state.executionState,
+            publicationRunId: randomUUID(),
+            terminated: false,
+            phases: orderedPhases.map(createPendingPhaseState),
+        };
+        delete state.executionState.terminationReason;
+        delete state.executionState.terminationOutcome;
+        return state;
+    }
+    const targetPhaseId = state.continuation?.stopPhaseId ?? parseTerminationLocation(state.executionState.terminationReason).stopPhaseId;
+    if (!targetPhaseId) {
+        throw new TaskRunnerError("Continue is impossible because the stop phase could not be determined safely. Use restart.");
+    }
+    rewindFlowRunStateToPhase(state, orderedPhases, targetPhaseId);
+    state.executionState.publicationRunId = randomUUID();
+    return state;
+}