root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: package code organization wave 18 (executor pure peels) (#3317)

Browse Source 
## Summary

Wave 18 continues the package code-organization program after wave 17
domain folders (U4 Slice A from
`docs/plans/2026-07-14-001-refactor-package-code-organization-plan.md`).

### What changed
Peel **pure, behavior-preserving** helpers out of
`packages/engine/src/executor.ts` into domain modules under
`packages/engine/src/executor/`, with **stable re-exports** from
`executor.ts` so deep imports and `vi.mock("../executor.js")` keep
working.

| New module | Symbols |
|------------|---------|
| `executor/task-done-refusal.ts` | `evaluateTaskDoneRefusal`,
`determineRevisionResetStart`, skip-bypass refusal helper |
| `executor/workflow-feedback-paths.ts` |
`extractReferencedPathsFromWorkflowFeedback`,
`isAlwaysAllowedScopeLeakPath`, `workflowPathMatchesDeclaredScope` |
| `executor/workflow-step-verdict.ts` |
`FUSION_WORKFLOW_STEP_CONVENTIONS_PREAMBLE`, `parseWorkflowStepVerdict`
/ `parseWorkflowStepOutput`, step outcome types |
| `executor/await-input-parse.ts` | `parseAwaitInputSentinel`,
`parseAwaitInputQuestionToolCall` |
| `executor/no-commit-eligibility.ts` | `getNoCommitEligibilityReason`
(+ prompt heuristics) |

`executor.ts` live LOC ~**22817 → ~22427** (first pure-peel batch; more
peels needed to approach the 2k cap).

### Shims
- `old path` `executor.ts` public exports → `new path` `executor/*.ts` →
delete-when consumer deep-imports are re-pointed (not this PR)

### Test plan
- [x] `@fusion/engine` typecheck
- [x] Oracle: task-done refusal, skip-bypass, workflow malformed
verdict, scope-leak allowlist, executor-step-session, executor-prompt
- [x] `vitest --project=engine-core` (merge-gate curated suite)
- [ ] CI merge gate

**Stack:** wave17 (merged) → **this PR**

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Improved recognition of workflow outcomes from structured and
conversational responses.
* Added support for extracting questions from await-input responses and
tool calls.
* Improved workflow feedback handling for referenced files and declared
scope patterns.
* Added clearer guidance for task execution, approvals, verification,
and available tools.

* **Bug Fixes**
* Prevented completion when required review approvals are missing or
revisions remain pending.
* Improved handling of workflows that legitimately require no code
changes.
  * Added clearer refusal messages and more reliable revision restarts.
  * Sanitized repository paths in Git remediation instructions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
gsxdsm
2026-08-09 15:46:09 -10:00
committed by GitHub
parent 746a8f0808
commit 1cf86baa1c
262 changed files with 31867 additions and 24727 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/settings-reference.md
View File

@@ -1892,7 +1892,7 @@ One terminal `tool_error` after the current execution-run cursor therefore quali
Choose the alternate model with the standard provider-aware selector in **Settings → Models · Project**; clearing it removes both persisted pair keys, and incomplete legacy pairs display as unset. **Settings → Scheduling** retains the enable toggle, optional node target, and retry policy. Escalation is enabled only when the toggle is true and either a complete provider/model pair or a node ID is configured. It is single-shot: after FN-7996 exhausts same-model retries, Fusion persists the override and tries once before the existing terminal park. The alternate model enters the [model-selection hierarchy](#model-selection-hierarchy) as a task-level override; a node target enters `resolveEffectiveNode` as a task-level routing override and is requeued so scheduler routing is recalculated. This remains opt-in by default to avoid unexpected model cost or execution behavior. Column-agent overrides still govern their sessions and can supersede a task-level model target.
| `triageDuplicateResolution` | `"prompt" \| "keep" \| "delete"` | `"prompt"` | Controls exact `DUPLICATE: PREFIX-NNNN` markers emitted during triage. **prompt** flags and system-pauses the task for an operator Keep/Delete decision; the existing decision banner links to the canonical task. **keep** dismisses the marker and replans a real task. **delete** restores legacy auto-delete behavior. |
| `triageDuplicateResolution` | `"prompt" \| "keep" \| "delete"` | `"prompt"` | Controls `DUPLICATE: FN-NNNN` markers emitted during triage. **prompt** flags and system-pauses the task for an operator Keep/Delete decision; the existing decision banner links to the canonical task. **keep** dismisses the marker and replans a real task. **delete** restores legacy auto-delete behavior. |
### `mobileNavPrimaryItems`

11
docs/task-management.md
View File

@@ -115,16 +115,15 @@ Archiving a workspace (multi-repository) task now synchronously removes every re
Fusion also recognizes the canonical one-line redirect marker:
- `DUPLICATE: FN-1234`
- `DUPLICATE: KB-1234`
- `` `DUPLICATE: KB-1234` ``
- `**DUPLICATE: KB-1234**`
- `` `DUPLICATE: FN-1234` ``
- `**DUPLICATE: FN-1234**`
- fenced single-line wrappers such as:
```text
DUPLICATE: FN-1234
```
The shared parser lives in `packages/core/src/duplicates/explicit-duplicate-marker.ts` (`parseExplicitDuplicateMarker`). It is intentionally strict: after trimming outer whitespace and one optional wrapper layer, the content must reduce to exactly one substantive line matching `^DUPLICATE:\s*[A-Z]+-\d+$`. Exact markers are recognized in either `PROMPT.md` or the task title; a prompt marker wins only when both sources name the same canonical ID. Conflicting exact title/prompt markers fail closed for operator or planning correction. Any extra prose, multiple markers, malformed IDs, or full PROMPT bodies that merely mention duplicate text are ignored.
The shared parser lives in `packages/core/src/explicit-duplicate-marker.ts` (`parseExplicitDuplicateMarker`). It is intentionally strict: after trimming outer whitespace and one optional wrapper layer, the content must reduce to exactly one substantive line matching `^DUPLICATE:\s*FN-\d+$`. Any extra prose, multiple markers, or full PROMPT bodies that merely mention duplicate text are ignored.
This guard adds three fail-open layers on top of the existing duplicate stack, in final order:
@@ -136,10 +135,10 @@ This guard adds three fail-open layers on top of the existing duplicate stack, i
Layer behavior:
- **Dashboard intake (`POST /api/tasks`)** — after deterministic/similarity/near-duplicate checks and before `createTask`, intake returns `409 duplicate_candidates` with `reason: "explicit-marker"` when the combined title/description is exactly a canonical redirect and the canonical target exists. `acknowledgedDuplicates` and `bypassDuplicateCheck: true` both suppress the conflict. Because this guard runs before task creation, the activity breadcrumb is attached to the canonical target.
- **Triage planning loop** — before triage starts a planner session, an exact redirect in the prompt or title short-circuits directly into `finalizeApprovedTask()`. Normal plans run deterministic spec hygiene checks in triage, then the selected workflow's optional Plan Review gate owns AI plan review before execution.
- **Triage planning loop** — after triage reads the generated `PROMPT.md`, an exact redirect marker short-circuits directly into `finalizeApprovedTask()`. Normal plans run deterministic spec hygiene checks in triage, then the selected workflow's optional Plan Review gate owns AI plan review before execution.
- **Self-healing sweep** — maintenance Batch 2 runs `resolveExplicitDuplicateMarkerTasks()` across `triage`/`todo` tasks to clean up older stuck marker tasks. The sweep is best-effort, capped at 50 marker tasks per cycle, and can be disabled with the internal setting `resolveExplicitDuplicateMarkerEnabled: false` (default `true`).
An operator's decision is durable for a task and its active canonical pair. **Keep** records the acknowledgement, clears the exact redirect source and triage decision hold, and lets planning continue; triage and self-healing will not ask again if that same marker is reprocessed. A marker for a different active canonical remains a new decision. **Delete** for an explicit-marker decision soft-deletes the duplicate, while **Archive** for an ordinary near-duplicate leaves it terminal in Archived; neither outcome is reopened as a duplicate decision.
An operator's decision is durable for a task and its active canonical pair. **Keep** records the acknowledgement, clears the marker-only prompt and triage decision hold, and lets planning continue; triage and self-healing will not ask again if that same marker is reprocessed. A marker for a different active canonical remains a new decision. **Delete** for an explicit-marker decision soft-deletes the duplicate, while **Archive** for an ordinary near-duplicate leaves it terminal in Archived; neither outcome is reopened as a duplicate decision.
All three layers fail open: parse errors, task lookup failures, file-read failures, activity-recording errors, or other unexpected exceptions log a warning and continue normal intake/triage/self-healing flow instead of blocking task creation or recovery.

7
packages/cli/src/plugin-sdk-core-runtime-shim.mjs
View File

@@ -10,12 +10,15 @@ import { spawn } from "node:child_process";
* without a private @fusion/core dependency.
*/
import * as postgresSchema from "../../core/src/postgres/schema/index.js";
import { AgentStore } from "../../core/src/agents/agent-store.js";
/*
* FNXC:BundledPlugins 2026-08-03-17:18:
* The bundled Todo plugin lists project agents through AgentStore. Re-export the source implementation from the runtime shim so clean CLI packaging does not leave a private @fusion/core runtime import unresolved.
*
* FNXC:BundledPlugins 2026-08-03-12:25:
* FN-8762 also needs AgentStore for create-task-from-item routes. A second import/export of the same binding broke lint (no-redeclare) and esbuild ("already been declared") after main merged two parallel shim fixes — keep a single AgentStore re-export.
*/
import { AgentStore } from "../../core/src/agents/agent-store.js";
export { AgentStore, postgresSchema };
/*

16
packages/core/src/__tests__/legacy-adoption.test.ts
View File

@@ -102,9 +102,21 @@ describe("KTD-8 adoption table — write-site census completeness (build-failing
});
it("the census actually finds task-status writes (guards against a broken/vacuous regex)", () => {
const files = [readFileSync(join(engineSrc, "executor.ts"), "utf-8")];
/*
FNXC:LegacyAdoption 2026-08-03-12:00 (U4 executor peels / code-organization wave18):
Vacuous-regex guard must scan the whole TaskExecutor surface — `executor.ts` plus free
functions under `executor/*` — because U4 peels move live task.status write literals out of
the monolith into peel modules (e.g. create-task-done-tool, task-done-refusal-handler).
Scanning only executor.ts drops size to exactly 3 (failed/needs-replan/queued) and falsely
fails this guard while the recursive completeness census above remains green.
*/
const executorSurface = [
join(engineSrc, "executor.ts"),
...listSourceFiles(join(engineSrc, "executor")),
];
const files = executorSurface.map((f) => readFileSync(f, "utf-8"));
const written = censusTaskStatusWrites(files);
// executor writes at least these — proves the census pattern is live, not vacuous.
// executor surface writes at least these — proves the census pattern is live, not vacuous.
expect(written.has("failed")).toBe(true);
expect(written.has("needs-replan")).toBe(true);
expect(written.size).toBeGreaterThan(3);

2
packages/core/src/mesh/mesh-task-replication.ts
View File

@@ -109,6 +109,6 @@ export function isTaskAwaitingPlanning(
A duplicate-only PROMPT is unplanned for execution — badge and triage must agree with
scheduler filesystem validation so the card shows "Queued to plan", not Ready.
*/
if (isDuplicateRedirectOnlyPrompt(promptContent, task.title)) return true;
if (isDuplicateRedirectOnlyPrompt(promptContent)) return true;
return isUnplannedSeedPrompt(promptContent, task.id, task.title, task.description);
}

78
packages/dashboard/src/routes/__tests__/register-task-workflow-routes.awaiting-planning.test.ts
View File

@@ -22,7 +22,7 @@ Surface enumeration (the invariant, not just the reported repro):
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import express from "express";
import { mkdtemp, mkdir, readFile, writeFile, rm } from "node:fs/promises";
import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { TaskStore, Task } from "@fusion/core";
@@ -52,7 +52,7 @@ function makeTask(overrides: Partial<Task> = {}): Task {
/** Write PROMPT.md for a task; omit `content` to leave the file missing. */
async function seedTaskDir(taskId: string, content?: string): Promise<void> {
const dir = join(tasksRoot, ".fusion", "tasks", taskId);
const dir = join(tasksRoot, taskId);
await mkdir(dir, { recursive: true });
if (content !== undefined) await writeFile(join(dir, "PROMPT.md"), content);
}
@@ -76,21 +76,10 @@ const RENAMED_HOLD_IR = {
function createHarness(tasks: Task[], workflowIrs?: unknown[]) {
const store: TaskStore = {
getRootDir: vi.fn(() => tasksRoot),
getRootDir: vi.fn(() => process.cwd()),
getProjectScopedPluginMcpServers: vi.fn(async () => []),
getTaskDir: vi.fn((id: string) => join(tasksRoot, ".fusion", "tasks", id)),
getTaskDir: vi.fn((id: string) => join(tasksRoot, id)),
getSettingsFast: vi.fn(async () => ({})),
getTask: vi.fn(async (id: string) => tasks.find((task) => task.id === id) ?? null),
updateTask: vi.fn(async (id: string, updates: Record<string, unknown>) => {
const task = tasks.find((candidate) => candidate.id === id);
if (!task) throw new Error("Task not found");
const { sourceMetadataPatch, ...directUpdates } = updates;
Object.assign(task, directUpdates);
if (sourceMetadataPatch && typeof sourceMetadataPatch === "object") {
task.sourceMetadata = { ...task.sourceMetadata, ...sourceMetadataPatch };
}
return task;
}),
listTasks: vi.fn(async () => tasks),
...(workflowIrs ? { listWorkflowDefinitions: vi.fn(async () => workflowIrs.map((ir) => ({ ir }))) } : {}),
} as unknown as TaskStore;
@@ -164,7 +153,7 @@ describe("GET /tasks awaitingPlanning enrichment", () => {
// A directory where the file should be: EISDIR, not ENOENT. That is not evidence either way, so
// the client must fall back instead of being handed a fabricated label.
const task = makeTask({ id: "FN-EISDIR" });
await mkdir(join(tasksRoot, ".fusion", "tasks", "FN-EISDIR", "PROMPT.md"), { recursive: true });
await mkdir(join(tasksRoot, "FN-EISDIR", "PROMPT.md"), { recursive: true });
const [row] = await fetchTasks([task]);
@@ -215,9 +204,9 @@ describe("GET /tasks awaitingPlanning enrichment", () => {
await seedTaskDir("FN-RENAMED", REAL_SPEC);
const store = {
getRootDir: vi.fn(() => tasksRoot),
getRootDir: vi.fn(() => process.cwd()),
getProjectScopedPluginMcpServers: vi.fn(async () => []),
getTaskDir: vi.fn((id: string) => join(tasksRoot, ".fusion", "tasks", id)),
getTaskDir: vi.fn((id: string) => join(tasksRoot, id)),
getSettingsFast: vi.fn(async () => ({})),
listTasks: vi.fn(async () => [task]),
listWorkflowDefinitions: vi.fn(async () => [{
@@ -240,59 +229,6 @@ describe("GET /tasks awaitingPlanning enrichment", () => {
expect((store as unknown as { listWorkflowDefinitions: { mock: { calls: unknown[] } } }).listWorkflowDefinitions.mock.calls).toHaveLength(1);
});
/*
FNXC:DuplicateIntake 2026-08-09-02:29:
A title-only redirect reaches the same Keep endpoint as a PROMPT.md redirect. The endpoint must
clear the exact title marker and preserve the full prompt, or the next triage pass re-flags the
dismissed duplicate after operator-authored work was destroyed.
*/
it("keeps a title-only redirect without deleting its executable prompt", async () => {
const task = makeTask({
title: "DUPLICATE: KB-123",
paused: true,
pausedReason: "duplicate-decision-required",
sourceMetadata: { duplicateSource: "triage-marker", nearDuplicateOf: "KB-123" },
});
await seedTaskDir(task.id, REAL_SPEC);
const { app } = createHarness([task]);
const res = await REQUEST(
app,
"PATCH",
`/api/tasks/${task.id}`,
JSON.stringify({ dismissNearDuplicate: true }),
{ "content-type": "application/json" },
);
expect(res.status).toBe(200);
expect(task.title).toBe("Duplicate redirect cleared: KB-123");
expect(task.sourceMetadata).toMatchObject({ nearDuplicateDismissed: true });
await expect(readFile(join(tasksRoot, ".fusion", "tasks", task.id, "PROMPT.md"), "utf8")).resolves.toBe(REAL_SPEC);
});
it("cleans both matching sources when keeping a dual-source redirect", async () => {
const task = makeTask({
title: "DUPLICATE: KB-123",
paused: true,
pausedReason: "duplicate-decision-required",
sourceMetadata: { duplicateSource: "triage-marker", nearDuplicateOf: "KB-123" },
});
await seedTaskDir(task.id, "DUPLICATE: KB-123\n");
const { app } = createHarness([task]);
const res = await REQUEST(
app,
"PATCH",
`/api/tasks/${task.id}`,
JSON.stringify({ dismissNearDuplicate: true }),
{ "content-type": "application/json" },
);
expect(res.status).toBe(200);
expect(task.title).toBe("Duplicate redirect cleared: KB-123");
await expect(readFile(join(tasksRoot, ".fusion", "tasks", task.id, "PROMPT.md"), "utf8")).rejects.toMatchObject({ code: "ENOENT" });
});
it("still returns the board when the enrichment cannot resolve task directories", async () => {
// Best-effort contract: a store without getTaskDir must not fail the board load.
const task = makeTask({ id: "FN-NODIR" });

4
packages/dashboard/src/routes/register-task-workflow-routes.ts
View File

@@ -2363,6 +2363,10 @@ export function registerTaskWorkflowRoutes(ctx: ApiRoutesContext, deps: TaskWork
A prior link is reusable only while its child remains in a live task lane. Archived and
soft-deleted children are historical records, not an actionable Created result; conflict
rather than silently resurrecting or linking a second child.
FNXC:TaskRecommendations 2026-08-09-03:30:
Archive unavailability uses archivedColumnsForTask (workflow archived trait), not a
legacy `"archived"` column literal — custom archive-lane boards keep the same rule.
*/
if (!linked || linked.deletedAt || linkedArchiveColumns.has(linked.column)) {
throw conflict("Recommendation link points to an unavailable task");

28
packages/engine/src/__tests__/executor-base-commit-capture.test.ts
View File

@@ -1,6 +1,11 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
import "./executor-test-helpers.js";
import { TaskExecutor } from "../executor.js";
/*
FNXC:CodeOrganization 2026-08-03-14:10:
captureBaseCommitSha peeled to executor/worktree-git-refs.ts (U4 Slice B).
Gate suite calls the free function with an injected store — no TaskExecutor method.
*/
import { captureBaseCommitSha } from "../executor/worktree-git-refs.js";
import { executorLog } from "../logger.js";
import type { Task } from "@fusion/core";
import { createMockStore, mockedExec, mockedExecSync, resetExecutorMocks } from "./executor-test-helpers.js";
@@ -32,10 +37,9 @@ describe("captureBaseCommitSha", () => {
return {} as any;
}) as any);
const store = createMockStore();
const executor = new TaskExecutor(store, "/tmp/test");
const audit = { git: vi.fn().mockResolvedValue(undefined) };
await (executor as any).captureBaseCommitSha(makeTask(), "/tmp/test/.worktrees/fn-4383", audit);
await captureBaseCommitSha(store, makeTask(), "/tmp/test/.worktrees/fn-4383", audit);
expect(store.updateTask).toHaveBeenCalledWith("FN-4383", { baseCommitSha: "abc1234" });
expect(audit.git).toHaveBeenCalledWith(expect.objectContaining({ metadata: { purpose: "base", preserved: false } }));
@@ -44,10 +48,10 @@ describe("captureBaseCommitSha", () => {
it("preserves existing valid baseCommitSha across resumed sessions", async () => {
mockedExecSync.mockReturnValue("");
const store = createMockStore();
const executor = new TaskExecutor(store, "/tmp/test");
const audit = { git: vi.fn().mockResolvedValue(undefined) };
await (executor as any).captureBaseCommitSha(
await captureBaseCommitSha(
store,
makeTask({ baseCommitSha: "old123" }),
"/tmp/test/.worktrees/fn-4383",
audit,
@@ -69,10 +73,10 @@ describe("captureBaseCommitSha", () => {
return {} as any;
}) as any);
const store = createMockStore();
const executor = new TaskExecutor(store, "/tmp/test");
const audit = { git: vi.fn().mockResolvedValue(undefined) };
await (executor as any).captureBaseCommitSha(
await captureBaseCommitSha(
store,
makeTask({ baseCommitSha: "stale_main_sha" }),
"/tmp/test/.worktrees/fn-4383",
audit,
@@ -96,10 +100,9 @@ describe("captureBaseCommitSha", () => {
return {} as any;
}) as any);
const store = createMockStore();
const executor = new TaskExecutor(store, "/tmp/test");
const audit = { git: vi.fn().mockResolvedValue(undefined) };
await (executor as any).captureBaseCommitSha(makeTask({ baseCommitSha: "stale999" }), "/tmp/test/.worktrees/fn-4383", audit);
await captureBaseCommitSha(store, makeTask({ baseCommitSha: "stale999" }), "/tmp/test/.worktrees/fn-4383", audit);
expect(store.updateTask).toHaveBeenCalledWith("FN-4383", { baseCommitSha: "new456" });
});
@@ -107,10 +110,10 @@ describe("captureBaseCommitSha", () => {
it("preserves prior merge base on resume for FN-4309/FN-4383 multi-session regression", async () => {
mockedExecSync.mockReturnValue("");
const store = createMockStore();
const executor = new TaskExecutor(store, "/tmp/test");
const audit = { git: vi.fn().mockResolvedValue(undefined) };
await (executor as any).captureBaseCommitSha(
await captureBaseCommitSha(
store,
makeTask({ baseCommitSha: "merge_base_sha" }),
"/tmp/test/.worktrees/fn-4383",
audit,
@@ -131,10 +134,9 @@ describe("captureBaseCommitSha", () => {
return {} as any;
}) as any);
const store = createMockStore();
const executor = new TaskExecutor(store, "/tmp/test");
const audit = { git: vi.fn().mockResolvedValue(undefined) };
await (executor as any).captureBaseCommitSha(makeTask(), "/tmp/test/.worktrees/fn-4383", audit);
await captureBaseCommitSha(store, makeTask(), "/tmp/test/.worktrees/fn-4383", audit);
expect(store.updateTask).toHaveBeenCalledWith("FN-4383", { baseCommitSha: "head777" });
expect(vi.mocked(executorLog.warn)).toHaveBeenCalledWith(expect.stringContaining("falling back to HEAD"));

11
packages/engine/src/__tests__/executor-graph-failure-lanes-resolved.test.ts
View File

@@ -498,12 +498,17 @@ describe("one lane snapshot per recovery, across every classifier", () => {
it("threads the memo from handleGraphFailure into every one of them", async () => {
const { readFile } = await import("node:fs/promises");
const source = await readFile(new URL("../executor.ts", import.meta.url), "utf8");
const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
/*
FNXC:CodeOrganization 2026-08-03-15:05 (U4 handleGraphFailure peel):
Call sites live in the free-function peel (`deps.<classifier>(…resumeLanesMemo)`), not the
thin TaskExecutor facade. Scan the peel (and still accept `this.` for any residual class body).
*/
const peel = await readFile(new URL("../executor/handle-graph-failure.ts", import.meta.url), "utf8");
const code = peel.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
// The call sites must PASS it — accepting an unused optional parameter proves nothing.
for (const name of MEMO_THREADED.filter((n) => n !== "isReentrantPausedAbortedInFlightNode")) {
const callSite = new RegExp(`this\\.${name}\\([^;]*resumeLanesMemo`);
const callSite = new RegExp(`(?:this|deps)\\.${name}\\([^;]*resumeLanesMemo`);
expect(callSite.test(code), `${name} call site does not pass resumeLanesMemo`).toBe(true);
}
});

26
packages/engine/src/__tests__/executor-implementation-exit-events.test.ts
View File

@@ -162,7 +162,12 @@ describe("execute seam announces the implementation phase's exit", () => {
is wired, and that the two out-of-band ids sit with the handoff they describe.
*/
it("every exit id has a real call site in runImplementation", () => {
const source = readFileSync(new URL("../executor.ts", import.meta.url), "utf8")
/*
FNXC:CodeOrganization 2026-08-03-16:20 (U4 runImplementation peel):
Call sites live in executor/run-implementation.ts free function, not the thin facade.
Scan the peel (deps.markCompletionFinalized / deps.handoffTaskToReview after transform).
*/
const source = readFileSync(new URL("../executor/run-implementation.ts", import.meta.url), "utf8")
.replace(/\/\*[\s\S]*?\*\//g, " ")
.replace(/(^|[^:])\/\/[^\n]*/g, "$1 ");
const ALL_EXITS: ImplementationExit[] = [
@@ -188,15 +193,28 @@ describe("execute seam announces the implementation phase's exit", () => {
that precedes this report must be nearer to it than any earlier handoff is, which is what
"this site's own marker" means, and the handoff must follow the report.
*/
const markerIdx = source.lastIndexOf("markCompletionFinalized(", idx);
const priorHandoffIdx = source.lastIndexOf("handoffTaskToReview(", idx);
const markerIdx = Math.max(
source.lastIndexOf("markCompletionFinalized(", idx),
source.lastIndexOf("deps.markCompletionFinalized(", idx),
);
const priorHandoffIdx = Math.max(
source.lastIndexOf("handoffTaskToReview(", idx),
source.lastIndexOf("deps.handoffTaskToReview(", idx),
);
expect(markerIdx, `${exit} must set the durable completion-finalize marker before handing off`).toBeGreaterThan(-1);
expect(
markerIdx,
`${exit}'s completion-finalize marker must belong to this site, not an earlier one`,
).toBeGreaterThan(priorHandoffIdx);
const handoffAfter = (() => {
const a = source.indexOf("handoffTaskToReview(", idx);
const b = source.indexOf("deps.handoffTaskToReview(", idx);
if (a === -1) return b;
if (b === -1) return a;
return Math.min(a, b);
})();
expect(
source.indexOf("handoffTaskToReview(", idx),
handoffAfter,
`${exit} must be followed by the review handoff it describes`,
).toBeGreaterThan(idx);
}

83
packages/engine/src/__tests__/executor-lifecycle-ownership-ledger.test.ts
View File

@@ -54,6 +54,28 @@ import { fileURLToPath } from "node:url";
import ts from "typescript";
const EXECUTOR_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "executor.ts");
/*
FNXC:CodeOrganization 2026-08-03-15:05 (U4 handleGraphFailure peel):
handleGraphFailure's junction-box body lives in executor/handle-graph-failure.ts as a free
function; the class method is a thin deps-bag facade. The U8 ownership ledger must measure the
real disposition sites (deps.store.moveTask / deps.handoffTaskToReview / status:"failed"), not
the facade, or every count collapses to zero while nothing about ownership changed.
FNXC:CodeOrganization 2026-08-03-16:15 (U4 runImplementation peel):
Same for runImplementation — the ~3.4k-line junction box is executor/run-implementation.ts.
*/
const HANDLE_GRAPH_FAILURE_PATH = join(
dirname(fileURLToPath(import.meta.url)),
"..",
"executor",
"handle-graph-failure.ts",
);
const RUN_IMPLEMENTATION_PATH = join(
dirname(fileURLToPath(import.meta.url)),
"..",
"executor",
"run-implementation.ts",
);
const SOURCE_FILE = ts.createSourceFile(
EXECUTOR_PATH,
@@ -62,6 +84,20 @@ const SOURCE_FILE = ts.createSourceFile(
/* setParentNodes */ true,
);
const HANDLE_GRAPH_FAILURE_SOURCE = ts.createSourceFile(
HANDLE_GRAPH_FAILURE_PATH,
readFileSync(HANDLE_GRAPH_FAILURE_PATH, "utf8"),
ts.ScriptTarget.ESNext,
/* setParentNodes */ true,
);
const RUN_IMPLEMENTATION_SOURCE = ts.createSourceFile(
RUN_IMPLEMENTATION_PATH,
readFileSync(RUN_IMPLEMENTATION_PATH, "utf8"),
ts.ScriptTarget.ESNext,
/* setParentNodes */ true,
);
/**
* Find a class method's body by NAME through the AST. Throws rather than returning empty — a
* silent miss would make every count zero and report "U8 complete" while nothing had changed.
@@ -81,10 +117,31 @@ function methodBody(name: string): ts.Block {
}
/**
* Count call expressions of `this.<property>.…(…)` shapes inside a method body.
* `member` is the dotted path after `this.` — e.g. `store.moveTask` or `handoffTaskToReview`.
* Free-function body by name (U4 peels). Same throw-on-miss discipline as methodBody.
*/
function freeFunctionBody(sourceFile: ts.SourceFile, name: string): ts.Block {
let found: ts.Block | undefined;
const visit = (node: ts.Node): void => {
if (ts.isFunctionDeclaration(node) && node.name?.text === name && node.body) {
if (found) throw new Error(`ambiguous free function name: ${name}`);
found = node.body;
}
ts.forEachChild(node, visit);
};
visit(sourceFile);
if (!found) throw new Error(`free function not found: ${name}`);
return found;
}
/**
* Count call expressions of `this.<property>.…(…)` or `deps.<property>.…(…)` shapes inside a
* method/free-function body.
* `member` is the dotted path after the receiver — e.g. `store.moveTask` or `handoffTaskToReview`.
* Matching on the callee EXPRESSION (not text) is what makes a call inside a string impossible
* to miscount, and a renamed-but-equivalent call impossible to miss.
*
* FNXC:CodeOrganization 2026-08-03-15:05: U4 peels rewrite `this.X` to `deps.X`; accept either
* receiver so the ledger tracks dispositions after the peel without redefining ownership.
*/
function countCalls(body: ts.Block, member: string): number {
const path = member.split(".");
@@ -95,7 +152,8 @@ function countCalls(body: ts.Block, member: string): number {
if (!ts.isPropertyAccessExpression(current) || current.name.text !== path[i]) return false;
current = current.expression;
}
return current.kind === ts.SyntaxKind.ThisKeyword;
if (current.kind === ts.SyntaxKind.ThisKeyword) return true;
return ts.isIdentifier(current) && current.text === "deps";
};
const visit = (node: ts.Node): void => {
if (ts.isCallExpression(node) && matchesPath(node.expression)) total++;
@@ -137,8 +195,8 @@ function countTerminalParks(body: ts.Block): number {
return total;
}
const RUN_IMPLEMENTATION = methodBody("runImplementation");
const HANDLE_GRAPH_FAILURE = methodBody("handleGraphFailure");
const RUN_IMPLEMENTATION = freeFunctionBody(RUN_IMPLEMENTATION_SOURCE, "runImplementation");
const HANDLE_GRAPH_FAILURE = freeFunctionBody(HANDLE_GRAPH_FAILURE_SOURCE, "handleGraphFailure");
/** The three ways the executor performs a lifecycle disposition itself. */
const EXECUTOR_OWNED_LABELS = [
@@ -150,9 +208,9 @@ const EXECUTOR_OWNED_LABELS = [
/** The one way the implementation phase hands the decision back to the graph. */
const GRAPH_HANDBACK_LABEL = "graph handbacks (graphCompletion)";
function bodyLineCount(body: ts.Block): number {
const { line: start } = SOURCE_FILE.getLineAndCharacterOfPosition(body.getStart(SOURCE_FILE));
const { line: end } = SOURCE_FILE.getLineAndCharacterOfPosition(body.getEnd());
function bodyLineCount(body: ts.Block, sourceFile: ts.SourceFile = SOURCE_FILE): number {
const { line: start } = sourceFile.getLineAndCharacterOfPosition(body.getStart(sourceFile));
const { line: end } = sourceFile.getLineAndCharacterOfPosition(body.getEnd());
return end - start + 1;
}
@@ -207,10 +265,11 @@ describe("U8 execution-lifecycle ownership ledger", () => {
something else while still reporting a comfortable pass.
*/
it("extracts both junction-box method bodies at their real size", () => {
expect(bodyLineCount(RUN_IMPLEMENTATION)).toBeGreaterThan(2000);
expect(bodyLineCount(RUN_IMPLEMENTATION)).toBeLessThan(4500);
expect(bodyLineCount(HANDLE_GRAPH_FAILURE)).toBeGreaterThan(500);
expect(bodyLineCount(HANDLE_GRAPH_FAILURE)).toBeLessThan(1600);
// Free-function bodies after U4 peels — still the multi-k junction boxes, not facades.
expect(bodyLineCount(RUN_IMPLEMENTATION, RUN_IMPLEMENTATION_SOURCE)).toBeGreaterThan(2000);
expect(bodyLineCount(RUN_IMPLEMENTATION, RUN_IMPLEMENTATION_SOURCE)).toBeLessThan(4500);
expect(bodyLineCount(HANDLE_GRAPH_FAILURE, HANDLE_GRAPH_FAILURE_SOURCE)).toBeGreaterThan(500);
expect(bodyLineCount(HANDLE_GRAPH_FAILURE, HANDLE_GRAPH_FAILURE_SOURCE)).toBeLessThan(1600);
});
it("runImplementation: executor-owned dispositions match the ledger", () => {

32
packages/engine/src/__tests__/executor-prompt.test.ts
View File

@@ -322,13 +322,25 @@ describe("buildExecutionPrompt", () => {
});
it("keeps the executor source prompt wording and examples for commit summaries", async () => {
const { readFileSync } = await vi.importActual<typeof import("node:fs")>("node:fs");
const executorSource = readFileSync(new URL("../executor.ts", import.meta.url), "utf8");
/*
FNXC:CodeOrganization 2026-08-03-08:00:
EXECUTOR_SYSTEM_PROMPT lives in executor/system-prompt.ts (U4 pure peels); commit-template
examples may still sit in buildExecutionPrompt in executor.ts. Read both surfaces.
expect(executorSource).toContain("Always include a short, specific summary after the em dash (5–10 words)");
expect(executorSource).toContain("Do NOT commit just \\`complete Step N\\`");
expect(executorSource).toContain("\\`feat(FN-1234): complete Step 4 — tighten prompt examples for commit summaries\\`");
expect(executorSource).toContain("\\`feat(FN-1234): complete Step 2\\`");
FNXC:CodeOrganization 2026-08-03-12:45:
buildExecutionPrompt peeled to executor/execution-prompt.ts; include that surface so wording
ratchet still covers the implementation, not only the facade re-export.
*/
const { readFileSync } = await vi.importActual<typeof import("node:fs")>("node:fs");
const systemPromptSource = readFileSync(new URL("../executor/system-prompt.ts", import.meta.url), "utf8");
const executionPromptSource = readFileSync(new URL("../executor/execution-prompt.ts", import.meta.url), "utf8");
const executorSource = readFileSync(new URL("../executor.ts", import.meta.url), "utf8");
const combined = `${systemPromptSource}\n${executionPromptSource}\n${executorSource}`;
expect(combined).toContain("Always include a short, specific summary after the em dash (5–10 words)");
expect(combined).toContain("Do NOT commit just \\`complete Step N\\`");
expect(combined).toContain("\\`feat(FN-1234): complete Step 4 — tighten prompt examples for commit summaries\\`");
expect(combined).toContain("\\`feat(FN-1234): complete Step 2\\`");
});
it("omits Project Commands section when neither command is set", () => {
@@ -3035,10 +3047,14 @@ describe("executor base prompt runtime self-awareness", () => {
});
it("stays byte-identical with the core EXECUTOR_PROMPT_TEXT mirror at the shared preamble", async () => {
/*
FNXC:CodeOrganization 2026-08-03-08:00:
System prompt constant was peeled to executor/system-prompt.ts; assert the mirror lives there.
*/
const { FUSION_RUNTIME_SELF_AWARENESS } = await import("@fusion/core");
const { readFileSync } = await vi.importActual<typeof import("node:fs")>("node:fs");
const executorSource = readFileSync(new URL("../executor.ts", import.meta.url), "utf8");
expect(executorSource).toContain("const EXECUTOR_SYSTEM_PROMPT = `${FUSION_RUNTIME_SELF_AWARENESS}");
const systemPromptSource = readFileSync(new URL("../executor/system-prompt.ts", import.meta.url), "utf8");
expect(systemPromptSource).toContain("const EXECUTOR_SYSTEM_PROMPT = `${FUSION_RUNTIME_SELF_AWARENESS}");
expect(FUSION_RUNTIME_SELF_AWARENESS.length).toBeGreaterThan(0);
});

31
packages/engine/src/__tests__/executor-resume-query-lanes.test.ts
View File

@@ -29,16 +29,41 @@ REVERT PROOF, measured: restore either literal read and this fails.
import { readFileSync } from "node:fs";
import { describe, expect, it } from "vitest";
/*
FNXC:CodeOrganization 2026-08-03-09:55:
resumeTaskForAgent peeled into executor/resume-task-for-agent.ts (U4). The structural
count must include the free module so both resume sweeps still pin listWipLaneTasks.
*/
/*
FNXC:CodeOrganization 2026-08-03-10:25:
listWipLaneTasks body also peeled to executor/list-wip-lane-tasks.ts; role resolution lives there.
*/
const source = readFileSync(new URL("../executor.ts", import.meta.url), "utf8");
const resumeTaskForAgentSource = readFileSync(
new URL("../executor/resume-task-for-agent.ts", import.meta.url),
"utf8",
);
const listWipLaneTasksSource = readFileSync(
new URL("../executor/list-wip-lane-tasks.ts", import.meta.url),
"utf8",
);
const resumeOrphanedSource = readFileSync(
new URL("../executor/resume-orphaned.ts", import.meta.url),
"utf8",
);
const combined = `${source}\n${resumeTaskForAgentSource}\n${listWipLaneTasksSource}\n${resumeOrphanedSource}`;
describe("the resume sweeps read the resolved wip lane", () => {
it("resolves project wip columns instead of querying the literal", () => {
expect(source).toContain('resolveProjectColumnsForRoles(this.store, ["countsTowardWip"])');
expect(source).not.toContain('listTasks({ slim: true, column: "in-progress" })');
expect(listWipLaneTasksSource).toContain('resolveProjectColumnsForRoles(store, ["countsTowardWip"])');
expect(combined).not.toContain('listTasks({ slim: true, column: "in-progress" })');
});
it("routes BOTH sweeps through the one helper", () => {
// A second copy of the read is how two sweeps drift apart later.
expect(source.split("await this.listWipLaneTasks()").length - 1).toBe(2);
// Facade uses this.listWipLaneTasks; free module uses deps.listWipLaneTasks.
const thisCalls = combined.split("await this.listWipLaneTasks()").length - 1;
const depsCalls = combined.split("await deps.listWipLaneTasks()").length - 1;
expect(thisCalls + depsCalls).toBe(2);
});
});

14
packages/engine/src/__tests__/executor-stale-spec-active-lanes.test.ts
View File

@@ -40,7 +40,15 @@ Whoever next touches `execute()`'s test scaffolding should add the end-to-end ca
import { describe, expect, it } from "vitest";
import { readFileSync } from "node:fs";
const source = readFileSync(new URL("../executor.ts", import.meta.url), "utf8");
/*
FNXC:CodeOrganization 2026-08-03-16:25 (U4 runImplementation peel):
Active-lane stale-spec guard body lives in executor/run-implementation.ts free function
(`deps.store`); still concatenate residual class surfaces so either shape stays greppable.
*/
const source = [
readFileSync(new URL("../executor.ts", import.meta.url), "utf8"),
readFileSync(new URL("../executor/run-implementation.ts", import.meta.url), "utf8"),
].join("\n");
describe("the stale-spec skip resolves the board's own active lanes", () => {
it("resolves the task's own workflow IR before deciding the skip", () => {
@@ -62,8 +70,8 @@ describe("the stale-spec skip resolves the board's own active lanes", () => {
behind worktree and session setup that a unit test has no business standing up. Re-pointing it is
maintenance, not the end-to-end case it asks for.
*/
expect(source).toContain(
"const activeIr = await resolveWorkflowIrForTask(this.store, task.id);",
expect(source).toMatch(
/const activeIr = await resolveWorkflowIrForTask\((?:this|deps)\.store, task\.id\);/,
);
});

37
packages/engine/src/__tests__/executor-task-done-shared-helper.test.ts
View File

@@ -4,11 +4,40 @@ import { evaluateTaskDoneRefusal } from "../executor.js";
describe("FN-4946 shared task_done refusal helper invariant", () => {
it("keeps a single helper implementation and routes explicit+implicit paths through it", () => {
const source = readFileSync(new URL("../executor.ts", import.meta.url), "utf8");
const invocations = source.match(/evaluateTaskDoneRefusal\(/g) ?? [];
const helperDecl = source.match(/\bfunction evaluateTaskDoneRefusal\b/g) ?? [];
/*
FNXC:CodeOrganization 2026-08-03-07:30:
Wave18 peels evaluateTaskDoneRefusal into executor/task-done-refusal.ts; executor.ts
re-exports it. The single-implementation invariant still holds: one export function
declaration in the domain module, multiple call sites in the executor facade.
expect(invocations.length).toBeGreaterThanOrEqual(3);
FNXC:CodeOrganization 2026-08-03-13:45:
Implicit completion path peels into completion-predicates.ts; count call sites across
facade + that peel so the ratchet still covers explicit and implicit routes.
FNXC:CodeOrganization 2026-08-03-13:10:
Explicit fn_task_done path peels into create-task-done-tool.ts; include that call site
so the ratchet still counts both routes after the U4 tool peel.
*/
const facade = readFileSync(new URL("../executor.ts", import.meta.url), "utf8");
const implicitPeel = readFileSync(new URL("../executor/completion-predicates.ts", import.meta.url), "utf8");
const explicitPeel = readFileSync(new URL("../executor/create-task-done-tool.ts", import.meta.url), "utf8");
const helper = readFileSync(new URL("../executor/task-done-refusal.ts", import.meta.url), "utf8");
const isCallSite = (line: string) =>
/evaluateTaskDoneRefusal\s*\(/.test(line)
&& !line.includes("from \"./executor/task-done-refusal")
&& !line.includes('from "./task-done-refusal')
&& !/^\s*(import|export)\b/.test(line.trim())
&& !/evaluateTaskDoneRefusal,/.test(line);
// Call sites only — skip re-export/import lines.
const callLines = [
...facade.split("\n").filter(isCallSite),
...implicitPeel.split("\n").filter(isCallSite),
...explicitPeel.split("\n").filter(isCallSite),
];
const helperDecl = helper.match(/\bexport function evaluateTaskDoneRefusal\b/g) ?? [];
// Exact count: explicit (create-task-done-tool) + implicit (completion-predicates).
expect(callLines.length).toBe(2);
expect(helperDecl).toHaveLength(1);
});

22
packages/engine/src/__tests__/executor-worktree.test.ts
View File

@@ -4,7 +4,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import "./executor-test-helpers.js";
import { AgentSemaphore } from "../concurrency/concurrency.js";
import { detectReviewHandoffIntent, determineRevisionResetStart } from "../executor.js";
import { TaskExecutor, buildExecutionPrompt } from "../executor.js";
import { TaskExecutor, buildExecutionPrompt, extractWorktreeConflictInfo } from "../executor.js";
import { createFnAgent } from "../pi.js";
import { reviewStep as mockedReviewStepFn } from "../execution/reviewer.js";
import { execSync } from "node:child_process";
@@ -881,7 +881,7 @@ describe("TaskExecutor worktree recovery", () => {
"FN-050",
expect.objectContaining({
status: "failed",
error: expect.stringContaining(`git config --global --add safe.directory "${rootDir}"`),
error: expect.stringContaining("git config --global --add safe.directory <project-directory>"),
}),
);
const failedPatch = store.updateTask.mock.calls.find(
@@ -896,26 +896,21 @@ describe("TaskExecutor worktree recovery", () => {
});
it("extractWorktreeConflictInfo classifies not-a-git-repository errors", () => {
const store = createMockStore();
const executor = createWorktreeExecutor(store, "/tmp/test");
const error: any = new Error("fatal: not a git repository");
error.stderr = Buffer.from("fatal: not a git repository");
const conflictInfo = (executor as any).extractWorktreeConflictInfo(error);
const conflictInfo = extractWorktreeConflictInfo(error);
expect(conflictInfo.type).toBe("not-git-repo");
expect(conflictInfo.message).toContain("not a git repository");
});
it("extractWorktreeConflictInfo does not misclassify dubious ownership as not-git-repo", () => {
const store = createMockStore();
const executor = createWorktreeExecutor(store, "/tmp/test");
const rootDir = "C:/Users/drewd/Documents/1. App Development/1. Active/NextGenEHS";
const error: any = new Error(`fatal: detected dubious ownership in repository at '${rootDir}'`);
error.stderr = Buffer.from(`fatal: detected dubious ownership in repository at '${rootDir}'`);
const conflictInfo = (executor as any).extractWorktreeConflictInfo(error);
const conflictInfo = extractWorktreeConflictInfo(error);
expect(conflictInfo.type).toBe("unknown");
expect(conflictInfo.message).toContain("detected dubious ownership");
});
@@ -958,7 +953,7 @@ describe("TaskExecutor worktree recovery", () => {
"fatal: 'fusion/fn-050' is already checked out at '/tmp/test/.worktrees/green-sage'",
);
const conflictInfo = (executor as any).extractWorktreeConflictInfo(error);
const conflictInfo = extractWorktreeConflictInfo(error);
expect(conflictInfo).toMatchObject({
type: "already-used",
path: "/tmp/test/.worktrees/green-sage",
@@ -1550,7 +1545,9 @@ describe("TaskExecutor worktree recovery", () => {
mockedExecSync.mockImplementation((cmd: string | string[]) => {
const command = typeof cmd === "string" ? cmd : cmd[0];
if (command.includes('git worktree add -b "fusion/fn-050"')) {
// Exact branch only — `"fusion/fn-050"` is a prefix of `"fusion/fn-050-2"`, so a naive
// includes() would fail every sibling-rename attempt and recurse forever.
if (command.includes('git worktree add -b "fusion/fn-050"') && !command.includes('fusion/fn-050-')) {
const error: any = new Error(
`fatal: 'fusion/fn-050' is already used by worktree at '${conflictPath}'`,
);
@@ -1612,7 +1609,8 @@ describe("TaskExecutor worktree recovery", () => {
mockedExecSync.mockImplementation((cmd: string | string[]) => {
const command = typeof cmd === "string" ? cmd : cmd[0];
if (command.includes('git worktree add -b "fusion/fn-050"')) {
// Exact branch only — avoid matching sibling rename branches (fusion/fn-050-2, …).
if (command.includes('git worktree add -b "fusion/fn-050"') && !command.includes("fusion/fn-050-")) {
const error: any = new Error("fatal: A branch named 'fusion/fn-050' already exists.");
error.stderr = Buffer.from(error.message);
throw error;

73
packages/engine/src/__tests__/liveness-gate-ratchet.test.ts
View File

@@ -30,10 +30,11 @@ no fixtures (FN-5048 — do not add slow tests). Production source only.
const REPO_ROOT = resolve(import.meta.dirname, "../../../..");
function readSource(relPath: string): string {
function readSource(relPath: string, minLength = 1000): string {
const source = readFileSync(join(REPO_ROOT, relPath), "utf8");
// FAIL CLOSED: a moved/emptied file must not silently pass every assertion below.
expect(source.length, `${relPath} is empty or unreadable — the ratchet checked nothing`).toBeGreaterThan(1000);
// Peeled U4 free functions can be short pure helpers; still require non-trivial content.
expect(source.length, `${relPath} is empty or unreadable — the ratchet checked nothing`).toBeGreaterThan(minLength);
return source;
}
@@ -104,6 +105,14 @@ function findDiscardedCalls(source: string, name: string): string[] {
const SELF_HEALING = "packages/engine/src/self-healing.ts";
const EXECUTOR = "packages/engine/src/executor.ts";
/*
FNXC:CodeOrganization 2026-08-03-20:25:
U4 peels move free-function bodies under executor/*. Source-scan ratchets must
follow the peel (facade in executor.ts + body in the peeled module) so they do
not re-block legitimate extractions.
*/
const CLEAR_PHANTOM = "packages/engine/src/executor/clear-phantom-executor-binding.ts";
const HAS_LIVE_SESSION_SURFACE = "packages/engine/src/executor/has-live-session-surface.ts";
const IN_PROCESS_RUNTIME = "packages/engine/src/runtimes/in-process-runtime.ts";
describe("FN-6756 liveness-gate ratchet", () => {
@@ -142,19 +151,31 @@ describe("FN-6756 liveness-gate ratchet", () => {
sweep be "fixed" without fixing the next.
*/
it("clearPhantomExecutorBinding delegates to the shared hasLiveSessionSurface probe", () => {
const source = stripComments(readSource(EXECUTOR));
const start = source.indexOf("clearPhantomExecutorBinding(taskId: string");
expect(start, "clearPhantomExecutorBinding not found in executor source").toBeGreaterThan(-1);
const body = source.slice(start, start + 1200);
// Facade on TaskExecutor must forward to the free function (or call the probe).
const facadeSource = stripComments(readSource(EXECUTOR));
const facadeStart = facadeSource.indexOf("clearPhantomExecutorBinding(taskId: string");
expect(facadeStart, "clearPhantomExecutorBinding not found in executor source").toBeGreaterThan(-1);
const facadeBody = facadeSource.slice(facadeStart, facadeStart + 1200);
expect(
body.includes("this.hasLiveSessionSurface(taskId)"),
"clearPhantomExecutorBinding must call the shared hasLiveSessionSurface probe, not re-derive liveness inline — a second copy can drift from the one callers gate on",
facadeBody.includes("this.hasLiveSessionSurface(taskId)")
|| /hasLiveSessionSurface:\s*\(id\)\s*=>\s*this\.hasLiveSessionSurface\(id\)/.test(facadeBody)
|| /clearPhantomExecutorBindingImpl\(/.test(facadeBody),
"clearPhantomExecutorBinding facade must call the shared hasLiveSessionSurface probe (directly or via peeled Impl deps), not re-derive liveness inline",
).toBe(true);
expect(
/activeSessions\.has|activeStepExecutors\.has|activeWorkflowStepSessions\.has|activeCliTaskSessions\.has/.test(body),
"the session-map disjunction is inlined here again; it belongs only in hasLiveSessionSurface",
/activeSessions\.has|activeStepExecutors\.has|activeWorkflowStepSessions\.has|activeCliTaskSessions\.has/.test(facadeBody),
"the session-map disjunction is inlined on the facade; it belongs only in hasLiveSessionSurface",
).toBe(false);
// Peeled free function must consume the hasLiveSessionSurface deps callback.
const peelSource = stripComments(readSource(CLEAR_PHANTOM));
expect(
peelSource.includes("deps.hasLiveSessionSurface(taskId)"),
"clearPhantomExecutorBinding peel must call deps.hasLiveSessionSurface, not re-derive liveness inline",
).toBe(true);
expect(
/activeSessions\.has|activeStepExecutors\.has|activeWorkflowStepSessions\.has|activeCliTaskSessions\.has/.test(peelSource),
"the session-map disjunction is inlined in clear-phantom-executor-binding; it belongs only in hasLiveSessionSurface",
).toBe(false);
});
@@ -202,22 +223,32 @@ describe("FN-6756 liveness-gate ratchet", () => {
restores the exact blind spot FN-8600 and FN-6756 both went through.
*/
it("hasLiveSessionSurface counts registered session paths, not just executor maps", () => {
const source = stripComments(readSource(EXECUTOR));
const start = source.indexOf("hasLiveSessionSurface(taskId: string): boolean");
expect(start, "hasLiveSessionSurface not found — the probe was removed or renamed").toBeGreaterThan(-1);
// Facade must remain on TaskExecutor (public API for self-healing wiring).
const facadeSource = stripComments(readSource(EXECUTOR));
const facadeStart = facadeSource.indexOf("hasLiveSessionSurface(taskId: string): boolean");
expect(facadeStart, "hasLiveSessionSurface not found — the probe was removed or renamed").toBeGreaterThan(-1);
/*
FNXC:NodeWorktreeIsolation 2026-07-29-16:20 (PR #2540 review — coderabbit):
FAIL CLOSED on a missing boundary. `indexOf` returning -1 made `slice(start, -1)`
scan nearly the whole of executor.ts, so an unrelated later `activeSessionRegistry`
reference could satisfy this assertion after the probe itself was deleted.
*/
const end = source.indexOf("\n }", start);
expect(end, "could not find the end of hasLiveSessionSurface — the ratchet would scan the whole file").toBeGreaterThan(start);
const body = source.slice(start, end);
const facadeEnd = facadeSource.indexOf("\n }", facadeStart);
expect(facadeEnd, "could not find the end of hasLiveSessionSurface facade — the ratchet would scan the whole file").toBeGreaterThan(facadeStart);
const facadeBody = facadeSource.slice(facadeStart, facadeEnd);
expect(
body.includes("activeSessionRegistry.pathsForTask(taskId)"),
"hasLiveSessionSurface no longer consults activeSessionRegistry — a triage planner is owned by TriageProcessor and appears in NO executor-owned map, so this term is the only thing that sees it",
facadeBody.includes("activeSessionRegistry.pathsForTask")
|| facadeBody.includes("pathsForTask")
|| /hasLiveSessionSurfaceImpl\(/.test(facadeBody),
"hasLiveSessionSurface facade must consult registry paths (directly or via peeled Impl)",
).toBe(true);
// Free-function body must include the registry/paths term (FN-6756 blind spot).
const peelSource = stripComments(readSource(HAS_LIVE_SESSION_SURFACE, 200));
expect(
peelSource.includes("pathsForTask")
|| peelSource.includes("activeSessionRegistry.pathsForTask"),
"hasLiveSessionSurface no longer consults activeSessionRegistry paths — a triage planner is owned by TriageProcessor and appears in NO executor-owned map, so this term is the only thing that sees it",
).toBe(true);
});
});

21
packages/engine/src/__tests__/mcp-surface-coverage.test.ts
View File

@@ -1,4 +1,4 @@
import { readFileSync } from "node:fs";
import { readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import type { McpSecretReader } from "@fusion/core";
@@ -94,8 +94,19 @@ describe("MCP surface coverage", () => {
});
it("keeps every executor-owned fresh-session seam on immediate MCP re-resolution", () => {
const source = readFileSync(join(process.cwd(), "src/executor.ts"), "utf8");
const immediateResolutions = source.match(/mcpServers: await this\.resolveMcpServers\(/g) ?? [];
/*
FNXC:CodeOrganization 2026-08-03-16:25 (U4 runImplementation peel):
Fresh-session MCP re-resolution call sites moved into free peels
(`mcpServers: await deps.resolveMcpServers(...)`) under executor/*. Scan the
whole executor/ tree so U4 peels cannot drop a create-session MCP seam silently.
*/
const executorDir = join(process.cwd(), "src/executor");
const peelSources = readdirSync(executorDir)
.filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts") && !name.endsWith(".d.ts"))
.map((name) => readFileSync(join(executorDir, name), "utf8"));
const monolith = readFileSync(join(process.cwd(), "src/executor.ts"), "utf8");
const source = [monolith, ...peelSources].join("\n");
const immediateResolutions = source.match(/mcpServers:\s*await\s+(?:this|deps)\.resolveMcpServers\(/g) ?? [];
// Main executor, fresh retry, workflow/manual model seams, self-fix/review,
// and spawned-child paths all resolve at their own create-session call.
@@ -115,6 +126,10 @@ describe("MCP surface coverage", () => {
});
it("keeps the PR response merger seam wired to resolved MCP", () => {
/*
FNXC:CodeOrganization 2026-08-03-16:25:
pr-response-run-ops lives under merge/, not the engine package root.
*/
expectResolvedMcpForwarded(
"src/merge/pr-response-run-ops.ts",
"const mcpServers = store ? (await resolveMcpServersForStore(store)).servers : undefined;",

35
packages/engine/src/__tests__/worktree-primary-checkout-invariant.test.ts
View File

@@ -41,8 +41,15 @@ function createExecutor(rootDir: string): TaskExecutor {
return new TaskExecutor(store as any, rootDir);
}
/*
FNXC:CodeOrganization 2026-08-03-15:20:
U4 Slice B peels createWorktree into worktree-create-outer.ts / worktree-create-conflict.ts;
worktree-acquisition lives under worktree/. Source-scan surfaces must follow the peels.
*/
const executorSource = readFileSync(fileURLToPath(new URL("../executor.ts", import.meta.url)), "utf8");
const acquisitionSource = readFileSync(fileURLToPath(new URL("../worktree-acquisition.ts", import.meta.url)), "utf8");
const createOuterSource = readFileSync(fileURLToPath(new URL("../executor/worktree-create-outer.ts", import.meta.url)), "utf8");
const createConflictSource = readFileSync(fileURLToPath(new URL("../executor/worktree-create-conflict.ts", import.meta.url)), "utf8");
const acquisitionSource = readFileSync(fileURLToPath(new URL("../worktree/worktree-acquisition.ts", import.meta.url)), "utf8");
const mergerSource = readFileSync(fileURLToPath(new URL("../merger.ts", import.meta.url)), "utf8");
function sourceRegion(source: string, start: string, end: string): string {
@@ -112,18 +119,38 @@ describe("TaskExecutor primary-checkout worktree invariant", () => {
This source guard complements the real-git test above. It must fail if a task-worktree creation or
acquisition surface reintroduces `git checkout`/`git switch` against the project root to select a
task branch. Merger's later integration-target checkout is deliberately outside the reacquire slice.
FNXC:CodeOrganization 2026-08-03-15:20:
createWorktree implementation now lives in executor/worktree-create-outer.ts +
worktree-create-conflict.ts; the executor.ts facade is a thin deps-wiring wrapper only.
*/
const executorCreation = sourceRegion(executorSource, "private async createWorktree(", "private async cleanupConflictingWorktree(");
/*
FNXC:CodeOrganization 2026-08-03-15:45:
sourceRegion is exclusive of the end marker — end after the facade body so
`createWorktreeImpl` remains in the scanned slice (not used as the end itself).
*/
const executorFacade = sourceRegion(
executorSource,
"private async createWorktree(",
"private async removeOwnWorktreeWithReconcile(",
);
// Full peeled modules: createWorktree is not first in worktree-create-outer.ts.
const outerImpl = createOuterSource;
const conflictImpl = createConflictSource;
const acquisition = sourceRegion(acquisitionSource, "const createWorktreeImpl = createWorktree", "const logConfiguredCopyFileResults");
const mergerReacquire = sourceRegion(mergerSource, "const reacquireReuseIntegrationWorktree = async", "// 3b. Ensure rootDir is based on the resolved integration target before merging.");
expect(executorCreation).toContain("git worktree add");
expect(executorFacade).toContain("createWorktreeImpl");
expect(outerImpl).toContain("export async function createWorktree");
expect(conflictImpl).toContain("git worktree add");
expect(acquisition).toContain("backend.create(");
expect(mergerReacquire).toContain("git worktree add -f");
const rootCheckoutSwitch = /execAsync\(\s*`git\s+(?:checkout|switch)(?:\s+(?:-b|-c))?\b/;
for (const [surface, source] of [
["TaskExecutor.createWorktree", executorCreation],
["TaskExecutor.createWorktree facade", executorFacade],
["worktree-create-outer createWorktree", outerImpl],
["worktree-create-conflict tryCreateWorktree", conflictImpl],
["acquireTaskWorktree createWorktreeImpl", acquisition],
["merger reacquire callback", mergerReacquire],
] as const) {

10
packages/engine/src/execution/hold-release.ts
View File

@@ -289,14 +289,6 @@ export async function isUnplannedForExecution(store: TaskStore, task: Task, ir:
*/
if (task.status === "needs-replan") return true;
/*
FNXC:DuplicateIntake 2026-08-09-01:02:
The title is already durable task state, so its exact redirect must hold capacity before the
store capability check and prompt read. This keeps title-only redirects non-dispatchable even
for adapters without task directories or during prompt I/O failures.
*/
if (isDuplicateRedirectOnlyPrompt(null, task.title)) return true;
/*
FNXC:WorkflowScheduling 2026-07-19-02:10 (U4):
Gate the bootstrap-stub check on the TRAIT, not the literal "todo" id. An
@@ -321,7 +313,7 @@ export async function isUnplannedForExecution(store: TaskStore, task: Task, ir:
A DUPLICATE-only PROMPT is unplanned for execution (FN-8704). Hold capacity release
until triage writes a real plan — filesystem validation is the twin of this check.
*/
if (isDuplicateRedirectOnlyPrompt(promptContent, task.title)) return true;
if (isDuplicateRedirectOnlyPrompt(promptContent)) return true;
return isUnplannedSeedPrompt(promptContent, task.id, task.title, task.description);
} catch {
// Missing prompt is handled by filesystem validation elsewhere; do not block on it here.

24416
packages/engine/src/executor.ts
View File

File diff suppressed because it is too large Load Diff

43
packages/engine/src/executor/__tests__/resolve-task-step-source.test.ts Normal file
View File

@@ -0,0 +1,43 @@
/**
* FNXC:CodeOrganization 2026-08-03-21:50:
* Unit tests for resolveTaskStepSource pure peel (KTD-12).
*/
import { describe, expect, it } from "vitest";
import { resolveTaskStepSource } from "../resolve-task-step-source.js";
import type { WorkflowIr } from "@fusion/core";
function ir(nodes: WorkflowIr["nodes"]): WorkflowIr {
return { version: "v2", nodes, edges: [], name: "t", columns: [] } as unknown as WorkflowIr;
}
describe("resolveTaskStepSource", () => {
it("returns undefined without IR or parse-steps node", () => {
expect(resolveTaskStepSource(undefined)).toBeUndefined();
expect(resolveTaskStepSource(ir([{ id: "code", kind: "code" } as any]))).toBeUndefined();
});
it("reads artifact+parser from the first parse-steps node", () => {
expect(
resolveTaskStepSource(
ir([
{ id: "p", kind: "parse-steps", config: { artifact: "SPEC.md", parser: "markdown-h2" } } as any,
]),
),
).toEqual({ artifact: "SPEC.md", parser: "markdown-h2" });
});
it("defaults artifact to PROMPT.md when missing/blank", () => {
expect(
resolveTaskStepSource(ir([{ id: "p", kind: "parse-steps", config: { parser: "markdown-h2" } } as any])),
).toEqual({ artifact: "PROMPT.md", parser: "markdown-h2" });
expect(
resolveTaskStepSource(ir([{ id: "p", kind: "parse-steps", config: { artifact: " ", parser: "markdown-h2" } } as any])),
).toEqual({ artifact: "PROMPT.md", parser: "markdown-h2" });
});
it("skips parse-steps nodes without a string parser", () => {
expect(
resolveTaskStepSource(ir([{ id: "p", kind: "parse-steps", config: { artifact: "X.md" } } as any])),
).toBeUndefined();
});
});

121
packages/engine/src/executor/__tests__/session-worktree-pure-helpers.test.ts Normal file
View File

@@ -0,0 +1,121 @@
/**
* FNXC:CodeOrganization 2026-08-03-20:20:
* Unit tests for U4 pure peels: hasLiveSessionSurface, listWorktreeHolders,
* isAgentEffectivelyExecuting, getWorktreePath, ephemeral deletion helpers,
* and buildInjectedRuntimeEnv.
*/
import { describe, expect, it } from "vitest";
import { hasLiveSessionSurface } from "../has-live-session-surface.js";
import { listWorktreeHolders } from "../list-worktree-holders.js";
import { isAgentEffectivelyExecuting } from "../is-agent-effectively-executing.js";
import { getWorktreePath } from "../get-worktree-path.js";
import {
disposeEphemeralTimers,
isEphemeralDeletionPending,
} from "../ephemeral-deletion-pending.js";
import { buildInjectedRuntimeEnv } from "../build-injected-runtime-env.js";
describe("hasLiveSessionSurface", () => {
it("is true when any session map owns the task", () => {
const deps = {
activeSessions: new Map([["T1", {}]]),
activeStepExecutors: new Map<string, unknown>(),
activeWorkflowStepSessions: new Map<string, unknown>(),
activeCliTaskSessions: new Map<string, unknown>(),
pathsForTask: () => [] as string[],
};
expect(hasLiveSessionSurface(deps, "T1")).toBe(true);
expect(hasLiveSessionSurface(deps, "T2")).toBe(false);
});
it("is true when registry paths exist even if maps are empty", () => {
const deps = {
activeSessions: new Map<string, unknown>(),
activeStepExecutors: new Map<string, unknown>(),
activeWorkflowStepSessions: new Map<string, unknown>(),
activeCliTaskSessions: new Map<string, unknown>(),
pathsForTask: (id: string) => (id === "T1" ? ["/wt"] : []),
};
expect(hasLiveSessionSurface(deps, "T1")).toBe(true);
expect(hasLiveSessionSurface(deps, "T2")).toBe(false);
});
});
describe("listWorktreeHolders", () => {
it("emits one row per path including multi-worktree tasks", () => {
const map = new Map<string, Set<string>>([
["T1", new Set(["/a", "/b"])],
["T2", new Set(["/c"])],
]);
expect(listWorktreeHolders(map)).toEqual([
{ taskId: "T1", worktreePath: "/a" },
{ taskId: "T1", worktreePath: "/b" },
{ taskId: "T2", worktreePath: "/c" },
]);
});
});
describe("isAgentEffectivelyExecuting", () => {
it("matches any effective column-agent principal", () => {
const map = new Map([
["T1", "agent-a"],
["T2", "agent-b"],
]);
expect(isAgentEffectivelyExecuting(map, "agent-b")).toBe(true);
expect(isAgentEffectivelyExecuting(map, "agent-c")).toBe(false);
expect(isAgentEffectivelyExecuting(map, "")).toBe(false);
});
});
describe("getWorktreePath", () => {
it("returns first path for single-repo mode and undefined in workspace mode", () => {
const paths = (id: string) => (id === "T1" ? ["/only"] : []);
expect(getWorktreePath(null, paths, "T1")).toBe("/only");
expect(getWorktreePath({ repos: [] }, paths, "T1")).toBeUndefined();
});
});
describe("ephemeral deletion helpers", () => {
it("tracks pending deletes and clears on dispose", () => {
const pending = new Set<string>(["a1"]);
expect(isEphemeralDeletionPending(pending, "a1")).toBe(true);
expect(isEphemeralDeletionPending(pending, "a2")).toBe(false);
disposeEphemeralTimers(pending);
expect(pending.size).toBe(0);
});
});
describe("buildInjectedRuntimeEnv", () => {
it("merges plugin env and path prepend without mutating process.env", async () => {
const originalPath = process.env.PATH;
const result = await buildInjectedRuntimeEnv(
{
rootDir: "/repo",
collectExecutorRuntimeEnv: async () => ({
env: { FUSION_CE_SKILLS_DIR: "/skills" },
pathPrepend: ["/plugin/bin"],
}),
},
"T1",
"/wt",
"branch",
);
expect(result.injectedKeyCount).toBe(1);
expect(result.pathEntryCount).toBe(1);
expect(result.env.FUSION_CE_SKILLS_DIR).toBe("/skills");
expect(result.env.PATH?.startsWith("/plugin/bin")).toBe(true);
expect(process.env.PATH).toBe(originalPath);
expect(process.env.FUSION_CE_SKILLS_DIR).toBeUndefined();
});
it("works without a plugin collector", async () => {
const result = await buildInjectedRuntimeEnv(
{ rootDir: "/repo" },
"T1",
"/wt",
undefined,
);
expect(result.injectedKeyCount).toBe(0);
expect(result.pathEntryCount).toBe(0);
});
});

44
packages/engine/src/executor/__tests__/shared-worker-tools.test.ts Normal file
View File

@@ -0,0 +1,44 @@
/**
* FNXC:CodeOrganization 2026-08-03-22:05:
* Smoke tests for shared worker-tool free factories peeled from TaskExecutor (U4).
*/
import { describe, expect, it, vi } from "vitest";
import {
createArtifactListTool,
createArtifactRegisterTool,
createTaskLogTool,
createTaskPromoteTool,
createTraitListTool,
createWorkflowListTool,
type SharedWorkerToolsDeps,
} from "../shared-worker-tools.js";
function makeDeps(overrides: Partial<SharedWorkerToolsDeps> = {}): SharedWorkerToolsDeps {
return {
store: {
getTask: vi.fn(),
getSettings: vi.fn().mockResolvedValue({}),
} as any,
rootDir: "/repo",
messageStore: undefined,
getRunContextFor: () => undefined,
...overrides,
};
}
describe("shared-worker-tools", () => {
it("creates store-scoped tools with expected names", () => {
const deps = makeDeps();
expect(createTaskLogTool(deps, "FN-1").name).toBe("fn_task_log");
expect(createArtifactListTool(deps).name).toBe("fn_artifact_list");
expect(createWorkflowListTool(deps).name).toBe("fn_workflow_list");
expect(createTaskPromoteTool(deps, "FN-1").name).toBe("fn_task_promote");
expect(createTraitListTool().name).toBe("fn_trait_list");
});
it("artifact register anchors at worktree and defaults task id", () => {
const deps = makeDeps();
const tool = createArtifactRegisterTool(deps, "executor", "FN-9", "/wt");
expect(tool.name).toBe("fn_artifact_register");
});
});

83
packages/engine/src/executor/__tests__/worktree-create-binders.test.ts Normal file
View File

@@ -0,0 +1,83 @@
/**
* FNXC:CodeOrganization 2026-08-04-02:05:
* Characterization for bindTryCreateWorktree / bindHandleWorktreeConflict (U4).
* Default-fills optional allowSibling/settings the same way the former inline
* façade lambdas did, so multi-site create/conflict wiring cannot drift.
*/
import { describe, expect, it, vi } from "vitest";
import {
bindHandleWorktreeConflict,
bindTryCreateWorktree,
} from "../worktree-create-binders.js";
import {
BRANCH_CONFLICT_TRIPWIRE_THRESHOLD,
COMPLETED_TASK_WATCHDOG_MS,
MAX_AUTO_RECOVERY_ATTEMPTS,
MAX_WORKFLOW_STEP_RETRIES,
MAX_WORKTREE_RETRIES,
WORKFLOW_RERUN_WATCHDOG_MS,
WORKTREE_RETRY_DELAYS,
} from "../executor-constants.js";
describe("worktree-create-binders", () => {
it("fills allowSiblingBranchRename=false and settings={} when omitted on tryCreate", async () => {
const tryCreateWorktree = vi.fn(async () => ({ path: "/wt", branch: "fusion/x" }));
const bound = bindTryCreateWorktree({ tryCreateWorktree });
await bound("fusion/x", "/wt", "FN-1", "origin/main", 2, 1);
expect(tryCreateWorktree).toHaveBeenCalledWith(
"fusion/x",
"/wt",
"FN-1",
"origin/main",
2,
1,
false,
{},
);
});
it("preserves explicit allowSibling and settings on tryCreate", async () => {
const tryCreateWorktree = vi.fn(async () => ({ path: "/wt", branch: "fusion/x" }));
const bound = bindTryCreateWorktree({ tryCreateWorktree });
const settings = { worktreesDir: "/custom" };
await bound("fusion/x", "/wt", "FN-1", undefined, 0, 0, true, settings);
expect(tryCreateWorktree).toHaveBeenCalledWith(
"fusion/x",
"/wt",
"FN-1",
undefined,
0,
0,
true,
settings,
);
});
it("fills defaults on handleWorktreeConflict the same way", async () => {
const handleWorktreeConflict = vi.fn(async () => null);
const bound = bindHandleWorktreeConflict({ handleWorktreeConflict });
await bound("/conflict", "fusion/x", "/wt", "FN-1", "main", 1);
expect(handleWorktreeConflict).toHaveBeenCalledWith(
"/conflict",
"fusion/x",
"/wt",
"FN-1",
"main",
1,
false,
{},
);
});
});
describe("executor-constants", () => {
it("keeps the historical tuning values used by TaskExecutor facades", () => {
expect(MAX_WORKFLOW_STEP_RETRIES).toBe(3);
expect(COMPLETED_TASK_WATCHDOG_MS).toBe(60_000);
expect(WORKFLOW_RERUN_WATCHDOG_MS).toBe(15_000);
expect(MAX_WORKTREE_RETRIES).toBe(3);
expect([...WORKTREE_RETRY_DELAYS]).toEqual([100, 500, 1000]);
expect(MAX_AUTO_RECOVERY_ATTEMPTS).toBe(3);
expect(BRANCH_CONFLICT_TRIPWIRE_THRESHOLD).toBe(5);
});
});

62
packages/engine/src/executor/abort-all-in-flight.ts Normal file
View File

@@ -0,0 +1,62 @@
/**
* FNXC:CodeOrganization 2026-08-03-11:10:
* abortAllInFlight peeled from TaskExecutor (U4).
* Runtime shutdown / broad abort: every task surface + child sessions.
*/
import type { AgentSession } from "@earendil-works/pi-coding-agent";
import { executorLog } from "../logger.js";
export type AbortAllInFlightDeps = {
activeSessions: Map<string, unknown>;
activeStepExecutors: Map<string, unknown>;
activeWorkflowStepSessions: Map<string, unknown>;
activeConfiguredCommandControllers: Map<string, unknown>;
activeWorkflowGraphAbortControllers: Map<string, unknown>;
activeSubagentSessions: Map<string, unknown>;
activeCliTaskSessions: Map<string, unknown>;
childSessions: Map<string, AgentSession>;
awaitAbortInFlightTaskWork: (taskId: string, reason: string) => Promise<void>;
};
export async function abortAllInFlight(
deps: AbortAllInFlightDeps,
reason: string,
): Promise<void> {
const taskIds = new Set<string>([
...deps.activeSessions.keys(),
...deps.activeStepExecutors.keys(),
...deps.activeWorkflowStepSessions.keys(),
...deps.activeConfiguredCommandControllers.keys(),
...deps.activeWorkflowGraphAbortControllers.keys(),
...deps.activeSubagentSessions.keys(),
...deps.activeCliTaskSessions.keys(),
]);
for (const taskId of taskIds) {
try {
await deps.awaitAbortInFlightTaskWork(taskId, reason);
} catch (err) {
executorLog.warn(`abortAllInFlight: failed to abort task ${taskId} — ${reason}: ${err}`);
}
}
for (const [agentId, session] of deps.childSessions) {
try {
const sessionWithAbort = session as AgentSession & { abort?: () => Promise<void> };
if (typeof sessionWithAbort.abort === "function") {
await sessionWithAbort.abort();
}
} catch (err) {
executorLog.warn(`abortAllInFlight: failed to abort child session ${agentId} — ${reason}: ${err}`);
}
try {
session.dispose();
} catch (err) {
executorLog.warn(`abortAllInFlight: failed to dispose child session ${agentId} — ${reason}: ${err}`);
}
}
deps.childSessions.clear();
executorLog.log(`abortAllInFlight: aborted ${taskIds.size} task surface(s) — ${reason}`);
}

43
packages/engine/src/executor/abort-all-session-bash.ts Normal file
View File

@@ -0,0 +1,43 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:00:
* abortAllSessionBash peeled from TaskExecutor (U4).
*
* Abort the in-flight bash subprocess (if any) on every active agent session.
* Invoked at runtime shutdown so detached subprocess trees spawned by agent bash
* tools — including grandchildren like vitest workers — are killed via
* pi-coding-agent's killProcessTree. Without this, when the worker is killed those
* process groups are orphaned because they're detached. Sessions are not disposed
* here so any near-complete agent loop still has a chance to wrap up during the
* runtime's graceful drain window.
*/
import { executorLog } from "../logger.js";
export type AbortAllSessionBashDeps = {
activeSessions: Map<string, { session: { abortBash: () => void } }>;
childSessions: Map<string, { abortBash: () => void }>;
activeStepExecutors: Map<string, { abortAllSessionBash: () => void }>;
};
export function abortAllSessionBash(deps: AbortAllSessionBashDeps): void {
for (const [taskId, { session }] of deps.activeSessions) {
try {
session.abortBash();
} catch (err) {
executorLog.warn(`abortAllSessionBash: failed for task ${taskId}: ${err}`);
}
}
for (const [agentId, session] of deps.childSessions) {
try {
session.abortBash();
} catch (err) {
executorLog.warn(`abortAllSessionBash: failed for child agent ${agentId}: ${err}`);
}
}
for (const [taskId, stepExecutor] of deps.activeStepExecutors) {
try {
stepExecutor.abortAllSessionBash();
} catch (err) {
executorLog.warn(`abortAllSessionBash: failed for step executor ${taskId}: ${err}`);
}
}
}

58
packages/engine/src/executor/acquire-session-registry-path.ts Normal file
View File

@@ -0,0 +1,58 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:30:
* acquireSessionRegistryPath peeled from TaskExecutor (U4).
*
* FNXC:SessionContention 2026-07-25-21:30 (contention prevention at the registration seam):
* Every executor session registration goes through acquireActiveSessionPath instead of the raw
* registerPath, so a LEAKED entry owned by a task with no live session surface in this process is
* RECLAIMED rather than throwing at the newcomer. That closes the second contention class (a dead
* holder can never release, so waiting on it is waiting forever). A genuinely live holder still throws
* the typed error — that case is real serialization, and callers classify it as a retryable contention
* hold (SESSION_CONTENTION_HOLD_VALUE), never as a provider/model failure.
* The probe reports LIVE on any uncertainty: an unknown holder with a fresh entry is treated as live by
* the staleness floor, so the reclaim only ever fires on proven-dead, aged entries.
*/
import type { TaskStore } from "@fusion/core";
import {
ActiveSessionPathHeldByForeignTaskError,
acquireActiveSessionPath,
activeSessionRegistry,
executingTaskLock,
type ActiveSessionKind,
} from "../agents/active-session-registry.js";
import { executorLog } from "../logger.js";
import { generateSyntheticRunId } from "../util/run-audit.js";
export type AcquireSessionRegistryPathDeps = {
store: TaskStore;
hasLiveTaskSessionSurface: (taskId: string) => boolean;
};
export function acquireSessionRegistryPath(
deps: AcquireSessionRegistryPathDeps,
taskId: string,
registryPath: string,
kind: ActiveSessionKind,
ownerKey: string,
): void {
const outcome = acquireActiveSessionPath(activeSessionRegistry, registryPath, { taskId, kind, ownerKey }, {
holderLiveProbe: (holderTaskId) => deps.hasLiveTaskSessionSurface(holderTaskId) || executingTaskLock.has(holderTaskId),
});
if (outcome.action === "contended") {
throw new ActiveSessionPathHeldByForeignTaskError(registryPath, outcome.holderTaskId, taskId);
}
if (outcome.action === "reclaimed-stale-foreign") {
executorLog.warn(
`${taskId}: reclaimed a stale active-session entry on ${registryPath} from dead task ${outcome.holderTaskId} (idle ${outcome.ageMs}ms)`,
);
void deps.store.recordRunAuditEvent?.({
taskId,
agentId: "executor",
runId: generateSyntheticRunId("session-path-reclaim", taskId),
domain: "database",
mutationType: "session:reclaim-stale-foreign-path",
target: taskId,
metadata: { taskId, holderTaskId: outcome.holderTaskId, kind, ageMs: outcome.ageMs },
})?.catch?.(() => undefined);
}
}

148
packages/engine/src/executor/active-session-bookkeeping.ts Normal file
View File

@@ -0,0 +1,148 @@
/**
* FNXC:CodeOrganization 2026-08-03-18:00:
* set/delete active session, step-executor, and workflow-step session bookkeeping
* peeled from TaskExecutor (U4).
*
* FNXC:Workspace 2026-06-21-12:00 / 2026-06-24-15:45 (KTD2):
* Delete paths unregister EVERY held worktree path (or an explicit path) via the
* task-scoped sessionRegistryPath key so workspace browse-root synthetic keys
* are the ones cleared.
*/
import type { AgentSession } from "@earendil-works/pi-coding-agent";
import { activeSessionRegistry, type ActiveSessionKind } from "../agents/active-session-registry.js";
import type { StepSessionExecutor } from "../execution/step-session-executor.js";
import { sessionRegistryPath } from "./session-registry-path.js";
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- session state shape is executor-private
type ActiveExecutorSessionState = any;
export type ActiveSessionBookkeepingDeps = {
rootDir: string;
activeSessions: Map<string, ActiveExecutorSessionState>;
activeStepExecutors: Map<string, StepSessionExecutor>;
activeStepExecutorSeenSteeringIds: Map<string, Set<string>>;
activeWorkflowStepSessions: Map<string, AgentSession>;
activeWorkflowStepSessionSeenSteeringIds: Map<string, Set<string>>;
effectiveColumnAgentByTask: Map<string, unknown>;
graphRouting: Set<string>;
graphExecuteSelfRequeued: Set<string>;
getActiveWorktreePaths: (taskId: string) => string[];
acquireSessionRegistryPath: (
taskId: string,
registryPath: string,
kind: ActiveSessionKind,
ownerKey: string,
) => void;
};
export function setActiveSession(
deps: ActiveSessionBookkeepingDeps,
taskId: string,
sessionState: ActiveExecutorSessionState,
worktreePath: string,
): void {
deps.activeSessions.set(taskId, sessionState);
deps.acquireSessionRegistryPath(
taskId,
sessionRegistryPath(deps.rootDir, taskId, worktreePath),
"executor",
taskId,
);
}
export function markGraphExecuteSelfRequeued(
deps: ActiveSessionBookkeepingDeps,
taskId: string,
): void {
if (deps.graphRouting.has(taskId)) {
deps.graphExecuteSelfRequeued.add(taskId);
}
}
export function deleteActiveSession(
deps: ActiveSessionBookkeepingDeps,
taskId: string,
worktreePath?: string,
): void {
deps.activeSessions.delete(taskId);
// U5: drop the effective column-agent principal for this task's session.
deps.effectiveColumnAgentByTask.delete(taskId);
// FNXC:Workspace 2026-06-21-12:00: KTD2 — when no explicit path is given, unregister EVERY worktree path the task holds (a workspace task holds N sub-repo paths); single-repo tasks resolve a one-element set.
const resolvedWorktreePaths = worktreePath ? [worktreePath] : deps.getActiveWorktreePaths(taskId);
for (const path of resolvedWorktreePaths) {
// FNXC:Workspace 2026-06-24-15:45: map through sessionRegistryPath so the task-scoped synthetic
// session key registered for the shared workspace browse-root is the one we unregister (the
// in-memory Set holds the REAL root). Non-workspace/sub-repo paths pass through unchanged.
activeSessionRegistry.unregisterPath(sessionRegistryPath(deps.rootDir, taskId, path));
}
}
export function setActiveStepExecutor(
deps: ActiveSessionBookkeepingDeps,
taskId: string,
stepExecutor: StepSessionExecutor,
worktreePath: string,
seenSteeringIds = new Set<string>(),
): void {
deps.activeStepExecutors.set(taskId, stepExecutor);
deps.activeStepExecutorSeenSteeringIds.set(taskId, seenSteeringIds);
deps.acquireSessionRegistryPath(
taskId,
sessionRegistryPath(deps.rootDir, taskId, worktreePath),
"step-session",
`${taskId}#step-session`,
);
}
export function deleteActiveStepExecutor(
deps: ActiveSessionBookkeepingDeps,
taskId: string,
worktreePath?: string,
): void {
deps.activeStepExecutors.delete(taskId);
deps.activeStepExecutorSeenSteeringIds.delete(taskId);
// U5: drop the effective column-agent principal for this task's step session.
deps.effectiveColumnAgentByTask.delete(taskId);
// FNXC:Workspace 2026-06-21-12:00: KTD2 — unregister every held worktree path (Set), not one.
const resolvedWorktreePaths = worktreePath ? [worktreePath] : deps.getActiveWorktreePaths(taskId);
for (const path of resolvedWorktreePaths) {
// FNXC:Workspace 2026-06-24-15:45: map through sessionRegistryPath so the task-scoped synthetic
// session key registered for the shared workspace browse-root is the one we unregister (the
// in-memory Set holds the REAL root). Non-workspace/sub-repo paths pass through unchanged.
activeSessionRegistry.unregisterPath(sessionRegistryPath(deps.rootDir, taskId, path));
}
}
export function setActiveWorkflowStepSession(
deps: ActiveSessionBookkeepingDeps,
taskId: string,
session: AgentSession,
worktreePath: string,
seenSteeringIds = new Set<string>(),
): void {
deps.activeWorkflowStepSessions.set(taskId, session);
deps.activeWorkflowStepSessionSeenSteeringIds.set(taskId, seenSteeringIds);
deps.acquireSessionRegistryPath(
taskId,
sessionRegistryPath(deps.rootDir, taskId, worktreePath),
"workflow-step",
`${taskId}#workflow-step`,
);
}
export function deleteActiveWorkflowStepSession(
deps: ActiveSessionBookkeepingDeps,
taskId: string,
worktreePath?: string,
): void {
deps.activeWorkflowStepSessions.delete(taskId);
deps.activeWorkflowStepSessionSeenSteeringIds.delete(taskId);
// FNXC:Workspace 2026-06-21-12:00: KTD2 — unregister every held worktree path (Set), not one.
const resolvedWorktreePaths = worktreePath ? [worktreePath] : deps.getActiveWorktreePaths(taskId);
for (const path of resolvedWorktreePaths) {
// FNXC:Workspace 2026-06-24-15:45: map through sessionRegistryPath so the task-scoped synthetic
// session key registered for the shared workspace browse-root is the one we unregister (the
// in-memory Set holds the REAL root). Non-workspace/sub-repo paths pass through unchanged.
activeSessionRegistry.unregisterPath(sessionRegistryPath(deps.rootDir, taskId, path));
}
}

27
packages/engine/src/executor/active-worktrees.ts Normal file
View File

@@ -0,0 +1,27 @@
/**
* FNXC:CodeOrganization 2026-08-03-18:00:
* activeWorktrees helpers peeled from TaskExecutor (U4).
*
* FNXC:Workspace 2026-06-21-12:00:
* activeWorktrees tracks paths a task currently holds as a SET (N sub-repos in
* workspace mode; one-element set for single-repo). Membership semantics keep
* the single-repo path byte-for-byte unchanged (KTD2).
*/
export function addActiveWorktree(
activeWorktrees: Map<string, Set<string>>,
taskId: string,
worktreePath: string,
): void {
const set = activeWorktrees.get(taskId) ?? new Set<string>();
set.add(worktreePath);
activeWorktrees.set(taskId, set);
}
export function getActiveWorktreePaths(
activeWorktrees: Map<string, Set<string>>,
taskId: string,
): string[] {
const set = activeWorktrees.get(taskId);
return set ? Array.from(set) : [];
}

63
packages/engine/src/executor/adopt-column-agent-for-node.ts Normal file
View File

@@ -0,0 +1,63 @@
/**
* FNXC:CodeOrganization 2026-08-03-11:30:
* adoptColumnAgentForNode peeled from TaskExecutor (U4).
* Resolve column-agent model/persona for a graph node (best-effort R8 fallback).
*/
import type { AgentStore, TaskDetail, TaskStore, WorkflowColumnAgent, WorkflowIrNode } from "@fusion/core";
import { executorLog } from "../logger.js";
import type { EngineRunContext } from "../util/run-audit.js";
import { buildAgentPersona } from "./agent-binding-pure.js";
export type AdoptColumnAgentForNodeDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
agentStore?: AgentStore | null;
};
export async function adoptColumnAgentForNode(
deps: AdoptColumnAgentForNodeDeps,
node: WorkflowIrNode,
live: TaskDetail,
columnAgentId: string,
mode: WorkflowColumnAgent["mode"] | undefined,
): Promise<{ modelProvider?: string; modelId?: string; persona?: string } | undefined> {
try {
const agent = await deps.agentStore?.getAgent(columnAgentId);
if (!agent) {
await deps.store.logEntry(
live.id,
`Workflow node '${node.id}': column agent '${columnAgentId}' not found — falling back to node/default resolution`,
undefined,
deps.getRunContextFor(live.id),
);
return undefined;
}
const rc = (agent.runtimeConfig ?? {}) as { executorProvider?: string; executorModelId?: string };
await deps.store.logEntry(
live.id,
`Workflow node '${node.id}': running as column agent '${columnAgentId}' (${mode})`,
undefined,
deps.getRunContextFor(live.id),
);
return {
modelProvider: rc.executorProvider,
modelId: rc.executorModelId,
persona: buildAgentPersona(agent),
};
} catch {
// Agent lookup is best-effort; fall back to node/default resolution (R8).
// A secondary logEntry failure (DB locked / mid-recovery) must NOT propagate
// out of this error handler and escalate the node to a hard failure.
try {
await deps.store.logEntry(
live.id,
`Workflow node '${node.id}': column agent '${columnAgentId}' lookup failed — falling back to node/default resolution`,
undefined,
deps.getRunContextFor(live.id),
);
} catch (logErr: unknown) {
executorLog.warn(`${live.id}: failed to log column-agent lookup failure: ${logErr instanceof Error ? logErr.message : String(logErr)}`);
}
return undefined;
}
}

30
packages/engine/src/executor/agent-binding-pure.ts Normal file
View File

@@ -0,0 +1,30 @@
/**
* FNXC:CodeOrganization 2026-08-03-13:35:
* Pure agent/task binding helpers peeled from TaskExecutor (U4).
*/
import type { Agent, EffectiveAgentInput, Task } from "@fusion/core";
/**
* Extract the task's own agent/model fields for effective-agent resolution.
* Centralizes the previously-duplicated extraction so call sites share one normalized idiom.
*/
export function extractOwnSettings(
task: Pick<Task, "assignedAgentId" | "modelProvider" | "modelId">,
): Pick<EffectiveAgentInput, "ownAgentId" | "ownModelProvider" | "ownModelId"> {
const ownAgentId = typeof task.assignedAgentId === "string" && task.assignedAgentId.trim()
? task.assignedAgentId.trim()
: undefined;
const ownModelComplete = Boolean(task.modelProvider && task.modelId);
return {
ownAgentId,
ownModelProvider: ownModelComplete ? task.modelProvider : undefined,
ownModelId: ownModelComplete ? task.modelId : undefined,
};
}
export function buildAgentPersona(agent: Agent): string | undefined {
const parts = [agent.soul, agent.instructionsText]
.map((p) => (typeof p === "string" ? p.trim() : ""))
.filter((p) => p.length > 0);
return parts.length > 0 ? parts.join("\n\n") : undefined;
}

247
packages/engine/src/executor/attempt-executor-verification-fix.ts Normal file
View File

@@ -0,0 +1,247 @@
/**
* FNXC:CodeOrganization 2026-08-03-12:55:
* attemptExecutorVerificationFix peeled from TaskExecutor (U4).
*
* Spawns a dedicated coding session to repair failing deterministic test/build
* verification mid-execution, then re-runs full verification. Mirrors the merger
* in-merge verification-fix pattern.
*
* FNXC:SessionRouting 2026-06-24-11:20:
* Propagate task id so verification-fix requests share session affinity.
*
* FNXC:PluginSkills 2026-07-12-00:00:
* Verification-fix sessions inherit plugin skill body dirs from task skill context.
*/
import type { Settings, Task, TaskStore } from "@fusion/core";
import { resolveExecutorFallbackModel, resolvePersistAgentThinkingLog } from "@fusion/core";
import { AgentLogger } from "../agents/agent-logger.js";
import {
createResolvedAgentSession,
resolveExecutorSessionModel,
resolveExecutorFallbackThinkingLevel,
resolveExecutorThinkingLevel,
} from "../agents/agent-session-helpers.js";
import { buildSessionSkillContext } from "../cli-runtime/session-skill-context.js";
import { accumulateSessionTokenUsage } from "../execution/session-token-usage.js";
import { VERIFICATION_LOG_MAX_CHARS } from "../execution/verification-utils.js";
import { withRateLimitRetry } from "../errors/rate-limit-retry.js";
import { describeModel, promptWithFallback } from "../pi.js";
import { executorLog } from "../logger.js";
import { createRunAuditor, type EngineRunContext } from "../util/run-audit.js";
import type { PluginRunner } from "../plugins/plugin-runner.js";
import type { AgentStore } from "@fusion/core";
export type AttemptExecutorVerificationFixDeps = {
store: TaskStore;
agentStore?: AgentStore | null;
pluginRunner?: PluginRunner;
onAgentText?: ConstructorParameters<typeof AgentLogger>[0]["onAgentText"];
onAgentTool?: ConstructorParameters<typeof AgentLogger>[0]["onAgentTool"];
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
getAssignedAgentRuntimeConfig: (agentId: string | null | undefined) => Promise<Record<string, unknown> | undefined>;
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- MCP map shape owned by session helpers
resolveMcpServers: (agentId?: string | null) => Promise<any>;
runExecutorDeterministicVerification: (
task: Task,
worktreePath: string,
settings: Settings,
extraEnv?: NodeJS.ProcessEnv,
) => Promise<{ allPassed: boolean }>;
};
/**
* Attempt to fix verification failures by spawning a dedicated AI fix agent.
* Follows the pattern established by the merger's attemptInMergeVerificationFix.
* Returns true if verification passes after the fix attempt, false otherwise.
*/
export async function attemptExecutorVerificationFix(
deps: AttemptExecutorVerificationFixDeps,
task: Task,
worktreePath: string,
failureContext: {
command: string;
exitCode: number | null;
output: string;
type: "test" | "build";
},
settings: Settings,
retryNumber: number,
maxRetries: number,
extraEnv?: NodeJS.ProcessEnv,
): Promise<boolean> {
try {
executorLog.log(`${task.id}: spawning executor verification fix agent (attempt ${retryNumber}/${maxRetries})`);
const logger = new AgentLogger({
store: deps.store,
taskId: task.id,
agent: "executor",
persistAgentToolOutput: settings.persistAgentToolOutput,
// Executor sessions are task-scoped ephemeral workers.
persistAgentThinkingLog: resolvePersistAgentThinkingLog(settings, { ephemeral: true }),
onAgentText: deps.onAgentText,
onAgentTool: deps.onAgentTool,
});
// Build skill selection context
let skillContext: Awaited<ReturnType<typeof buildSessionSkillContext>> | undefined;
if (deps.agentStore) {
try {
skillContext = await buildSessionSkillContext({
agentStore: deps.agentStore,
task,
sessionPurpose: "executor",
projectRootDir: worktreePath,
pluginRunner: deps.pluginRunner,
});
} catch {
// Graceful fallback - no skill selection
}
}
// Resolve model using the executor's model hierarchy
const assignedRuntimeConfig = await deps.getAssignedAgentRuntimeConfig(task.assignedAgentId);
const executorSessionModel = resolveExecutorSessionModel(
task.modelProvider,
task.modelId,
settings,
assignedRuntimeConfig,
task.credentialInstanceId,
);
const { provider: executorProvider, modelId: executorModelId } = executorSessionModel;
const executorFallback = resolveExecutorFallbackModel(settings);
// Create the fix agent session
const { session } = await createResolvedAgentSession({
sessionPurpose: "executor",
pluginRunner: deps.pluginRunner,
cwd: worktreePath, // Run in the task's worktree
systemPrompt: `You are a verification fix agent running during task execution in a worktree.
All step-session steps completed successfully but the deterministic verification command failed. Your job is to fix the failing code directly in the working directory.
## Scope
Only fix what is required to make the failing verification pass.
Do not refactor, rename broadly, or make opportunistic improvements.
## Rules
1. Read the error output carefully to understand what is failing before editing anything
2. Before assuming a code fix is needed, check whether the failure is caused by stale/missing build artifacts in a sibling workspace package — typical signatures: \`Failed to resolve import "./X.js"\` pointing into another package's \`dist/\`, \`Cannot find module\`, or \`ERR_MODULE_NOT_FOUND\` referencing a workspace-internal path. In that case, rebuild the affected package(s) (e.g. \`pnpm --filter <pkg> build\`, or \`pnpm --filter "<scope>/*" build\` for a group) and re-run verification before editing source files.
3. Make targeted fixes to the failing code path
4. After fixing, run the verification command to confirm the fix works
5. Do NOT make any git commits — just fix the code
6. You MAY modify any files needed to make the verification pass, including files unrelated to this task's original change. Pre-existing build/test breakage is in scope: fix it. Prefer the smallest change that makes verification green.
7. If you cannot fix the issue within scope, explain why and what evidence indicates a deeper/root problem`,
tools: "coding",
onText: logger.onText,
onThinking: logger.onThinking,
onToolStart: logger.onToolStart,
onToolEnd: logger.onToolEnd,
defaultProvider: executorProvider,
defaultModelId: executorModelId,
...(executorSessionModel.credentialInstanceId ? { credentialInstanceId: executorSessionModel.credentialInstanceId } : {}),
fallbackProvider: executorFallback.provider,
fallbackModelId: executorFallback.modelId,
fallbackThinkingLevel: resolveExecutorFallbackThinkingLevel(task.thinkingLevel, settings),
defaultThinkingLevel: resolveExecutorThinkingLevel(task.thinkingLevel, settings),
runAuditor: createRunAuditor(deps.store, deps.getRunContextFor(task.id)),
settings,
taskEnv: extraEnv,
mcpServers: await deps.resolveMcpServers(undefined),
// FNXC:SessionRouting 2026-06-24-11:20:
// #1675: propagate task id so verification-fix requests carry the same
// X-Session-Id/X-Session-Affinity as the primary session.
taskId: task.id,
// FNXC:PluginSkills 2026-07-12-00:00: Verification-fix sessions share task skill selection; include plugin skill body dirs so fixes can use plugin-authored guidance.
...(skillContext?.skillSelectionContext ? { skillSelection: skillContext.skillSelectionContext } : {}),
...(skillContext && skillContext.additionalSkillPaths.length > 0 ? { additionalSkillPaths: skillContext.additionalSkillPaths } : {}),
});
await deps.store.logEntry(
task.id,
`Executor verification fix agent started (model: ${describeModel(session)}, attempt ${retryNumber}/${maxRetries})`,
undefined,
deps.getRunContextFor(task.id),
);
await deps.store.appendAgentLog(
task.id,
`Fix agent started (model: ${describeModel(session)}, attempt ${retryNumber}/${maxRetries})`,
"status",
undefined,
"executor",
);
try {
// Build the fix prompt
const fixPrompt = `Fix the failing ${failureContext.type} verification for task ${task.id}.
## Failed command
Command: \`${failureContext.command}\`
Exit code: ${failureContext.exitCode}
## Error output
${failureContext.output.slice(0, VERIFICATION_LOG_MAX_CHARS)}
## Instructions
1. Read the error output and identify the root cause
2. Make targeted fixes to resolve the failure
3. Run the verification command \`${failureContext.command}\` to confirm your fix works
4. If the fix doesn't work, try a different approach
5. Do NOT make any git commits`;
// Run the agent with rate limit retry
await withRateLimitRetry(async () => {
await promptWithFallback(session, fixPrompt);
}, {
onRetry: (attempt, delayMs, error) => {
const delaySec = Math.round(delayMs / 1000);
executorLog.warn(`⏳ ${task.id} executor fix agent rate limited — retry ${attempt} in ${delaySec}s: ${error.message}`);
},
});
await accumulateSessionTokenUsage(deps.store, task.id, session, {
agentId: task.assignedAgentId ?? undefined,
role: "executor",
});
// Re-run full deterministic verification (test AND build) after the fix attempt
executorLog.log(`${task.id}: re-running deterministic verification after fix attempt ${retryNumber}/${maxRetries}`);
await deps.store.logEntry(
task.id,
`Re-running deterministic verification (attempt ${retryNumber}/${maxRetries})`,
undefined,
deps.getRunContextFor(task.id),
);
await deps.store.appendAgentLog(
task.id,
`Re-running verification (attempt ${retryNumber}/${maxRetries})`,
"status",
undefined,
"executor",
);
const reRunResult = await deps.runExecutorDeterministicVerification(task, worktreePath, settings, extraEnv);
return reRunResult.allPassed;
} finally {
await logger.flush();
session.dispose();
}
} catch (err: unknown) {
const errorMessage = err instanceof Error ? err.message : String(err);
executorLog.warn(`${task.id}: executor verification fix agent error: ${errorMessage}`);
await deps.store.logEntry(
task.id,
`Executor verification fix agent encountered an error`,
errorMessage,
deps.getRunContextFor(task.id),
);
await deps.store.appendAgentLog(
task.id,
"Fix agent encountered an error",
"tool_error",
errorMessage,
"executor",
);
return false;
}
}

186
packages/engine/src/executor/await-abort-in-flight.ts Normal file
View File

@@ -0,0 +1,186 @@
/**
* FNXC:CodeOrganization 2026-08-03-11:00:
* awaitAbortInFlightTaskWork peeled from TaskExecutor (U4).
* Hard-cancel / pause abort: claim surfaces synchronously, then abort/dispose.
*
* FNXC:WorkflowLifecycle 2026-07-26-11:20:
* KB-PROV: Stamp provenance the caller reported (hard-cancel vs engine-abort), not a blanket hard-cancel.
*
* FNXC:WorkflowExecution 2026-07-19-01:30:
* U5d — no completion-interceptor cleanup; graph-owned signal is call-scoped.
*/
import type { AgentSession } from "@earendil-works/pi-coding-agent";
import { executorLog } from "../logger.js";
import type { PausedAbortProvenance } from "./paused-abort-provenance.js";
export type AwaitAbortInFlightTaskWorkDeps = {
userCanceledTaskIds: Set<string>;
markPausedAborted: (taskId: string, provenance: PausedAbortProvenance, source: string) => void;
untrackStuckTask: (taskId: string) => void;
clearWorkflowRerunWatchdog: (taskId: string) => void;
clearCompletedTaskWatchdog: (taskId: string) => void;
processWideGraphRouting: Set<string>;
activeSessions: Map<string, { session: AgentSession }>;
deleteActiveSession: (taskId: string) => void;
activeStepExecutors: Map<string, {
terminateAllSessions(): Promise<void>;
abortAllSessionBash?: () => void;
}>;
deleteActiveStepExecutor: (taskId: string) => void;
activeWorkflowStepSessions: Map<string, AgentSession>;
deleteActiveWorkflowStepSession: (taskId: string) => void;
activeConfiguredCommandControllers: Map<string, Set<AbortController>>;
activeWorkflowGraphAbortControllers: Map<string, AbortController>;
activeSubagentSessions: { has(taskId: string): boolean };
disposeSubagentsForTask: (taskId: string, reason: string) => void;
activeCliTaskSessions: Map<string, { kill(reason?: string): Promise<void> }>;
loopRecoveryState: Map<string, unknown>;
stuckAborted: Map<string, unknown>;
safeLogEntry: (taskId: string, message: string) => void;
};
export async function awaitAbortInFlightTaskWork(
deps: AwaitAbortInFlightTaskWorkDeps,
taskId: string,
reason: string,
options: { userCanceled?: boolean } = {},
): Promise<void> {
let hadActiveSurface = false;
const abortedSurfaces: string[] = [];
if (options.userCanceled) {
deps.userCanceledTaskIds.add(taskId);
}
/*
FNXC:WorkflowLifecycle 2026-07-26-11:20:
KB-PROV: Stamp the provenance the caller actually reported instead of a blanket `hard-cancel`. `options.userCanceled` is already the truthful operator-intent signal every caller computes (`source === "user"`, soft-delete, the registered move disposer), so derive the label from it: operator withdrawal keeps `hard-cancel`, everything else is an `engine-abort`. Without this, the FN-8596 engine rerun bounce told the operator `provenance=hard-cancel` for work the engine itself re-dispatched, and any future consumer branching on `hard-cancel` would read an engine bounce as an operator withdrawal. Behaviour is unchanged: `userPaused` is still never set by engine rebounds, and the downstream classifiers accept both labels via `isGenericAbortProvenance()`.
*/
deps.markPausedAborted(taskId, options.userCanceled ? "hard-cancel" : "engine-abort", `abort-in-flight:${reason}`);
deps.untrackStuckTask(taskId);
deps.clearWorkflowRerunWatchdog(taskId);
deps.clearCompletedTaskWatchdog(taskId);
// Defensive graph-interpreter cleanup: a pause/abort mid-graph must not leave a
// stale routing claim behind. The graph runner's own finally blocks also clear
// this; double-delete is harmless.
// FNXC:WorkflowExecution 2026-07-19-01:30: U5d — there is no completion-interceptor
// entry to clear anymore. The graph-owned signal is now a call-scoped callback
// parameter (see GraphCompletionCallback), so it cannot outlive the run that created
// it and needs no abort-time cleanup.
deps.processWideGraphRouting.delete(taskId);
// FN-5256: claim each surface synchronously BEFORE awaiting any async
// abort. Without this, two concurrent disposal calls for the same task
// (e.g., task:moved-away followed immediately by task:deleted) both pass
// the `has(taskId)` guards and double-call abort/dispose.
const claimedSession = deps.activeSessions.get(taskId);
if (claimedSession) {
hadActiveSurface = true;
abortedSurfaces.push("agent-session");
deps.deleteActiveSession(taskId);
}
const claimedStepExecutor = deps.activeStepExecutors.get(taskId);
if (claimedStepExecutor) {
hadActiveSurface = true;
abortedSurfaces.push("step-session");
deps.deleteActiveStepExecutor(taskId);
}
const claimedWorkflowSession = deps.activeWorkflowStepSessions.get(taskId);
if (claimedWorkflowSession) {
hadActiveSurface = true;
abortedSurfaces.push("workflow-step-session");
deps.deleteActiveWorkflowStepSession(taskId);
}
const claimedConfiguredCommands = deps.activeConfiguredCommandControllers.get(taskId);
if (claimedConfiguredCommands && claimedConfiguredCommands.size > 0) {
hadActiveSurface = true;
abortedSurfaces.push(`configured-command:${claimedConfiguredCommands.size}`);
deps.activeConfiguredCommandControllers.delete(taskId);
for (const controller of claimedConfiguredCommands) {
controller.abort();
}
}
const claimedWorkflowGraphController = deps.activeWorkflowGraphAbortControllers.get(taskId);
if (claimedWorkflowGraphController) {
hadActiveSurface = true;
abortedSurfaces.push("workflow-graph");
deps.activeWorkflowGraphAbortControllers.delete(taskId);
claimedWorkflowGraphController.abort();
}
const claimedSubagents = deps.activeSubagentSessions.has(taskId);
if (claimedSubagents) {
hadActiveSurface = true;
abortedSurfaces.push("subagent-session");
deps.disposeSubagentsForTask(taskId, reason);
}
// CLI Agent Executor (U7): a cli-agent session is a hard-cancel surface like
// any API session. Claim it synchronously, then SIGKILL the PTY and mark
// `killed` (never resume-eligible) — the same dispose/abort contract API
// sessions honor. moveTask(in-progress→todo) routes here (AGENTS.md hard
// cancel), so this is what guarantees the PTY tree is reaped on column exit.
const claimedCliSession = deps.activeCliTaskSessions.get(taskId);
if (claimedCliSession) {
hadActiveSurface = true;
abortedSurfaces.push("cli-agent-session");
deps.activeCliTaskSessions.delete(taskId);
}
if (claimedSession) {
const { session } = claimedSession;
const sessionWithAbort = session as AgentSession & { abort?: () => Promise<void> };
if (typeof sessionWithAbort.abort === "function") {
await sessionWithAbort.abort().catch((err) => {
executorLog.warn(`Failed to abort agent session for ${taskId}: ${err}`);
});
}
try {
session.dispose();
} catch (err) {
executorLog.warn(`Failed to dispose agent session for ${taskId}: ${err}`);
}
}
if (claimedStepExecutor) {
const stepExecutorWithAbort = claimedStepExecutor as { abortAllSessionBash?: () => void; terminateAllSessions(): Promise<void> };
if (typeof stepExecutorWithAbort.abortAllSessionBash === "function") {
try {
stepExecutorWithAbort.abortAllSessionBash();
} catch (err) {
executorLog.warn(`Failed to abort step-session bash for ${taskId}: ${err}`);
}
}
await claimedStepExecutor.terminateAllSessions().catch((err) =>
executorLog.error(`Failed to terminate step sessions for ${taskId}:`, err),
);
}
if (claimedWorkflowSession) {
const sessionWithAbort = claimedWorkflowSession as AgentSession & { abort?: () => Promise<void> };
if (typeof sessionWithAbort.abort === "function") {
await sessionWithAbort.abort().catch((err) => {
executorLog.warn(`Failed to abort workflow step session for ${taskId}: ${err}`);
});
}
try {
claimedWorkflowSession.dispose();
} catch (err) {
executorLog.warn(`Failed to dispose workflow step session for ${taskId}: ${err}`);
}
}
if (claimedCliSession) {
await claimedCliSession.kill("killed").catch((err) => {
executorLog.warn(`Failed to kill CLI agent session for ${taskId}: ${err}`);
});
}
deps.loopRecoveryState.delete(taskId);
deps.stuckAborted.delete(taskId);
if (hadActiveSurface) {
executorLog.log(`${taskId}: awaited abort of in-flight work — ${reason}`);
deps.safeLogEntry(
taskId,
`Pause abort cleanup completed: reason=${reason}; surfaces=${abortedSurfaces.join(", ") || "none"}`,
);
}
}

108
packages/engine/src/executor/await-input-node.ts Normal file
View File

@@ -0,0 +1,108 @@
/**
* FNXC:CodeOrganization 2026-08-03-19:50:
* runAwaitInputNode peeled from TaskExecutor (U4).
*
* FNXC:WorkflowAskUser 2026-07-05-00:00:
* FN-7579's `ask-user` node is the first-class discoverable surface over this
* SAME park/resume plumbing that a `prompt` node with `config.awaitInput: true`
* already used. Question resolution order: `config.question` (the ask-user
* node's dedicated field) first, then `config.prompt` (back-compat with the
* original awaitInput alias), then the shared default string. Nothing below
* this line branches on node.kind — both node kinds share one pause/resume
* contract so behavior can never drift between them.
*/
import type { TaskDetail, TaskStore, WorkflowIrNode } from "@fusion/core";
import type { EngineRunContext } from "../util/run-audit.js";
export type AwaitInputNodeResult = {
outcome: "success" | "failure";
value: string;
contextPatch?: Record<string, string>;
};
export type AwaitInputNodeDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
};
export async function runAwaitInputNode(
deps: AwaitInputNodeDeps,
node: WorkflowIrNode,
live: TaskDetail,
): Promise<AwaitInputNodeResult> {
const question = typeof node.config?.question === "string" && node.config.question.trim()
? node.config.question.trim()
: typeof node.config?.prompt === "string" && node.config.prompt.trim()
? node.config.prompt.trim()
: "This workflow is waiting for your input.";
const marker = `workflow-input:${node.id}`;
const steering = Array.isArray(live.steeringComments) ? live.steeringComments : [];
// Resume only when THIS node previously paused the task (its marker is on
// pausedReason). A pre-existing steering comment (e.g. one added at task
// creation) must never short-circuit the pause on the node's first run —
// otherwise the node consumes a stale comment and never asks the user.
const pausedReason = live.pausedReason ?? "";
const pausedByThisNode = pausedReason.startsWith(marker);
if (!live.paused && pausedByThisNode) {
// Correlate the reply to THIS pause: the marker embeds a watermark
// (`${marker}@${pauseEpochMs}: …`) recorded when the node paused. Only
// count steering comments created at/after that watermark as the answer,
// so an unpause-without-reply can't consume a comment that predates the
// pause. The watermark is epoch milliseconds (colon-free) so it never
// collides with the `:` that separates the marker from the question, nor
// with the dashboard's colon-delimited question parser.
const watermark = (() => {
const m = pausedReason.slice(marker.length).match(/^@(\d+)/);
const t = m ? Number(m[1]) : NaN;
return Number.isFinite(t) ? t : undefined;
})();
const replies = watermark === undefined
? steering
: steering.filter((c) => {
const created = Date.parse((c as { createdAt?: string }).createdAt ?? "");
return Number.isFinite(created) ? created >= watermark : false;
});
if (replies.length > 0) {
// Input has arrived (user replied and unpaused): consume the latest
// post-pause comment and clear this node's marker so a future fresh
// visit re-asks instead of silently consuming a stale comment.
const latest = replies[replies.length - 1] as { text?: string; comment?: string };
const answer = (latest?.text ?? latest?.comment ?? "").toString();
await deps.store.updateTask(live.id, { status: null, pausedReason: null }, deps.getRunContextFor(live.id));
await deps.store.logEntry(live.id, `Workflow input received for node '${node.id}'`, undefined, deps.getRunContextFor(live.id));
return { outcome: "success", value: "input-received", contextPatch: { [`input:${node.id}`]: answer } };
}
// Unpaused but no post-pause reply yet — re-park below and keep waiting.
}
await deps.store.logEntry(live.id, `Workflow paused for user input: ${question}`, undefined, deps.getRunContextFor(live.id));
await deps.store.updateTask(
live.id,
{ status: "awaiting-user-input", paused: true, pausedReason: `${marker}@${Date.now()}: ${question}` },
deps.getRunContextFor(live.id),
);
// Failure outcome ends the walk; handleGraphFailure leaves paused tasks
// untouched, so the task sits awaiting input until the user responds.
return { outcome: "failure", value: "awaiting-user-input" };
}
/**
* FNXC:CodeOrganization 2026-08-03-19:55:
* pauseForCliApproval peeled with await-input-node (U4). Dashboard approve + unpause resumes.
*/
export async function pauseForCliApproval(
deps: AwaitInputNodeDeps,
node: WorkflowIrNode,
live: TaskDetail,
command: string,
): Promise<AwaitInputNodeResult> {
const marker = `workflow-cli-approval:${node.id}`;
await deps.store.logEntry(live.id, `Workflow paused for CLI command approval: ${command}`, undefined, deps.getRunContextFor(live.id));
await deps.store.updateTask(
live.id,
{ status: "awaiting-cli-approval", paused: true, pausedReason: `${marker}: ${command}` },
deps.getRunContextFor(live.id),
);
return { outcome: "failure", value: "awaiting-cli-approval" };
}

55
packages/engine/src/executor/await-input-parse.ts Normal file
View File

@@ -0,0 +1,55 @@
/**
* FNXC:CodeOrganization 2026-08-03-07:20:
* Await-input parsers peeled from executor.ts (wave18 / U4 Slice A).
*/
/**
* Sentinel a skill running in a Fusion workflow step emits when it needs to ask
* the user a blocking question (it has no synchronous question tool — see the CE
* skills' "Running inside Fusion" sections). The executor detects this in the
* step's output and parks the task `awaiting-user-input`, reusing the same
* pause/resume machinery as an `awaitInput` node (U6). Returns the question text,
* or null when no well-formed sentinel is present.
*/
export function parseAwaitInputSentinel(output: string | undefined): string | null {
if (!output) return null;
const m = output.match(/===FUSION_AWAIT_INPUT===\s*([\s\S]*?)\s*===END_FUSION_AWAIT_INPUT===/);
const question = m?.[1]?.trim();
return question ? question : null;
}
const USER_QUESTION_TOOL_NAMES = new Set([
"askuserquestion",
"ask_user",
"ask_followup_question",
"request_user_input",
"elicit",
"ask_question",
"fn_ask_question",
]);
/**
* Normalize a question-tool invocation into the same durable await-input
* contract used by skill sentinels. Some runtimes expose an interactive
* question tool even though Fusion workflow-step sessions have no synchronous
* listener; detecting the call at the session event boundary prevents the
* task from continuing after the unanswered question is rendered.
*/
export function parseAwaitInputQuestionToolCall(
toolName: string,
args: Record<string, unknown> | undefined,
): string | null {
if (!USER_QUESTION_TOOL_NAMES.has(toolName.trim().toLowerCase()) || !args) return null;
const records = Array.isArray(args.questions) ? args.questions : [args];
const questions = records.flatMap((value) => {
if (!value || typeof value !== "object" || Array.isArray(value)) return [];
const record = value as Record<string, unknown>;
const question = [record.question, record.prompt, record.message, record.text, record.title]
.find((candidate): candidate is string => typeof candidate === "string" && candidate.trim().length > 0)
?.trim();
return question ? [question] : [];
});
return questions.length > 0 ? questions.join("\n\n") : null;
}

61
packages/engine/src/executor/block-outer-dispatch-when-ephemeral-disabled.ts Normal file
View File

@@ -0,0 +1,61 @@
/**
* FNXC:CodeOrganization 2026-08-03-13:50:
* blockOuterDispatchWhenEphemeralDisabled peeled from TaskExecutor (U4).
*
* FNXC:EphemeralAgents 2026-07-01-00:00:
* `ephemeralAgentsEnabled: false` means "never spawn short-lived executor-FN-XXXX workers; only permanent agents run work" (see types.ts ephemeralAgentsEnabled). The legacy spawn refusal lives in EphemeralWorkerManager.onTaskStart (ephemeral-worker-manager.ts), but that runs as a fire-and-forget bookkeeping callback AFTER execution has already begun, so it cannot stop a run. The workflow-engine dispatch paths (executeWorkflowGraph, maybeDispatchWorkflowWorkEngine) execute tasks in-process without ever consulting the toggle. Any task that reaches execute() without a permanent assignment via a non-scheduler path (resume-after-restart, heartbeat re-entry, mission/autopilot, work-engine claim) therefore ran despite the operator disabling ephemeral agents.
*
* This guard is the executor's last line of defense, mirroring the scheduler cutover gate and the spawn refusal. It runs once at the top of the outer dispatch — before all three workflow paths — so a single check covers every workflow dispatch entry point. A task explicitly assigned to a permanent (non-ephemeral) agent is exactly how ephemeral-off mode is meant to run, so those are allowed through; everything else is re-queued for the scheduler to auto-assign a permanent agent or hold.
*/
import type { Task, TaskStore, AgentStore } from "@fusion/core";
import { isEphemeralAgent } from "@fusion/core";
import type { EngineRunContext } from "../util/run-audit.js";
import { executorLog } from "../logger.js";
import { resolveReboundColumnFor } from "./lifecycle-columns.js";
export type BlockOuterDispatchWhenEphemeralDisabledDeps = {
store: TaskStore;
agentStore?: AgentStore | null;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
};
export async function blockOuterDispatchWhenEphemeralDisabled(
deps: BlockOuterDispatchWhenEphemeralDisabledDeps,
task: Task,
): Promise<boolean> {
const settings = await deps.store.getSettings();
if (settings.ephemeralAgentsEnabled !== false) return false;
// A permanent (non-ephemeral) assignment is the sanctioned executor when
// ephemeral workers are off. `assignedAgentId` is only ever set by permanent
// assignment — default ephemeral mode never sets it — so when we cannot
// resolve the agent (no agentStore) we trust the presence of the id and allow
// the run rather than starving a legitimately-assigned task.
const assignedId = task.assignedAgentId?.trim();
if (assignedId) {
if (!deps.agentStore) return false;
const agent = await deps.agentStore.getAgent(assignedId).catch(() => null);
if (agent && !isEphemeralAgent(agent)) return false;
}
const liveTask = (await deps.store.getTask(task.id).catch(() => null)) ?? task;
const reboundColumn = await resolveReboundColumnFor(deps.store, liveTask.id);
if (liveTask.column !== reboundColumn) {
await deps.store.moveTask(liveTask.id, reboundColumn, {
preserveProgress: true,
preserveWorktree: true,
preserveResumeState: true,
moveSource: "engine",
recoveryRehome: true,
});
}
await deps.store.updateTask(liveTask.id, { status: "queued" }, deps.getRunContextFor(liveTask.id));
await deps.store.logEntry(
liveTask.id,
"queued — ephemeral agents disabled; no permanent executor assigned",
"Executor pre-dispatch ephemeral gate blocked workflow/authoritative execution.",
deps.getRunContextFor(liveTask.id),
);
executorLog.log(`${liveTask.id}: executor dispatch blocked — ephemeralAgentsEnabled=false and no permanent agent assigned`);
return true;
}

86
packages/engine/src/executor/bootstrap-misbinding-recovery.ts Normal file
View File

@@ -0,0 +1,86 @@
/**
* FNXC:CodeOrganization 2026-08-03-20:15:
* tryBootstrapMisbindingRecovery peeled from TaskExecutor (U4).
* Re-anchor branches that were bootstrapped onto wrong base with zero own commits.
*/
import type { Task, TaskStore } from "@fusion/core";
import {
BranchCrossContaminationError,
classifyBootstrapMisbinding,
reanchorBranchToBase,
} from "../execution/branch-conflicts.js";
import { classifyTaskWorktree } from "../worktree/worktree-pool.js";
import { formatError } from "../logger.js";
import type { EngineRunContext, RunAuditor } from "../util/run-audit.js";
import { resolveReboundColumnFor } from "./lifecycle-columns.js";
export type BootstrapMisbindingRecoveryDeps = {
rootDir: string;
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
markGraphExecuteSelfRequeued: (taskId: string) => void;
};
export async function tryBootstrapMisbindingRecovery(
deps: BootstrapMisbindingRecoveryDeps,
task: Task,
contamination: BranchCrossContaminationError,
audit: RunAuditor,
): Promise<boolean> {
const bootstrap = await classifyBootstrapMisbinding({
repoDir: deps.rootDir,
branchName: contamination.branchName,
baseSha: contamination.baseSha,
taskId: task.id,
foreignCommits: contamination.foreignCommits,
});
if (!bootstrap.isBootstrapMisbinding) {
return false;
}
const worktreePath = task.worktree;
const worktreeClassification = worktreePath
? await classifyTaskWorktree(deps.rootDir, worktreePath)
: { ok: false as const };
if (!worktreePath || !worktreeClassification.ok) {
await deps.store.logEntry(task.id, `[recovery] bootstrap misbinding detected but worktree unavailable for re-anchor: ${worktreePath ?? "none"}`, undefined, deps.getRunContextFor(task.id));
return false;
}
await deps.store.logEntry(task.id, `[recovery] bootstrap-time branch misbinding detected on ${contamination.branchName}: 0 own commits, re-anchoring to ${contamination.baseSha}`, undefined, deps.getRunContextFor(task.id));
try {
const reanchor = await reanchorBranchToBase({
repoDir: deps.rootDir,
worktreePath,
branchName: contamination.branchName,
baseSha: contamination.baseSha,
taskId: task.id,
});
await audit.git({
type: "branch:reanchor",
target: contamination.branchName,
metadata: {
taskId: task.id,
baseSha: contamination.baseSha,
previousTipSha: reanchor.previousTipSha,
newTipSha: reanchor.newTipSha,
trigger: "bootstrap-misbinding",
},
});
await deps.store.updateTask(task.id, {
recoveryRetryCount: null,
nextRecoveryAt: null,
error: null,
paused: false,
pausedReason: null,
});
deps.markGraphExecuteSelfRequeued(task.id);
await deps.store.moveTask(task.id, await resolveReboundColumnFor(deps.store, task.id), { preserveResumeState: false, preserveWorktree: true });
return true;
} catch (error) {
await deps.store.logEntry(task.id, `[recovery] bootstrap re-anchor failed; falling back to contamination safety path: ${formatError(error)}`, undefined, deps.getRunContextFor(task.id));
return false;
}
}

38
packages/engine/src/executor/branch-conflict-format.ts Normal file
View File

@@ -0,0 +1,38 @@
/**
* FNXC:CodeOrganization 2026-08-03-13:35:
* Pure branch-conflict log formatters peeled from TaskExecutor (U4).
*/
import type { BranchConflictError } from "../execution/branch-conflicts.js";
export function formatBranchConflictLifecycleLog(_taskId: string, error: BranchConflictError): string {
const strandedSummary = error.strandedCommits.length > 0
? error.strandedCommits.map((commit) => `${commit.sha.slice(0, 12)} ${commit.subject}`).join("; ")
: "none";
const recommendation = "Resolve the local branch/worktree conflict with git tooling (inspect/reclaim or discard) before retrying.";
return [
`Branch conflict: ${error.branchName} is already checked out at ${error.conflictingWorktreePath}`,
`Existing tip: ${error.existingTipSha}`,
`Stranded commits since ${error.startPoint}: ${strandedSummary}`,
recommendation,
].join("\n");
}
export function formatBranchConflictAgentLog(_taskId: string, error: BranchConflictError): string {
const lines = [
`branch=${error.branchName}`,
`worktree=${error.conflictingWorktreePath}`,
`existingTipSha=${error.existingTipSha}`,
`startPoint=${error.startPoint}`,
];
if (error.strandedCommits.length > 0) {
lines.push(
...error.strandedCommits.map((commit) => `stranded=${commit.sha.slice(0, 12)} ${commit.subject}`),
);
} else {
lines.push("stranded=none");
}
lines.push(
`recommendation=Resolve the local branch/worktree conflict with git tooling (inspect/reclaim or discard) before retrying.`,
);
return lines.join("\n");
}

196
packages/engine/src/executor/build-action-gate-context.ts Normal file
View File

@@ -0,0 +1,196 @@
/**
* FNXC:CodeOrganization 2026-08-03-09:55:
* buildActionGateContext peeled from TaskExecutor (U4).
*
* FNXC:AgentPermissions 2026-07-02-00:00:
* FN-7413 requires task-scoped runtime gates for permanent identity agents, stored ephemeral agents, and fallback executor-FN task workers. Use a stable synthetic actor for fallback workers so category/exact-tool rules and approval dedupe keys apply even when no agent row exists.
*
* FNXC:ApprovalRedemption 2026-07-26-14:30:
* decidedAt lets resolveGateOutcome apply the approval-grant TTL at redemption.
*
* FNXC:ApprovalHold 2026-07-09-00:10:
* FN-7736: stamp the canonical AWAITING_APPROVAL_PAUSE_REASON on the
* task (not just the agent) so recovery/oversight code can durably
* recognize this hold via isTaskBlockedOnApproval -- previously only
* `paused: true` was set with no reason, which self-healing's
* autoReboundPausedScopeDecay could rebound before the operator ever
* decided.
*
* FNXC:ApprovalResume 2026-07-12-17:02:
* MAIN-008: record the approval-specific suspension before pauseTask emits its
* task:updated event so every abort branch can preserve the in-progress row
* for a deterministic fresh resume. Clear the mark if pauseTask fails so a
* failed pause does not leave a sticky suspended marker.
*
* FNXC:AgentGating 2026-07-05-00:10:
* FN-7608: pauseTask() alone does not stop the in-flight LLM turn -- make
* wait-for-approval a REAL session-suspending state by aborting the in-flight
* session fire-and-forget (await would deadlock inside the tool call).
*
* FNXC:ApprovalRedemption 2026-07-26-14:35:
* ownership guard — an agent must not be able to burn another agent's approval by id.
*/
import type { Agent, AgentStore, TaskStore } from "@fusion/core";
import {
AWAITING_APPROVAL_PAUSE_REASON,
ApprovalRequestStore,
isEphemeralAgent,
resolveEffectiveAgentPermissionPolicy,
resolveWorkflowIrForTask,
} from "@fusion/core";
import type { AgentActionGateContext } from "../agents/agent-action-gate.js";
import { isCurrentReviewerNodeOverride } from "../agents/workflow-agent-router.js";
import { executorLog } from "../logger.js";
import type { EngineRunContext } from "../util/run-audit.js";
import type { ActiveWorkflowAuthority } from "./workflow-principal-before-node.js";
export type BuildActionGateContextDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
approvalSuspended: Set<string>;
awaitAbortInFlightTaskWork: (taskId: string, reason: string) => Promise<void>;
agentStore?: AgentStore | null;
approvalRequestStore: ApprovalRequestStore;
activeWorkflowAuthorities: Map<string, ActiveWorkflowAuthority>;
activeWorkflowGraphAbortControllers: Map<string, AbortController>;
};
export function buildActionGateContext(
deps: BuildActionGateContextDeps,
taskId: string | undefined,
agent: Agent | null | undefined,
projectDefaultPolicy?: {
rules?: Partial<import("@fusion/core").AgentPermissionPolicy["rules"]>;
toolRules?: import("@fusion/core").AgentPermissionPolicyToolRules;
},
): AgentActionGateContext | undefined {
const actorId = agent?.id ?? `executor-${taskId ?? "unknown"}`;
const actorName = agent?.name ?? `Task worker ${taskId ?? "unknown"}`;
const isEphemeral = !agent || isEphemeralAgent(agent);
const policy = resolveEffectiveAgentPermissionPolicy(agent?.permissionPolicy, projectDefaultPolicy);
const workflowAuthority = taskId ? deps.activeWorkflowAuthorities.get(taskId) : undefined;
const authorityMatchesActor = workflowAuthority?.agentId === actorId;
return {
agentId: actorId,
agentName: actorName,
isEphemeral,
taskId,
runId: authorityMatchesActor ? workflowAuthority!.runId : taskId ? deps.getRunContextFor(taskId)?.runId : undefined,
permissionPolicy: policy,
...(authorityMatchesActor ? {
workflowAuthority: {
projectId: deps.store.getRootDir(),
taskId: workflowAuthority!.taskId,
runId: workflowAuthority!.runId,
workItemId: workflowAuthority!.workItemId,
nodeInstanceId: workflowAuthority!.nodeInstanceId,
principalAgentId: workflowAuthority!.agentId,
kind: workflowAuthority!.kind,
isLive: async () => {
const current = deps.activeWorkflowAuthorities.get(workflowAuthority!.taskId);
if (current !== workflowAuthority
|| !deps.activeWorkflowGraphAbortControllers.has(workflowAuthority!.taskId)
|| deps.activeWorkflowGraphAbortControllers.get(workflowAuthority!.taskId)!.signal.aborted) {
return false;
}
if (!workflowAuthority!.requiresDurableFence) return true;
/*
* FNXC:WorkflowAgentRouting 2026-08-07-04:31:
* Tool authority for a claimed continuation survives only while its exact leased
* work item still names this principal and node.
*/
const items = await deps.store.listWorkflowWorkItemsForTask(workflowAuthority!.taskId);
const item = items.find((candidate) => candidate.id === workflowAuthority!.workItemId);
if (item?.state !== "running"
|| item.principalAgentId !== workflowAuthority!.agentId
|| item.nodeInstanceId !== workflowAuthority!.nodeInstanceId
|| !item.leaseOwner
|| (item.leaseExpiresAt !== null && Date.parse(item.leaseExpiresAt) <= Date.now())) {
return false;
}
const liveTask = await deps.store.getTask(workflowAuthority!.taskId);
if (workflowAuthority!.kind === "task-assignee") {
return liveTask.assignedAgentId === workflowAuthority!.agentId;
}
/*
* FNXC:WorkflowAgentRouting 2026-08-07-04:56:
* A reviewer override is authority for one exact IR node attempt, not a
* task-wide reviewer grant. Re-read the selected workflow definition at
* every gated call so an operator removing or changing the node override
* immediately fences an already-running session.
*/
if (workflowAuthority!.kind === "review-node-override") {
const liveIr = await resolveWorkflowIrForTask(deps.store, workflowAuthority!.taskId);
return isCurrentReviewerNodeOverride(
liveIr,
workflowAuthority!.nodeInstanceId,
workflowAuthority!.agentId,
);
}
return false;
},
},
} : {}),
createApprovalRequest: async (decision, args) => await deps.approvalRequestStore.create({
requester: {
actorId,
actorType: "agent",
actorName,
},
taskId,
runId: taskId ? deps.getRunContextFor(taskId)?.runId : undefined,
targetAction: {
category: decision.category === "exempt" ? "command_execution" : decision.category,
action: decision.operation,
summary: decision.summary,
resourceType: decision.resourceType,
resourceId: decision.resourceId ?? "",
context: {
...decision.metadata,
approvalDedupeKey: decision.approvalDedupeKey,
toolName: decision.toolName,
toolArgs: args,
},
},
}),
findApprovalByDedupeKey: async (dedupeKey) => {
const latest = await deps.approvalRequestStore.findLatestByDedupeKey({ requesterActorId: actorId, taskId, dedupeKey });
return latest ? { id: latest.id, status: latest.status, decidedAt: latest.decidedAt } : null;
},
findPendingApprovalByDedupeKey: async (dedupeKey) => {
const latest = await deps.approvalRequestStore.findLatestByDedupeKey({ requesterActorId: actorId, taskId, dedupeKey });
return latest?.status === "pending" ? { id: latest.id } : null;
},
pauseForApproval: async ({ approvalRequestId, decision }) => {
if (taskId) {
deps.approvalSuspended.add(taskId);
try {
await deps.store.pauseTask(taskId, true, deps.getRunContextFor(taskId), { pausedByAgentId: actorId, pausedReason: AWAITING_APPROVAL_PAUSE_REASON });
} catch (error) {
deps.approvalSuspended.delete(taskId);
throw error;
}
await deps.store.logEntry(
taskId,
`Approval required for ${decision.toolName}. Request ${approvalRequestId} created; task and agent paused awaiting decision.`,
undefined,
deps.getRunContextFor(taskId),
);
void deps.awaitAbortInFlightTaskWork(taskId, `awaiting-approval:${decision.toolName}`).catch((error) => {
executorLog.warn(`${taskId}: failed to suspend in-flight session while awaiting approval: ${error instanceof Error ? error.message : String(error)}`);
});
}
if (agent && deps.agentStore) {
await deps.agentStore.updateAgentState(agent.id, "paused");
await deps.agentStore.updateAgent(agent.id, { pauseReason: "awaiting-approval" });
}
},
markApprovalCompleted: async (approvalRequestId) => {
await deps.approvalRequestStore.markCompleted(approvalRequestId, {
actor: { actorId, actorType: "agent", actorName },
note: "Tool executed after approval",
expectedRequesterActorId: actorId,
});
},
};
}

32
packages/engine/src/executor/build-branch-persistence.ts Normal file
View File

@@ -0,0 +1,32 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:30:
* buildBranchPersistence peeled from TaskExecutor (U4).
*
* FNXC:PostgresOnlyDataAccess 2026-07-16-12:40:
* Store methods are async (PostgreSQL routing); persistence interfaces await them.
*/
import type { TaskStore } from "@fusion/core";
import type {
WorkflowBranchPersistence,
WorkflowBranchRunState,
} from "../workflows/workflow-graph-branches.js";
export type BuildBranchPersistenceDeps = {
store: TaskStore;
};
export function buildBranchPersistence(
deps: BuildBranchPersistenceDeps,
): WorkflowBranchPersistence | undefined {
const store = deps.store as unknown as {
saveWorkflowRunBranch?: (state: WorkflowBranchRunState) => void | Promise<void>;
loadWorkflowRunBranches?: (taskId: string, runId: string) => WorkflowBranchRunState[] | Promise<WorkflowBranchRunState[]>;
clearWorkflowRunBranches?: (taskId: string, keepRunId: string) => void | Promise<void>;
};
if (typeof store.saveWorkflowRunBranch !== "function") return undefined;
return {
saveBranchState: (state) => store.saveWorkflowRunBranch?.(state),
loadBranchStates: async (taskId, runId) => (await store.loadWorkflowRunBranches?.(taskId, runId)) ?? [],
clearStaleBranchStates: (taskId, keepRunId) => store.clearWorkflowRunBranches?.(taskId, keepRunId),
};
}

57
packages/engine/src/executor/build-code-node-runner.ts Normal file
View File

@@ -0,0 +1,57 @@
/**
* FNXC:CodeOrganization 2026-08-03-12:00:
* buildCodeNodeRunner peeled from TaskExecutor (U4).
* Wires createCodeNodeRunner with task store artifact/cwd/custom-field adapters.
*/
import type { TaskStore } from "@fusion/core";
import { executorLog } from "../logger.js";
import { createCodeNodeRunner } from "../execution/code-node-runner.js";
import type { CodeNodeRunner } from "../workflows/workflow-node-handlers.js";
export type BuildCodeNodeRunnerDeps = {
store: TaskStore;
rootDir: string;
readTaskArtifact: (taskId: string, key: string) => Promise<string | undefined | null>;
};
export function buildCodeNodeRunner(deps: BuildCodeNodeRunnerDeps): CodeNodeRunner {
return createCodeNodeRunner({
resolveCwd: async (task): Promise<string> => {
try {
return (await deps.store.getTask(task.id)).worktree || deps.rootDir;
} catch {
return deps.rootDir;
}
},
readArtifacts: async (task): Promise<Record<string, string>> => {
const out: Record<string, string> = {};
try {
const docs = await deps.store.getTaskDocuments(task.id);
for (const doc of docs) out[doc.key] = doc.content;
} catch {
// No documents — pass an empty artifact map.
}
// Surface PROMPT.md from the task prompt when not already a document
// (shared artifact-read fallback — FIX 7).
if (out["PROMPT.md"] === undefined) {
const prompt = await deps.readTaskArtifact(task.id, "PROMPT.md");
if (typeof prompt === "string") out["PROMPT.md"] = prompt;
}
return out;
},
writeCustomFields: async (task, patch) => {
if (typeof deps.store.updateTaskCustomFields !== "function") {
return {
ok: false as const,
rejection: { code: "no-fields-defined" as const, fieldId: "", detail: "custom fields unsupported by store" },
};
}
const result = await deps.store.updateTaskCustomFields(task.id, patch);
return result.ok ? { ok: true as const } : { ok: false as const, rejection: result.rejection };
},
audit: (reason, detail) => {
executorLog.warn(`[code-node] ${reason}: ${detail}`);
},
});
}

34
packages/engine/src/executor/build-column-boundary-hooks.ts Normal file
View File

@@ -0,0 +1,34 @@
/**
* FNXC:CodeOrganization 2026-08-03-18:00:
* buildColumnBoundaryHooks peeled from TaskExecutor (U4).
*
* FNXC:WorkflowColumnBoundary 2026-07-27-16:40 (PR #2475 review, P2):
* Wiring lives in createExecutorColumnBoundaryHooks; this only threads Executor
* state (in-flight graph-move marker + logger).
*/
import type { Task, TaskStore } from "@fusion/core";
import type { WorkflowColumnBoundaryHooks } from "../workflows/workflow-graph-task-runner.js";
import { createExecutorColumnBoundaryHooks } from "../workflow-column-boundary-hooks.js";
import { executorLog } from "../logger.js";
export type BuildColumnBoundaryHooksDeps = {
store: TaskStore;
workflowLifecycleMovesInFlight: Set<string>;
};
export function buildColumnBoundaryHooks(
deps: BuildColumnBoundaryHooksDeps,
task: Pick<Task, "id">,
workflowRunId?: string,
): WorkflowColumnBoundaryHooks {
return createExecutorColumnBoundaryHooks({
store: deps.store,
task,
workflowRunId,
markMoveInFlight: (taskId) => deps.workflowLifecycleMovesInFlight.add(taskId),
clearMoveInFlight: (taskId) => deps.workflowLifecycleMovesInFlight.delete(taskId),
onWarn: (message, detail) => {
executorLog.debug(`[workflow-column-boundary] ${task.id}: ${message} ${JSON.stringify(detail)}`);
},
});
}

304
packages/engine/src/executor/build-foreach-worktree-deps.ts Normal file
View File

@@ -0,0 +1,304 @@
/**
* FNXC:CodeOrganization 2026-08-03-12:20:
* buildForeachWorktreeDeps peeled from TaskExecutor (U4).
*
* FNXC:WorkflowForeach 2026-08-03-12:20 (U10 / KTD-11):
* Build worktree-isolation + ordered-integration + parallel-scheduling deps for a
* graph-owned foreach. Per-instance worktrees branch off the task main tip;
* integration rebases each branch in step order; projection flips done-iff-integrated.
* Best-effort: a git failure routes the foreach to a clean failure rather than crashing the run.
*/
import type { Task, TaskStore } from "@fusion/core";
import { exec } from "node:child_process";
import { promisify } from "node:util";
import { getConflictedFiles } from "../merger.js";
import {
canonicalStepInstanceBranchName,
resolveTaskWorkingBranch,
} from "../worktree/worktree-names.js";
import { resolveTaskWorktreePath } from "../worktree/worktree-paths.js";
import type {
IntegrationAttemptResult,
IntegrationGitOps,
IntegrationProjection,
} from "../execution/step-integration.js";
import type { WorkflowStepInstanceState } from "../workflows/workflow-graph-foreach.js";
import { executorLog } from "../logger.js";
const execAsync = promisify(exec);
export type BuildForeachWorktreeDepsBag = {
store: TaskStore;
rootDir: string;
createWorktree: (
branch: string,
path: string,
taskId: string,
startPoint?: string,
) => Promise<{ path: string; branch: string }>;
semaphoreAvailableCount: () => number;
};
export type ForeachWorktreeDeps = {
allocateInstanceWorktree: (
stepIndex: number,
base: string | undefined,
) => Promise<{ worktreePath: string; branchName: string }>;
resolveIntegrationBase: () => Promise<string | undefined>;
integrationGitOps: IntegrationGitOps;
integrationProjection: IntegrationProjection;
semaphoreAvailability: () => number;
resumeReconcile: (
pinned: number,
) => Promise<Array<{ stepIndex: number; disposition: "integrated" | "reintegrate" | "rerun"; branchName?: string }>>;
};
/**
* Build the worktree-isolation + ordered-integration + parallel-scheduling deps
* for a graph-owned foreach (KTD-11, U10). Returns the additive set the
* WorkflowGraphTaskRunner forwards to the foreach sub-walk:
*
* - `allocateInstanceWorktree(i, base)` — a per-instance worktree on a
* canonical `fusion/<task>-step-<i>` branch off `base` (the main tip),
* created via the existing `createWorktree` path (the file-scope guard the
* session machinery installs applies unchanged to anything the instance
* session commits in this worktree — we do NOT bypass it);
* - `resolveIntegrationBase()` — the task's main branch tip, re-read before each
* (re)allocation so a rework lands on the UPDATED base;
* - `integrationGitOps` — rebase the instance branch onto the main branch in
* the instance worktree (branch is checked out there), fast-forward main on
* success from the MAIN worktree; on conflict reuse merger.ts
* `getConflictedFiles` (NOT reimplemented) and abort the rebase so the next
* instance can integrate; `discardBranch` deletes the branch + frees the
* instance worktree (pool hygiene);
* - `integrationProjection` — projection-first ordering (KTD-7): `markStepDone`
* flips the step `done` via `updateStep(source:"graph")` (the dependency-order
* guard admits it), THEN `markInstanceIntegrated` flips the persisted row;
* - `semaphoreAvailability` — the live free-slot count so parallel scheduling
* clamps without hold-and-wait.
*
* Best-effort throughout: a git failure routes the foreach to a clean failure
* (parked for human review) rather than crashing the run.
*/
export function buildForeachWorktreeDeps(
deps: BuildForeachWorktreeDepsBag,
task: Task,
runId?: string,
): ForeachWorktreeDeps {
const taskId = task.id;
// Per-instance worktree paths, so discard can free them.
const instancePaths = new Map<number, string>();
const mainWorktree = async (): Promise<string> => {
try {
return (await deps.store.getTask(taskId)).worktree || deps.rootDir;
} catch {
return deps.rootDir;
}
};
const mainBranch = async (): Promise<string> => {
try {
const detail = await deps.store.getTask(taskId);
return resolveTaskWorkingBranch(detail);
} catch {
return resolveTaskWorkingBranch(task);
}
};
return {
resolveIntegrationBase: async (): Promise<string | undefined> => {
// The main branch tip (HEAD of the task's working branch in its worktree).
try {
const { stdout } = await execAsync("git rev-parse HEAD", { cwd: await mainWorktree() });
const sha = stdout.trim();
return sha.length > 0 ? sha : await mainBranch();
} catch {
return await mainBranch();
}
},
allocateInstanceWorktree: async (stepIndex, base): Promise<{ worktreePath: string; branchName: string }> => {
const branchName = canonicalStepInstanceBranchName(taskId, stepIndex);
const worktreePath = resolveTaskWorktreePath(
deps.rootDir,
undefined,
`${taskId.toLowerCase()}-step-${stepIndex}`,
);
// createWorktree installs the file-scope guard (session machinery,
// unchanged) and branches off `base` (the integration base / updated tip).
const created = await deps.createWorktree(branchName, worktreePath, taskId, base);
instancePaths.set(stepIndex, created.path);
return { worktreePath: created.path, branchName: created.branch };
},
integrationGitOps: {
integrate: async (branchName, stepIndex): Promise<IntegrationAttemptResult> => {
const cwd = await mainWorktree();
const target = await mainBranch();
// The instance branch is checked out in its OWN worktree, so the rebase
// (which checks out `branchName`) must run THERE — running it from the
// main worktree fails with "branch is already checked out in another
// worktree". The final fast-forward merge still runs from the main
// worktree (it only advances `target`, which is checked out there).
const instanceCwd = instancePaths.get(stepIndex) ?? cwd;
try {
// Rebase the instance branch onto the current main tip (in its own
// worktree), then ff main from the main worktree.
await execAsync(`git rebase ${target} ${branchName}`, { cwd: instanceCwd });
await execAsync(`git checkout ${target}`, { cwd });
await execAsync(`git merge --ff-only ${branchName}`, { cwd });
return { kind: "integrated", integratedAt: new Date().toISOString() };
} catch (err) {
// Conflict (or other rebase failure): classify via merger helper, abort.
// The rebase ran in the instance worktree, so conflicts live there and
// the abort must target that same cwd.
const conflictedFiles = await getConflictedFiles(instanceCwd);
try {
await execAsync("git rebase --abort", { cwd: instanceCwd });
} catch {
// best-effort; leave the worktree recoverable.
}
// Restore main checkout so the next instance integrates cleanly.
try {
await execAsync(`git checkout ${target}`, { cwd });
} catch {
// best-effort.
}
executorLog.warn(
`[step-integration] ${taskId} step ${stepIndex} branch ${branchName} conflict: ${err instanceof Error ? err.message : String(err)}`,
);
return { kind: "conflict", conflictedFiles };
}
},
discardBranch: async (branchName, stepIndex): Promise<void> => {
const cwd = await mainWorktree();
const path = instancePaths.get(stepIndex);
if (path) {
// Remove the instance worktree (pool hygiene). Best-effort; force so a
// dirty/conflicting tree is still cleaned up.
try {
await execAsync(`git worktree remove --force "${path}"`, { cwd: deps.rootDir });
} catch {
// best-effort cleanup.
}
instancePaths.delete(stepIndex);
}
// Delete the (now-merged or conflicting) branch.
try {
await execAsync(`git branch -D ${branchName}`, { cwd });
} catch {
// best-effort — the branch may already be gone.
}
},
},
integrationProjection: {
markStepDone: async (stepIndex): Promise<void> => {
// Projection-first (KTD-7): graph-source write relaxes the guard to
// dependency order; predecessors are integrated (done) by construction.
await deps.store.updateStep(taskId, stepIndex, "done", { source: "graph" });
},
markInstanceIntegrated: async (stepIndex, integratedAt, identity): Promise<void> => {
const store = deps.store as unknown as {
saveWorkflowRunStepInstanceAsync?: (state: WorkflowStepInstanceState) => Promise<void>;
loadWorkflowRunStepInstancesAsync?: (taskId: string, runId: string) => Promise<WorkflowStepInstanceState[]>;
saveWorkflowRunStepInstance?: (state: WorkflowStepInstanceState) => void;
loadWorkflowRunStepInstances?: (taskId: string, runId: string) => WorkflowStepInstanceState[];
};
if (typeof store.saveWorkflowRunStepInstanceAsync !== "function" && typeof store.saveWorkflowRunStepInstance !== "function") return;
// The upsert is keyed by (taskId, runId, foreachNodeId, stepIndex). The
// queue passes the REAL identity (the same runId + foreachNodeId the
// foreach sub-walk persisted the row under) so this FLIPS the existing
// row to completed/integratedAt instead of writing an orphan (FIX 1).
// Load the current row to preserve its fields (currentNodeId, baseline,
// reworkCount) we don't otherwise carry on the identity.
let existing: WorkflowStepInstanceState | undefined;
try {
const rows = await store.loadWorkflowRunStepInstancesAsync?.(taskId, identity.runId)
?? store.loadWorkflowRunStepInstances?.(taskId, identity.runId)
?? [];
existing = rows.find(
(r) => r.foreachNodeId === identity.foreachNodeId && r.stepIndex === stepIndex,
);
} catch {
// Best-effort read; fall back to a minimal flip below.
}
try {
await (store.saveWorkflowRunStepInstanceAsync?.({
...(existing ?? {}),
taskId,
runId: identity.runId,
foreachNodeId: identity.foreachNodeId,
stepIndex,
pinnedStepCount: identity.pinnedStepCount,
currentNodeId: existing?.currentNodeId ?? "",
status: "completed",
reworkCount: existing?.reworkCount ?? 0,
branchName: identity.branchName || canonicalStepInstanceBranchName(taskId, stepIndex),
integratedAt,
} as WorkflowStepInstanceState) ?? store.saveWorkflowRunStepInstance?.({
...(existing ?? {}),
taskId,
runId: identity.runId,
foreachNodeId: identity.foreachNodeId,
stepIndex,
pinnedStepCount: identity.pinnedStepCount,
currentNodeId: existing?.currentNodeId ?? "",
status: "completed",
reworkCount: existing?.reworkCount ?? 0,
branchName: identity.branchName || canonicalStepInstanceBranchName(taskId, stepIndex),
integratedAt,
} as WorkflowStepInstanceState));
} catch {
// Persistence is additive bookkeeping — never fail the integration.
}
},
},
semaphoreAvailability: (): number => deps.semaphoreAvailableCount(),
resumeReconcile: async (
pinned,
): Promise<Array<{ stepIndex: number; disposition: "integrated" | "reintegrate" | "rerun"; branchName?: string }>> => {
// Crash-resume reconciliation (KTD-11): reconcile each persisted instance
// row against branch existence. integrated → done; branch exists not
// integrated → re-enter the integration queue; branch missing → re-run.
// NOTE (handoff): this is the per-run resume seeding only; the full
// self-healing sweep across stale runs (recoverStaleTransitionPending
// analogue) is out of scope for U10.
const store = deps.store as unknown as {
loadWorkflowRunStepInstancesAsync?: (taskId: string, runId: string) => Promise<WorkflowStepInstanceState[]>;
loadWorkflowRunStepInstances?: (taskId: string, runId: string) => WorkflowStepInstanceState[];
};
if (typeof store.loadWorkflowRunStepInstancesAsync !== "function" && typeof store.loadWorkflowRunStepInstances !== "function") return [];
let rows: WorkflowStepInstanceState[] = [];
try {
// Load under the REAL run id (threaded) so resume actually sees the rows
// the sub-walk persisted; the legacy literal is the unthreaded fallback.
rows = await store.loadWorkflowRunStepInstancesAsync?.(taskId, runId ?? `${taskId}:run`)
?? store.loadWorkflowRunStepInstances?.(taskId, runId ?? `${taskId}:run`)
?? [];
} catch {
return [];
}
const cwd = await mainWorktree();
const out: Array<{ stepIndex: number; disposition: "integrated" | "reintegrate" | "rerun"; branchName?: string }> = [];
for (const row of rows) {
if (row.stepIndex < 0 || row.stepIndex >= pinned) continue;
if (row.status === "completed" || row.integratedAt) {
out.push({ stepIndex: row.stepIndex, disposition: "integrated" });
continue;
}
const branchName = row.branchName || canonicalStepInstanceBranchName(taskId, row.stepIndex);
let branchExists = false;
try {
await execAsync(`git rev-parse --verify --quiet ${branchName}`, { cwd });
branchExists = true;
} catch {
branchExists = false;
}
if (branchExists && row.status === "awaiting-integration") {
out.push({ stepIndex: row.stepIndex, disposition: "reintegrate", branchName });
} else {
out.push({ stepIndex: row.stepIndex, disposition: "rerun" });
}
}
return out;
},
};
}

43
packages/engine/src/executor/build-injected-runtime-env.ts Normal file
View File

@@ -0,0 +1,43 @@
/**
* FNXC:CodeOrganization 2026-08-03-20:15:
* buildInjectedRuntimeEnv peeled from TaskExecutor (U4).
*
* Build task-scoped runtime env carrying plugin-injected keys plus PATH contribution.
* Never mutates process.env globally — scoped env is threaded through taskEnv.
*/
import { delimiter } from "node:path";
export type BuildInjectedRuntimeEnvDeps = {
rootDir: string;
collectExecutorRuntimeEnv?: (input: {
taskId: string;
worktreePath: string;
rootDir: string;
branch: string | undefined;
}) => Promise<{ env?: NodeJS.ProcessEnv; pathPrepend?: string[] } | undefined | null> | undefined;
};
export async function buildInjectedRuntimeEnv(
deps: BuildInjectedRuntimeEnvDeps,
taskId: string,
worktreePath: string,
branch: string | undefined,
): Promise<{ env: NodeJS.ProcessEnv; injectedKeyCount: number; pathEntryCount: number }> {
const runtimeEnvContribution = await deps.collectExecutorRuntimeEnv?.({
taskId,
worktreePath,
rootDir: deps.rootDir,
branch,
});
const pathPrepend = runtimeEnvContribution?.pathPrepend ?? [];
const injectedEnv = runtimeEnvContribution?.env ?? {};
return {
env: {
...process.env,
...injectedEnv,
PATH: [...pathPrepend, process.env.PATH ?? ""].filter(Boolean).join(delimiter),
},
injectedKeyCount: Object.keys(injectedEnv).length,
pathEntryCount: pathPrepend.length,
};
}

53
packages/engine/src/executor/build-parse-steps-deps.ts Normal file
View File

@@ -0,0 +1,53 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:00:
* buildParseStepsDeps peeled from TaskExecutor (U4).
*
* Artifact/step-write deps bag for the parse-steps graph handler, including
* foreach expansion pin protection (KTD-3).
*/
import type { TaskStep, TaskStore } from "@fusion/core";
import type { ParseStepsHandlerDeps } from "../workflows/workflow-node-handlers.js";
import type { WorkflowStepInstanceState } from "../workflows/workflow-graph-foreach.js";
import { executorLog } from "../logger.js";
export type BuildParseStepsDepsDeps = {
store: TaskStore;
readTaskArtifact: (taskId: string, key: string) => Promise<string | undefined>;
};
export function buildParseStepsDeps(
deps: BuildParseStepsDepsDeps,
runId?: string,
): ParseStepsHandlerDeps {
return {
readArtifact: (task, key): Promise<string | undefined> => deps.readTaskArtifact(task.id, key),
writeSteps: async (task, steps: TaskStep[]): Promise<void> => {
await deps.store.updateTask(task.id, { steps });
},
hasExpandedForeach: async (task): Promise<boolean> => {
const store = deps.store as unknown as {
loadWorkflowRunStepInstancesAsync?: (taskId: string, runId: string) => Promise<WorkflowStepInstanceState[]>;
loadWorkflowRunStepInstances?: (taskId: string, runId: string) => WorkflowStepInstanceState[];
};
if (typeof store.loadWorkflowRunStepInstancesAsync !== "function" && typeof store.loadWorkflowRunStepInstances !== "function") return false;
try {
// Any persisted instance row for THIS run means a foreach has expanded —
// re-parsing would desynchronize the pinned instance set (KTD-3). Probe
// under the REAL run id (threaded from executeWorkflowGraph) so the
// pin protection actually fires; fall back to the legacy literal only when
// the run id was not threaded (older store / no definition).
const rows = await store.loadWorkflowRunStepInstancesAsync?.(task.id, runId ?? `${task.id}:run`)
?? store.loadWorkflowRunStepInstances?.(task.id, runId ?? `${task.id}:run`)
?? [];
return rows.length > 0;
} catch {
return false;
}
},
audit: (reason, detail) => {
// The detail string carries the task id (handler convention); emit on the
// engine log so the routable failure is auditable without a taskId arg.
executorLog.warn(`[parse-steps] ${reason}: ${detail}`);
},
};
}

103
packages/engine/src/executor/build-permanent-agent-gating-context.ts Normal file
View File

@@ -0,0 +1,103 @@
/**
* FNXC:CodeOrganization 2026-08-03-10:05:
* buildPermanentAgentGatingContext peeled from TaskExecutor (U4).
*
* FNXC:AgentGating 2026-07-05-00:00:
* FN-7609: operators approving a gated action need the real command/args,
* and a stateless heartbeat retrying the same command must reuse a single
* pending approval instead of minting duplicates.
*
* FNXC:AgentGating 2026-07-26-14:50:
* Audit finding (gate-path divergence): the permanent gate minted an
* approval request but never paused, so the agent kept its turn while
* "awaiting approval". Mirror the action gate's task-level hold (canonical
* AWAITING_APPROVAL_PAUSE_REASON + approvalSuspended marker). Session
* suspension is intentionally not wired here: the permanent gate only runs
* in lanes WITHOUT an actionGateContext, where no executor in-flight
* session surface exists to abort.
*/
import type { Agent, PermanentAgentGatingContext, TaskStore } from "@fusion/core";
import {
AWAITING_APPROVAL_PAUSE_REASON,
ApprovalRequestStore,
resolveEffectiveAgentPermissionPolicy,
} from "@fusion/core";
import { buildAgentGatedActionSummary } from "../agents/permanent-agent-gating.js";
import type { EngineRunContext } from "../util/run-audit.js";
export type BuildPermanentAgentGatingContextDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
approvalSuspended: Set<string>;
approvalRequestStore: ApprovalRequestStore;
};
export function buildPermanentAgentGatingContext(
deps: BuildPermanentAgentGatingContextDeps,
taskId: string | undefined,
agent: Agent | null | undefined,
projectDefaultPolicy?: {
rules?: Partial<import("@fusion/core").AgentPermissionPolicy["rules"]>;
toolRules?: import("@fusion/core").AgentPermissionPolicyToolRules;
},
): PermanentAgentGatingContext | undefined {
const actorId = agent?.id ?? `executor-${taskId ?? "unknown"}`;
const actorName = agent?.name ?? `Task worker ${taskId ?? "unknown"}`;
return {
permissionPolicy: resolveEffectiveAgentPermissionPolicy(agent?.permissionPolicy, projectDefaultPolicy),
requester: {
actorId,
actorType: "agent",
actorName,
},
taskId,
runId: taskId ? deps.getRunContextFor(taskId)?.runId : undefined,
createApprovalRequest: async ({ category, toolName, args, approvalDedupeKey }) => await deps.approvalRequestStore.create({
requester: {
actorId,
actorType: "agent",
actorName,
},
taskId,
runId: taskId ? deps.getRunContextFor(taskId)?.runId : undefined,
targetAction: {
category,
action: toolName,
summary: buildAgentGatedActionSummary(toolName, args),
resourceType: "tool",
resourceId: toolName,
context: {
toolName,
toolArgs: args,
source: "agent-gating",
...(approvalDedupeKey ? { approvalDedupeKey } : {}),
...(typeof (args as Record<string, unknown> | undefined)?.command === "string"
? { command: (args as Record<string, unknown>).command }
: {}),
...(typeof (args as Record<string, unknown> | undefined)?.cwd === "string"
? { cwd: (args as Record<string, unknown>).cwd }
: {}),
},
},
}),
findPendingApprovalRequest: async (dedupeKey) => {
const pending = await deps.approvalRequestStore.list({ status: "pending", requesterActorId: actorId, taskId, limit: 100 });
return pending.find((request) => request.targetAction.context?.approvalDedupeKey === dedupeKey) ?? null;
},
pauseForApproval: async ({ approvalRequestId, toolName }) => {
if (!taskId) return;
deps.approvalSuspended.add(taskId);
try {
await deps.store.pauseTask(taskId, true, deps.getRunContextFor(taskId), { pausedByAgentId: actorId, pausedReason: AWAITING_APPROVAL_PAUSE_REASON });
await deps.store.logEntry(
taskId,
`Approval required for ${toolName}. Request ${approvalRequestId} created; task paused awaiting decision.`,
);
} catch (error) {
deps.approvalSuspended.delete(taskId);
throw error;
}
},
};
}

39
packages/engine/src/executor/build-step-instance-persistence.ts Normal file
View File

@@ -0,0 +1,39 @@
/**
* FNXC:CodeOrganization 2026-08-03-14:15:
* buildStepInstancePersistence peeled from TaskExecutor (U4).
*
* FNXC:PostgresOnlyDataAccess 2026-07-16-12:40:
* Async store methods; persistence interface awaits Promise-returning impls.
*/
import type { TaskStore } from "@fusion/core";
import type {
WorkflowStepInstancePersistence,
WorkflowStepInstanceState,
} from "../workflows/workflow-graph-foreach.js";
export type BuildStepInstancePersistenceDeps = {
store: TaskStore;
};
export function buildStepInstancePersistence(
deps: BuildStepInstancePersistenceDeps,
): WorkflowStepInstancePersistence | undefined {
// FNXC:PostgresOnlyDataAccess 2026-07-16-12:40: async store methods; the
// persistence interface awaits Promise-returning impls.
const store = deps.store as unknown as {
saveWorkflowRunStepInstanceAsync?: (state: WorkflowStepInstanceState) => Promise<void>;
loadWorkflowRunStepInstancesAsync?: (taskId: string, runId: string) => Promise<WorkflowStepInstanceState[]>;
clearWorkflowRunStepInstancesAsync?: (taskId: string, keepRunId: string) => Promise<void>;
saveWorkflowRunStepInstance?: (state: WorkflowStepInstanceState) => void;
loadWorkflowRunStepInstances?: (taskId: string, runId: string) => WorkflowStepInstanceState[];
clearWorkflowRunStepInstances?: (taskId: string, keepRunId: string) => void;
};
if (typeof store.saveWorkflowRunStepInstanceAsync !== "function" && typeof store.saveWorkflowRunStepInstance !== "function") return undefined;
return {
saveInstanceState: (state) => store.saveWorkflowRunStepInstanceAsync?.(state) ?? store.saveWorkflowRunStepInstance?.(state),
loadInstanceStates: async (taskId, runId) =>
await store.loadWorkflowRunStepInstancesAsync?.(taskId, runId) ?? store.loadWorkflowRunStepInstances?.(taskId, runId) ?? [],
clearStaleInstanceStates: (taskId, keepRunId) =>
store.clearWorkflowRunStepInstancesAsync?.(taskId, keepRunId) ?? store.clearWorkflowRunStepInstances?.(taskId, keepRunId),
};
}

70
packages/engine/src/executor/cleanup-merge-state.ts Normal file
View File

@@ -0,0 +1,70 @@
/**
* FNXC:CodeOrganization 2026-08-03-09:25:
* cleanupMergeStateForReverification peeled from TaskExecutor (U4).
* Clears merge/status bookkeeping and reopens verification suffix steps for re-verification.
*/
import type { Task, TaskStore } from "@fusion/core";
import type { EngineRunContext } from "../util/run-audit.js";
import { isTaskWorkComplete } from "./task-predicates.js";
import { preservePreExecutionWorkflowStepResults } from "./workflow-step-satisfaction.js";
export type CleanupMergeStateDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
reopenLastStepForRevision: (
taskId: string,
task: Task,
) => Promise<{ index: number } | null | undefined | false | void>;
};
export async function cleanupMergeStateForReverification(
deps: CleanupMergeStateDeps,
task: Task,
logMessage: string,
options?: { preserveVerificationFailureCount?: boolean },
): Promise<Task> {
const preservedWorkflowStepResults = preservePreExecutionWorkflowStepResults(task);
await deps.store.updateTask(task.id, {
mergeDetails: null,
mergeRetries: 0,
status: null,
error: null,
verificationFailureCount: options?.preserveVerificationFailureCount ? task.verificationFailureCount ?? 0 : 0,
workflowStepResults: preservedWorkflowStepResults,
});
const refreshedTask = await deps.store.getTask(task.id);
const steps = refreshedTask.steps ?? [];
if (steps.length > 0) {
const allStepsComplete = isTaskWorkComplete(refreshedTask);
if (allStepsComplete) {
await deps.reopenLastStepForRevision(task.id, refreshedTask);
} else {
const resetIndexes = new Set<number>();
for (let i = 0; i < steps.length; i++) {
const name = steps[i].name.toLowerCase();
if (/testing|verification/.test(name) || /documentation|delivery/.test(name)) {
resetIndexes.add(i);
}
}
if (resetIndexes.size === 0) {
const reopened = await deps.reopenLastStepForRevision(task.id, refreshedTask);
if (reopened && typeof reopened === "object" && "index" in reopened) {
resetIndexes.add(reopened.index);
}
} else {
for (const index of resetIndexes) {
if (steps[index].status !== "pending") {
await deps.store.updateStep(task.id, index, "pending");
}
}
const earliestIndex = Math.min(...Array.from(resetIndexes));
await deps.store.updateTask(task.id, { currentStep: earliestIndex });
}
}
}
await deps.store.logEntry(task.id, logMessage, undefined, deps.getRunContextFor(task.id));
return deps.store.getTask(task.id);
}

60
packages/engine/src/executor/cleanup-task-worktree.ts Normal file
View File

@@ -0,0 +1,60 @@
/**
* FNXC:CodeOrganization 2026-08-03-15:40:
* TaskExecutor.cleanup peeled from TaskExecutor (U4).
*
* Drops in-memory active-worktree tracking and removes the single-repo worktree
* when no other task still needs it. Workspace roots are tracking-only (never removed).
*/
import type { TaskStore, WorkspaceConfig } from "@fusion/core";
import { findWorktreeUser } from "../merger.js";
import { RemovalReason } from "../worktree/worktree-pool.js";
import { executorLog } from "../logger.js";
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- mirror TaskExecutor method surface
type AnyFn = (...args: any[]) => any;
export type CleanupTaskWorktreeDeps = {
store: TaskStore;
workspaceConfig: WorkspaceConfig | null | undefined;
activeWorktrees: Map<string, Set<string>>;
getActiveWorktreePaths: (taskId: string) => string[];
removeOwnWorktreeWithReconcile: AnyFn;
};
export async function cleanupTaskWorktree(
deps: CleanupTaskWorktreeDeps,
taskId: string,
): Promise<void> {
const worktreePaths = deps.getActiveWorktreePaths(taskId);
if (worktreePaths.length === 0) return;
deps.activeWorktrees.delete(taskId);
// FNXC:Workspace 2026-06-21-12:00: KTD1 — in workspace mode the tracked path is the non-git workspace root (browse-only), never a removable worktree. Drop the in-memory tracking above but never remove the root. Per-repo worktree teardown returns in Phase B.
if (deps.workspaceConfig) {
return;
}
// Non-workspace tasks hold a one-element set — preserve the original single-path removal semantics.
const worktreePath = worktreePaths[0];
// Check if another task still needs this worktree
const otherUser = await findWorktreeUser(deps.store, worktreePath, taskId);
if (otherUser) {
executorLog.log(`Worktree retained for ${taskId} — still needed by ${otherUser}`);
return;
}
try {
const settings = await deps.store.getSettings();
await deps.removeOwnWorktreeWithReconcile({
worktreePath,
settings,
taskId,
reason: RemovalReason.ExecutorDispose,
});
executorLog.log(`Cleaned up worktree for ${taskId}`);
} catch (err: unknown) {
const errorMessage = err instanceof Error ? err.message : String(err);
executorLog.error(`Failed to clean up worktree for ${taskId}:`, errorMessage);
}
}

14
packages/engine/src/executor/clear-completed-task-watchdog.ts Normal file
View File

@@ -0,0 +1,14 @@
/**
* FNXC:CodeOrganization 2026-08-03-18:30:
* clearCompletedTaskWatchdog peeled from TaskExecutor (U4).
*/
export function clearCompletedTaskWatchdog(
completedTaskWatchdogs: Map<string, ReturnType<typeof setTimeout>>,
taskId: string,
): void {
const handle = completedTaskWatchdogs.get(taskId);
if (!handle) return;
clearTimeout(handle);
completedTaskWatchdogs.delete(taskId);
}

100
packages/engine/src/executor/clear-phantom-executor-binding.ts Normal file
View File

@@ -0,0 +1,100 @@
/**
* FNXC:CodeOrganization 2026-08-03-09:20:
* clearPhantomExecutorBinding peeled from TaskExecutor (U4).
*
* FNXC:ExecutorBinding 2026-06-19-00:00:
* FN-6736 gives self-healing a narrow escape hatch for phantom in-memory executor bindings after the liveness gate proves the owner is dead. Never use this as a general task stopper: it refuses to detach observable live session surfaces, then clears only stale bookkeeping (`executing`, resume/recovery sets, process-wide graph routing, activeWorktrees, activeSessionRegistry paths, and executingTaskLock) so the scheduler can re-dispatch the preserved worktree.
*
* FNXC:ExecutorBinding 2026-06-30-00:00:
* `preserveWorktrees: true` is the FN-6736 self-healing path. When the caller has already committed to `moveTask(..., { preserveWorktree: true })`, unregistering the held worktree path from `activeSessionRegistry` defeats the preserve: re-dispatch then sees the path as free and re-acquires a brand-new worktree (observed on FN-7249: gentle-peach orphaned, rosy-thorn rebuilt ~20s after reclaim). The preserve variant clears only the in-memory executor/lock bookkeeping and leaves the session-registry path entry intact so the re-dispatch reattaches to the same worktree. Non-self-healing callers (leaked-slot reaper, pause-abort recovery) keep the default full-clear behavior.
*
* FNXC:NodeWorktreeIsolation 2026-07-29-02:10 (FN-6756 — planner worktrees reaped from under live planners):
* THE REGISTRY IS PART OF THE LIVENESS SIGNAL, not just something this method
* tears down.
*
* This is documented as "the last line of defense against pulling a worktree out
* from under a running agent" (see `reapLeakedConcurrencySlots`). It was blind to
* an entire class of agent. The four sets below are all TaskExecutor-owned; a
* triage PLANNING session is owned by `TriageProcessor` and lives in ITS OWN
* `activeSessions` map, so a live planner matched none of them.
*
* The consequence was not theoretical — it is FN-8600 recurring through a second
* door. Under plan-in-place a card is specified while it sits in `todo`/`triage`,
* both of which `reapLeakedConcurrencySlots` treats as reapable, and planning
* routinely outlives that sweep's 60s grace. Every earlier gate passes for a
* planner (not in the executor's `executing` set, reapable column, past grace), so
* this method decided alone — and returned true, releasing the slot and then
* UNREGISTERING the planner's own registry paths below. It destroyed the very
* evidence that proves the planner alive.
*
* FN-8600 fixed the self-owned-branch reclaim sweep by registering planning paths
* here (`triage.ts` acquireActiveSessionPath, and see the "planning" kind note in
* active-session-registry.ts). That fix landed at ONE surface. This is the second,
* which is what the AGENTS.md Surface Enumeration rule exists to prevent.
*
* Deliberately keyed on ANY registered path for the task, not on kind: the point
* is that a registered session surface of any kind means someone is working in
* that worktree. A leaked entry now blocks THIS sweep rather than a live planner
* losing its worktree — the strictly safer failure, and the one the "last line of
* defense" wording already promises. The registry is process-local and in-memory,
* so a leak cannot outlive the process; stale entries have their own reconciler
* (`reconcileStaleSelfOwned`) and the reclaim-aware `acquireActiveSessionPath`.
*
* NOT fixed by raising the grace period: a longer timeout only makes this rarer
* and harder to reproduce. The liveness gate is the bug.
*
* FNXC:Workspace 2026-06-21-12:00: KTD2 — collect every worktree path the task holds (a workspace task holds N) before clearing the binding, so the registry sweep below unregisters all of them, not just one.
*/
import { executorLog } from "../logger.js";
import { activeSessionRegistry, executingTaskLock } from "../agents/active-session-registry.js";
export type ClearPhantomExecutorBindingDeps = {
hasLiveSessionSurface: (taskId: string) => boolean;
getActiveWorktreePaths: (taskId: string) => string[];
activeWorktrees: Map<string, Set<string>>;
executing: Set<string>;
recoveringCompleted: Set<string>;
resumingUnpaused: Set<string>;
approvalSuspended: Set<string>;
approvalResumeAfterUnwind: Set<string>;
processWideGraphRouting: Set<string>;
effectiveColumnAgentByTask: Map<string, string>;
};
export function clearPhantomExecutorBinding(
deps: ClearPhantomExecutorBindingDeps,
taskId: string,
options: { preserveWorktrees?: boolean } = {},
): boolean {
if (deps.hasLiveSessionSurface(taskId)) {
executorLog.warn(`${taskId}: refusing to clear phantom executor binding because a live session surface is still registered`);
return false;
}
const heldWorktreePaths = deps.getActiveWorktreePaths(taskId);
deps.activeWorktrees.delete(taskId);
deps.executing.delete(taskId);
deps.recoveringCompleted.delete(taskId);
deps.resumingUnpaused.delete(taskId);
deps.approvalSuspended.delete(taskId);
deps.approvalResumeAfterUnwind.delete(taskId);
deps.processWideGraphRouting.delete(taskId);
executingTaskLock.release(taskId);
deps.effectiveColumnAgentByTask.delete(taskId);
if (options.preserveWorktrees) {
executorLog.warn(`${taskId}: cleared phantom executor binding for self-healing re-dispatch (worktree session-registry entries preserved)`);
return true;
}
const registeredPaths = new Set(activeSessionRegistry.pathsForTask(taskId));
for (const path of heldWorktreePaths) {
registeredPaths.add(path);
}
for (const path of registeredPaths) {
activeSessionRegistry.unregisterPath(path);
}
executorLog.warn(`${taskId}: cleared phantom executor binding for self-healing re-dispatch`);
return true;
}

35
packages/engine/src/executor/clear-resume-failure-state.ts Normal file
View File

@@ -0,0 +1,35 @@
/**
* FNXC:CodeOrganization 2026-08-03-09:25:
* clearResumeFailureState peeled from TaskExecutor (U4).
*
* Pre-dispatch gating state must not survive into a resumed in-progress run.
* The scheduler sets status="queued" + blockedBy on dep/file-scope conflicts
* (scheduler.ts) and clears them on the todo→in-progress transition.
* Resume paths (unpause, drift recovery, engine restart) bypass that clear,
* so a task can end up actively executing while still labeled "queued" in the UI.
*/
import type { Task, TaskStore } from "@fusion/core";
export type ClearResumeFailureStateDeps = {
store: TaskStore;
};
export async function clearResumeFailureState(
deps: ClearResumeFailureStateDeps,
task: Task,
): Promise<void> {
const updates: { status?: null; error?: null; blockedBy?: null } = {};
if (task.status === "failed" || task.error) {
updates.status = null;
updates.error = null;
}
if (task.status === "queued") {
updates.status = null;
}
if (task.blockedBy) {
updates.blockedBy = null;
}
if (Object.keys(updates).length > 0) {
await deps.store.updateTask(task.id, updates);
}
}

33
packages/engine/src/executor/clear-terminal-step-failures-for-retry.ts Normal file
View File

@@ -0,0 +1,33 @@
/**
* FNXC:CodeOrganization 2026-08-03-19:00:
* clearTerminalStepFailuresForRetry peeled from TaskExecutor (U4).
*
* FNXC:ReviewLeniency 2026-07-02-02:10:
* Clear prior terminal failure results (failed/advisory_failure — incl. optional gate nodes like
* code-review) so a retry starts clean. Call this ONLY once the task has left the mergeable
* in-review column (i.e. it is in `todo`): clearing while still in-review drops the merge blocker
* during the rerun-bounce window and could let a concurrent auto-merge sweep merge an empty-`steps`
* graph-native task with its gate failure unaddressed. `moveTask(in-review→todo)` already clears
* ALL results (applyReopenFieldClears), so this is chiefly for the in-progress→todo bounce path
* where the move does not. Passed/skipped/pending evidence is kept.
*/
import type { TaskStore } from "@fusion/core";
import type { EngineRunContext } from "../util/run-audit.js";
import { clearTerminalWorkflowStepFailures } from "./workflow-step-failures.js";
export type ClearTerminalStepFailuresForRetryDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
};
export async function clearTerminalStepFailuresForRetry(
deps: ClearTerminalStepFailuresForRetryDeps,
taskId: string,
): Promise<void> {
const live = await deps.store.getTask(taskId).catch(() => null);
if (!live) return;
const cleared = clearTerminalWorkflowStepFailures(live.workflowStepResults);
if (cleared !== live.workflowStepResults) {
await deps.store.updateTask(taskId, { workflowStepResults: cleared }, deps.getRunContextFor(taskId));
}
}

14
packages/engine/src/executor/clear-workflow-rerun-watchdog.ts Normal file
View File

@@ -0,0 +1,14 @@
/**
* FNXC:CodeOrganization 2026-08-03-19:00:
* clearWorkflowRerunWatchdog peeled from TaskExecutor (U4).
*/
export function clearWorkflowRerunWatchdog(
workflowRerunWatchdogs: Map<string, ReturnType<typeof setTimeout>>,
taskId: string,
): void {
const handle = workflowRerunWatchdogs.get(taskId);
if (!handle) return;
clearTimeout(handle);
workflowRerunWatchdogs.delete(taskId);
}

26
packages/engine/src/executor/cli-executor-config.ts Normal file
View File

@@ -0,0 +1,26 @@
/**
* FNXC:CodeOrganization 2026-08-03-13:35:
* Pure CLI executor config resolver peeled from TaskExecutor (U4).
*/
import type { ResolvedCliExecutorConfig } from "../cli-agent/task-session.js";
/**
* Resolve cli-agent node config into a snapshotted ResolvedCliExecutorConfig.
* Returns null when cliAdapterId is missing/blank.
*/
export function resolveCliExecutorConfig(cfg: Record<string, unknown>): ResolvedCliExecutorConfig | null {
const cliAdapterId = typeof cfg.cliAdapterId === "string" && cfg.cliAdapterId.trim()
? cfg.cliAdapterId.trim()
: undefined;
if (!cliAdapterId) return null;
const cliAutonomy = cfg.cliAutonomy && typeof cfg.cliAutonomy === "object"
? (cfg.cliAutonomy as ResolvedCliExecutorConfig["cliAutonomy"])
: null;
const cliNotify = cfg.cliNotify && typeof cfg.cliNotify === "object"
? (cfg.cliNotify as Record<string, unknown>)
: null;
const settings = cfg.cliSettings && typeof cfg.cliSettings === "object"
? (cfg.cliSettings as Record<string, unknown>)
: undefined;
return { cliAdapterId, cliAutonomy, cliNotify, settings };
}

96
packages/engine/src/executor/completed-task-watchdog.ts Normal file
View File

@@ -0,0 +1,96 @@
/**
* FNXC:CodeOrganization 2026-08-03-21:15:
* scheduleCompletedTaskWatchdog peeled from TaskExecutor (U4).
* Bounded recovery when a completed task remains stuck in-progress after fn_task_done.
*/
import type { Task, TaskStore } from "@fusion/core";
import { executorLog } from "../logger.js";
import { isTaskWorkComplete } from "./task-predicates.js";
export type CompletedTaskWatchdogDeps = {
store: TaskStore;
completedTaskWatchdogs: Map<string, ReturnType<typeof setTimeout>>;
recoveringCompleted: Set<string>;
executing: Set<string>;
activeSessions: Map<string, unknown>;
activeStepExecutors: Map<string, unknown>;
activeWorkflowStepSessions: Map<string, unknown>;
resumingUnpaused: Set<string>;
completedTaskWatchdogMs: number;
clearCompletedTaskWatchdog: (taskId: string) => void;
getExecutionPauseLabel: () => Promise<string | null>;
resolveResumeLanes: (taskId: string) => Promise<{ wip: string }>;
recoverCompletedTask: (task: Task) => Promise<boolean>;
};
export function scheduleCompletedTaskWatchdog(
deps: CompletedTaskWatchdogDeps,
taskId: string,
trigger: string,
): void {
deps.clearCompletedTaskWatchdog(taskId);
const handle = setTimeout(async () => {
deps.completedTaskWatchdogs.delete(taskId);
// Claim recovery slot atomically (synchronously) before any async work.
// Without this, two paths can pass the in-flight guards on the same
// event-loop turn and both call recoverCompletedTask() concurrently.
if (
deps.recoveringCompleted.has(taskId)
|| deps.executing.has(taskId)
|| deps.activeSessions.has(taskId)
|| deps.activeStepExecutors.has(taskId)
|| deps.activeWorkflowStepSessions.has(taskId)
|| deps.resumingUnpaused.has(taskId)
) {
return;
}
deps.recoveringCompleted.add(taskId);
try {
const pauseLabel = await deps.getExecutionPauseLabel();
if (pauseLabel) {
return;
}
let currentTask: Task | null = null;
try {
currentTask = await deps.store.getTask(taskId);
} catch (err: unknown) {
const errorMessage = err instanceof Error ? err.message : String(err);
executorLog.warn(`${taskId}: completed-task watchdog could not read latest task state: ${errorMessage}`);
return;
}
if (!currentTask || currentTask.paused
|| currentTask.column !== (await deps.resolveResumeLanes(taskId)).wip) {
return;
}
if (!isTaskWorkComplete(currentTask)) {
return;
}
executorLog.warn(
`${taskId}: completed-task watchdog fired after ${deps.completedTaskWatchdogMs / 1000}s ` +
`(${trigger}) — attempting direct recovery to in-review`,
);
await deps.store.logEntry(
taskId,
`Watchdog: task remained in-progress ${deps.completedTaskWatchdogMs / 1000}s after ${trigger} — attempting direct recovery to in-review`,
).catch(() => undefined);
const recovered = await deps.recoverCompletedTask(currentTask);
if (!recovered) {
await deps.store.logEntry(
taskId,
"Watchdog recovery attempt could not finalize completed task — leaving for follow-up recovery",
).catch(() => undefined);
}
} finally {
deps.recoveringCompleted.delete(taskId);
}
}, deps.completedTaskWatchdogMs);
deps.completedTaskWatchdogs.set(taskId, handle);
}

56
packages/engine/src/executor/completion-feature-video.ts Normal file
View File

@@ -0,0 +1,56 @@
/**
* FNXC:CodeOrganization 2026-08-03-18:30:
* generateCompletionFeatureVideo + awaitFeatureVideoBounded peeled from TaskExecutor (U4).
*
* FNXC:ReviewArtifacts 2026-07-19-10:00:
* A successful executor handoff may offer reviewers a short local feature-video, but capture is
* strictly best-effort. Bound and swallow this optional work before the review transition so
* browser, scenario, and artifact failures never delay or fail it.
*/
import type { Task, TaskStore } from "@fusion/core";
import { executorLog } from "../logger.js";
import {
generateFeatureVideo,
type FeatureVideoResult,
type GenerateFeatureVideoOptions,
} from "../review-artifacts/feature-video.js";
export type CompletionFeatureVideoDeps = {
store: TaskStore;
options: {
reviewArtifactGenerator?: (opts: GenerateFeatureVideoOptions) => Promise<FeatureVideoResult>;
[k: string]: unknown;
};
};
const FEATURE_VIDEO_TIMEOUT_MS = 20_000;
export async function awaitFeatureVideoBounded(
result: Promise<FeatureVideoResult>,
): Promise<FeatureVideoResult> {
let timeout: ReturnType<typeof setTimeout> | undefined;
try {
return await Promise.race([
result,
new Promise<never>((_, reject) => {
timeout = setTimeout(() => reject(new Error("feature-video timeout")), FEATURE_VIDEO_TIMEOUT_MS);
}),
]);
} finally {
if (timeout) clearTimeout(timeout);
}
}
export async function generateCompletionFeatureVideo(
deps: CompletionFeatureVideoDeps,
task: Task,
): Promise<void> {
try {
const [settings, detail] = await Promise.all([deps.store.getSettings(), deps.store.getTask(task.id)]);
const generator = deps.options.reviewArtifactGenerator ?? generateFeatureVideo;
const result = await awaitFeatureVideoBounded(generator({ store: deps.store, task: detail ?? task, settings }));
executorLog.log(`${task.id}: feature-video ${result.status}${"reason" in result ? ` (${result.reason})` : ""}`);
} catch (error) {
executorLog.warn(`${task.id}: feature-video capture ignored: ${error instanceof Error ? error.message : String(error)}`);
}
}

144
packages/engine/src/executor/completion-finalization.ts Normal file
View File

@@ -0,0 +1,144 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:25:
* parkCompletedBlockedTask + completion finalization decision peeled from TaskExecutor (U4).
* FN-7926 completed-blocked park + FN-8141 finalize decision path.
*/
import type { Task, TaskStore } from "@fusion/core";
import { evaluateSkipBypassTaint } from "@fusion/core";
import { COMPLETED_BLOCKED_PAUSE_REASON } from "../self-healing.js";
import { executorLog } from "../logger.js";
import { generateSyntheticRunId, type EngineRunContext } from "../util/run-audit.js";
import { isTaskWorkComplete } from "./task-predicates.js";
import {
resolveReboundColumnFor,
resolveTerminalColumnsFor,
} from "./lifecycle-columns.js";
export type CompletionFinalizationDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
getTaskCompletionBlocker: (task: Task) => Promise<string | undefined>;
};
export async function parkCompletedBlockedTask(
deps: CompletionFinalizationDeps,
task: Task,
completionBlocker: string,
source: string,
workComplete = isTaskWorkComplete(task),
): Promise<boolean> {
if (task.paused === true || task.userPaused === true) return false;
/*
FNXC:WorkflowLifecycleColumns 2026-07-29-13:10:
Was the raw literal pair `column === "done" || column === "archived"`. On a renamed
board neither matched, so this "already finished, nothing to park" guard was INERT
and a completed card resting in the workflow's own terminal column fell through —
and the `column !== "todo"` branch below would then have MOVED it back out of that
terminal column. Resolved through core's shared `resolveTerminalColumns`, which owns
the per-role fallback (a partially-declared workflow keeps the legacy id for the
half it did not declare).
*/
const terminalColumns = await resolveTerminalColumnsFor(deps.store, task.id);
/*
FNXC:WorkflowLifecycleColumns 2026-07-30-21:40 (PR #2568 review — greptile):
RE-READ AFTER THE AWAIT. The pause and column guards above ran against the `task`
snapshot the caller passed, and this conversion introduced the first `await`
between those guards and the writes below. Another dispatch or an operator action
can move or pause the card while the IR resolution is in flight, and the stale
snapshot would then let this method move a now-terminal task out of its terminal
column, or overwrite a pause an operator just applied.
Re-reading is cheap next to the resolution that precedes it, and it is the pause
check that matters most: a user pause landing during the await is precisely the
case where proceeding is least forgivable. Falling back to the passed snapshot on
a read failure keeps this no worse than before the await existed.
*/
const liveTask = await deps.store.getTask(task.id).catch(() => undefined) ?? task;
if (liveTask.paused === true || liveTask.userPaused === true) return false;
if (terminalColumns.includes(liveTask.column)) return false;
if (!workComplete) return false;
const message = `Completed work held — ${completionBlocker}; will advance to review when blocker clears`;
/*
FNXC:WorkflowLifecycle 2026-07-12-23:13:
FN-7926: completed work with a persistent `getTaskCompletionBlocker` result must not self-requeue through the execute node. Re-running implementation cannot clear dependency/blockedBy state, so it only feeds FN-7863's generic no-progress backstop and misclassifies good work as `EXECUTION_DISPATCH_LOOP_EXHAUSTED`. Park in a scheduler-skipped todo state, preserve worktree/branch/steps, and reset the FN-7863 signature so the backstop remains reserved for genuinely incomplete no-progress loops.
*/
/*
FNXC:WorkflowLifecycleColumns 2026-07-30-21:40 (rebase merge, both sides kept):
main (#2644) resolved the literal `todo` into `reboundColumn`; this branch added the
post-await `liveTask` re-read. Taking either side alone loses the other — the
literal comes back, or the stale snapshot does.
*/
const reboundColumn = await resolveReboundColumnFor(deps.store, task.id);
if (liveTask.column !== reboundColumn) {
await deps.store.moveTask(task.id, reboundColumn, {
preserveProgress: true,
preserveResumeState: true,
preserveWorktree: true,
moveSource: "engine",
recoveryRehome: true,
});
}
await deps.store.updateTask(task.id, {
paused: true,
pausedReason: COMPLETED_BLOCKED_PAUSE_REASON,
status: "queued",
error: null,
executeRequeueLoopCount: null,
executeRequeueLoopSignature: null,
}, deps.getRunContextFor(task.id));
executorLog.log(`${task.id}: ${message}`);
await deps.store.logEntry(task.id, message, undefined, deps.getRunContextFor(task.id));
await deps.store.recordRunAuditEvent?.({
taskId: task.id,
agentId: "executor",
runId: generateSyntheticRunId("completed-blocked-park", task.id),
domain: "database",
mutationType: "task:completed-blocked-parked",
target: task.id,
metadata: {
taskId: task.id,
blocker: completionBlocker,
source,
priorColumn: task.column,
priorStatus: task.status ?? null,
},
});
return true;
}
export async function getCompletedTaskFinalizationDecision(
deps: CompletionFinalizationDeps,
taskId: string,
taskDone: boolean,
): Promise<"finalize" | "blocked" | "incomplete"> {
const task = await deps.store.getTask(taskId);
const completionBlocker = await deps.getTaskCompletionBlocker(task);
/*
FNXC:Lifecycle 2026-07-16-21:40:
FN-8141 — `taskDone` means an ACCEPTED fn_task_done (explicit or a non-tainted
implicit completion), which is the honest exit and always finalizes. Only the
step-status-derived `isTaskWorkComplete` path can be laundered by skip-bypass, so
the taint guard gates that path alone; a genuine no-op/PREMISE-STALE accepted done
is never blocked.
*/
const workComplete = taskDone
|| (isTaskWorkComplete(task) && !evaluateSkipBypassTaint(task).blocked);
if (completionBlocker) {
executorLog.log(`${taskId} completion blocked — ${completionBlocker}`);
if (workComplete && await parkCompletedBlockedTask(deps, task, completionBlocker, "finalization", workComplete)) {
return "blocked";
}
return "incomplete";
}
if (workComplete) return "finalize";
return "incomplete";
}
export async function shouldFinalizeCompletedTask(
deps: CompletionFinalizationDeps,
taskId: string,
taskDone: boolean,
): Promise<boolean> {
return await getCompletedTaskFinalizationDecision(deps, taskId, taskDone) === "finalize";
}

61
packages/engine/src/executor/completion-predicates.ts Normal file
View File

@@ -0,0 +1,61 @@
/**
* FNXC:CodeOrganization 2026-08-03-13:45:
* Pure completion/refusal predicates peeled from TaskExecutor (U4).
*/
import type { Task } from "@fusion/core";
import { evaluateSkipBypassTaint } from "@fusion/core";
import type { ReviewVerdict } from "../execution/reviewer.js";
import {
buildSkipBypassTaintRefusal,
evaluateTaskDoneRefusal,
} from "./task-done-refusal.js";
import { isTaskWorkComplete } from "./task-predicates.js";
/*
FNXC:Lifecycle 2026-07-16-21:40: FN-8141 — the step-status "already complete" branch
must not treat skip-bypass-tainted skips as completion; an accepted done / in-review
column are honest completion signals and stay unaffected.
The review lane arrives from the caller because the synchronous resolver returns the
default workflow in PostgreSQL mode, so resolving it here would change the census and not the behaviour.
*/
export function isTaskAlreadyCompleteForNonContinuableSession(
task: Task,
taskDone: boolean,
reviewLane: string,
): boolean {
return taskDone
|| task.column === reviewLane
|| (isTaskWorkComplete(task) && !evaluateSkipBypassTaint(task).blocked);
}
/*
FNXC:Lifecycle 2026-07-16-21:40:
FN-8141 — the implicit completion path (agent exit without fn_task_done while steps look complete)
must enforce the same skip-bypass taint refusal as explicit task_done. A synthesized taint refusal
here re-parks the run through the existing refusal budget rather than laundering skipped-after-refusal
steps into review. The explicit fn_task_done tool path is NOT routed here — that call remains the honest exit.
*/
export function evaluateImplicitCompletionRefusal(
task: Task,
codeReviewVerdicts: Map<number, ReviewVerdict>,
): ReturnType<typeof evaluateTaskDoneRefusal> {
const refusal = evaluateTaskDoneRefusal(task, {}, codeReviewVerdicts);
if (!refusal.ok) return refusal;
const taint = evaluateSkipBypassTaint(task);
if (taint.blocked) return buildSkipBypassTaintRefusal(taint);
return { ok: true };
}
/*
FNXC:Lifecycle 2026-07-16-21:40:
FN-8141 — a `bulk-step-completion-without-review` refusal stamps the durable taint
marker so that later skips (in this or a requeued lifecycle) cannot auto-promote. The
marker is cleared only on an honest exit (accepted fn_task_done / operator retry).
*/
export function skipBypassTaintUpdateForRefusal(
refusal: Extract<ReturnType<typeof evaluateTaskDoneRefusal>, { ok: false }>,
): { bulkCompletionRefusalAt: string } | Record<string, never> {
if (refusal.refusalClass !== "bulk-step-completion-without-review") return {};
return { bulkCompletionRefusalAt: new Date().toISOString() };
}

27
packages/engine/src/executor/configured-command-controllers.ts Normal file
View File

@@ -0,0 +1,27 @@
/**
* FNXC:CodeOrganization 2026-08-03-18:00:
* register/unregister configured-command AbortControllers peeled from TaskExecutor (U4).
*/
export function registerConfiguredCommandController(
activeConfiguredCommandControllers: Map<string, Set<AbortController>>,
taskId: string,
controller: AbortController,
): void {
const controllers = activeConfiguredCommandControllers.get(taskId) ?? new Set<AbortController>();
controllers.add(controller);
activeConfiguredCommandControllers.set(taskId, controllers);
}
export function unregisterConfiguredCommandController(
activeConfiguredCommandControllers: Map<string, Set<AbortController>>,
taskId: string,
controller: AbortController,
): void {
const controllers = activeConfiguredCommandControllers.get(taskId);
if (!controllers) return;
controllers.delete(controller);
if (controllers.size === 0) {
activeConfiguredCommandControllers.delete(taskId);
}
}

81
packages/engine/src/executor/configured-command.ts Normal file
View File

@@ -0,0 +1,81 @@
/**
* FNXC:CodeOrganization 2026-08-03-07:45:
* Configured command output formatting + sandbox backend selection peeled from executor.ts.
*/
import type { RunCommandResult } from "@fusion/core";
import type { RunAuditor } from "../util/run-audit.js";
import { resolveSandboxBackend, type SandboxBackend } from "../sandbox/index.js";
const WORKFLOW_SCRIPT_OUTPUT_MAX_CHARS = 4_000;
export function truncateWorkflowScriptOutput(output: string): string {
if (output.length <= WORKFLOW_SCRIPT_OUTPUT_MAX_CHARS) return output;
return `... output truncated to last ${WORKFLOW_SCRIPT_OUTPUT_MAX_CHARS} characters ...\n${output.slice(-WORKFLOW_SCRIPT_OUTPUT_MAX_CHARS)}`;
}
export function configuredCommandErrorMessage(result: RunCommandResult): string {
if (result.spawnError) return result.spawnError.message;
const parts: string[] = [];
if (result.timedOut) parts.push("Timed out");
if (result.exitCode !== null) parts.push(`Exit code: ${result.exitCode}`);
if (result.signal) parts.push(`Signal: ${result.signal}`);
const stdout = result.stdout.trim();
const stderr = result.stderr.trim();
if (stdout) parts.push(`stdout: ${truncateWorkflowScriptOutput(stdout)}`);
if (stderr) parts.push(`stderr: ${truncateWorkflowScriptOutput(stderr)}`);
return parts.length ? parts.join("\n") : "Command failed";
}
export function getConfiguredCommandSandboxBackend(auditor?: RunAuditor): SandboxBackend {
return resolveSandboxBackend({ auditor });
}
/**
* FNXC:CodeOrganization 2026-08-03-16:00:
* Shared sandbox-backed command runner used by runImplementation and test hooks.
* Lives with configured-command peels so U4 free functions do not re-open executor.ts locals.
*/
export async function runConfiguredCommand(
command: string,
cwd: string,
timeoutMs: number,
extraEnv?: NodeJS.ProcessEnv,
auditor?: RunAuditor,
signal?: AbortSignal,
): Promise<RunCommandResult> {
const backend = getConfiguredCommandSandboxBackend(auditor);
const result = await backend.run(command, {
cwd,
timeoutMs,
maxBuffer: 10 * 1024 * 1024,
encoding: "utf-8",
...(extraEnv !== undefined && { env: extraEnv }),
...(signal !== undefined && { signal }),
});
return {
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.exitCode,
signal: result.signal,
bufferExceeded: result.bufferExceeded,
timedOut: result.timedOut,
spawnError: result.spawnError,
};
}
/*
FNXC:CodeOrganization 2026-08-04-06:25:
Test-only wrapper re-exported from executor.ts so sandbox wiring tests import a stable
facade path without holding the helper body on TaskExecutor's module surface.
*/
export async function __runConfiguredCommandForTests(
command: string,
cwd: string,
timeoutMs: number,
extraEnv?: NodeJS.ProcessEnv,
auditor?: RunAuditor,
signal?: AbortSignal,
): Promise<RunCommandResult> {
return runConfiguredCommand(command, cwd, timeoutMs, extraEnv, auditor, signal);
}

497
packages/engine/src/executor/create-authoritative-workflow-primitives.ts Normal file
View File

@@ -0,0 +1,497 @@
/**
* FNXC:CodeOrganization 2026-08-03-14:15:
* createAuthoritativeWorkflowPrimitivesFromExecutor peeled from TaskExecutor (U4).
*
* FNXC:WorkflowExecution 2026-06-23-11:49 / 2026-06-23-22:31:
* prepareWorktree must not re-acquire; only trust live rows for the same task id.
*
* FNXC:WorkflowExecutionOwnership 2026-07-29-16:20:
* runCodingSession is the live implementation owner and announces NodeCompleted exits.
*/
import type { Settings, TaskDetail, TaskStore } from "@fusion/core";
import { emitWorkflowLifecycleEvent, resolveTaskLifecycleColumns } from "@fusion/core";
import type { ImplementationExit } from "./implementation-exit.js";
import type {
AuditPrimitiveInput,
PreparedWorktree,
WorkflowPrimitiveContext,
WorkflowRuntimePrimitives,
} from "../execution/runtime-primitives.js";
import { WorkflowPlanningService } from "../workflows/workflow-planning-service.js";
import {
FOREACH_ACTIVE_CONTEXT_KEY,
SEAM_GOVERNING_NODE_CONTEXT_KEY,
SEAM_SKILL_NAME_CONTEXT_KEY,
SPLIT_ACTIVE_CONTEXT_KEY,
type ForeachActiveContext,
} from "../workflows/workflow-node-handlers.js";
import { graphActiveContextKey } from "./task-predicates.js";
import { hasNonTerminalWorkflowSteps } from "./workflow-step-satisfaction.js";
import { makeAncestryBlastRadiusGuard, resetStepToBaseline } from "../execution/step-runner.js";
import { finalizeProvenAutoMergeTask } from "../merge/auto-merge-finalization.js";
import { createRunAuditor, type EngineRunContext } from "../util/run-audit.js";
import { executorLog } from "../logger.js";
import { resolveExternalExecutionCheckoutRoute } from "../execution/external-execution-checkout.js";
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- mirror TaskExecutor method surface without re-typing the class
type AnyFn = (...args: any[]) => any;
export type CreateAuthoritativeWorkflowPrimitivesDeps = {
store: TaskStore;
rootDir: string;
graphSeamGoverningNodeId: Map<string, string>;
graphStepActiveContext: Map<string, unknown>;
pausedAborted: Set<string>;
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- merge requester accepts optional signal bag
mergeRequester?: ((taskId: string, opts?: any) => Promise<any>) | null;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
buildParseStepsDeps: AnyFn;
createAuthoritativeWorkflowSeams: AnyFn;
ensureWorkflowMergeBoundaryTask: AnyFn;
getWorkflowMergeImplementationProofFailure: AnyFn;
handoffTaskToReview: AnyFn;
markPausedAborted: AnyFn;
persistTokenUsage: AnyFn;
runImplementationPhase: AnyFn;
runProjectedGraphTaskStep: AnyFn;
};
export function createAuthoritativeWorkflowPrimitivesFromExecutor(
deps: CreateAuthoritativeWorkflowPrimitivesDeps,
settings: Settings,
): WorkflowRuntimePrimitives {
const logAudit = async (taskId: string | undefined, input: AuditPrimitiveInput): Promise<void> => {
if (!taskId) return;
try {
await deps.store.logEntry(taskId, input.message, input.metadata ? JSON.stringify(input.metadata) : undefined);
} catch {
// Audit is diagnostic-only and must not affect workflow execution.
}
};
const planningService = new WorkflowPlanningService();
return {
prepareWorktree: async (_ctx, task) => {
const live = await deps.store.getTask(task.id).catch(() => null);
const liveTask = live?.id === task.id ? live : null;
const routedTask = liveTask ?? task;
const externalRoute = await resolveExternalExecutionCheckoutRoute(routedTask);
if (externalRoute.configured && !externalRoute.valid) {
return {
outcome: "failure",
value: `external-execution-checkout-invalid: ${externalRoute.reason ?? "unknown error"}`,
};
}
/*
FNXC:WorkflowExecution 2026-06-23-11:49:
The workflow execute node must not perform a second worktree acquisition ahead of the authoritative executor. Passing the repo root as a prepared worktree makes the inner execute() reject a valid fresh-worktree task as repo-root reuse; pass only an existing task worktree and let execute() acquire when none exists.
FNXC:WorkflowExecution 2026-06-23-22:31:
Upgrade safety requires the graph primitive to tolerate older or minimal stores that return null or a mismatched row during startup/cutover. Only trust the live row when it is for the requested task; otherwise fall back to the runner snapshot.
FNXC:ExternalExecutionCheckout 2026-08-09-23:53:
Operator-routed external checkouts supply the prepared path/branch when configured.
*/
const prepared: PreparedWorktree = {
worktreePath: externalRoute.configured
? externalRoute.checkoutPath ?? ""
: liveTask?.worktree || task.worktree || "",
branchName: externalRoute.configured
? externalRoute.branch
: liveTask?.branch || task.branch,
};
return { outcome: "success", value: "worktree-ready", data: prepared };
},
readArtifact: async (_ctx, task, key) => {
const parseDeps = deps.buildParseStepsDeps(`${task.id}:artifact-read`);
return parseDeps.readArtifact(task, key);
},
writeArtifact: async (ctx, task, key, content) => {
const writer = (deps.store as unknown as {
writeTaskDocument?: (taskId: string, key: string, content: string) => Promise<void>;
}).writeTaskDocument;
if (!writer) {
await logAudit(task.id, {
type: "artifact-write-unavailable",
message: `Workflow node ${ctx.node.node.id} could not write artifact ${key}: store writer unavailable`,
});
return { outcome: "failure", value: "artifact-write-unavailable" };
}
await writer.call(deps.store, task.id, key, content);
return { outcome: "success", value: "artifact-written", data: { key } };
},
runPlanningSession: (ctx, task) => planningService.runPlanningSession(ctx, task),
runCodingSession: async (ctx, task, prepared) => {
const governingNodeId = ctx.node.context?.[SEAM_GOVERNING_NODE_CONTEXT_KEY];
if (typeof governingNodeId === "string") {
deps.graphSeamGoverningNodeId.set(task.id, governingNodeId);
}
let result: { taskDone: boolean; modifiedFiles: string[]; exit?: ImplementationExit };
try {
result = await deps.runImplementationPhase(task, prepared);
} finally {
deps.graphSeamGoverningNodeId.delete(task.id);
}
/*
FNXC:WorkflowExecutionOwnership 2026-07-29-16:20 (U8 / R4, R5):
THIS is the live implementation node, not the identically-shaped `execute` entry in
`createAuthoritativeWorkflowSeams`. `createDefaultNodeHandlers` prefers the PRIMITIVES
handler whenever `deps.primitives` is set, and `executeWorkflowGraph` always sets it — so
the legacy-seams prompt handler is unreachable for prompt nodes and anything wired only
there never runs. The exit announcement was wired only there; it is announced here now.
Measured, not assumed: instrumenting the seam and `createPromptLikeHandler` produced no
output for a graph run that demonstrably visited `steps#0:step-execute`, while a
module-load write from the same file appeared — so the negative was real and not swallowed
output.
*/
emitWorkflowLifecycleEvent({
type: "NodeCompleted",
taskId: task.id,
at: new Date().toISOString(),
runId: deps.getRunContextFor(task.id)?.runId,
nodeId: typeof governingNodeId === "string" ? governingNodeId : ctx.node.node.id,
outcome: result.taskDone ? "success" : "failure",
...(result.exit ? { exit: result.exit } : {}),
});
if (result.taskDone) {
return { outcome: "success", value: "implemented", data: result };
}
let paused = deps.pausedAborted.has(task.id);
if (!paused) {
try {
paused = Boolean((await deps.store.getTask(task.id)).paused);
} catch {
// Best-effort pause probe; fall through to the failure value.
}
}
/*
FNXC:WorkflowExecutionOwnership 2026-07-29-18:45 (U8 / R4):
THE PENDING-REVIEW ENDING IS A ROUTED OUTCOME, not a transition this phase performs. The
implementation phase used to call `handoffTaskToReview` itself and let the graph discover
the move afterwards; it now reports and stops, and this value routes the run to the
workflow's `review-pending-handoff` node, which performs the handoff and ends the run —
the same two effects in the same order, with the graph as the owner. Checked before the
pause probe because a pending-review stop is not a pause.
*/
if (result.exit === "review-handoff-pending-review") {
return { outcome: "failure", value: "review-pending", data: result };
}
return {
outcome: "failure",
value: paused ? "implementation-paused" : "implementation-incomplete",
data: result,
};
},
runTaskStep: async (ctx, task, stepIndex) => {
const context = ctx.node.context ?? {};
const active = context[FOREACH_ACTIVE_CONTEXT_KEY] as ForeachActiveContext | undefined;
if (!active || typeof active.stepIndex !== "number") {
return { outcome: "failure" };
}
const live = await deps.store.getTask(task.id);
/*
FNXC:WorkflowResume 2026-06-29-08:53:
`step-execute` is a workflow node and must be idempotent on replay. If the live projection already says this foreach instance is terminal, return success before invoking the step runner so retries/restarts cannot fail a fully completed task on a stale step snapshot.
*/
const liveStatus = live.steps[stepIndex]?.status;
if (liveStatus === "done" || liveStatus === "skipped") {
return {
outcome: "success",
value: "step-already-terminal",
data: { status: liveStatus },
};
}
deps.graphStepActiveContext.set(graphActiveContextKey(task.id, active.instanceId), active);
const stepGoverningNodeId = context[SEAM_GOVERNING_NODE_CONTEXT_KEY];
const seamSkillName = context[SEAM_SKILL_NAME_CONTEXT_KEY];
return await deps.runProjectedGraphTaskStep(
task,
live,
stepIndex,
active,
typeof stepGoverningNodeId === "string" ? stepGoverningNodeId : undefined,
undefined,
typeof seamSkillName === "string" && seamSkillName.trim() ? seamSkillName.trim() : undefined,
);
},
resetTaskStep: async (ctx, task, stepIndex, baselineSha, checkpointId) => {
const active = ctx.node.context?.[FOREACH_ACTIVE_CONTEXT_KEY] as ForeachActiveContext | undefined;
const branchScoped = typeof active?.worktreePath === "string" && active.worktreePath.length > 0;
let worktreePath = active?.worktreePath ?? deps.rootDir;
if (!branchScoped) {
try {
worktreePath = (await deps.store.getTask(task.id)).worktree || deps.rootDir;
} catch {
// Best-effort worktree resolution; fall back to rootDir.
}
}
const liveSteps = await deps.store.getTask(task.id).then((t) => t.steps).catch(() => []);
return await resetStepToBaseline(
{
store: deps.store,
worktreePath,
sessionRef: { current: null },
reviewType: "code",
blastRadiusGuard: branchScoped
? undefined
: makeAncestryBlastRadiusGuard({
worktreePath,
task: { id: task.id, steps: liveSteps },
stepIndex,
}),
},
{ id: task.id, steps: liveSteps },
stepIndex,
baselineSha,
checkpointId,
);
},
runReview: async (ctx, task, input) => {
if (typeof input.stepIndex === "number") {
const context = ctx.node.context ?? {};
const active = context[FOREACH_ACTIVE_CONTEXT_KEY] as ForeachActiveContext | undefined;
if (!active || typeof active.stepIndex !== "number") {
return {
outcome: "success",
value: "unavailable",
data: { verdict: "UNAVAILABLE", review: "no active step instance" },
};
}
const config = {
type: input.type,
advisory: context[SPLIT_ACTIVE_CONTEXT_KEY] === true,
} as const;
const seamResult = await deps.createAuthoritativeWorkflowSeams(settings).stepReview?.(
task,
context,
config,
);
return {
outcome: "success",
value: seamResult?.verdict === "APPROVE" ? "approve" : seamResult?.verdict === "REVISE" ? "revise" : seamResult?.verdict === "RETHINK" ? "rethink" : "unavailable",
data: seamResult ?? { verdict: "UNAVAILABLE", review: "step review unavailable" },
};
}
const live = await deps.store.getTask(task.id);
await deps.persistTokenUsage(task.id);
await deps.handoffTaskToReview(live, "workflow-graph-review");
return {
outcome: "success",
value: "in-review",
data: { verdict: "APPROVE", summary: "Task handed off for merge review" },
};
},
runVerification: async () => ({ outcome: "success", value: "verification-skipped", data: {
verdict: "skipped",
} }),
// FNXC:WorkflowExecution 2026-06-25-00:00: U4 (KTD-2) — the legacy
// `runWorkflowStep` primitive + the `workflow-step` seam it served were
// removed. Workflow quality gates run as the graph's own optional-group /
// gate nodes (builtin:coding already routes through them), which record
// results into `task.workflowStepResults` directly (U2). No `runWorkflowStep`
// primitive remains in `WorkflowRuntimePrimitives`.
updateSteps: async (_ctx, task, steps) => {
await deps.store.updateTask(task.id, { steps });
return { outcome: "success", value: "steps-updated", data: { count: steps.length } };
},
transitionTask: async (_ctx, task, input) => {
const taskStore = deps.store;
const patch: Partial<TaskDetail> = {};
/*
FNXC:WorkflowLifecycleColumns 2026-07-30-21:40:
Resolve a requested ROLE to this task's own column, because the seam that asks cannot.
`workflow-node-handlers.ts`'s review-handoff seam is a pure function over an IR node and a
task — no store — so it could only name `in-review`. Post-U12 `moveTask` REJECTS a destination
the workflow does not declare, so on a renamed review lane that transition threw
`TransitionRejectionError` and killed the walk mid-run. Not a silent wrong answer for once: a
hard failure in the middle of a workflow, which is why it outranked the rest of the backlog.
Resolved per task from its OWN selection, so there is one authority — the mistake that took
#2843 five review rounds was answering one question with two reads. `column` still wins when
both are supplied, and an unresolvable role falls back to the legacy id rather than failing
the transition, which is exactly the behaviour callers had before.
*/
let targetColumn = input.column;
if (targetColumn === undefined && input.columnRole === "review") {
targetColumn = (await resolveTaskLifecycleColumns(taskStore, task.id))?.review ?? "in-review";
}
/*
FNXC:WorkflowNotifications 2026-06-29-08:50:
Workflow graph lifecycle transitions must use TaskStore move semantics, not raw `updateTask({ column })`, because ntfy/webhook notification delivery is subscribed to `task:moved`. Direct column writes make graph-owned tasks invisible to in-review/done lifecycle notifications and bypass column hooks.
*/
if (targetColumn !== undefined) {
const moveOptions = {
preserveProgress: input.preserveProgress,
moveSource: "engine" as const,
workflowMoveSource: "workflow-graph",
workflowMoveMetadata: {
reason: input.reason,
nodeId: _ctx.node.node.id,
workflowId: _ctx.run.workflowId,
runId: _ctx.run.runId,
},
};
const storeWithMove = taskStore as typeof taskStore & {
moveTask?: typeof taskStore.moveTask;
};
if (typeof storeWithMove.moveTask === "function") {
await storeWithMove.moveTask(task.id, targetColumn, moveOptions);
} else {
patch.column = targetColumn;
}
}
if (input.status !== undefined && input.status !== null) patch.status = input.status;
if (Object.keys(patch).length > 0) {
await taskStore.updateTask(task.id, patch);
}
return { outcome: "success", value: input.reason };
},
requestMerge: async (ctx, task) => {
if (!deps.mergeRequester) {
return { outcome: "failure", value: "merge-unavailable", data: { status: "failed", reason: "merge-unavailable" } };
}
/*
FNXC:WorkflowCancellation 2026-07-15-10:42:
Fail fast on an already-cancelled walk BEFORE any side effect. `ensureWorkflowMergeBoundaryTask` mutates the task row and the requester enqueues a real merge; neither may run for a walk the engine has already abandoned. `merge-cancelled` is deliberately not `data.status: "failed"` — `classifyMergeFailure` would read an unknown reason as `merge-failed` and route a cancellation into bounded auto-merge retry.
*/
if (ctx.signal?.aborted) {
return { outcome: "failure", value: "merge-cancelled" };
}
const mergeTask = await deps.ensureWorkflowMergeBoundaryTask(task, {
reason: "workflow-merge-boundary",
nodeId: ctx.node.node.id,
workflowId: ctx.run.workflowId,
runId: ctx.run.runId,
});
/*
FNXC:WorkflowMerge 2026-06-29-23:18:
FN-7261 reached the merge node in fast mode with every legacy implementation step still pending, producing a no-op merge proof for work that never ran. A graph-native workflow may project its checklist at the merge boundary only when node workflow results prove implementation completed; otherwise incomplete legacy steps are authoritative and merge must fail before the merger can create stale no-op proof.
FNXC:WorkflowMerge 2026-06-30-00:38:
Fast default Coding tasks must still execute implementation work. FN-7260/FN-7271 reached merge with no parsed task steps, no foreach instances, and no implementation proof, then finalized through no-op merge. The workflow merge boundary must fail before requesting merge when a coding workflow has not produced implementation evidence; fast mode only bypasses review/verification gates.
*/
const missingImplementationProof = await deps.getWorkflowMergeImplementationProofFailure(mergeTask);
if (missingImplementationProof) {
await deps.store.logEntry(
mergeTask.id,
`Workflow merge blocked before requester: ${missingImplementationProof}`,
undefined,
deps.getRunContextFor(mergeTask.id),
);
return {
outcome: "failure",
value: "implementation-incomplete",
data: { status: "failed", reason: "implementation-incomplete" },
};
}
if (hasNonTerminalWorkflowSteps(mergeTask)) {
await deps.store.logEntry(
mergeTask.id,
"Workflow merge blocked before requester: implementation steps are incomplete",
undefined,
deps.getRunContextFor(mergeTask.id),
);
return {
outcome: "failure",
value: "implementation-incomplete",
data: { status: "failed", reason: "implementation-incomplete" },
};
}
/*
FNXC:WorkflowCancellation 2026-07-15-10:42:
The timeout bounds a wedged merge queue; it is NOT the cancellation path. `ctx.signal` (graph abort) is linked in via `AbortSignal.any` so a hard-cancel collapses the merge node immediately instead of after the full timeout, and is raced separately so the walk returns rather than waiting on a requester that may not settle on abort. Keep both signals live: dropping the timeout re-strands the walk behind a wedged queue, dropping the cancel link restores the 30-minute stall.
*/
const GRAPH_MERGE_TIMEOUT_MS = 30 * 60 * 1000;
const controller = new AbortController();
const mergeSignal = ctx.signal ? AbortSignal.any([ctx.signal, controller.signal]) : controller.signal;
let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
const timeout = new Promise<"timeout">((resolve) => {
timeoutHandle = setTimeout(() => {
controller.abort();
resolve("timeout");
}, GRAPH_MERGE_TIMEOUT_MS);
timeoutHandle.unref?.();
});
let onGraphAbort: (() => void) | undefined;
const cancelled = new Promise<"cancelled">((resolve) => {
if (!ctx.signal) return;
onGraphAbort = () => resolve("cancelled");
ctx.signal.addEventListener("abort", onGraphAbort, { once: true });
});
try {
const result = await Promise.race([deps.mergeRequester(mergeTask.id, { signal: mergeSignal }), timeout, cancelled]);
if (result === "cancelled") {
executorLog.warn(`${mergeTask.id}: workflow merge primitive cancelled by graph abort`);
return { outcome: "failure", value: "merge-cancelled" };
}
if (result === "timeout") {
executorLog.warn(`${mergeTask.id}: workflow merge primitive timed out after ${GRAPH_MERGE_TIMEOUT_MS}ms`);
return { outcome: "failure", value: "merge-timeout", data: { status: "timeout" } };
}
if (result.merged || result.noOp) {
/*
FNXC:WorkflowMerge 2026-06-29-09:24:
The workflow merge primitive owns the normal lifecycle transition after a graph merge node succeeds. Finalize the proven landed task here so `mergeConfirmed` cannot strand a card in `in-progress`; executor preflight recovery is only a fallback for rows already stranded by older runs.
*/
const finalization = await finalizeProvenAutoMergeTask({
store: deps.store,
taskId: mergeTask.id,
result,
rootDir: deps.rootDir,
audit: createRunAuditor(deps.store, {
runId: ctx.run.runId,
agentId: "executor",
taskId: mergeTask.id,
taskLineageId: mergeTask.lineageId,
phase: "workflow-merge",
}),
auditAgentId: "executor",
auditPhase: "workflow-merge",
source: "workflow-graph-merge-finalize",
log: (message) => executorLog.warn(message),
});
if (finalization.outcome === "blocked" || finalization.outcome === "missing") {
return {
outcome: "failure",
value: `merge-finalize-${finalization.outcome}`,
data: { status: "failed", reason: finalization.reason ?? finalization.outcome },
};
}
return {
outcome: "success",
value: result.noOp ? "merge-noop" : "merged",
data: { status: "merged", noOp: result.noOp },
};
}
return {
outcome: "failure",
value: result.reason ?? result.error ?? "merge-failed",
data: { status: "failed", reason: result.reason ?? result.error ?? "merge-failed" },
};
} finally {
if (timeoutHandle) clearTimeout(timeoutHandle);
// FNXC:WorkflowCancellation 2026-07-15-10:42: the graph signal outlives this node; leaving the listener attached leaks one per merge attempt across a retry loop.
if (onGraphAbort) ctx.signal?.removeEventListener("abort", onGraphAbort);
await logAudit(mergeTask.id, {
type: "merge-requested",
message: `Workflow node ${ctx.node.node.id} requested merge`,
});
}
},
abortRun: async (_ctx, task, input) => {
if (input.hardCancel) {
deps.markPausedAborted(task.id, "merge-seam", "workflow-abort-run:merge-seam");
}
await deps.store.updateTask(task.id, {
paused: true,
pausedReason: input.reason,
} as Partial<TaskDetail>);
return { outcome: "success", value: "aborted" };
},
audit: async (ctx: WorkflowPrimitiveContext, input) => {
await logAudit(ctx.run.taskId, input);
},
};
}

483
packages/engine/src/executor/create-authoritative-workflow-seams.ts Normal file
View File

@@ -0,0 +1,483 @@
/**
* FNXC:CodeOrganization 2026-08-03-14:20:
* createAuthoritativeWorkflowSeams peeled from TaskExecutor (U4).
*
* FNXC:WorkflowExecutionOwnership 2026-07-27-16:25 / 2026-07-28-20:25:
* Seam return vocabulary is the ownership boundary; exit events announce without changing outcomes.
*/
import type { AgentStore, Settings, TaskStore, ThinkingLevel, WorkspaceConfig } from "@fusion/core";
import { emitWorkflowLifecycleEvent, THINKING_LEVELS } from "@fusion/core";
import type { ImplementationExit } from "./implementation-exit.js";
import type { WorkflowLegacySeams } from "../workflows/workflow-node-handlers.js";
import type { AgentSemaphore } from "../concurrency/concurrency.js";
import {
FOREACH_ACTIVE_CONTEXT_KEY,
SEAM_GOVERNING_NODE_CONTEXT_KEY,
SEAM_SKILL_NAME_CONTEXT_KEY,
SEAM_THINKING_LEVEL_CONTEXT_KEY,
type ForeachActiveContext,
} from "../workflows/workflow-node-handlers.js";
import { graphActiveContextKey } from "./task-predicates.js";
import { WorkflowReviewService } from "../workflows/workflow-review-service.js";
import { mergeEffectiveSettings } from "../project/effective-settings.js";
import { resolveReviewCheckoutCwd } from "../execution/review-checkout.js";
import { logReviewCheckoutRouting } from "./review-checkout-routing.js";
import { selectUserCommentsForAgentContext } from "../agents/agent-user-comments.js";
import {
resolveValidatorThinkingLevel,
resolveValidatorFallbackThinkingLevel,
} from "../agents/agent-session-helpers.js";
import type { ReviewVerdict } from "../execution/reviewer.js";
import {
buildReviewUnavailableMessage,
buildPlanVerifiedMessage,
buildReviewVerdictMessage,
emitProactiveStatus,
sanitizeFailureReason,
} from "../project/proactive-status.js";
import type { EngineRunContext } from "../util/run-audit.js";
import { executorLog, reviewerLog } from "../logger.js";
const WORKFLOW_THINKING_LEVEL_SET: ReadonlySet<string> = new Set(THINKING_LEVELS);
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- mirror TaskExecutor method surface
type AnyFn = (...args: any[]) => any;
export type CreateAuthoritativeWorkflowSeamsDeps = {
store: TaskStore;
rootDir: string;
options: {
agentStore?: AgentStore | null;
pluginRunner?: unknown;
semaphore?: AgentSemaphore;
mergeRequester?: unknown;
[k: string]: unknown;
};
workspaceConfig: WorkspaceConfig | null | undefined;
activeWorkflowPrincipals: Map<string, { agentId: string; nodeInstanceId: string; agent?: import("@fusion/core").Agent }>;
graphSeamGoverningNodeId: Map<string, string>;
graphSeamThinkingLevel: Map<string, ThinkingLevel>;
graphStepActiveContext: Map<string, unknown>;
graphRethinkNarrations: Map<string, unknown>;
pausedAborted: Set<string>;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
mergeRequester?: ((taskId: string, opts?: any) => Promise<any>) | null;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
persistTokenUsage: AnyFn;
runImplementationPhase: AnyFn;
handoffTaskToReview: AnyFn;
ensureWorkflowMergeBoundaryTask: AnyFn;
getWorkflowMergeImplementationProofFailure: AnyFn;
runProjectedGraphTaskStep: AnyFn;
updateStepGraph: AnyFn;
reviewWorkspacePerRepo: AnyFn;
registerSubagentSession: AnyFn;
unregisterSubagentSession: AnyFn;
};
export function createAuthoritativeWorkflowSeams(
deps: CreateAuthoritativeWorkflowSeamsDeps,
_settings: Settings,
): WorkflowLegacySeams {
return {
// Built-in triage/spec generation runs upstream of the interpreter today,
// so planning is a no-op for already-specified tasks. Custom planning
// behavior is expressed as a custom prompt node before the execute seam.
planning: async () => ({ outcome: "success", value: "pre-specified" }),
execute: async (seamTask, context) => {
// Column-agent seam wiring (U4, R4): record the governing node id (the
// execute-seam prompt node, stamped into context by createPromptLikeHandler)
// so execute()'s session build can resolve the column-agent binding for the
// node's DECLARED column. Cleared after the pass so a later seam without a
// binding cannot inherit a stale node id.
const governingNodeId = context?.[SEAM_GOVERNING_NODE_CONTEXT_KEY];
if (typeof governingNodeId === "string") {
deps.graphSeamGoverningNodeId.set(seamTask.id, governingNodeId);
}
const seamThinkingLevel = context?.[SEAM_THINKING_LEVEL_CONTEXT_KEY];
if (typeof seamThinkingLevel === "string" && WORKFLOW_THINKING_LEVEL_SET.has(seamThinkingLevel)) {
deps.graphSeamThinkingLevel.set(seamTask.id, seamThinkingLevel as ThinkingLevel);
}
let result: { taskDone: boolean; modifiedFiles: string[]; exit?: ImplementationExit };
try {
result = await deps.runImplementationPhase(seamTask);
} finally {
deps.graphSeamGoverningNodeId.delete(seamTask.id);
deps.graphSeamThinkingLevel.delete(seamTask.id);
}
/*
FNXC:WorkflowExecutionOwnership 2026-07-27-16:25 (U8 / R4):
THIS BOOLEAN IS THE OWNERSHIP BOUNDARY, and it is too narrow. `runImplementation` has
28 measured ways of disposing of a task (16 column moves, 3 review handoffs, 9 terminal
parks — counted by `executor-lifecycle-ownership-ledger.test.ts`) and exactly 3 ways of
telling the graph anything, all of which collapse to `taskDone: true` here.
The consequence is not a missing feature, it is a second lifecycle owner. Because the
seam has no value for "the agent stopped because a step is blocked on a pending review"
or "the session was paused after the work was already complete", the implementation
phase performs those transitions ITSELF (`executor-exit-while-review-pending`,
`paused-after-completion`) and the graph learns about them afterwards — which is why
`handleGraphFailure` carries `alreadyFinalizedToReview` / `completionFinalized`
classifiers whose whole job is to recognise a move the graph did not make.
U8's direction: widen this vocabulary so a disposition is REPORTED here and the graph
routes it, rather than performed upstream and compensated for downstream. The
compensating classifiers are the acceptance test — they become unreachable, and then
deletable, exactly when the last out-of-band transition is gone.
*/
/*
FNXC:WorkflowExecutionOwnership 2026-07-28-20:25 (U8 / R4, R5):
Announce the exit on the U3 lifecycle bus. Until this, the two out-of-band review
handoffs left NO trace anywhere that the executor — not the graph — moved the card;
they surfaced as an ordinary `implementation-incomplete` failure that
`handleGraphFailure` then quietly compensated for. An operator could not tell the two
apart, and neither could a test.
Emission is deliberately AFTER the phase and BEFORE the return, and it changes nothing:
the outcome/value below are byte-identical to what this seam returned before, for every
exit, which `executor-implementation-exit-events.test.ts` pins by driving each exit and
asserting the seam's return. Per R5 an exit id is a REACTION — dropping every subscriber
must change no execution outcome, and that is asserted too.
*/
emitWorkflowLifecycleEvent({
type: "NodeCompleted",
taskId: seamTask.id,
at: new Date().toISOString(),
runId: deps.getRunContextFor(seamTask.id)?.runId,
nodeId: typeof governingNodeId === "string" ? governingNodeId : "execute",
outcome: result.taskDone ? "success" : "failure",
...(result.exit ? { exit: result.exit } : {}),
});
if (result.taskDone) {
return { outcome: "success", value: "implemented" };
}
// Distinguish pause/abort from genuine implementation failure so the
// failure handler can leave paused tasks to the pause machinery.
let paused = deps.pausedAborted.has(seamTask.id);
if (!paused) {
try {
paused = Boolean((await deps.store.getTask(seamTask.id)).paused);
} catch {
// Best-effort pause probe; fall through to the failure value.
}
}
return {
outcome: "failure",
value: paused ? "implementation-paused" : "implementation-incomplete",
};
},
// FNXC:WorkflowExecution 2026-06-25-00:00: U4 (KTD-2) — the legacy
// `workflowStep` seam was removed. Workflow quality gates run as the graph's
// own optional-group / gate nodes (builtin:coding replaced its `workflow-step`
// seam node with optional-group nodes) which record into
// `task.workflowStepResults` (U2). `WorkflowLegacySeams.workflowStep` no
// longer exists, and `resolveSeamName` no longer recognizes the
// `workflow-step` seam (an IR node still declaring it now fails loudly via
// WorkflowIrError rather than silently no-opping).
review: async (seamTask) => {
// The legacy "review" stage is the in-review handoff: the in-review column is
// the staging state the merge queue consumes.
const live = await deps.store.getTask(seamTask.id);
await deps.persistTokenUsage(seamTask.id);
await deps.handoffTaskToReview(live, "workflow-graph-review");
return { outcome: "success", value: "in-review" };
},
"review-handoff": async (seamTask) => {
/*
* FNXC:WorkflowPrPolicy 2026-06-29-16:42:
* Compound Engineering can run an optional manual PR review lane after implementation. That lane must start from the review column without invoking the generic reviewer again; this seam is a pure lifecycle handoff so PR creation/feedback nodes run while the card is visibly in review.
*/
const live = await deps.store.getTask(seamTask.id);
await deps.persistTokenUsage(seamTask.id);
await deps.handoffTaskToReview(live, "workflow-graph-review-handoff");
return { outcome: "success", value: "in-review" };
},
merge: async (seamTask, _context, signal) => {
if (!deps.mergeRequester) {
return { outcome: "failure", value: "merge-unavailable" };
}
// FNXC:WorkflowCancellation 2026-07-15-10:42: fail fast before the boundary-task mutation and the merge request — an abandoned walk must not enqueue a merge. Mirrors the `requestMerge` primitive.
if (signal?.aborted) {
return { outcome: "failure", value: "merge-cancelled" };
}
const mergeTask = await deps.ensureWorkflowMergeBoundaryTask(seamTask, {
reason: "workflow-merge-boundary",
nodeId: "legacy-merge-seam",
workflowId: "legacy-seams",
runId: deps.getRunContextFor(seamTask.id)?.runId ?? "legacy-seam",
});
const missingImplementationProof = await deps.getWorkflowMergeImplementationProofFailure(mergeTask);
if (missingImplementationProof) {
await deps.store.logEntry(
mergeTask.id,
`Workflow merge blocked before requester: ${missingImplementationProof}`,
undefined,
deps.getRunContextFor(mergeTask.id),
);
return { outcome: "failure", value: "implementation-incomplete" };
}
// Bound the wait: a wedged merge queue must not strand the graph walk
// holding the routing claim. On timeout the run fails cleanly and the
// task is parked for human review; the queue can still finish later.
// FNXC:WorkflowCancellation 2026-07-15-10:42: the timeout is the wedged-queue bound, `signal` is the cancellation path — both must stay live. See the `requestMerge` primitive for the stall this prevents.
const GRAPH_MERGE_TIMEOUT_MS = 30 * 60 * 1000;
let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
const timeout = new Promise<"timeout">((resolve) => {
timeoutHandle = setTimeout(() => resolve("timeout"), GRAPH_MERGE_TIMEOUT_MS);
timeoutHandle.unref?.();
});
let onGraphAbort: (() => void) | undefined;
const cancelled = new Promise<"cancelled">((resolve) => {
if (!signal) return;
onGraphAbort = () => resolve("cancelled");
signal.addEventListener("abort", onGraphAbort, { once: true });
});
try {
const result = await Promise.race([deps.mergeRequester(mergeTask.id, signal ? { signal } : undefined), timeout, cancelled]);
if (result === "cancelled") {
executorLog.warn(`${mergeTask.id}: graph merge seam cancelled by graph abort`);
return { outcome: "failure", value: "merge-cancelled" };
}
if (result === "timeout") {
executorLog.warn(`${mergeTask.id}: graph merge seam timed out after ${GRAPH_MERGE_TIMEOUT_MS}ms`);
return { outcome: "failure", value: "merge-timeout" };
}
if (result.merged || result.noOp) {
return { outcome: "success", value: result.noOp ? "merge-noop" : "merged" };
}
return { outcome: "failure", value: result.reason ?? result.error ?? "merge-failed" };
} finally {
if (timeoutHandle) clearTimeout(timeoutHandle);
if (onGraphAbort) signal?.removeEventListener("abort", onGraphAbort);
}
},
schedule: async () => ({ outcome: "success" }),
// Step-inversion (KTD-2/KTD-4, U3): run exactly the foreach-active step.
// The foreach sub-walk has set `foreach:active` with the step index; here
// we drive runTaskStep (step-runner.ts) over the task's worktree, then
// capture the per-step baselineSha/checkpointId back INTO the active
// context object so a later RETHINK (U5) can reset the step. The full
// single-step session physics (a StepSessionExecutor scoped to one step)
// is U5/U7 territory; U3 wires the seam and the context capture, using the
// existing implementation phase as the single-pass step driver.
stepExecute: async (seamTask, context) => {
const active = context[FOREACH_ACTIVE_CONTEXT_KEY] as ForeachActiveContext | undefined;
if (!active || typeof active.stepIndex !== "number") {
return { outcome: "failure", value: "no-active-step-instance" };
}
const live = await deps.store.getTask(seamTask.id);
// Worktree isolation (KTD-11, U10): run the instance's session in ITS OWN
// worktree when the foreach allocated one; otherwise the task's main
// worktree (shared isolation — unchanged). The file-scope guard the session
// machinery installs applies to either worktree unchanged (not bypassed).
// Stamp the active instance so `runGraphTaskStep` can honor
// `deferDoneToReview` when judging a non-terminal step (FIX 3).
deps.graphStepActiveContext.set(graphActiveContextKey(seamTask.id, active.instanceId), active);
// Column-agent seam wiring (U4, R4): the governing node id — the foreach
// INSTANCE node id (`<foreachId>#<i>:<templateNodeId>`) stamped into
// context by createPromptLikeHandler — threads INTO runGraphTaskStep,
// which stamps the per-task slot only when it CREATES the memoized
// implementation pass and clears it when that pass settles (PR #1432
// review). One step-session pass serves every instance, so the
// session-identity binding is deterministically the pass-initiating
// instance's; per-invocation set/delete here would race under parallel
// foreach (overwrite mid-build, or clear while the shared pass is live).
const stepGoverningNodeId = context[SEAM_GOVERNING_NODE_CONTEXT_KEY];
const seamThinkingLevel = context[SEAM_THINKING_LEVEL_CONTEXT_KEY];
const seamSkillName = context[SEAM_SKILL_NAME_CONTEXT_KEY];
const result = await deps.runProjectedGraphTaskStep(
seamTask,
live,
active.stepIndex,
active,
typeof stepGoverningNodeId === "string" ? stepGoverningNodeId : undefined,
typeof seamThinkingLevel === "string" && WORKFLOW_THINKING_LEVEL_SET.has(seamThinkingLevel)
? (seamThinkingLevel as ThinkingLevel)
: undefined,
typeof seamSkillName === "string" && seamSkillName.trim() ? seamSkillName.trim() : undefined,
);
// Capture baseline/checkpoint back into the reserved active context so the
// foreach sub-walk threads them to later template nodes (step-review/reset).
active.baselineSha = result.baselineSha;
active.checkpointId = result.checkpointId;
/*
FNXC:WorkflowExecutionOwnership 2026-07-29-11:30 (U8 / R4):
`step-done` / `step-failed` was a two-value flattening of every possible ending, and it
is why the pending-review ending could never reach an edge on the stepwise shape. A
blocked-on-pending-review pass is a WAIT, not a step defect: the outcome stays `failure`
(the step genuinely did not complete) while the VALUE names the ending, which is what the
foreach propagates upward — `runForeach` returns a failing instance's value as its own —
so the `steps` node can carry an `outcome:review-pending` edge to the park node.
Every other ending keeps `step-failed` exactly as before.
*/
const failureValue = result.exit === "review-handoff-pending-review" ? "review-pending" : "step-failed";
return {
outcome: result.outcome,
value: result.outcome === "success" ? "step-done" : failureValue,
contextPatch: {
[FOREACH_ACTIVE_CONTEXT_KEY]: active,
},
};
},
// Step-inversion (KTD-4, U5): review the foreach-active step. Mirrors the
// legacy in-session review call (deleted in U10): run
// reviewStep under semaphore.runNested against the instance's step number/
// name and the task's PROMPT content. On an authoritative (non-advisory)
// APPROVE, mark the step done through the projection (updateStep, KTD-7) —
// the step-execute seam left it in-progress (markDoneOnSuccess:false) so the
// review is the single done authority. The handler maps the returned verdict
// to outcome edges and applies the UNAVAILABLE bounded-retry limiter.
stepReview: async (seamTask, context, config) => {
const active = context[FOREACH_ACTIVE_CONTEXT_KEY] as ForeachActiveContext | undefined;
if (!active || typeof active.stepIndex !== "number") {
// No active instance — surface UNAVAILABLE so the handler routes it
// rather than fabricating an authoritative verdict.
return { verdict: "UNAVAILABLE", review: "no active step instance" };
}
const stepIndex = active.stepIndex;
const detail = await deps.store.getTask(seamTask.id);
// Worktree isolation (KTD-11): review the instance's OWN worktree when set.
const worktreePath = active.worktreePath || detail.worktree || deps.rootDir;
const reviewCwd = resolveReviewCheckoutCwd(detail, worktreePath);
logReviewCheckoutRouting(seamTask.id, detail, reviewCwd, worktreePath);
const stepName = detail.steps[stepIndex]?.name ?? `Step ${stepIndex}`;
const promptContent = detail.prompt ?? "";
const userComments = selectUserCommentsForAgentContext(detail, { limit: null });
// Merge per-task effective workflow settings (U3, KTD-3) so the validator
// model-lane reads below pick up workflow values. Behavior-inert by default.
const settings = await mergeEffectiveSettings(deps.store, detail, await deps.store.getSettings());
/*
FNXC:AgentSteering 2026-06-30-12:37:
Workflow graph step-review nodes are optional or mandatory reviewer gates. Pass canonical user comments and legacy steering into each per-cwd reviewer so workspace aggregation never drops operator requirements.
FNXC:AgentSteering 2026-06-30-13:20:
Graph reviewer gates request uncapped comment context because every user-authored requirement can affect approval, including older steering retained on long-running tasks.
*/
const sem = deps.options.semaphore;
// FNXC:Workspace 2026-06-22-00:30: KTD3 — step-inversion review seam loops per sub-repo.
// `reviewStep` stays single-cwd; THIS CALLER loops. Single-cwd by default reviews
// `worktreePath`; in workspace mode that is the browse-only non-git root, so we instead spawn
// one reviewer per acquired sub-repo (cwd = repo.worktreePath) via reviewWorkspacePerRepo and
// aggregate as a conjunction. `invokeReviewerForCwd` is the per-cwd reviewStep call both modes share.
const reviewService = new WorkflowReviewService();
const invokeReviewerForCwd = (cwd: string) =>
reviewService.reviewStep({
cwd,
taskId: seamTask.id,
stepIndex,
stepName,
type: config.type,
promptContent,
// Code reviews diff against the per-step baseline captured at
// step-execute; plan reviews pass no baseline (advisory).
baselineSha: config.type === "code" ? active.baselineSha : undefined,
options: {
defaultProvider: settings.defaultProvider,
defaultModelId: settings.defaultModelId,
fallbackProvider: settings.fallbackProvider,
fallbackModelId: settings.fallbackModelId,
/*
* FNXC:Settings-ThinkingLevel 2026-07-13-00:27:
* Step-review model sessions honor per-node `config.thinkingLevel` before the task validator override, then shared task thinking, validator workflow lane, global lane, and default thinking settings.
*/
defaultThinkingLevel: resolveValidatorThinkingLevel(
typeof config.thinkingLevel === "string" && WORKFLOW_THINKING_LEVEL_SET.has(config.thinkingLevel)
? (config.thinkingLevel as ThinkingLevel)
: detail.validatorThinkingLevel ?? detail.thinkingLevel,
settings,
),
fallbackThinkingLevel: resolveValidatorFallbackThinkingLevel(
typeof config.thinkingLevel === "string" && WORKFLOW_THINKING_LEVEL_SET.has(config.thinkingLevel)
? (config.thinkingLevel as ThinkingLevel)
: detail.validatorThinkingLevel ?? detail.thinkingLevel,
settings,
),
taskValidatorProvider: detail.validatorModelProvider,
taskValidatorModelId: detail.validatorModelId,
taskValidatorCredentialInstanceId: detail.validatorCredentialInstanceId,
projectValidatorProvider: settings.validatorProvider,
projectValidatorModelId: settings.validatorModelId,
projectValidatorFallbackProvider: settings.validatorFallbackProvider,
projectValidatorFallbackModelId: settings.validatorFallbackModelId,
globalValidatorProvider: settings.validatorGlobalProvider,
globalValidatorModelId: settings.validatorGlobalModelId,
projectDefaultOverrideProvider: settings.defaultProviderOverride,
projectDefaultOverrideModelId: settings.defaultModelIdOverride,
store: deps.store,
taskId: seamTask.id,
task: detail,
userComments: userComments.length > 0 ? userComments : undefined,
agentPrompts: settings.agentPrompts,
agentStore: deps.options.agentStore ?? undefined,
rootDir: deps.rootDir,
settings,
/* FNXC:WorkflowAgentRouting 2026-08-07-04:45: reviewer sessions inherit the exact graph-fenced principal, including a node-local override. */
agentId: deps.activeWorkflowPrincipals.get(seamTask.id)?.agentId,
onSessionCreated: (s) => deps.registerSubagentSession(seamTask.id, s),
onSessionEnded: (s) => deps.unregisterSubagentSession(seamTask.id, s),
},
});
const runForCwd = (cwd: string): Promise<{ verdict: ReviewVerdict; review: string; summary: string }> => {
const invoke = () => invokeReviewerForCwd(cwd);
return sem ? sem.runNested(invoke) : invoke();
};
const invokeReviewer = () =>
deps.workspaceConfig && reviewCwd === worktreePath
? deps.reviewWorkspacePerRepo(detail, (cwd: string) => runForCwd(cwd))
: runForCwd(reviewCwd);
let review: { verdict: ReviewVerdict; review: string; summary: string };
try {
review = await invokeReviewer();
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
reviewerLog.error(`${seamTask.id}: step-review failed: ${message}`);
const narration = buildReviewUnavailableMessage(err);
void emitProactiveStatus(deps.store, seamTask.id, narration, "reviewer", sanitizeFailureReason(err));
return { verdict: "UNAVAILABLE", review: `reviewer error: ${message}` };
}
await deps.store.logEntry(
seamTask.id,
`${config.type} step-review Step ${stepIndex}: ${review.verdict}${config.advisory ? " (advisory)" : ""}`,
review.summary,
);
const narration = config.type === "plan" && review.verdict === "APPROVE"
? buildPlanVerifiedMessage()
: review.verdict === "UNAVAILABLE"
? buildReviewUnavailableMessage(review.summary)
: buildReviewVerdictMessage(review.verdict, review.summary);
if (review.verdict === "RETHINK") {
// RETHINK's rollback claim is emitted by applyGraphRethinkReset only after reset succeeds.
deps.graphRethinkNarrations.set(graphActiveContextKey(seamTask.id, active.instanceId), review.summary);
} else {
void emitProactiveStatus(deps.store, seamTask.id, narration, "reviewer", narration ? sanitizeFailureReason(review.summary) : undefined);
}
// Single-writer rule (KTD-4): advisory (split-branch) reviews never write
// the projection — they are fan-out checks that cannot clobber the
// authoritative verdict. Only an on-path APPROVE marks the step done.
if (review.verdict === "APPROVE" && !config.advisory) {
try {
const cur = await deps.store.getTask(seamTask.id);
const status = cur.steps[stepIndex]?.status;
if (stepIndex >= 0 && stepIndex < cur.steps.length && status !== "done" && status !== "skipped") {
await deps.updateStepGraph(seamTask.id, stepIndex, "done");
await deps.store.logEntry(
seamTask.id,
`Step ${stepIndex} (${stepName}) marked done by step-review APPROVE (graph)`,
);
}
} catch (err) {
reviewerLog.warn(
`${seamTask.id}: failed to mark Step ${stepIndex} done after APPROVE: ${err instanceof Error ? err.message : String(err)}`,
);
}
}
return { verdict: review.verdict, review: review.review, summary: review.summary };
},
};
}

376
packages/engine/src/executor/create-spawn-agent-tool.ts Normal file
View File

@@ -0,0 +1,376 @@
/**
* FNXC:CodeOrganization 2026-08-03-12:35:
* createSpawnAgentTool peeled from TaskExecutor (U4).
*
* FNXC:CapacityModel 2026-07-29-14:10:
* fn_spawn_agent gates on project agent count (and worktree budget), not private spawn caps.
*
* FNXC:CapacityModel 2026-07-29-19:20:
* Reserve the spawn slot synchronously before the first await (TOCTOU).
*
* FNXC:CapacityModel 2026-08-01-02:40:
* Also gate live children against maxWorktrees at acquisition.
*
* FNXC:WorkflowResolvedColumns 2026-08-01-03:05:
* Terminal worktree holders are role-resolved, not done/archived literals.
*/
import { Type, type Static } from "@earendil-works/pi-ai";
import type {
AgentCapability,
AgentState,
AgentStore,
Settings,
TaskStore,
} from "@fusion/core";
import { resolveExecutorFallbackModel, resolveProjectColumnsForRoles } from "@fusion/core";
import type { ToolDefinition, AgentSession } from "@earendil-works/pi-coding-agent";
import {
createResolvedAgentSession,
extractRuntimeHint,
resolveExecutorSessionModel,
resolveExecutorFallbackThinkingLevel,
} from "../agents/agent-session-helpers.js";
import { buildSessionSkillContext } from "../cli-runtime/session-skill-context.js";
import { computeTopLevelConcurrencyClaimedFromStore } from "../concurrency/concurrency.js";
import { buildSystemPromptWithInstructions } from "../agents/agent-instructions.js";
import { generateWorktreeName } from "../worktree/worktree-names.js";
import { resolveTaskWorktreePath } from "../worktree/worktree-paths.js";
import { createRunAuditor, type EngineRunContext } from "../util/run-audit.js";
import { executorLog } from "../logger.js";
import type { PluginRunner } from "../plugins/plugin-runner.js";
export const spawnAgentParams = Type.Object({
name: Type.String({ description: "Name for the child agent" }),
role: Type.Union([
Type.Literal("triage"),
Type.Literal("executor"),
Type.Literal("reviewer"),
Type.Literal("merger"),
Type.Literal("engineer"),
Type.Literal("custom"),
], { description: "Role for the child agent" }),
task: Type.String({ description: "Task description for the child agent to execute" }),
systemPromptOverride: Type.Optional(
Type.String({
description:
"Optional persona/system-prompt for the child agent. When provided (non-empty), it replaces the generic child base prompt so the child runs as a specific persona (e.g. a compound-engineering reviewer). Executor instructions are still appended.",
}),
),
});
/** Result returned from fn_spawn_agent tool */
export interface SpawnAgentResult {
agentId: string;
name: string;
state: AgentState;
role: AgentCapability;
message: string;
}
export type CreateSpawnAgentToolDeps = {
store: TaskStore;
rootDir: string;
agentStore?: AgentStore | null;
pluginRunner?: PluginRunner;
/** Live spawn counter owned by TaskExecutor (check-and-reserve TOCTOU). */
getTotalSpawnedCount: () => number;
setTotalSpawnedCount: (n: number) => void;
childSessions: Map<string, AgentSession>;
spawnedAgents: Map<string, Set<string>>;
createWorktree: (
branch: string,
path: string,
taskId: string,
startPoint?: string,
) => Promise<{ path: string; branch: string }>;
resolveInstructionsForRole: (role: string, settings: Settings) => Promise<string>;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- MCP server map shape is owned by session helpers
resolveMcpServers: (agentId: string) => Promise<any>;
runSpawnedChild: (agentId: string, session: AgentSession, taskPrompt: string) => Promise<void>;
};
/**
* Create the fn_spawn_agent tool definition.
* Allows the parent agent to spawn child agents with delegated tasks.
*/
export function createSpawnAgentTool(
deps: CreateSpawnAgentToolDeps,
taskId: string,
worktreePath: string,
settings: Settings,
taskEnv?: NodeJS.ProcessEnv,
): ToolDefinition {
return {
name: "fn_spawn_agent",
label: "Spawn Agent",
description:
"Spawn a child agent to handle parallel work or specialized sub-tasks. " +
"Each child runs in its own git worktree (branched from your worktree) and executes autonomously. " +
"When you end (fn_task_done), all spawned children are terminated.",
parameters: spawnAgentParams,
execute: async (_id: string, params: Static<typeof spawnAgentParams>) => {
const { name, role, task: taskPrompt, systemPromptOverride } = params;
// Check if AgentStore is available
if (!deps.agentStore) {
return {
content: [{ type: "text" as const, text: "Agent spawning is not available (no AgentStore configured)" }],
details: { agentId: "", state: "error" },
};
}
/*
FNXC:CapacityModel 2026-07-29-14:10 (two numbers — spawned agents count):
`maxSpawnedAgentsPerParent` (5) and `maxSpawnedAgentsGlobal` (20) are DELETED.
They were a THIRD and FOURTH limiter with their own private budgets, invisible
to the two the operator configures — and they measured the wrong thing: a
child that finished still counted against `totalSpawnedCount` until its parent
task ended, so the cap throttled cumulative spawns rather than concurrent ones.
A spawned child IS an agent and runs in its own git worktree (branched from the
parent's), so it consumes both configured dimensions. It now checks the SAME
project agent count every other lane checks, via the shared live-claim helper —
one number, one answer, no private budget that can disagree with the board.
This closes a real hole rather than only deleting knobs: children were counted
by NEITHER capacity gate, so a fan-out could put up to 20 extra worktrees on
disk while the scheduler believed the project was at its limit.
*/
const spawnClaimed = await computeTopLevelConcurrencyClaimedFromStore({
store: deps.store,
tasks: await deps.store.listTasks({ slim: true, includeArchived: false }),
});
const spawnCap = settings.maxConcurrent ?? 2;
const liveChildren = deps.getTotalSpawnedCount();
if (spawnClaimed + liveChildren >= spawnCap) {
return {
content: [{
type: "text" as const,
text: `Agent capacity reached (${spawnClaimed + liveChildren}/${spawnCap} running, including ${liveChildren} spawned child agent(s)). Wait for work to finish, or raise Max Concurrent Tasks.`,
}],
details: { agentId: "", state: "error" },
};
}
/*
FNXC:CapacityModel 2026-07-29-19:20 (PR #2579 review — greptile P1, TOCTOU):
RESERVE THE SLOT SYNCHRONOUSLY, before the first await.
The check above reads capacity, then several awaits follow (createAgent,
createWorktree, updateAgentState) before `totalSpawnedCount` was incremented.
Two parents calling fn_spawn_agent with one slot left both passed the check
and both spawned — more agents and more worktrees than Max Concurrent Tasks
permits, which is the very hole this change set out to close.
JS is single-threaded, so incrementing here — with NO await between the read
and the increment — makes check-and-reserve atomic against every other spawn
call. The reservation is rolled back on any failure below, and the success
path no longer double-counts.
*/
deps.setTotalSpawnedCount(deps.getTotalSpawnedCount() + 1);
let spawnReservationHeld = true;
const releaseSpawnReservation = () => {
if (!spawnReservationHeld) return;
spawnReservationHeld = false;
deps.setTotalSpawnedCount(Math.max(0, deps.getTotalSpawnedCount() - 1));
};
/*
FNXC:CapacityModel 2026-08-01-02:40 (same class as the planning-admission gap, 374956ef23):
The FNXC above says a child "consumes both configured dimensions" — and then gated only ONE.
A child's worktree is not a task row, so the task-ledger gates never see it; count live
children against the worktree budget here at the acquisition source, like planning admission
now does. Runs AFTER the synchronous agent-slot reservation (its own TOCTOU rule: the awaits
in this check must not reopen the two-racing-spawns hole — the reservation is already held,
and a worktree refusal unwinds it). Absent/null maxWorktrees (worktrees off) falls through
to the agent gate alone, matching every other lane.
*/
{
const spawnMaxWorktrees = (settings as { maxWorktrees?: number | null }).maxWorktrees ?? 4;
if (typeof spawnMaxWorktrees === "number" && Number.isFinite(spawnMaxWorktrees)) {
const spawnTasks = await deps.store.listTasks({ slim: true, includeArchived: false });
/*
FNXC:WorkflowResolvedColumns 2026-08-01-03:05:
TERMINAL IS A ROLE, NOT A NAME — same conversion as the planning-admission ledger this
gate was copied from. Against the literals a RENAMED board matches neither `done` nor
`archived`, so finished cards keep counting as live worktree holders, `heldWorktrees`
only ever grows, and every spawn is refused on a board with free slots. A permanent
refusal is worse than the over-spawn this gate exists to prevent, because it is silent.
PROJECT-level (`resolveProjectColumnsForRoles`) because the ledger spans the whole
board with no single task to resolve against; it is legacy-seeded, so a default board
still excludes exactly `done` and `archived` and this is byte-identical there.
*/
const spawnTerminalColumns = await resolveProjectColumnsForRoles(deps.store, ["complete", "archived"]);
const heldWorktrees = spawnTasks.filter((t) =>
!spawnTerminalColumns.has(t.column)
&& typeof t.worktree === "string" && t.worktree.length > 0).length;
// totalSpawnedCount already includes THIS reservation; heldWorktrees covers task lanes.
if (heldWorktrees + deps.getTotalSpawnedCount() > spawnMaxWorktrees) {
releaseSpawnReservation();
return {
content: [{
type: "text" as const,
text: `Worktree capacity reached (${heldWorktrees + deps.getTotalSpawnedCount() - 1}/${spawnMaxWorktrees} held, including spawned child agent(s)). Wait for work to finish, or raise Max Worktrees.`,
}],
details: { agentId: "", state: "error" },
};
}
}
}
try {
// Create agent in AgentStore with reportsTo = parent task ID
const agent = await deps.agentStore.createAgent({
name: name.trim(),
role: role as AgentCapability,
reportsTo: taskId,
metadata: { type: "spawned", parentTaskId: taskId },
});
// Create git worktree for child (branched from parent's worktree)
const childWorktreeName = generateWorktreeName(deps.rootDir, settings);
const childWorktreePath = resolveTaskWorktreePath(deps.rootDir, settings, childWorktreeName);
const childBranch = `fusion/spawn-${agent.id}`;
await deps.createWorktree(childBranch, childWorktreePath, taskId, worktreePath);
// Transition agent to active state
await deps.agentStore.updateAgentState(agent.id, "active");
// Child agents inherit executor instructions
const childInstructions = await deps.resolveInstructionsForRole("executor", settings);
// A non-empty systemPromptOverride lets the caller run the child as a
// specific persona (e.g. a compound-engineering reviewer) instead of the
// generic child executor. Executor instructions are still appended below.
//
// (U9 / KTD-7) The engine does NOT itself resolve the persona def file —
// the calling skill reads `$FUSION_CE_AGENTS_DIR/<persona>.md` (the
// FUSION_WORKFLOW_STEP_CONVENTIONS_PREAMBLE instructs a path-confined
// read: confined to the install dir, `../` rejected, body-size sanity
// checked) and passes the stripped body here. The override body is
// therefore trusted only to the extent that read was confined; the
// agents dir is plugin-installer-owned and lives OUTSIDE the task
// worktree (so coding-mode plan/code-review steps can't write into it —
// see assertPluginLocalAgentsTarget in the CE plugin installer).
const personaOverride = systemPromptOverride?.trim();
const childBasePrompt = personaOverride
? `${personaOverride}
Parent task: ${taskId}
Child agent: ${agent.id} (${name})`
: `You are a child agent spawned by a parent task executor.
Your role:
- Complete the delegated task in your own worktree.
- Work autonomously, but stay tightly scoped to the delegated request.
- Prefer existing project patterns over inventing new ones.
- Run relevant tests and report what you verified.
- Do not widen scope or refactor unrelated areas.
Output expectations:
- Provide a concise summary of what you changed.
- Call out files touched and validations run.
- Explicitly mention unresolved blockers if you could not finish.
Parent task: ${taskId}
Child agent: ${agent.id} (${name})`;
const childSystemPrompt = buildSystemPromptWithInstructions(childBasePrompt, childInstructions);
// Build skill selection context for child agent session
const childTask = await deps.store.getTask(taskId);
const skillContext = await buildSessionSkillContext({
agentStore: deps.agentStore!,
task: childTask,
sessionPurpose: "executor",
projectRootDir: deps.rootDir,
pluginRunner: deps.pluginRunner,
});
const parentAgent = childTask.assignedAgentId
? await deps.agentStore.getAgent(childTask.assignedAgentId).catch(() => null)
: null;
const childRuntimeHint = extractRuntimeHint(agent.runtimeConfig)
?? extractRuntimeHint(parentAgent?.runtimeConfig);
// Resolve executor model via canonical lane hierarchy so child agents
// honor project executionProvider/executionModelId overrides (parity
// with main executor at the top of agentWork()).
const childExecutorSessionModel = resolveExecutorSessionModel(
undefined,
undefined,
settings,
agent.runtimeConfig as Record<string, unknown> | undefined,
);
const { provider: childExecutorProvider, modelId: childExecutorModelId } = childExecutorSessionModel;
const childExecutorFallback = resolveExecutorFallbackModel(settings);
// Create child agent session
const { session: childSession } = await createResolvedAgentSession({
sessionPurpose: "executor",
runtimeHint: childRuntimeHint,
pluginRunner: deps.pluginRunner,
cwd: childWorktreePath,
systemPrompt: childSystemPrompt,
tools: "coding",
defaultProvider: childExecutorProvider,
defaultModelId: childExecutorModelId,
...(childExecutorSessionModel.credentialInstanceId ? { credentialInstanceId: childExecutorSessionModel.credentialInstanceId } : {}),
fallbackProvider: childExecutorFallback.provider,
fallbackModelId: childExecutorFallback.modelId,
fallbackThinkingLevel: resolveExecutorFallbackThinkingLevel(undefined, settings),
runAuditor: createRunAuditor(deps.store, deps.getRunContextFor(taskId)),
settings,
taskEnv,
mcpServers: await deps.resolveMcpServers(agent.id),
// FNXC:SessionRouting 2026-06-24-11:20:
// #1675: propagate task id so child-agent requests carry the same
// X-Session-Id/X-Session-Affinity as the parent task session.
taskId,
// FNXC:PluginSkills 2026-07-12-00:00: Child-agent sessions inherit plugin skill body directories from the task skill context so delegated work can load plugin skill guidance.
...(skillContext.skillSelectionContext ? { skillSelection: skillContext.skillSelectionContext } : {}),
...(skillContext.additionalSkillPaths.length > 0 ? { additionalSkillPaths: skillContext.additionalSkillPaths } : {}),
});
// Store tracking state
deps.childSessions.set(agent.id, childSession);
if (!deps.spawnedAgents.has(taskId)) {
deps.spawnedAgents.set(taskId, new Set());
}
deps.spawnedAgents.get(taskId)!.add(agent.id);
// The slot was already reserved before the awaits above; converting the
// reservation into the live count is a no-op rather than a second increment.
spawnReservationHeld = false;
// Run child asynchronously (don't await — parent continues working)
deps.runSpawnedChild(agent.id, childSession, taskPrompt).catch((err: unknown) => {
const errorMessage = err instanceof Error ? err.message : String(err);
executorLog.warn(`Child agent ${agent.id} async error: ${errorMessage}`);
});
const result: SpawnAgentResult = {
agentId: agent.id,
name: agent.name,
state: "running",
role: agent.role,
message: `Agent "${name}" spawned and executing task: ${taskPrompt.slice(0, 100)}${taskPrompt.length > 100 ? "..." : ""}`,
};
return {
content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
details: result,
};
} catch (err: unknown) {
// FNXC:CapacityModel 2026-07-29-19:20: a failed spawn must return the slot
// it reserved, or a project permanently loses capacity to a spawn that
// never happened.
releaseSpawnReservation();
const errorMessage = err instanceof Error ? err.message : String(err);
return {
content: [{ type: "text" as const, text: `Failed to spawn agent: ${errorMessage}` }],
details: { agentId: "", state: "error", message: errorMessage },
};
}
},
};
}

546
packages/engine/src/executor/create-task-done-tool.ts Normal file
View File

@@ -0,0 +1,546 @@
/**
* FNXC:CodeOrganization 2026-08-03-13:10:
* createTaskDoneTool peeled from TaskExecutor (U4).
*
* FNXC:Lifecycle 2026-07-16-10:20:
* FN-8141: outcome=blocked is the sanctioned honest exit (no completion claim).
*
* FNXC:HonestBlockedExit 2026-08-02-23:59:
* Blocked exits classify on Fusion task dependencies only (no open-PR blockers).
*
* FNXC:WorkflowResolvedColumns 2026-07-31-09:20:
* Completed-task watchdog arms on resolved WIP column, not literal in-progress.
*/
import { Type } from "@earendil-works/pi-ai";
import type { Settings, Task, TaskDetail, TaskRecommendation, TaskStore } from "@fusion/core";
import {
parseNoOpCompletionMarker,
resolveWipTargetForTask,
} from "@fusion/core";
import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
import type { ReviewVerdict } from "../execution/reviewer.js";
import {
BLOCKED_THRASH_LIMIT,
buildExternalBlockMetadataPatch,
classifyBlockedExit,
countBlockedThrashHits,
partitionBlockedByRefs,
} from "../execution-block-classifier.js";
import { moveTaskToReplanColumn, resolveReplanTargetColumn } from "../execution/replan-target.js";
import { mergeEffectiveSettings } from "../project/effective-settings.js";
import { generateSyntheticRunId, type EngineRunContext, type RunAuditor } from "../util/run-audit.js";
import { executorLog } from "../logger.js";
import { resolveReboundColumnFor } from "./lifecycle-columns.js";
import { evaluateTaskDoneRefusal } from "./task-done-refusal.js";
import { skipBypassTaintUpdateForRefusal } from "./completion-predicates.js";
import { MAX_TASK_DONE_REQUEUE_RETRIES } from "./task-done-refusal-handler.js";
import { validateCompletionRecommendations } from "./validate-completion-recommendations.js";
import type { FinalizeAcceptedNoOpCompletionParams } from "./plan-review-no-op.js";
export type CreateTaskDoneToolDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
workflowLifecycleMovesInFlight: Set<string>;
persistTokenUsage: (taskId: string) => Promise<void>;
getTaskCompletionBlocker: (task: Task) => Promise<string | undefined>;
evaluateTaskVerdictProviders: (
task: TaskDetail,
opts: Record<string, unknown>,
) => Promise<{ ok: true } | { ok: false; message: string }>;
verifyWorktreeInvariants: (
task: Task,
worktreePathOverride?: string,
allowReanchor?: boolean,
options?: { noOpCompletion?: boolean; noOpCompletionReason?: string },
) => Promise<
| { ok: true }
| { ok: false; reason: string; observed: string; expected: string; repo?: string }
>;
evaluateTaskDoneScopeLeak: (
task: Task,
worktreePath: string,
promptContent: string,
settings: Settings,
audit?: RunAuditor,
) => Promise<{ blocked: false } | { blocked: true; message: string }>;
scheduleCompletedTaskWatchdog: (taskId: string, source: string) => void;
/**
* FNXC:PlanReviewNoOp 2026-08-09-22:10:
* Shared terminalization for PREMISE STALE / DUPLICATE no-op completion (FN-8841).
*/
finalizeAcceptedNoOpCompletion: (
params: FinalizeAcceptedNoOpCompletionParams,
) => Promise<{ completed: boolean; hardPauseActive: boolean }>;
};
/**
* Create fn_task_done for the executor coding session.
* `codeReviewVerdicts` retained for refusal evaluation compatibility.
*/
export function createTaskDoneTool(
deps: CreateTaskDoneToolDeps,
taskId: string,
worktreePath: string,
promptContent: string,
codeReviewVerdicts: Map<number, ReviewVerdict>,
onDone: () => void,
audit?: RunAuditor,
): ToolDefinition {
const store = deps.store;
return {
name: "fn_task_done",
label: "Mark Task Done",
description:
"End the task. With outcome=\"completed\" (default): signal that all steps are complete, tests pass, and " +
"documentation is updated — call as the final action after finishing all work; automatically marks all " +
"remaining steps as done. At this accepted final checkpoint, when recommendation capture is enabled, submit up to " +
"the project cap of genuine, task-ready out-of-scope recommendations with stable unique ids, or explicitly send " +
"recommendations: [] when none qualify; at cap 0, omit recommendations (an empty list is accepted for compatibility). " +
"Do not use recommendations for required fixes, blockers, secrets, commands, or reasoning. " +
"With outcome=\"blocked\": honestly park the task when the work genuinely cannot proceed (upstream API break, " +
"missing dependency task, unresolvable external blocker). Blocked is NOT a completion claim — it does not " +
"trip the review/completion gates, does not auto-complete or auto-skip steps, and preserves your worktree/" +
"branch/step progress so the task can be requeued once the blocker clears. Prefer blocked over marking steps " +
"skipped when the task cannot be finished.",
parameters: Type.Object({
summary: Type.Optional(Type.String({
description: "Optional summary of what was changed/fixed and what was verified (2-4 sentences). Used when outcome=\"completed\".",
})),
/*
FNXC:TaskRecommendations 2026-08-08-05:02:
Capture optional out-of-scope follow-ups only after every completion gate accepts.
*/
recommendations: Type.Optional(Type.Array(Type.Object({
id: Type.String(),
title: Type.String(),
description: Type.String(),
category: Type.Union([Type.Literal("improvement"), Type.Literal("feature"), Type.Literal("bug"), Type.Literal("other")]),
}), { description: "For accepted completed outcomes when capture is enabled: submit at most the project cap of task-ready out-of-scope suggestions with unique stable ids, or [] when none qualify. At cap 0, omit this field; an empty list is accepted for compatibility but populated input is rejected. Never send for blocked/refused outcomes or include mandatory fixes, secrets, executable commands, or reasoning." })),
/*
FNXC:Lifecycle 2026-07-16-10:20:
FN-8141 laundered a genuinely-impossible task into `done`: fn_task_done only expressed success, the bulk-completion
gate refused it, the requeue budget re-ran the doomed task 5 times, and the only remaining affordance (skip every
step) made `isTaskComplete()` return true so self-healing + the AI merger finalized an empty diff as done. The
`blocked` outcome is the sanctioned honest exit: it parks the task `failed` (error `BLOCKED: <reason>`) without any
completion claim, so laundering is never the cheapest path.
*/
outcome: Type.Optional(Type.Union(
[Type.Literal("completed"), Type.Literal("blocked")],
{ description: "\"completed\" (default) finishes the task; \"blocked\" honestly parks it as failed because the work cannot proceed. Use \"blocked\" instead of skipping steps + completing when you are stuck." },
)),
blockedBy: Type.Optional(Type.Array(Type.String(), {
description: "When outcome=\"blocked\": Fusion task IDs (e.g. [\"FN-8145\"]) that must complete before this task can proceed. Task IDs become real dependency edges. Open GitHub PRs are not valid blockers.",
})),
reason: Type.Optional(Type.String({
description: "Required when outcome=\"blocked\": concrete explanation of what is blocking the work and what is needed to unblock it.",
})),
}),
execute: async (_id: string, params: { summary?: string; recommendations?: TaskRecommendation[]; outcome?: "completed" | "blocked"; blockedBy?: string[]; reason?: string }) => {
/*
FNXC:Lifecycle 2026-07-16-10:20:
FN-8141 — the blocked exit runs BEFORE every completion gate (completion blocker, verdict providers, worktree
invariants, bulk-completion refusal). Blocked is not a completion claim, so none of those gates apply; parking
`failed` with a `BLOCKED:` error + real dependency edges is the whole action. Steps keep their true statuses
(no auto-done, no auto-skip) so a laundered "all steps skipped ⇒ complete" state can never form.
*/
if (params.outcome === "blocked") {
const reason = params.reason?.trim();
if (!reason) {
const message = "fn_task_done(outcome=\"blocked\") requires a non-empty `reason` describing what is blocking the work. Provide `reason` (and optional `blockedBy` task IDs) and call again.";
return {
content: [{ type: "text" as const, text: message }],
details: { error: message },
};
}
const blockedTask = await store.getTask(taskId);
const rawBlockedBy = Array.from(
new Set((params.blockedBy ?? []).map((id) => id.trim()).filter((id) => id.length > 0)),
);
/*
FNXC:HonestBlockedExit 2026-08-02-23:59 (operator decision — FN-8728 vs PR #2398):
Blocked exits classify on Fusion task dependencies ONLY. The FN-8700 file-claim/open-PR
classification is removed: open PRs are never blockers, legacy pr:N refs are discarded,
and reason prose never makes a block durable. Task deps → durable failed park (requeues
when deps complete); no deps → plan defect → needs-replan (FN-8634).
*/
const classification = classifyBlockedExit(reason, rawBlockedBy);
const { taskIds: blockedByIds } = partitionBlockedByRefs(rawBlockedBy);
const thrashCount = countBlockedThrashHits(
blockedTask.log,
classification.thrashSignature,
) + 1;
const thrashExhausted = !classification.allowAutoReplan && thrashCount >= BLOCKED_THRASH_LIMIT;
const parkError = thrashExhausted
? `BLOCKED: ${reason} [thrash-exhausted after ${thrashCount} identical durable blocks]`
: `BLOCKED: ${reason}`;
// Record blockedBy TASK ids as real dependency edges (union with existing).
const mergedDependencies = blockedByIds.length > 0
? Array.from(new Set([...(blockedTask.dependencies ?? []), ...blockedByIds]))
: undefined;
/*
FNXC:HonestBlockedExit 2026-08-01-01:40 (operator: FN-8634 "shouldn't show a failed badge"):
When `blockedBy` is EMPTY, park needs-replan (auto-replan) — nothing external to wait for.
Task-dependency blocks park failed so the scheduler leaves the card alone until deps complete.
*/
const autoReplanPark = classification.allowAutoReplan && blockedByIds.length === 0 && !thrashExhausted;
const metaPatch = !autoReplanPark
? buildExternalBlockMetadataPatch(classification, thrashCount)
: undefined;
if (autoReplanPark) {
const replanColumn = await resolveReplanTargetColumn(deps.store, taskId);
await store.logEntry(
taskId,
`${parkError} — no blocking dependencies recorded; parking for automatic replan in ${replanColumn} (steps preserved)`,
undefined,
deps.getRunContextFor(taskId),
);
deps.workflowLifecycleMovesInFlight.add(taskId);
try {
await moveTaskToReplanColumn(deps.store, { id: taskId, column: blockedTask.column }, replanColumn);
} finally {
deps.workflowLifecycleMovesInFlight.delete(taskId);
}
await store.updateTask(taskId, {
status: "needs-replan",
error: null,
paused: false,
pausedByAgentId: null,
}, deps.getRunContextFor(taskId));
} else {
await store.updateTask(taskId, {
status: "failed",
error: parkError,
paused: false,
pausedByAgentId: null,
...(mergedDependencies ? { dependencies: mergedDependencies } : {}),
...(metaPatch ? { sourceMetadataPatch: metaPatch } : {}),
}, deps.getRunContextFor(taskId));
await store.logEntry(
taskId,
thrashExhausted
? `${parkError} — durable external block thrash-exhausted (signature=${classification.thrashSignature}); parked failed, no auto-requeue`
: `${parkError} — recorded dependencies: ${blockedByIds.join(", ")} — parked failed (honest blocked exit; steps preserved)`,
undefined,
deps.getRunContextFor(taskId),
);
}
await deps.store.recordRunAuditEvent?.({
taskId,
agentId: "executor",
runId: generateSyntheticRunId("execution-blocked", taskId),
domain: "database",
mutationType: "task:execution-blocked-parked",
target: taskId,
metadata: {
taskId,
blockedBy: blockedByIds,
hasReason: true,
parkedAs: autoReplanPark ? "auto-replan" : "failed",
blockedClass: classification.class,
thrashCount,
thrashExhausted,
},
});
await deps.persistTokenUsage(taskId);
executorLog.log(
`⛔ ${taskId} ${
autoReplanPark
? "parked for automatic replan via blocked exit (plan defect, no dependencies)"
: thrashExhausted
? `parked failed via blocked thrash-exhaustion (class=${classification.class})`
: `parked failed via durable blocked exit (class=${classification.class}; blockedBy tasks: ${blockedByIds.join(", ") || "none"})`
}`,
);
return {
content: [{
type: "text" as const,
text: autoReplanPark
? "Task parked as blocked with no blocking task dependencies — queued for automatic replan so the plan can resolve the conflict. Steps left in their true statuses; no completion recorded."
: thrashExhausted
? "Task parked as blocked (failed) after repeated identical durable blocks — no further automatic retries. Resolve the blocking tasks or replan manually."
: `Task parked as blocked (failed). Recorded ${blockedByIds.length} blocking task dependency(ies); it will requeue once they complete. Steps left in their true statuses; no completion recorded.`,
}],
details: {},
};
}
const task = await store.getTask(taskId);
const completionBlocker = await deps.getTaskCompletionBlocker(task);
if (completionBlocker) {
return {
content: [{
type: "text" as const,
text: `Cannot mark task done yet — ${completionBlocker}. Resolve the blocker before calling fn_task_done().`,
}],
details: {},
};
}
const providerVerdict = await deps.evaluateTaskVerdictProviders(task, {
summary: params.summary,
source: "fn_task_done",
});
if (!providerVerdict.ok) {
await store.logEntry(taskId, providerVerdict.message, undefined, deps.getRunContextFor(task.id));
executorLog.error(`${taskId}: ${providerVerdict.message}`);
return {
content: [{ type: "text" as const, text: providerVerdict.message }],
details: {
error: providerVerdict.message,
},
};
}
const noOpMarker = parseNoOpCompletionMarker(params.summary);
const invariantCheck = await deps.verifyWorktreeInvariants(task, worktreePath, true, {
noOpCompletion: Boolean(noOpMarker),
noOpCompletionReason: noOpMarker
? `verified ${noOpMarker.kind} completion sentinel${noOpMarker.canonicalId ? ` (${noOpMarker.canonicalId})` : ""}`
: undefined,
});
if (!invariantCheck.ok) {
const refusalMessage = `fn_task_done refused: ${invariantCheck.reason} — observed=${invariantCheck.observed}, expected=${invariantCheck.expected}`;
await store.logEntry(taskId, refusalMessage, undefined, deps.getRunContextFor(task.id));
executorLog.error(`${taskId}: fn_task_done refused (${invariantCheck.reason}) — observed=${invariantCheck.observed}, expected=${invariantCheck.expected}`);
const priorRequeues = task.taskDoneRetryCount ?? 0;
const nextRequeueCount = priorRequeues + 1;
if (priorRequeues < MAX_TASK_DONE_REQUEUE_RETRIES) {
await store.updateTask(taskId, {
status: "queued",
error: null,
taskDoneRetryCount: nextRequeueCount,
paused: false,
pausedByAgentId: null,
worktree: null,
branch: null,
sessionFile: null,
});
await store.logEntry(
taskId,
`${refusalMessage} — requeued to todo immediately (${nextRequeueCount}/${MAX_TASK_DONE_REQUEUE_RETRIES})`,
undefined,
deps.getRunContextFor(task.id),
);
await store.moveTask(taskId, await resolveReboundColumnFor(store, taskId), { preserveProgress: true });
executorLog.log(`✗ ${taskId} failed invariant check — requeued to todo (${nextRequeueCount}/${MAX_TASK_DONE_REQUEUE_RETRIES})`);
} else {
await store.updateTask(taskId, {
status: "failed",
error: refusalMessage,
paused: false,
pausedByAgentId: null,
worktree: null,
branch: null,
sessionFile: null,
});
await store.logEntry(taskId, `${refusalMessage} — invariant-check retry budget exhausted`, undefined, deps.getRunContextFor(task.id));
await deps.persistTokenUsage(taskId);
executorLog.log(`✗ ${taskId} failed invariant check`);
}
return {
content: [{ type: "text" as const, text: refusalMessage }],
details: {
error: refusalMessage,
},
};
}
const taskDoneRefusal = evaluateTaskDoneRefusal(task, params, codeReviewVerdicts);
if (!taskDoneRefusal.ok) {
const refusalMessage = taskDoneRefusal.message;
await store.logEntry(taskId, refusalMessage, undefined, deps.getRunContextFor(task.id));
executorLog.error(`${taskId}: fn_task_done refused (${taskDoneRefusal.refusalClass}) — ${taskDoneRefusal.reason}`);
// FNXC:Lifecycle 2026-07-16-21:40: FN-8141 — stamp the skip-bypass taint marker so a
// later skip-then-exit (in this or a requeued lifecycle) cannot auto-promote.
const taintUpdate = skipBypassTaintUpdateForRefusal(taskDoneRefusal);
const priorRequeues = task.taskDoneRetryCount ?? 0;
const nextRequeueCount = priorRequeues + 1;
if (priorRequeues < MAX_TASK_DONE_REQUEUE_RETRIES) {
await store.updateTask(taskId, {
status: "queued",
error: null,
taskDoneRetryCount: nextRequeueCount,
...taintUpdate,
paused: false,
pausedByAgentId: null,
worktree: null,
branch: null,
sessionFile: null,
});
await store.logEntry(
taskId,
`${refusalMessage} — requeued to todo immediately (${nextRequeueCount}/${MAX_TASK_DONE_REQUEUE_RETRIES})`,
undefined,
deps.getRunContextFor(task.id),
);
await store.moveTask(taskId, await resolveReboundColumnFor(store, taskId), { preserveProgress: true });
executorLog.log(`✗ ${taskId} fn_task_done refusal (${taskDoneRefusal.refusalClass}) — requeued to todo (${nextRequeueCount}/${MAX_TASK_DONE_REQUEUE_RETRIES})`);
} else {
await store.updateTask(taskId, {
status: "failed",
error: refusalMessage,
...taintUpdate,
paused: false,
pausedByAgentId: null,
worktree: null,
branch: null,
sessionFile: null,
});
await store.logEntry(taskId, `${refusalMessage} — fn_task_done refusal retry budget exhausted`, undefined, deps.getRunContextFor(task.id));
await deps.persistTokenUsage(taskId);
executorLog.log(`✗ ${taskId} fn_task_done refusal (${taskDoneRefusal.refusalClass})`);
}
return {
content: [{ type: "text" as const, text: refusalMessage }],
details: {
error: refusalMessage,
refusalClass: taskDoneRefusal.refusalClass,
},
};
}
// Merge per-task effective workflow settings (U3, KTD-3) so the
// planOnlyScopeLeakEnforcement read in evaluateTaskDoneScopeLeak picks up
// workflow values. Behavior-inert by default.
const settings = await mergeEffectiveSettings(store, task, await store.getSettings());
const scopeLeakCheck = await deps.evaluateTaskDoneScopeLeak(task, worktreePath, promptContent, settings, audit)
.catch((error: unknown) => {
const errorMessage = error instanceof Error ? error.message : String(error);
executorLog.warn(`${taskId}: scope-leak guard failed open: ${errorMessage}`);
return { blocked: false } as const;
});
if (scopeLeakCheck.blocked) {
await store.logEntry(taskId, `[scope-leak] blocked fn_task_done: ${scopeLeakCheck.message}`, undefined, deps.getRunContextFor(task.id));
return {
content: [{ type: "text" as const, text: scopeLeakCheck.message }],
details: {
error: scopeLeakCheck.message,
},
};
}
const completionRecommendations = params.recommendations === undefined
? undefined
: validateCompletionRecommendations(params.recommendations, settings.maxRecommendationsPerTask ?? 3);
if (typeof completionRecommendations === "string") {
return {
content: [{ type: "text" as const, text: `Cannot mark task done yet — ${completionRecommendations}.` }],
details: { error: completionRecommendations },
};
}
if (noOpMarker) {
const completion = await deps.finalizeAcceptedNoOpCompletion({
task,
marker: noOpMarker,
summary: params.summary?.trim() || `${noOpMarker.kind.toUpperCase()}: ${noOpMarker.reason}`,
recommendations: completionRecommendations,
onDone,
});
if (!completion.completed) {
return {
content: [{ type: "text" as const, text: "Cannot mark task done because completion handoff was interrupted." }],
details: { error: "no-op-completion-interrupted" },
};
}
const successMessage = completion.hardPauseActive
? "Task marked complete. Completion handoff deferred until pause is cleared."
: params.summary
? "Task marked complete with summary. All steps done. Moving to in-review."
: "Task marked complete. All steps done. Moving to in-review.";
return { content: [{ type: "text" as const, text: successMessage }], details: {} };
}
onDone();
// Mark all pending/in-progress steps as done
for (let i = 0; i < task.steps.length; i++) {
if (task.steps[i].status !== "done" && task.steps[i].status !== "skipped") {
await store.updateStep(taskId, i, "done");
}
}
// FN-4106: preserve the original completion summary on workflow-step reruns.
const newSummary = params.summary?.trim();
if (newSummary) {
const currentTask = await store.getTask(taskId);
const existingSummary = currentTask.summary?.trim();
const hasRunWorkflowSteps = (currentTask.workflowStepResults?.length ?? 0) > 0;
const rerunSuffix = `---\nRerun after workflow step revision:\n${newSummary}`;
if (existingSummary && hasRunWorkflowSteps && !existingSummary.endsWith(rerunSuffix)) {
await store.updateTask(taskId, {
summary: `${currentTask.summary}\n\n${rerunSuffix}`,
});
await store.logEntry(taskId, "fn_task_done summary appended to existing summary (workflow-step rerun)", undefined, deps.getRunContextFor(taskId));
} else if (!existingSummary || !hasRunWorkflowSteps) {
await store.updateTask(taskId, { summary: params.summary });
}
}
// FNXC:TaskRecommendations 2026-08-08-05:02: write only after every completion gate accepts; retries replace the list deterministically.
if (completionRecommendations !== undefined) {
await store.updateTask(taskId, { recommendations: completionRecommendations });
}
const hardPauseActive = Boolean(settings.globalPause);
// Task-level pause prevents new work from starting, not completion of
// in-flight work. Always clear it on explicit agent completion so the
// board cannot strand a completed task in a paused state.
await store.updateTask(taskId, {
paused: false,
pausedByAgentId: null,
status: null,
// FNXC:Lifecycle 2026-07-16-21:40: FN-8141 — an ACCEPTED explicit fn_task_done is the
// honest completion signal (covers the PREMISE STALE skip-then-done flow); clear any
// skip-bypass taint so a subsequent auto-promotion path is not blocked.
bulkCompletionRefusalAt: null,
});
await store.logEntry(taskId, "Task marked done by agent", undefined, deps.getRunContextFor(taskId));
const latestTask = await store.getTask(taskId);
let latestColumn = latestTask.column;
if (latestColumn === await resolveReboundColumnFor(store, taskId)) {
await store.logEntry(
taskId,
hardPauseActive
? "fn_task_done called while task was in todo during pause — promoting to in-progress for deferred completion handoff"
: "fn_task_done called while task was in todo — promoting to in-progress before completion handoff",
undefined,
deps.getRunContextFor(taskId),
);
/* FNXC:WorkflowResolvedColumns 2026-07-30-21:40: census-invisible moveTask DESTINATION, and `latestColumn` must be set from the SAME resolved value or the check below it compares against a lane the card is not in. */
const wipTarget = await resolveWipTargetForTask(store, taskId);
await store.moveTask(taskId, wipTarget);
latestColumn = wipTarget;
}
/*
FNXC:WorkflowResolvedColumns 2026-07-31-09:20 (fleet: executor lifecycle roles):
The completed-task watchdog arms when the card is in its IMPLEMENTATION lane. Naming
`in-progress` literally meant a renamed wip column never armed it — a watchdog that
silently never fires, on exactly the boards this program converted. The branch directly
above already resolves that lane through `resolveWipTargetForTask`; this asks the same
question of the same resolver rather than of an id.
*/
if (latestColumn === await resolveWipTargetForTask(store, taskId) && !hardPauseActive) {
deps.scheduleCompletedTaskWatchdog(taskId, "fn_task_done");
}
const successMessage = hardPauseActive
? "Task marked complete. Completion handoff deferred until pause is cleared."
: params.summary
? "Task marked complete with summary. All steps done. Moving to in-review."
: "Task marked complete. All steps done. Moving to in-review.";
return {
content: [{ type: "text" as const, text: successMessage }],
details: {},
};
},
};
}

320
packages/engine/src/executor/create-task-update-tool.ts Normal file
View File

@@ -0,0 +1,320 @@
/**
* FNXC:CodeOrganization 2026-08-03-12:50:
* createTaskUpdateTool peeled from TaskExecutor (U4).
*
* FNXC:StepNumbering 2026-06-17-00:00:
* FN-6607: step is 0-based matching PROMPT.md Step N numbers.
*
* FNXC:WorkflowReviewGates 2026-07-19-02:30:
* U10: in-session code-review REVISE gate on fn_task_update(done) deleted with fn_review_step.
*
* FNXC:StepLifecycle 2026-07-22-09:50:
* Persisted-status mismatch is a deterministic churn signal after loop recovery.
*/
import { Type, type Static } from "@earendil-works/pi-ai";
import type { StepStatus, TaskStore, WorkflowFieldDefinition } from "@fusion/core";
import type { ToolDefinition, AgentSession } from "@earendil-works/pi-coding-agent";
import type { ReviewVerdict } from "../execution/reviewer.js";
import type { StuckTaskDetector } from "../healing/stuck-task-detector.js";
import { executorLog } from "../logger.js";
const STEP_STATUSES: StepStatus[] = ["pending", "in-progress", "done", "skipped"];
const taskUpdateParams = Type.Object({
step: Type.Optional(Type.Number({ description: "Step number (0-indexed; matches the `### Step N:` numbers in PROMPT.md — Step 0 is Preflight). Omit when updating only custom_fields/dependencies." })),
status: Type.Optional(Type.Union(
STEP_STATUSES.map((s) => Type.Literal(s)),
{ description: "New status: pending, in-progress, done, or skipped. Required when step is set." },
)),
dependencies: Type.Optional(Type.Array(Type.String(), {
description: "Optional task dependency array. Replaces existing dependencies. Pass ['FN-001', 'FN-002'] to set dependencies. Pass [] to clear all dependencies. Omit parameter to preserve existing dependencies.",
})),
custom_fields: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
description:
"Optional patch of workflow-defined custom field values, keyed by field id. " +
"Values are validated against the task's workflow field schema (type/enum membership); " +
"pass null for a field to clear it. Rejected writes return the offending field id and reason. " +
"Only fields declared by the task's workflow may be written.",
})),
});
export type CreateTaskUpdateToolDeps = {
store: TaskStore;
resolveTaskCustomFieldDefs: (taskId: string) => Promise<WorkflowFieldDefinition[] | undefined>;
loopRecoveryState: Map<string, { attempts: number; pending: boolean }>;
};
/**
* Create fn_task_update for the executor coding session.
* `codeReviewVerdicts` / `sessionRef` remain in the signature for call-site compatibility
* (legacy review-gate args; U10 no longer consults them).
*/
export function createTaskUpdateTool(
deps: CreateTaskUpdateToolDeps,
taskId: string,
_codeReviewVerdicts: Map<number, ReviewVerdict>,
_sessionRef: { current: AgentSession | null },
stuckDetector?: StuckTaskDetector,
): ToolDefinition {
const store = deps.store;
return {
name: "fn_task_update",
label: "Update Step",
description:
"Update a step's status. Call before starting a step (in-progress), " +
"after completing it (done), or to skip it (skipped). " +
"Optionally update task dependencies by passing a dependencies array. " +
"Optionally set workflow-defined custom field values by passing a custom_fields patch " +
"(keyed by field id; validated against the workflow's field schema; pass null to clear a field). " +
"step/status may be omitted to update only custom_fields or dependencies. " +
"The board updates in real-time.",
parameters: taskUpdateParams,
execute: async (_id: string, params: Static<typeof taskUpdateParams>) => {
const { step, status, dependencies, custom_fields } = params;
// Bare-call guard (P1 api-contract): a call with none of
// step/status/dependencies/custom_fields silently no-op'd, which the
// agent cannot observe. Reject it up front so the failure is visible and
// self-describing. The legacy no-op text is preserved as the detail.
if (step === undefined && status === undefined && dependencies === undefined && custom_fields === undefined) {
return {
content: [{
type: "text" as const,
text: "ERROR: fn_task_update requires at least one of: step+status (report step progress), " +
"dependencies (array of task ids), or custom_fields (workflow-defined field patch). " +
"No-op: provide a step+status, dependencies, or custom_fields to update.",
}],
details: {},
isError: true,
};
}
// Custom-field patch (KTD-13): routed through the store's single write
// authority, which validates each value against the task's workflow field
// schema. A typed rejection surfaces the offending field id + reason as a
// tool error so the agent can correct it. Applied first so a field-only
// call (step omitted) returns here.
if (custom_fields !== undefined) {
const res = await store.updateTaskCustomFields(taskId, custom_fields);
if (!res.ok) {
const r = res.rejection;
// Self-correcting rejection text: append the valid field ids (and,
// for an enum violation, the valid values for the offending field)
// resolved from the task's workflow field schema so a failed write
// carries everything the agent needs to retry. Best-effort: a
// resolution failure just omits the hint (the base reason still ships).
let hint = "";
try {
const defs = await deps.resolveTaskCustomFieldDefs(taskId);
if (defs && defs.length > 0) {
if (r.code === "unknown-field" || r.code === "no-fields-defined") {
hint = ` Valid field ids: ${defs.map((f) => f.id).join(", ")}.`;
} else if (r.code === "enum-violation") {
const field = defs.find((f) => f.id === r.fieldId);
const opts = field?.options?.map((o) => o.value) ?? [];
if (opts.length > 0) hint = ` Valid values for '${r.fieldId}': ${opts.join(", ")}.`;
}
}
} catch { /* hint is best-effort */ }
return {
content: [{
type: "text" as const,
text: `ERROR: custom field '${r.fieldId}' rejected (${r.code}): ${r.detail}${hint}`,
}],
details: { fieldId: r.fieldId, code: r.code, detail: r.detail },
isError: true,
};
}
// A custom-fields-only update (no step) succeeds here.
if (step === undefined && status === undefined && dependencies === undefined) {
const updatedKeys = Object.keys(custom_fields);
return {
content: [{
type: "text" as const,
text: `Updated custom field(s): ${updatedKeys.join(", ")}.`,
}],
details: { updatedFields: updatedKeys },
};
}
}
// Record step progress for stuck task detection.
// Step transitions (in-progress, done, skipped) indicate real progress
// and reset the loop detection counter. Generic activity (text deltas,
// tool calls) is tracked separately via recordActivity in AgentLogger.
if (status === "in-progress" || status === "done" || status === "skipped") {
stuckDetector?.recordProgress(taskId);
}
// Dependencies-only update (no step) is permitted; handle deps then return.
if (step === undefined) {
if (dependencies !== undefined) {
if (dependencies.includes(taskId)) {
return {
content: [{ type: "text" as const, text: `Cannot add self-dependency: ${taskId} cannot depend on itself.` }],
details: {},
};
}
const invalidIds: string[] = [];
for (const depId of dependencies) {
try { await store.getTask(depId); } catch { invalidIds.push(depId); }
}
if (invalidIds.length > 0) {
return {
content: [{ type: "text" as const, text: `Cannot set dependencies — the following task(s) do not exist: ${invalidIds.join(", ")}` }],
details: {},
};
}
await store.updateTask(taskId, { dependencies });
return {
content: [{ type: "text" as const, text: `Dependencies updated.` }],
details: {},
};
}
return {
content: [{ type: "text" as const, text: `No-op: provide a step+status, dependencies, or custom_fields to update.` }],
details: {},
};
}
if (status === undefined) {
return {
content: [{ type: "text" as const, text: `Step ${step} provided without a status. Pass status (pending/in-progress/done/skipped).` }],
details: {},
};
}
if (!Number.isInteger(step) || step < 0) {
return {
content: [{
type: "text" as const,
text: `Invalid step number: ${step}. Steps are 0-indexed; Step 0 is Preflight.`,
}],
details: {},
};
}
/*
* FNXC:StepNumbering 2026-06-17-00:00:
* FN-6607 makes fn_task_update.step the same 0-based number agents see in PROMPT.md (`### Step N:`) and TaskStore.updateStep uses internally. The prior `step - 1` conversion made Step 0 impossible to mark done and shifted every review/progress update one array slot early.
*/
const stepIndex = step;
if (status === "in-progress") {
try {
const latestTask = await store.getTask(taskId);
const otherInProgressStepIndex = latestTask.steps.findIndex(
(taskStep, index) => index !== stepIndex && taskStep.status === "in-progress",
);
if (otherInProgressStepIndex !== -1) {
executorLog.warn(
`${taskId}: fn_task_update marking step ${step} in-progress while step ${otherInProgressStepIndex} is already in-progress`,
);
}
} catch (err) {
executorLog.warn(`${taskId}: failed to inspect step lease state before fn_task_update: ${err}`);
}
}
/*
FNXC:WorkflowReviewGates 2026-07-19-02:30:
U10 (R9): the in-session code-review REVISE gate on `fn_task_update(status="done")` is
deleted. Its verdict source was the legacy `fn_review_step` tool, which no longer exists,
so the map it read is permanently empty. A REVISE from a graph-owned Code Review node routes back to
the implementation node as a graph edge instead of blocking a step-status tool call.
*/
// Handle dependencies parameter if provided
if (dependencies !== undefined) {
// Validate: prevent self-dependency
if (dependencies.includes(taskId)) {
return {
content: [{
type: "text" as const,
text: `Cannot add self-dependency: ${taskId} cannot depend on itself.`,
}],
details: {},
};
}
// Validate: all dependency task IDs must exist
const invalidIds: string[] = [];
for (const depId of dependencies) {
try {
await store.getTask(depId);
} catch {
invalidIds.push(depId);
}
}
if (invalidIds.length > 0) {
return {
content: [{
type: "text" as const,
text: `Cannot set dependencies — the following task(s) do not exist: ${invalidIds.join(", ")}`,
}],
details: {},
};
}
// Update dependencies
await store.updateTask(taskId, { dependencies });
}
const task = await store.updateStep(taskId, stepIndex, status as StepStatus);
const stepInfo = task.steps[stepIndex];
if (!stepInfo) {
return {
content: [{
type: "text" as const,
text: `Invalid step number: ${step}. This task has ${task.steps.length} step(s) (0-indexed; valid range 0-${Math.max(0, task.steps.length - 1)}).`,
}],
details: {},
};
}
const persistedStatus = stepInfo.status;
const progress = task.steps.filter((s) => s.status === "done").length;
/*
FNXC:WorkflowReviewGates 2026-07-19-02:30:
U10 (R9): the pre-step conversation-checkpoint capture is deleted with `fn_review_step`.
Its only consumer was that tool's RETHINK rewind (`session.navigateTree`); a graph-owned
RETHINK re-enters the implementation node instead of rewinding the live conversation.
*/
// FNXC:StepLifecycle 2026-07-22-09:50: A persisted-status mismatch means
// the store rejected the transition (for example, a completed-step
// regression or an out-of-order start/completion). FN-5168 treats
// repeated rebuffs after loop recovery as a deterministic churn signal.
if (persistedStatus !== status) {
stuckDetector?.recordIgnoredStepUpdate(taskId);
const ignoredStepUpdates = stuckDetector?.getIgnoredStepUpdateCount(taskId) ?? 0;
const loopAttempts = deps.loopRecoveryState.get(taskId)?.attempts ?? 0;
if (loopAttempts >= 1 && ignoredStepUpdates === 25) {
executorLog.warn(
`${taskId}: no-progress churn detected ` +
`(ignoredStepUpdates=${ignoredStepUpdates}, stuckKillStreak=${task.stuckKillCount ?? 0}) — ` +
`escalating to STUCK_NO_PROGRESS_CHURN`,
);
}
return {
content: [{
type: "text" as const,
text: `Step ${step} (${stepInfo.name}) remains ${persistedStatus} — ${status} request ignored to preserve step lifecycle invariants. Progress: ${progress}/${task.steps.length} done.`,
}],
details: {},
};
}
return {
content: [{
type: "text" as const,
text: `Step ${step} (${stepInfo.name}) → ${persistedStatus}. Progress: ${progress}/${task.steps.length} done.`,
}],
details: {},
};
},
};
}

95
packages/engine/src/executor/dep-abort-cleanup.ts Normal file
View File

@@ -0,0 +1,95 @@
/**
* FNXC:CodeOrganization 2026-08-03-18:20:
* handleDepAbortCleanup peeled from TaskExecutor (U4).
* After mid-execution fn_task_add_dep: remove worktree, delete branch, rebound for replan.
*/
import { exec } from "node:child_process";
import { promisify } from "node:util";
import type { Settings, TaskStore } from "@fusion/core";
import { resolveTaskWorkingBranch } from "../worktree/worktree-names.js";
import { RemovalReason } from "../worktree/worktree-pool.js";
import { executorLog } from "../logger.js";
import { resolveExternalExecutionCheckoutRoute } from "../execution/external-execution-checkout.js";
import { resolveReboundColumnFor } from "./lifecycle-columns.js";
const execAsync = promisify(exec);
export type DepAbortCleanupDeps = {
rootDir: string;
store: TaskStore;
activeWorktrees: Map<string, unknown>;
removeOwnWorktreeWithReconcile: (input: {
worktreePath: string;
settings: Settings;
taskId: string;
reason: RemovalReason;
}) => Promise<void>;
};
export async function handleDepAbortCleanup(
deps: DepAbortCleanupDeps,
taskId: string,
worktreePath: string,
): Promise<void> {
executorLog.log(`${taskId} dependency added — work discarded, moved to triage for re-planning`);
const task = await deps.store.getTask(taskId);
const externalExecutionRoute = await resolveExternalExecutionCheckoutRoute(task);
/*
FNXC:ExternalExecutionCheckout 2026-08-09-22:43:
Persisted external execution routes are operator-owned checkouts. Executor cleanup may clear Fusion's managed task pointers, but it must never remove the routed directory or delete its branch during dependency abort, retry, pause, stuck-kill, or remediation recovery.
*/
if (!externalExecutionRoute.configured) {
try {
const settings = await deps.store.getSettings() as Settings;
await deps.removeOwnWorktreeWithReconcile({
worktreePath,
settings,
taskId,
reason: RemovalReason.ExecutorDispose,
});
} catch (err: unknown) {
const msg = err instanceof Error ? err.message : String(err);
executorLog.warn(`${taskId}: failed to remove worktree during dep-abort cleanup (${worktreePath}): ${msg}`);
}
}
// Delete only a Fusion-managed branch. External routes remain operator-owned.
const branch = resolveTaskWorkingBranch(task);
let branchDeleted = false;
if (!externalExecutionRoute.configured) {
try {
await execAsync(`git branch -D "${branch}"`, { cwd: deps.rootDir });
branchDeleted = true;
} catch (err: unknown) {
const msg = err instanceof Error ? err.message : String(err);
executorLog.warn(`${taskId}: failed to delete branch during dep-abort cleanup (${branch}): ${msg}`);
}
}
if (branchDeleted) {
// FN-2165 regression guard: null baseBranch on any task that stored this branch
try { await deps.store.clearStaleExecutionStartBranchReferences([branch], taskId); } catch { /* best-effort */ }
}
// Clear worktree tracking
deps.activeWorktrees.delete(taskId);
// Update task: clear worktree and status, move to triage
await deps.store.updateTask(taskId, { worktree: null, status: null });
/*
FNXC:WorkflowLifecycleColumns 2026-07-29-15:10 (P0 audit after the Planning-column merge):
This wrote the LITERAL `triage`. The default coding lineage no longer declares that column —
it has one pre-implementation column, id `todo` — so a card that gained a dependency
mid-execution had its work discarded and was then parked in a column its own workflow does
not define. Nothing in the graph routes a card out of an undeclared column, and the only
rescue is `reconcileUndeclaredTaskColumns` on the NEXT ENGINE START, so between the abort and
a restart the card is stalled with no automatic recovery. It does not throw, which is why it
would have surfaced as a user report rather than a red test.
Resolve the rebound target from the task's own workflow (hold -> intake -> first declared
column), the same helper the other ~16 executor rebounds already use.
*/
await deps.store.moveTask(taskId, await resolveReboundColumnFor(deps.store, taskId));
await deps.store.logEntry(taskId, "Execution stopped — work discarded, requeued for re-planning");
}

78
packages/engine/src/executor/dependency-dispatch-gate.ts Normal file
View File

@@ -0,0 +1,78 @@
/**
* FNXC:CodeOrganization 2026-08-03-19:20:
* blockOuterDispatchWhenDependenciesUnmet peeled from TaskExecutor (U4).
*
* FNXC:DependencyGating 2026-06-20-07:30:
* Workflow-graph and workflow-authoritative executor dispatches can be invoked outside the classic scheduler loop, so they must re-apply the shared scheduling dependency gate before graph routing, column-agent seams, or review handoff can run.
* Requeue with blockedBy instead of executing so missing or soft-deleted dependency residue keeps the scheduler helper's non-blocking semantics while live todo/queued/in-progress/triage dependencies block every dispatch surface.
*/
import type { Task, TaskStore } from "@fusion/core";
import { getUnmetSchedulingDependencies } from "../scheduler.js";
import { executorLog } from "../logger.js";
import type { EngineRunContext } from "../util/run-audit.js";
import { resolveReboundColumnFor } from "./lifecycle-columns.js";
export type DependencyDispatchGateDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
};
export async function blockOuterDispatchWhenDependenciesUnmet(
deps: DependencyDispatchGateDeps,
task: Task,
): Promise<boolean> {
if (!task.dependencies || task.dependencies.length === 0) return false;
const settings = await deps.store.getSettings();
const tasks = await deps.store.listTasks({ includeArchived: false, slim: true });
const liveTask = tasks.find((candidate) => candidate.id === task.id) ?? task;
const markerAcceptedByTaskId = new Map<string, boolean>();
if (settings.mergeRequestContractShadowEnabled === true) {
for (const depId of liveTask.dependencies) {
markerAcceptedByTaskId.set(depId, (await deps.store.getCompletionHandoffAcceptedMarker(depId)) !== null);
}
}
const unmetDeps = getUnmetSchedulingDependencies(
liveTask,
tasks,
settings.mergeRequestContractShadowEnabled === true ? { markerAcceptedByTaskId } : undefined,
);
if (unmetDeps.length === 0) return false;
const reboundColumn = await resolveReboundColumnFor(deps.store, liveTask.id);
if (liveTask.column !== reboundColumn) {
await deps.store.moveTask(liveTask.id, reboundColumn, {
preserveProgress: true,
preserveWorktree: true,
preserveResumeState: true,
moveSource: "engine",
recoveryRehome: true,
});
}
/*
FNXC:DependencyGating 2026-08-07-12:10:
Prefer the store's transitionQueuedEpisode so queued signature/blockedBy/audit are one atomic
write (FN-8806 / main). Falls back to updateTask+logEntry only when the store lacks the helper.
*/
const normalizedUnmetDeps = [...new Set(unmetDeps)].sort();
if (typeof deps.store.transitionQueuedEpisode === "function") {
await deps.store.transitionQueuedEpisode(liveTask.id, {
signature: `dependency:${normalizedUnmetDeps.join(",")}`,
blockedBy: unmetDeps[0] ?? null,
overlapBlockedBy: liveTask.overlapBlockedBy ?? null,
action: `queued — unmet dependencies: ${unmetDeps.join(", ")}`,
outcome: "Executor pre-dispatch dependency gate blocked workflow/authoritative execution.",
runContext: deps.getRunContextFor(liveTask.id),
});
} else {
await deps.store.updateTask(liveTask.id, { status: "queued", blockedBy: unmetDeps[0] }, deps.getRunContextFor(liveTask.id));
await deps.store.logEntry(
liveTask.id,
`queued — unmet dependencies: ${unmetDeps.join(", ")}`,
"Executor pre-dispatch dependency gate blocked workflow/authoritative execution.",
deps.getRunContextFor(liveTask.id),
);
}
executorLog.log(`${liveTask.id}: executor dispatch blocked by unmet dependencies: ${unmetDeps.join(", ")}`);
return true;
}

1394
packages/engine/src/executor/deps-bags.ts Normal file
View File

File diff suppressed because it is too large Load Diff

89
packages/engine/src/executor/deterministic-verification.ts Normal file
View File

@@ -0,0 +1,89 @@
/**
* FNXC:CodeOrganization 2026-08-03-18:40:
* runExecutorDeterministicVerification peeled from TaskExecutor (U4).
* Runs configured testCommand + buildCommand in the task worktree.
*
* FNXC:EngineDiagnostics 2026-07-26-09:33:
* Green path verification start/pass is expected work — debug so failures stay prominent.
*/
import type { Settings, Task, TaskStore } from "@fusion/core";
import {
runVerificationCommand,
type VerificationResult,
} from "../execution/verification-utils.js";
import { executorLog } from "../logger.js";
import type { EngineRunContext } from "../util/run-audit.js";
export type DeterministicVerificationDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
};
export async function runExecutorDeterministicVerification(
deps: DeterministicVerificationDeps,
task: Task,
worktreePath: string,
settings: Settings,
extraEnv?: NodeJS.ProcessEnv,
): Promise<VerificationResult> {
const testCommand = settings.testCommand?.trim();
const buildCommand = settings.buildCommand?.trim();
if (!testCommand && !buildCommand) {
executorLog.debug(`${task.id}: no test/build commands configured — skipping verification`);
return { allPassed: true };
}
const parts: string[] = [];
if (testCommand) parts.push(`test: ${testCommand}`);
if (buildCommand) parts.push(`build: ${buildCommand}`);
// FNXC:EngineDiagnostics 2026-07-26-09:33: green path verification start/pass is expected work — debug so failures stay prominent.
executorLog.debug(`${task.id}: [verification] running deterministic verification (${parts.join(", ")})`);
await deps.store.logEntry(
task.id,
`[verification] Running deterministic verification (${parts.join(", ")})`,
undefined,
deps.getRunContextFor(task.id),
);
const result: VerificationResult = { allPassed: true };
// Run test command first if configured
if (testCommand) {
const testResult = await runVerificationCommand(
deps.store, worktreePath, task.id, testCommand, "test", undefined, executorLog, "executor", extraEnv, settings.verificationCommandTimeoutMs,
);
result.testResult = testResult;
if (!testResult.success) {
result.allPassed = false;
result.failedCommand = "testCommand";
executorLog.log(`${task.id}: [verification] test failed (exit ${testResult.exitCode})`);
return result;
}
}
// Run build command second if configured
if (buildCommand) {
const buildResult = await runVerificationCommand(
deps.store, worktreePath, task.id, buildCommand, "build", undefined, executorLog, "executor", extraEnv, settings.verificationCommandTimeoutMs,
);
result.buildResult = buildResult;
if (!buildResult.success) {
result.allPassed = false;
result.failedCommand = "buildCommand";
executorLog.log(`${task.id}: [verification] build failed (exit ${buildResult.exitCode})`);
return result;
}
}
executorLog.debug(`${task.id}: [verification] passed`);
await deps.store.logEntry(
task.id,
`[verification] Deterministic verification passed`,
undefined,
deps.getRunContextFor(task.id),
);
return result;
}

20
packages/engine/src/executor/dispose-store-lifecycle-disposers.ts Normal file
View File

@@ -0,0 +1,20 @@
/**
* FNXC:CodeOrganization 2026-08-03-19:00:
* disposeStoreLifecycleDisposers peeled from TaskExecutor (U4).
*
* Remove only this executor's store-scoped lifecycle disposer registrations.
*/
export type DisposeStoreLifecycleDisposersDeps = {
clearTaskMoveDisposer: () => void;
clearArchiveWorktreeDisposer: () => void;
clearArchiveWorkspaceWorktreeDisposer: () => void;
};
export function disposeStoreLifecycleDisposers(
deps: DisposeStoreLifecycleDisposersDeps,
): void {
deps.clearTaskMoveDisposer();
deps.clearArchiveWorktreeDisposer();
deps.clearArchiveWorkspaceWorktreeDisposer();
}

24
packages/engine/src/executor/dispose-subagents.ts Normal file
View File

@@ -0,0 +1,24 @@
/**
* FNXC:CodeOrganization 2026-08-03-20:45:
* disposeSubagentsForTask peeled from TaskExecutor (U4).
*/
import type { AgentSession } from "@earendil-works/pi-coding-agent";
import { executorLog } from "../logger.js";
export function disposeSubagentsForTask(
activeSubagentSessions: Map<string, Set<AgentSession>>,
taskId: string,
reason: string,
): void {
const set = activeSubagentSessions.get(taskId);
if (!set || set.size === 0) return;
executorLog.log(`${taskId}: disposing ${set.size} subagent session(s) — ${reason}`);
for (const session of set) {
try {
session.dispose();
} catch (err) {
executorLog.warn(`${taskId}: failed to dispose subagent session: ${err}`);
}
}
activeSubagentSessions.delete(taskId);
}

129
packages/engine/src/executor/ensure-graph-custom-node-worktree.ts Normal file
View File

@@ -0,0 +1,129 @@
/**
* FNXC:CodeOrganization 2026-08-03-12:10:
* ensureGraphCustomNodeWorktree peeled from TaskExecutor (U4).
*
* FNXC:WorkflowExecution 2026-06-29-08:21:
* Custom graph nodes can be the first executable node in a workflow. If such a node is coding/script-capable, acquire the same task worktree the legacy executor would have acquired instead of failing with `no-worktree-for-write-node`.
*
* FNXC:EngineDiagnostics 2026-08-03-05:54:
* Per-node worktree acquisition is expected graph plumbing once the task has a worktree.
*/
import type { Settings, Task, TaskDetail, TaskStore } from "@fusion/core";
import { loadWorkspaceConfig, type RunCommandResult } from "@fusion/core";
import { executorLog } from "../logger.js";
import { generateSyntheticRunId, createRunAuditor, type EngineRunContext, type RunAuditor } from "../util/run-audit.js";
import { acquireTaskWorktree } from "../worktree/worktree-acquisition.js";
import { captureBaseCommitSha } from "./worktree-git-refs.js";
import { createConfiguredCommandAbortError } from "./task-predicates.js";
import type { WorktreePool } from "../worktree/worktree-pool.js";
export type EnsureGraphCustomNodeWorktreeDeps = {
store: TaskStore;
rootDir: string;
getWorkspaceConfig: () => Awaited<ReturnType<typeof loadWorkspaceConfig>> | undefined;
setWorkspaceConfig: (config: Awaited<ReturnType<typeof loadWorkspaceConfig>>) => void;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
pool?: WorktreePool;
secretsStore?: Parameters<typeof acquireTaskWorktree>[0]["secretsStore"];
createWorktree: (
branch: string,
path: string,
taskId: string,
startPoint?: string,
allowSiblingBranchRename?: boolean,
) => Promise<{ path: string; branch: string }>;
runConfiguredCommand: (
command: string,
cwd: string,
timeoutMs: number,
extraEnv?: NodeJS.ProcessEnv,
auditor?: RunAuditor,
signal?: AbortSignal,
) => Promise<RunCommandResult>;
addActiveWorktree: (taskId: string, path: string) => void;
onStart?: (task: Task, worktreePath: string) => void;
registerConfiguredCommandController: (taskId: string, controller: AbortController) => void;
unregisterConfiguredCommandController: (taskId: string, controller: AbortController) => void;
};
export async function ensureGraphCustomNodeWorktree(
deps: EnsureGraphCustomNodeWorktreeDeps,
task: TaskDetail,
settings: Settings,
nodeId: string,
refreshStaleBase = false,
): Promise<TaskDetail> {
let workspaceConfig = deps.getWorkspaceConfig();
if (workspaceConfig === undefined) {
workspaceConfig = await loadWorkspaceConfig(deps.rootDir);
deps.setWorkspaceConfig(workspaceConfig);
}
if (workspaceConfig && (workspaceConfig.repos.length ?? 0) > 0) {
return task;
}
const syntheticRunId = generateSyntheticRunId("workflow-node-worktree", task.id);
const audit = createRunAuditor(deps.store, {
runId: syntheticRunId,
agentId: task.assignedAgentId ?? "executor",
taskId: task.id,
phase: "execute",
});
const commandAbortController = new AbortController();
deps.registerConfiguredCommandController(task.id, commandAbortController);
try {
await deps.store.logEntry(
task.id,
`Workflow node '${nodeId}' requires a task worktree — acquiring worktree before node execution`,
undefined,
deps.getRunContextFor(task.id),
);
const acquisition = await acquireTaskWorktree({
task,
rootDir: deps.rootDir,
store: deps.store,
settings,
pool: deps.pool,
logger: executorLog,
audit,
runContext: deps.getRunContextFor(task.id),
runInitCommand: true,
createWorktree: deps.createWorktree,
runConfiguredCommand: (command, cwd, timeoutMs, env) =>
deps.runConfiguredCommand(
command,
cwd,
timeoutMs,
env,
audit,
commandAbortController.signal,
).then((result) => {
if (commandAbortController.signal.aborted) {
throw createConfiguredCommandAbortError(task.id, command);
}
return result;
}),
taskEnv: process.env,
secretsStore: deps.secretsStore,
refreshStaleBase,
});
deps.addActiveWorktree(task.id, acquisition.worktreePath);
if (!acquisition.isResume) {
await captureBaseCommitSha(deps.store, task, acquisition.worktreePath, audit, { isResume: false });
}
deps.onStart?.(task, acquisition.worktreePath);
executorLog.debug(`${task.id}: workflow node '${nodeId}' acquired worktree at ${acquisition.worktreePath}`);
return await deps.store.getTask(task.id);
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
await deps.store.logEntry(
task.id,
`Workflow node '${nodeId}' failed to acquire task worktree: ${message}`,
undefined,
deps.getRunContextFor(task.id),
);
throw error;
} finally {
deps.unregisterConfiguredCommandController(task.id, commandAbortController);
}
}

59
packages/engine/src/executor/ensure-task-worktree-for-planning.ts Normal file
View File

@@ -0,0 +1,59 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:30:
* ensureTaskWorktreeForPlanning peeled from TaskExecutor (U4).
*
* Acquires a planning worktree when none exists (non-workspace). Fail-soft: planning falls
* back to the repo root on acquisition failure.
*
* FNXC:NodeWorktreeIsolation 2026-07-25-22:10 (planning acquires the task worktree):
* Public seam for the planning/triage lane. Specification runs a CODING-tool session; pointing it at
* the shared main checkout meant every planning agent had write tools in the operator's tree and every
* concurrent planner shared one path. Acquire the task's own worktree up front and let the whole
* lifecycle — planning, Plan Review, implementation, code review — reuse that single worktree.
* Returns null (caller falls back to the root, unchanged behavior) when the project is a workspace, or
* when acquisition fails: planning must never be blocked by a worktree problem.
*/
import { existsSync } from "node:fs";
import type { Settings, TaskDetail, TaskStore, WorkspaceConfig } from "@fusion/core";
import { loadWorkspaceConfig } from "@fusion/core";
import { executorLog, formatError } from "../logger.js";
export type EnsureTaskWorktreeForPlanningDeps = {
store: TaskStore;
rootDir: string;
/** Mutable holder so lazy load updates TaskExecutor.workspaceConfig. */
getWorkspaceConfig: () => WorkspaceConfig | null | undefined;
setWorkspaceConfig: (cfg: WorkspaceConfig | null) => void;
ensureGraphCustomNodeWorktree: (
task: TaskDetail,
settings: Settings,
nodeId: string,
refreshStaleBase?: boolean,
) => Promise<{ worktree?: string }>;
};
export async function ensureTaskWorktreeForPlanning(
deps: EnsureTaskWorktreeForPlanningDeps,
taskId: string,
): Promise<string | null> {
try {
if (deps.getWorkspaceConfig() === undefined) {
deps.setWorkspaceConfig(await loadWorkspaceConfig(deps.rootDir));
}
const workspaceConfig = deps.getWorkspaceConfig();
if (workspaceConfig && (workspaceConfig.repos.length ?? 0) > 0) return null;
const live = await deps.store.getTask(taskId);
if (live.worktree && existsSync(live.worktree)) return live.worktree;
const settings = await deps.store.getSettings();
const acquisitionTask = live.worktree
? ({ ...live, worktree: undefined, sessionFile: undefined } as TaskDetail)
: live;
const acquired = await deps.ensureGraphCustomNodeWorktree(acquisitionTask, settings, "planning");
return acquired.worktree || null;
} catch (error) {
executorLog.warn(`${taskId}: could not acquire a planning worktree — planning falls back to the repo root: ${formatError(error)}`);
return null;
}
}

15
packages/engine/src/executor/ephemeral-delete-race.ts Normal file
View File

@@ -0,0 +1,15 @@
/**
* FNXC:CodeOrganization 2026-08-03-13:35:
* Pure ephemeral agent delete-race classifier peeled from TaskExecutor (U4).
*/
import { executorLog } from "../logger.js";
export function isBenignEphemeralDeleteRaceError(agentId: string, err: unknown): boolean {
const msg = err instanceof Error ? err.message : String(err);
const lower = msg.toLowerCase();
if (lower.includes("not found") || lower.includes("already deleted") || lower.includes("does not exist")) {
executorLog.debug(`Skip spawned-agent cleanup for ${agentId}: already deleted by another pathway`);
return true;
}
return false;
}

16
packages/engine/src/executor/ephemeral-deletion-pending.ts Normal file
View File

@@ -0,0 +1,16 @@
/**
* FNXC:CodeOrganization 2026-08-03-20:15:
* isEphemeralDeletionPending / disposeEphemeralTimers peeled from TaskExecutor (U4).
*/
export function isEphemeralDeletionPending(
pendingEphemeralDeletions: Set<string>,
agentId: string,
): boolean {
return pendingEphemeralDeletions.has(agentId);
}
export function disposeEphemeralTimers(
pendingEphemeralDeletions: Set<string>,
): void {
pendingEphemeralDeletions.clear();
}

56
packages/engine/src/executor/evaluate-task-verdict-providers.ts Normal file
View File

@@ -0,0 +1,56 @@
/**
* FNXC:CodeOrganization 2026-08-03-13:50:
* evaluateTaskVerdictProviders peeled from TaskExecutor (U4).
*
* Runs registered workflow verdict-provider extensions before fn_task_done acceptance.
*/
import type { TaskDetail, TaskStore, WorkflowIr } from "@fusion/core";
import { resolveWorkflowIrForTask, getWorkflowExtensionRegistry } from "@fusion/core";
import { executorLog } from "../logger.js";
export type EvaluateTaskVerdictProvidersDeps = {
store: TaskStore;
};
export async function evaluateTaskVerdictProviders(
deps: EvaluateTaskVerdictProvidersDeps,
task: TaskDetail,
context: Record<string, unknown> = {},
): Promise<{ ok: true } | { ok: false; message: string }> {
let workflow: WorkflowIr;
try {
workflow = await resolveWorkflowIrForTask(deps.store, task.id);
} catch (error) {
executorLog.warn(`${task.id}: failed to resolve workflow for verdict providers: ${error instanceof Error ? error.message : String(error)}`);
return { ok: true };
}
const providers = getWorkflowExtensionRegistry().list("verdict-provider");
for (const definition of providers) {
const extension = definition.extension;
if (definition.degraded || extension.kind !== "verdict-provider" || !extension.evaluate) continue;
try {
const verdict = await extension.evaluate({
task,
workflow,
reworkRound: 0,
metadata: context,
});
if (verdict.status === "pass") continue;
const reasons = verdict.failureReasons?.map((reason) => reason.message).filter(Boolean).join("; ");
return {
ok: false,
message: `fn_task_done refused (verdict-provider): ${verdict.summary}${reasons ? ` — ${reasons}` : ""}`,
};
} catch (error) {
if (extension.fallback === "degradeToDefault") continue;
const message = error instanceof Error ? error.message : String(error);
return {
ok: false,
message: `fn_task_done refused (verdict-provider): provider '${definition.id}' failed — ${message}`,
};
}
}
return { ok: true };
}

91
packages/engine/src/executor/evaluate-workflow-merge-boundary.ts Normal file
View File

@@ -0,0 +1,91 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:00:
* evaluateWorkflowMergeBoundary + getWorkflowMergeImplementationProofFailure peeled (U4).
*
* Graph merge admission: node-result presence/terminality, foreach coverage, and
* skip-bypass taint / implementation-proof failures.
*/
import type { TaskDetail, TaskStore, WorkflowIr, WorkflowStepResult as CoreWorkflowStepResult } from "@fusion/core";
import { evaluateForeachMergeProof, evaluateSkipBypassTaint, resolveWorkflowIrForTask } from "@fusion/core";
export type EvaluateWorkflowMergeBoundaryDeps = {
store: TaskStore;
loadMergeBoundaryInstances: (taskId: string, runId?: string) => Promise<Array<{ foreachNodeId: string; stepIndex: number; pinnedStepCount: number }>>;
};
export type WorkflowMergeBoundaryProof = {
resolved: boolean;
hasRelevantNodeResult: boolean;
allResultsTerminal: boolean;
coverageComplete: boolean;
hasForeachStepExecute: boolean;
missingInstanceIds: string[];
nonTerminalResult?: CoreWorkflowStepResult;
complete: boolean;
};
export async function evaluateWorkflowMergeBoundary(
deps: EvaluateWorkflowMergeBoundaryDeps,
task: TaskDetail,
runId?: string,
): Promise<WorkflowMergeBoundaryProof> {
const relevant = (task.workflowStepResults ?? []).filter((result) =>
result.source === "node" && (result.phase ?? "pre-merge") === "pre-merge",
);
// FNXC:WorkflowMerge 2026-07-27-12:30: FN-8601 keeps required presence
// independent from terminality: a failed node result proves execution occurred,
// while allResultsTerminal separately rejects it at the merge boundary.
const hasRelevantNodeResult = relevant.length > 0;
const nonTerminalResult = relevant.find((result) => result.status !== "passed" && result.status !== "skipped");
const allResultsTerminal = nonTerminalResult === undefined;
let ir: WorkflowIr | undefined;
try { ir = await resolveWorkflowIrForTask(deps.store, task.id); } catch { /* preserve legacy behavior for unresolved IRs */ }
if (!ir) return { resolved: false, hasRelevantNodeResult, allResultsTerminal, coverageComplete: true, hasForeachStepExecute: false, missingInstanceIds: [], nonTerminalResult, complete: false };
let persistedInstances: Array<{ foreachNodeId: string; stepIndex: number; pinnedStepCount: number }> = [];
try { persistedInstances = await deps.loadMergeBoundaryInstances(task.id, runId); } catch { /* persistence is additive */ }
const coverage = evaluateForeachMergeProof({ ir, steps: task.steps, workflowStepResults: task.workflowStepResults, persistedInstances });
const complete = hasRelevantNodeResult && allResultsTerminal && coverage.missingInstanceIds.length === 0;
return { resolved: true, hasRelevantNodeResult, allResultsTerminal, coverageComplete: coverage.missingInstanceIds.length === 0, hasForeachStepExecute: coverage.hasForeachStepExecute, missingInstanceIds: coverage.missingInstanceIds, nonTerminalResult, complete };
}
export type GetWorkflowMergeImplementationProofFailureDeps = {
store: TaskStore;
evaluateWorkflowMergeBoundary: (task: TaskDetail, runId?: string) => Promise<WorkflowMergeBoundaryProof>;
};
export async function getWorkflowMergeImplementationProofFailure(
deps: GetWorkflowMergeImplementationProofFailureDeps,
task: TaskDetail,
): Promise<string | undefined> {
/*
FNXC:Lifecycle 2026-07-16-21:40:
FN-8141 — the graph merge boundary is another AUTO-promotion path. If the task is
skip-bypass tainted (steps skipped after a bulk-step-completion refusal with no
accepted fn_task_done), treat it as missing implementation proof so the merge is
blocked with `implementation-incomplete` rather than laundered through a no-op merge.
Runs before the noCommitsExpected exemption so a tainted task cannot slip past it.
*/
const taint = evaluateSkipBypassTaint(task);
if (taint.blocked) return "implementation did not run: steps were skipped after a bulk-step-completion refusal without an accepted fn_task_done";
if (task.noCommitsExpected === true) return undefined;
let ir: WorkflowIr | undefined;
try { ir = await resolveWorkflowIrForTask(deps.store, task.id); } catch { ir = undefined; }
if (!ir) return undefined;
const usesParsedSteps = ir.nodes.some((node) => node.kind === "parse-steps");
const usesExecuteSeam = ir.nodes.some((node) => node.kind === "prompt" && node.config?.seam === "execute");
if (!usesParsedSteps && !usesExecuteSeam) return undefined;
const steps = Array.isArray(task.steps) ? task.steps : [];
const hasTerminalParsedSteps = steps.length > 0 && steps.every((step) => step.status === "done" || step.status === "skipped");
const hasModifiedFiles = (task.modifiedFiles?.length ?? 0) > 0;
const proof = await deps.evaluateWorkflowMergeBoundary(task);
const hasGraphNativeImplementationProof = proof.hasRelevantNodeResult && proof.allResultsTerminal && proof.coverageComplete;
if (usesParsedSteps) {
if (hasTerminalParsedSteps || hasGraphNativeImplementationProof) return undefined;
return proof.hasForeachStepExecute && !proof.coverageComplete
? `implementation did not run: foreach step instances are incomplete (missing ${proof.missingInstanceIds.join(", ")})`
: "implementation did not run: parsed coding steps are missing or incomplete";
}
if (usesExecuteSeam) return hasTerminalParsedSteps || hasModifiedFiles || hasGraphNativeImplementationProof ? undefined : "implementation did not run: execute seam has no completion proof";
return undefined;
}

111
packages/engine/src/executor/execute-core.ts Normal file
View File

@@ -0,0 +1,111 @@
/**
* FNXC:CodeOrganization 2026-08-03-11:20:
* executeCore peeled from TaskExecutor (U4).
* Routing-only entry: soft-delete refuse, graph claim, gates, then executeWorkflowGraph.
*
* FNXC:GlobalConcurrencyControls 2026-07-15-03:50:
* Structural cleanup for scheduler pre-held global slots lives on the execute() wrapper:
* every exit path must leave no unclaimed registration (dropPreHeldExecutorSlot + release).
*
* FNXC:WorkflowExecution 2026-07-19-02:10:
* U5e (R9) — `executeCore` is ROUTING ONLY. It decides who owns the task (duplicate-dispatch
* drop, dependency/ephemeral gates, the workflow graph, authoritative dispatch) and, when no
* one else claims it, drives the implementation phase itself.
*
* The routing block used to be wrapped in `if (!graphCompletion)` because the graph re-ENTERED
* `execute()` to run the implementation phase, and that inner call had to skip routing or it
* would recurse. The graph now calls `runImplementation()` directly, so there is no inner
* invocation to exclude and the gates are unconditional.
*
* FNXC:ExecutorSoftDelete 2026-07-20-23:30:
* Soft-delete refuse in routing so deleted cards never start a workflow run.
*
* FNXC:WorkflowExecution 2026-07-21-22:56:
* Claim graphRouting BEFORE any await (FN-8471 multi-entry race).
*
* FNXC:WorkflowExecution 2026-07-19-10:40 / 17:45 (U10/U10b):
* Authoritative driver and bare runImplementation fallback deleted; graph is sole orchestrator.
*/
import type { Task } from "@fusion/core";
import { executorLog } from "../logger.js";
import { dropPreHeldExecutorSlot } from "../concurrency/concurrency.js";
export type ExecuteCoreDeps = {
completionFinalizedTaskIds: Set<string>;
graphRouting: Set<string>;
releaseSemaphore: () => void;
clearStalePauseAbortBeforeDispatch: (task: Task) => Promise<void>;
blockOuterDispatchWhenDependenciesUnmet: (task: Task) => Promise<boolean>;
executeWorkflowGraph: (task: Task, options: { alreadyClaimed: true }) => Promise<void>;
};
export async function executeCore(deps: ExecuteCoreDeps, task: Task): Promise<void> {
deps.completionFinalizedTaskIds.delete(task.id);
/*
FNXC:ExecutorSoftDelete 2026-07-20-23:30:
Soft-delete refuse belongs in routing, not only inside runImplementation. After U10b the
graph owns every execute() call, so a deletedAt check that lives only under the
implementation seam never fires for graph entry (cursor capture / selection / fail-closed
parks run first). Refuse here before graph ownership so soft-deleted cards never start a
workflow run; runImplementation keeps the same check as defense-in-depth for graph-owned
re-entry that already holds the process lock.
*/
if (task.deletedAt) {
executorLog.warn(`${task.id}: refusing execute — task is soft-deleted`);
if (dropPreHeldExecutorSlot(task.id)) deps.releaseSemaphore();
return;
}
/*
FNXC:WorkflowExecution 2026-07-21-22:56:
Claim graphRouting BEFORE any await. The previous check-then-await-then-claim
window let concurrent execute() calls (task:moved + unpause resume after plan-review)
both pass the graphRouting.has gate, both enter executeWorkflowGraph, and one park
status=failed while the other still owned work (FN-8471 overseer thrash).
*/
if (deps.graphRouting.has(task.id)) {
// Duplicate dispatch while the graph runner owns this task — drop it,
// mirroring the executingTaskLock duplicate-invocation behavior.
executorLog.debug(`execute() called for ${task.id} while graph routing is active — skipping duplicate`);
return;
}
deps.graphRouting.add(task.id);
let graphRunnerOwnsClaim = false;
try {
await deps.clearStalePauseAbortBeforeDispatch(task);
if (await deps.blockOuterDispatchWhenDependenciesUnmet(task)) {
// FNXC:GlobalConcurrencyControls 2026-07-14-18:30: release any scheduler pre-held slot when outer dispatch aborts before agent work starts.
if (dropPreHeldExecutorSlot(task.id)) deps.releaseSemaphore();
return;
}
/*
FNXC:WorkflowAgentRouting 2026-08-07-09:11:
FN-8821: ephemeralAgentsEnabled is a routing-inert compatibility setting. Do not
rebound or queue at outer dispatch based on it; graph principal admission owns
durable identity/capacity. The old blockOuterDispatchWhenEphemeralDisabled gate is
retired from this path.
*/
/*
FNXC:WorkflowExecution 2026-07-19-10:40:
U10 (R9) — the `workflowAuthoritativeDispatch` branch is DELETED along with
WorkflowAuthoritativeDriver. It was the pre-graph "authoritative" runtime: a second
in-process execution path that could claim a task between the graph and the legacy
implementation. The graph is now the sole orchestrator, so a second claimant is not a
fallback, it is a race.
FNXC:WorkflowExecution 2026-07-19-17:45 (U10b / R9):
The trailing `await this.runImplementation(task)` is DELETED too, and
`maybeExecuteWorkflowGraph` is now `executeWorkflowGraph` returning void. The old boolean
meant "did the graph claim this task"; with the legacy fallback gone the answer is always
yes, so a bare `runImplementation` call with NO `graphCompletion` — an implementation pass
that nothing owns the completion of — is unreachable by construction rather than by
convention. That is what makes `graphCompletion` a required parameter below.
*/
graphRunnerOwnsClaim = true;
await deps.executeWorkflowGraph(task, { alreadyClaimed: true });
} finally {
// executeWorkflowGraph's finally releases the claim when it owns the run.
if (!graphRunnerOwnsClaim) {
deps.graphRouting.delete(task.id);
}
}
}

62
packages/engine/src/executor/execute-review-handoff.ts Normal file
View File

@@ -0,0 +1,62 @@
/**
* FNXC:CodeOrganization 2026-08-03-09:25:
* executeReviewHandoff peeled from TaskExecutor (U4).
* Agent-requested review handoff: awaiting-user-review, handoff to in-review, dispose session.
*/
import type { Task, TaskStore } from "@fusion/core";
import type { AgentSession } from "@earendil-works/pi-coding-agent";
import { executorLog } from "../logger.js";
import type { EngineRunContext } from "../util/run-audit.js";
export type ExecuteReviewHandoffDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
persistTokenUsage: (taskId: string) => Promise<void>;
handoffTaskToReview: (task: Task, reason: string) => Promise<unknown>;
activeSessions: Map<string, { session: AgentSession }>;
deleteActiveSession: (taskId: string) => void;
untrackStuckTask: (taskId: string) => void;
};
export async function executeReviewHandoff(
deps: ExecuteReviewHandoffDeps,
task: Task,
_session: AgentSession,
_sessionEntry: unknown,
): Promise<void> {
try {
executorLog.log(`Executing review handoff for ${task.id}`);
await deps.store.logEntry(
task.id,
"Review handoff requested by agent — moving to in-review for user review",
undefined,
deps.getRunContextFor(task.id),
);
await deps.store.updateTask(
task.id,
{
status: "awaiting-user-review",
assigneeUserId: "requesting-user",
},
deps.getRunContextFor(task.id),
);
await deps.persistTokenUsage(task.id);
await deps.handoffTaskToReview(task, "review-handoff-requested");
if (deps.activeSessions.has(task.id)) {
const { session: activeSession } = deps.activeSessions.get(task.id)!;
activeSession.dispose();
deps.deleteActiveSession(task.id);
}
deps.untrackStuckTask(task.id);
executorLog.log(`Review handoff complete for ${task.id} — task moved to in-review`);
} catch (err: unknown) {
const errorMessage = err instanceof Error ? err.message : String(err);
executorLog.error(`Failed to execute review handoff for ${task.id}: ${errorMessage}`);
}
}

718
packages/engine/src/executor/execute-workflow-graph.ts Normal file
View File

@@ -0,0 +1,718 @@
/**
* FNXC:CodeOrganization 2026-08-03-14:30:
* executeWorkflowGraph peeled from TaskExecutor (U4).
*
* Runs the graph-owned workflow path: claim routing, node preparation, custom-node
* execution, foreach worktree deps, and terminal handleGraphFailure.
*/
import type {
AgentStore,
Settings,
Task,
TaskDetail,
TaskStore,
ThinkingLevel,
WorkflowColumnAgent,
WorkflowIr,
WorkflowStepResult as CoreWorkflowStepResult,
WorkflowWorkItem,
} from "@fusion/core";
import {
ACTIVE_WORKFLOW_WORK_ITEM_STATES,
getBuiltinWorkflow,
resolveColumnAgentBinding,
resolveMaxConsecutiveToolFailureRetries,
resolveWorkflowIrForTask,
upsertWorkflowStepResult,
} from "@fusion/core";
import type { ImplementationExit } from "./implementation-exit.js";
import type { WorkflowGraphTaskRunResult } from "../workflows/workflow-graph-task-runner.js";
import { WorkflowGraphTaskRunner } from "../workflows/workflow-graph-task-runner.js";
import { WorkflowCustomNodeExecutionService } from "../workflows/workflow-custom-node-execution.js";
import {
requiredArtifactReadFailedValue,
workflowEntryArtifacts,
} from "../execution/required-workflow-artifacts.js";
import { getActiveNotificationService } from "../util/notifier.js";
import { executorLog } from "../logger.js";
import type { EngineRunContext } from "../util/run-audit.js";
import { takePreHeldExecutorSlot } from "../concurrency/concurrency.js";
import { resolveCompleteColumnFor } from "./lifecycle-columns.js";
import type { AgentSemaphore } from "../concurrency/concurrency.js";
import type { WorkflowAgentCapacity } from "../agents/workflow-agent-capacity.js";
import {
admitWorkflowPrincipalBeforeNode,
type ActiveWorkflowAuthority,
} from "./workflow-principal-before-node.js";
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- mirror TaskExecutor method/map surface
type AnyFn = (...args: any[]) => any;
export type ExecuteWorkflowGraphDeps = {
store: TaskStore;
options: {
prNodes?: unknown;
semaphore?: AgentSemaphore;
getLocalNodeId?: () => string | undefined;
agentStore?: AgentStore | null;
[k: string]: unknown;
};
activeWorkflowGraphAbortControllers: Map<string, AbortController>;
workflowAgentCapacity: WorkflowAgentCapacity;
activeWorkflowAuthorities: Map<string, ActiveWorkflowAuthority>;
activeWorkflowPrincipals: Map<string, { agentId: string; nodeInstanceId: string; agent?: import("@fusion/core").Agent }>;
graphColumnAgentResolver: Map<string, (nodeId: string) => WorkflowColumnAgent | undefined>;
graphExecuteSelfRequeued: Set<string>;
graphRethinkNarrations: Map<string, unknown>;
graphRouting: Set<string>;
graphSeamGoverningNodeId: Map<string, string>;
graphSeamSkillName: Map<string, string>;
graphSeamThinkingLevel: Map<string, ThinkingLevel>;
graphStepActiveContext: Map<string, unknown>;
graphStepRunOnce: Map<string, Promise<{ taskDone: boolean; modifiedFiles: string[]; exit?: ImplementationExit }>>;
graphStepSessionPinned: Set<string>;
graphToolFailureRunCursors: Map<string, number>;
graphUnattendedRuns: Set<string>;
outerConcurrencyClaims: Set<string>;
processWideGraphRouting: Set<string>;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
advanceNoMergeWorkflowToCompleteColumn: AnyFn;
applyGraphRethinkReset: AnyFn;
buildBranchPersistence: AnyFn;
buildCodeNodeRunner: AnyFn;
buildColumnBoundaryHooks: AnyFn;
buildForeachWorktreeDeps: AnyFn;
buildParseStepsDeps: AnyFn;
buildStepInstancePersistence: AnyFn;
createAuthoritativeWorkflowPrimitives: AnyFn;
createAuthoritativeWorkflowSeams: AnyFn;
finalizeMergeConfirmedWorkflowGraphTask: AnyFn;
handleGraphFailure: AnyFn;
isLiveSharedBranchGroupMember: (
task: Pick<TaskDetail, "branchContext" | "autoMerge" | "autoMergeProvenance">,
) => Promise<boolean>;
prepareGraphNodeExecution: AnyFn;
readTaskArtifact: AnyFn;
recoverMissingRequiredArtifacts: AnyFn;
requestPreMergeOptionalStepFix: AnyFn;
/** FNXC:PlanReviewNoOp 2026-08-09-22:10: CLOSE_NO_OP accepted terminalization (FN-8841). */
completePlanReviewNoOp: AnyFn;
/** FNXC:PlanReviewNoOp 2026-08-09-22:10: hold failed/invalid close evidence on the continuation. */
holdPlanReviewNoOpContinuation: AnyFn;
runGraphCustomNode: AnyFn;
terminateAllChildren: AnyFn;
};
export async function executeWorkflowGraph(
deps: ExecuteWorkflowGraphDeps,
task: Task,
opts?: { alreadyClaimed?: boolean },
): Promise<void> {
// Claim synchronously before any await so concurrent execute() calls for
// the same task cannot both enter graph routing (mirrors executingTaskLock).
// executeCore may already have claimed before its pre-graph awaits (FN-8471).
if (!opts?.alreadyClaimed) {
deps.graphRouting.add(task.id);
}
let graphAbortController: AbortController | undefined;
const workflowCapacityAttemptIds = new Set<string>();
/*
* FNXC:WorkflowAgentRouting 2026-08-07-05:06:
* Direct graph dispatch is also a production session-launch path. Track its
* per-node durable fences so direct runs do not degrade principals to a
* process-local map while scheduled continuations remain fenced in Postgres.
*/
const directWorkflowPrincipalWorkItemIds = new Set<string>();
const directWorkflowPrincipalHeldWorkItemIds = new Set<string>();
/*
FNXC:GlobalConcurrencyControls 2026-07-14-18:30:
The hold/release sweep may have already tryAcquired a global slot for this card before moving it to in-progress. Claim that pre-held slot for the full graph run so utilization stays honest between workflow nodes and triage cannot overfill the cap while this task is still graph-owned.
*/
const hadPreHeldExecutorSlot = takePreHeldExecutorSlot(task.id);
if (hadPreHeldExecutorSlot) {
deps.outerConcurrencyClaims.add(task.id);
}
try {
let settings: Settings;
try {
settings = await deps.store.getSettings();
} catch (err) {
await deps.handleGraphFailure(task, {
disposition: "failed",
outcome: "failure",
reason: `settings-load-failed: ${err instanceof Error ? err.message : String(err)}`,
visitedNodeIds: [],
});
return;
}
/*
FNXC:WorkflowExecution 2026-06-22-18:00:
workflowGraphExecutor graduated from Experimental. Every task routes through the graph runner by default, and stale persisted experimentalFeatures.workflowGraphExecutor=false values are ignored so the product no longer has a user-facing or runtime graph-engine kill switch.
*/
settings = { ...settings };
/*
* FNXC:ExecutorToolFailureRetry 2026-07-16-12:00:
* Capture a count cursor without reading the task log. Failure handling receives this
* execution-local boundary, so a stale task snapshot cannot accidentally qualify an old run.
*
* FNXC:ExecutorToolFailureRetry 2026-07-17-06:30:
* Minimal/test TaskStore adapters may omit getAgentLogCount (same optional pattern as
* project-engine). Treat a missing method as cursor 0 so graph entry does not throw
* "is not a function" and still records a durable detector boundary when updateTask exists.
*/
if (resolveMaxConsecutiveToolFailureRetries(settings) > 0) {
const cursor = typeof deps.store.getAgentLogCount === "function"
? await deps.store.getAgentLogCount(task.id).catch(() => 0)
: 0;
deps.graphToolFailureRunCursors.set(task.id, cursor);
if (typeof deps.store.updateTask === "function") {
await deps.store.updateTask(task.id, { toolFailureDetectorLogCursor: cursor }, deps.getRunContextFor(task.id));
}
}
let selection: { workflowId: string; stepIds: string[] } | undefined;
/*
FNXC:WorkflowExecution 2026-07-19-17:30 (U10b / R9):
The legacy fallback is DELETED. It used to return `false` here — handing the run to a
legacy execute path — when the store exposed neither workflow-selection reader. That
escape hatch is gone: graph ownership is now UNCONDITIONAL, which is what lets
`graphCompletion` be a required callback rather than an optional one and collapses the
three completion boundaries in `runImplementation` to plain returns.
A store that cannot resolve a workflow now ALWAYS fails closed, not only when the task
has enabled pre-merge steps. The old "no enabled steps means nothing to gate, so the
legacy path is safe" carve-out died with the path it protected: there is no second
executor left to fall back to, so returning `false` would silently run nothing.
*/
if (
typeof deps.store.getTaskWorkflowSelectionAsync !== "function"
&& typeof deps.store.getTaskWorkflowSelection !== "function"
) {
/*
FNXC:FastOptionalSteps 2026-06-30-09:45:
Fast mode only clears optional workflow steps by default; explicit `enabledWorkflowSteps` remains operator intent. Minimal or older stores that cannot resolve the graph must fail closed, even in fast mode, rather than falling through and silently skipping the selected optional-group body.
*/
await deps.handleGraphFailure(task, {
disposition: "failed",
outcome: "failure",
reason:
"workflow-selection-api-unavailable: store lacks a workflow-selection reader so the workflow graph cannot run; "
+ "the legacy execute fallback was removed (U10b) and the graph is the only executor. Failing closed rather than running nothing (KTD-5).",
visitedNodeIds: [],
});
return;
}
try {
selection = typeof deps.store.getTaskWorkflowSelectionAsync === "function"
? await deps.store.getTaskWorkflowSelectionAsync(task.id)
: deps.store.getTaskWorkflowSelection(task.id);
} catch (err) {
await deps.handleGraphFailure(task, {
disposition: "failed",
outcome: "failure",
reason: `workflow-selection-failed: ${err instanceof Error ? err.message : String(err)}`,
visitedNodeIds: [],
});
return;
}
selection ??= { workflowId: "builtin:coding", stepIds: [] };
// Resolve the production run id ONCE, here, so it is the single source of
// truth shared by the runner AND the executor-side persistence deps
// (parse-steps pin probe, foreach instance-row flips, resume reconcile). The
// runner derives `${task.id}:${definition.id}`; we mirror that derivation
// from the resolved definition and thread it everywhere. Best-effort: if the
// definition cannot be resolved (older store), the runner falls back to its
// own derivation and the deps fall back to the legacy `:run` literal — the
// prior behavior — so this never strands a task.
let resolvedRunId: string | undefined;
try {
const definition = selection.workflowId === "builtin:coding"
? { id: "builtin:coding" }
: await deps.store.getWorkflowDefinition?.(selection.workflowId);
if (definition) resolvedRunId = `${task.id}:${definition.id}`;
} catch {
// Definition load failure — leave undefined; deps/runner use fallbacks.
}
// Column-agent binding (plan U3): the IR is NOT in scope inside
// runGraphCustomNode, so resolve it here (the seam wiring) where the
// selection is known, and thread a per-node binding lookup into the custom
// node callback. Resolve the IR ONCE per run (never an uncached per-node
// fetch — mirrors the hold-release.ts irCache posture); best-effort, so a
// resolution failure simply yields no bindings (R8 graceful degradation).
/*
FNXC:WorkflowColumns 2026-06-22-18:00:
Column-agent binding now participates in every graph run. The former workflowColumns kill switch was removed, so stale persisted false values cannot silently disable custom-node, seam, or watcher bindings.
*/
let columnAgentIr: WorkflowIr | undefined;
try {
columnAgentIr = await resolveWorkflowIrForTask(deps.store, task.id);
} catch {
columnAgentIr = undefined;
}
if (columnAgentIr) {
const missingEntryArtifacts: string[] = [];
for (const artifact of workflowEntryArtifacts(columnAgentIr)) {
let content: string | undefined;
try {
content = await deps.readTaskArtifact(task.id, artifact.key);
} catch (error) {
const failureValue = requiredArtifactReadFailedValue(artifact.key);
await deps.handleGraphFailure(task, {
disposition: "failed",
outcome: "failure",
reason: `workflow-required-artifact-read-failed:${artifact.key}:${error instanceof Error ? error.message : String(error)}`,
visitedNodeIds: ["workflow-entry-artifact"],
context: { "node:workflow-entry-artifact:value": failureValue },
});
return;
}
if (typeof content !== "string" || !content.trim()) missingEntryArtifacts.push(artifact.key);
}
if (missingEntryArtifacts.length > 0) {
const liveTask = await deps.store.getTask(task.id).catch(() => task);
await deps.recoverMissingRequiredArtifacts(liveTask, missingEntryArtifacts, { source: "graph-entry" });
return;
}
}
const resolveBindingForNode = (nodeId: string): WorkflowColumnAgent | undefined =>
columnAgentIr ? resolveColumnAgentBinding(columnAgentIr, nodeId) : undefined;
// Column-agent seam wiring (U4): expose the same per-run resolver to the
// execute / step-execute seams (which key off a governing node id stamped
// into context), so the coding/step session runs as the column agent under
// the SAME binding lookup the custom-node seam uses (KTD-2 single resolver).
deps.graphColumnAgentResolver.set(task.id, resolveBindingForNode);
// (U3) Genuinely-unattended run signal. This is an EXPLICIT opt-in, not an
// inferred heuristic: a run is unattended only when an entrypoint that
// knows no human will ever answer (LFG / pipeline / disable-model-invocation)
// marks it so. No such marker reaches this executor path today (verified —
// KTD-3), so this resolves to false (board run) for every current run, and
// the safe default is preserved: absence of the explicit flag ALWAYS yields
// no FUSION_HEADLESS, so a board task can only ever park (a human can answer
// via the await-input card button), never silently skip approval. When such
// an entrypoint is added, it sets `unattended` here.
// No entrypoint sets this today, so clear any stale entry; a board run never
// sets FUSION_HEADLESS. When an LFG/pipeline/disable-model-invocation
// entrypoint is added, call `deps.graphUnattendedRuns.add(task.id)` here and
// the finally below clears it.
deps.graphUnattendedRuns.delete(task.id);
graphAbortController = new AbortController();
deps.activeWorkflowGraphAbortControllers.set(task.id, graphAbortController);
const customNodeExecution = new WorkflowCustomNodeExecutionService({
execute: (node, nodeTask, nodeSettings, columnBinding, context) =>
deps.runGraphCustomNode(node, nodeTask, nodeSettings, columnBinding, context),
resolveColumnBinding: resolveBindingForNode,
});
/*
FNXC:PlanReviewNoOp 2026-08-09-22:10:
Continuation is declared before the runner so holdPlanReviewNoOp can replace it
during CLOSE_NO_OP terminalization failure without a TDZ (FN-8841).
*/
let continuation: WorkflowWorkItem | undefined;
const runner = new WorkflowGraphTaskRunner({
localNodeId: deps.options.getLocalNodeId?.(),
store: {
...deps.store,
/*
FNXC:WorkflowSelection 2026-07-14-17:06:
Graph execution must reuse the asynchronously resolved selection. A PostgreSQL TaskStore cannot provide that selection through the synchronous compatibility method, and substituting builtin:coding here would silently execute the wrong graph.
*/
getTaskWorkflowSelection: () => selection,
getTaskWorkflowSelectionAsync: async () => selection,
getWorkflowDefinition: async (id: string) =>
(await deps.store.getWorkflowDefinition?.(id))
?? (id === "builtin:coding" ? getBuiltinWorkflow("builtin:coding") : undefined),
getTask: (taskId: string) => deps.store.getTask(taskId),
},
runId: resolvedRunId,
isLiveSharedBranchMember: (nodeTask) =>
deps.isLiveSharedBranchGroupMember(nodeTask),
primitives: deps.createAuthoritativeWorkflowPrimitives(settings),
seams: deps.createAuthoritativeWorkflowSeams(settings),
prepareNodeExecution: (node, nodeTask, requirement) =>
deps.prepareGraphNodeExecution(node, nodeTask, settings, requirement),
beforeNodeExecution: async (node, nodeTask, context) =>
admitWorkflowPrincipalBeforeNode(
{
store: deps.store,
options: deps.options,
workflowAgentCapacity: deps.workflowAgentCapacity,
activeWorkflowAuthorities: deps.activeWorkflowAuthorities,
activeWorkflowPrincipals: deps.activeWorkflowPrincipals,
workflowCapacityAttemptIds,
directWorkflowPrincipalWorkItemIds,
directWorkflowPrincipalHeldWorkItemIds,
columnAgentIr,
resolveBindingForNode,
resolvedRunId,
settings,
},
node,
nodeTask,
context,
),
runCustomNode: customNodeExecution.runner(settings),
publishTaskProjection: async (taskId, patch) => {
await deps.store.updateTaskAtomic(taskId, (liveTask) => {
const update: Parameters<TaskStore["updateTask"]>[1] = {};
if (patch.modifiedFiles) {
const merged = [...new Set([...(liveTask.modifiedFiles ?? []), ...patch.modifiedFiles])].sort();
if (merged.length > 0) update.modifiedFiles = merged;
}
if (patch.mergeDetails) {
update.mergeDetails = { ...(liveTask.mergeDetails ?? {}), ...patch.mergeDetails };
}
if (patch.summary !== undefined) update.summary = patch.summary;
return update;
});
},
onEvent: (event) => executorLog.debug(`[workflow-graph] ${event.type} ${event.taskId}: ${event.detail}`),
signal: graphAbortController.signal,
// Wire SQLite-backed per-branch persistence in production (#1407): the
// executor writes each branch's currentNodeId/status to
// workflow_run_branches so fan-out crash-resume and the U9 badges have
// real data, and prunes stale runs (#1412). Adapter degrades to no-op
// when the store predates these methods (additive guard).
branchPersistence: deps.buildBranchPersistence(),
// Step-inversion (KTD-6, U3/U4): per-instance run-state persistence.
stepInstancePersistence: deps.buildStepInstancePersistence(),
// Step-inversion (KTD-4, U5): RETHINK reset-on-rework — when the foreach
// sub-walk traverses a rework edge triggered by `outcome:rethink`, reset
// the active instance's step to its persisted per-step baseline (git reset
// + session rewind + step→pending) before re-entering step-execute.
onReworkReset: (active) => deps.applyGraphRethinkReset(task.id, active),
// Step-inversion (KTD-12, U12): parse-steps node handler deps — artifact
// read (through task-documents with PROMPT.md fallback), step-list write
// (graph-source projection), pin-protection probe, and audit.
parseStepsDeps: deps.buildParseStepsDeps(resolvedRunId),
// Step-inversion (KTD-15, U14): code node runner — esbuild compile +
// child-process execution with the harness contract.
runCode: deps.buildCodeNodeRunner(),
notifyDispatch: (event, payload) => getActiveNotificationService()?.dispatch(event, payload),
// PR-entity nodes (U3): pr-create/pr-respond/pr-merge handler deps —
// engine-owned store + CLI-injected GitHub callbacks. Absent → fail closed.
prNodes: deps.options.prNodes,
// Step-inversion (KTD-11, U10): worktree isolation + ordered integration +
// parallel scheduling. Per-instance worktrees branched off the task's main
// branch tip; integration rebases each branch in step order; the projection
// flips done-iff-integrated. Shared isolation never invokes these.
...deps.buildForeachWorktreeDeps(task, resolvedRunId),
// FIX 4 (context gap): task-level log sink so an integration-conflict
// rework writes a visible "reworking on updated base (files: ...)" entry
// the re-running agent can read. Best-effort; logging failures swallowed.
logTaskEntry: (summary: string, detail?: string) => {
void deps.store
.logEntry(task.id, summary, detail, deps.getRunContextFor(task.id))
.catch(() => {});
},
/*
FNXC:WorkflowStepResults 2026-06-25-12:00:
Plan U2 (KTD-1/KTD-2): persistence adapter for an ENABLED optional-group
node's outcome. The graph records each enabled group's WorkflowStepResult
into the EXISTING `task.workflowStepResults` field keyed by `node.id` so the
unified progress bar (getUnifiedTaskProgress) reflects graph-run steps —
NO new table/type/store method. Upsert by `workflowStepId === node.id`
(replace-if-present else append) through the existing
`store.updateTask({workflowStepResults})` path. Fail-soft: degrade to a
no-op when the store lacks updateTask, and swallow read/write errors (the
executor wrapper also swallows) so result recording never affects the run.
*/
/*
FNXC:PlanReviewNoOp 2026-08-09-01:55:
Invalid, unroutable, or failed Plan Review closes are explicit waits, not graph failures.
Keep one held continuation at plan-review so scheduler resume preserves the audited close
evidence without changing the task's column or manufacturing a task error.
*/
completePlanReviewNoOp: (nodeTask, marker) => deps.completePlanReviewNoOp(nodeTask, marker),
holdPlanReviewNoOp: async (nodeTask, suspension) => {
continuation = await deps.holdPlanReviewNoOpContinuation(nodeTask, suspension, continuation, resolvedRunId);
},
recordWorkflowStepResult: async (taskId: string, result: CoreWorkflowStepResult) => {
if (typeof deps.store.updateTask !== "function") return;
try {
const live = await deps.store.getTask(taskId);
/*
FNXC:WorkflowStepResults 2026-07-09-00:25:
FN-7727: route through the shared, pure upsert helper instead of a
bare `existing[idx] = result` replace-in-place — a self-healing
recovery re-run of this same node (e.g. code-review sent back for
fix) must preserve the prior `status:"failed"` entry's history in
`priorAttempts` rather than silently overwriting it.
*/
const existing = upsertWorkflowStepResult(live?.workflowStepResults, result);
await deps.store.updateTask(taskId, { workflowStepResults: existing }, deps.getRunContextFor(taskId));
} catch {
// Result recording is additive visibility — never affect the run.
}
},
requestPreMergeOptionalStepFix: (taskId, info) => deps.requestPreMergeOptionalStepFix(taskId, task, info),
// U5c (U1 KTD-1/2/3/12): wire the production lifecycle-move hooks so the
// graph interpreter owns the card's column moves (was reverted in U5a
// pending U6/U7 trait re-key; safe now). Absent → the graph performs no
// lifecycle moves (pre-cutover byte-identical); present → the controller
// moves the card on each node-column boundary with all move-safety.
columnBoundaryHooks: deps.buildColumnBoundaryHooks(task, resolvedRunId),
});
let result: WorkflowGraphTaskRunResult;
try {
const loadedDetail = await deps.store.getTask(task.id);
/*
FNXC:WorkflowExecution 2026-06-23-11:36:
Graph dispatch must preserve the row identity that entered execute(). Minimal test stores and stale adapters can return an unrelated fallback task from getTask(); trusting that row would run the workflow under the wrong task id and bypass executor invariants. Use the refreshed row only when it matches the dispatch task.
*/
const detail: TaskDetail = loadedDetail?.id === task.id
? loadedDetail
: { ...task, prompt: task.prompt ?? task.description ?? "" };
const workItems = await deps.store.listWorkflowWorkItemsForTask?.(task.id, { kinds: ["task"] }) ?? [];
for (let index = workItems.length - 1; index >= 0; index -= 1) {
const candidate = workItems[index];
if (ACTIVE_WORKFLOW_WORK_ITEM_STATES.includes(candidate.state)) {
continuation = candidate;
break;
}
}
if (continuation && continuation.state !== "running") {
continuation = await deps.store.transitionWorkflowWorkItem(continuation.id, "running", {
leaseOwner: `executor:${task.id}`,
leaseExpiresAt: null,
lastError: null,
});
}
/*
* FNXC:WorkflowAgentRouting 2026-08-07-07:45:
* A direct graph resume owns the same durable continuation as scheduler
* work-item dispatch. Rehydrate its fence before the graph reaches
* beforeNodeExecution so recovery validates this exact principal instead
* of silently choosing a fresh role-pool candidate.
*/
const continuationContext = continuation?.principalAgentId
? {
"workflow:work-item-id": continuation.id,
"workflow:principal-agent-id": continuation.principalAgentId,
"workflow:principal-role": continuation.workflowRole,
"workflow:principal-authority": continuation.authorityKind,
"workflow:node-instance-id": continuation.nodeInstanceId ?? continuation.nodeId,
}
: undefined;
/*
* FNXC:WorkflowExecution 2026-08-08-01:40:
* Only a TOP-LEVEL node id is a legal resume point. A foreach template node id
* is not in ir.nodes; re-enter at the column resume node instead of terminalizing.
*/
const resumeNodeId = continuation?.nodeId
&& columnAgentIr?.nodes.some((candidate) => candidate.id === continuation?.nodeId)
? continuation.nodeId
: undefined;
if (continuation?.nodeId && resumeNodeId === undefined) {
executorLog.debug(
`[workflow-graph] ${task.id}: continuation node '${continuation.nodeId}' is not a top-level graph node `
+ `(instance '${continuation.nodeInstanceId ?? "none"}') — re-entering at the column resume node`,
);
}
result = await runner.run(detail, settings, resumeNodeId, continuationContext);
} catch (err) {
if (continuation) {
await deps.store.transitionWorkflowWorkItem(continuation.id, "failed", {
leaseOwner: null,
leaseExpiresAt: null,
lastError: "workflow-continuation-dispatch-failed",
}).catch(() => undefined);
}
executorLog.error(
`[workflow-graph] ${task.id} interpreter threw — parking task as workflow failure: ${err instanceof Error ? err.message : String(err)}`,
);
await deps.handleGraphFailure(task, {
disposition: "failed",
outcome: "failure",
reason: `interpreter-error: ${err instanceof Error ? err.message : String(err)}`,
visitedNodeIds: [],
});
return;
}
const principalHoldReason = Object.values(result.context ?? {}).find((value): value is string =>
typeof value === "string" && value.startsWith("workflow-principal-"),
);
/*
* FNXC:WorkflowAgentRouting 2026-08-07-07:45:
* Principal availability is a recoverable continuation hold, not a graph
* failure. Do not terminalize the direct fence or call graph failure
* handling; the next direct resume must receive the same fenced identity.
*/
if (principalHoldReason) {
/*
* FNXC:WorkflowAgentRouting 2026-08-07-22:39:
* A principal hold is a WAIT and must not be invisible. Log holds; error for the
* never-clears composition fault (missing agent-store / IR).
*/
const neverClears = principalHoldReason.startsWith("workflow-principal-routing-unavailable:");
const holdMessage = `[workflow-graph] ${task.id} held at graph node — ${principalHoldReason}`;
if (neverClears) {
executorLog.error(`${holdMessage} (workflow principal routing is unavailable; this hold cannot self-clear)`);
} else {
executorLog.warn(holdMessage);
}
await deps.store.logEntry(task.id, `Workflow stage held — ${principalHoldReason}`).catch(() => undefined);
if (
continuation
&& typeof deps.store.transitionWorkflowWorkItem === "function"
&& !directWorkflowPrincipalHeldWorkItemIds.has(continuation.id)
) {
await deps.store.transitionWorkflowWorkItem(continuation.id, "held", {
leaseOwner: null,
leaseExpiresAt: null,
lastError: principalHoldReason,
blockedReason: principalHoldReason,
}).catch(() => undefined);
}
return;
}
/* Direct graph node fences are terminalized only after the interpreter
* returns, preserving their historical principal through all handler and
* tool-gate calls while ensuring completed work cannot render as active.
* Availability holds intentionally remain held for recovery instead. */
if (result.disposition !== "suspended" && directWorkflowPrincipalWorkItemIds.size > 0 && typeof deps.store.transitionWorkflowWorkItem === "function") {
const terminalState = result.disposition === "completed" ? "succeeded" : "failed";
await Promise.all([...directWorkflowPrincipalWorkItemIds].map(async (id) => {
if (directWorkflowPrincipalHeldWorkItemIds.has(id)) return;
await deps.store.transitionWorkflowWorkItem(id, terminalState, {
leaseOwner: null,
leaseExpiresAt: null,
lastError: terminalState === "failed" ? "workflow-graph-node-failed" : null,
}).catch(() => undefined);
}));
}
if (result.disposition === "fell-back") {
executorLog.warn(`[workflow-graph] ${task.id} could not resolve workflow — parking task instead of legacy fallback: ${result.reason}`);
await deps.handleGraphFailure(task, {
...result,
disposition: "failed",
outcome: "failure",
reason: result.reason ?? "workflow-resolution-failed",
});
return;
}
if (result.disposition === "suspended") {
/*
* FNXC:WorkflowExecution 2026-08-07-22:52:
* Record suspension so an invisible wait is greppable (ids/outcomes-only audit).
*/
const suspension = result.suspension;
await deps.store.recordRunAuditEvent?.({
taskId: task.id,
agentId: "executor",
runId: resolvedRunId ?? `workflow-run-suspended:${task.id}`,
domain: "database",
mutationType: "task:workflow-run-suspended",
target: task.id,
metadata: {
taskId: task.id,
nodeId: suspension?.nodeId ?? "unknown",
reason: suspension?.reason ?? "unknown",
fromColumn: suspension?.fromColumn ?? null,
toColumn: suspension?.toColumn ?? null,
continuationId: continuation?.id ?? null,
continuationNodeId: continuation?.nodeId ?? null,
continuationState: continuation?.state ?? null,
},
}).catch(() => undefined);
executorLog.log(
`[workflow-graph] ${task.id} suspended at node '${suspension?.nodeId ?? "unknown"}' (${suspension?.reason ?? "unknown"})`,
);
return;
}
/*
* FNXC:WorkflowExecution 2026-08-08-03:20:
* Closing the continuation is bookkeeping and must never skip handleGraphFailure.
*/
const closeContinuation = async (state: "failed" | "succeeded"): Promise<void> => {
if (!continuation || typeof deps.store.transitionWorkflowWorkItem !== "function") return;
if (directWorkflowPrincipalHeldWorkItemIds.has(continuation.id)) return;
try {
await deps.store.transitionWorkflowWorkItem(continuation.id, state, {
leaseOwner: null,
leaseExpiresAt: null,
lastError: state === "failed" ? "workflow-continuation-failed" : null,
});
} catch (closeErr) {
executorLog.debug(
`[workflow-graph] ${task.id}: continuation ${continuation.id} could not be closed as ${state} `
+ `(likely already terminal): ${closeErr instanceof Error ? closeErr.message : String(closeErr)}`,
);
}
};
if (result.disposition === "failed") {
await closeContinuation("failed");
await deps.handleGraphFailure(task, result);
} else if (result.disposition === "completed") {
await closeContinuation("succeeded");
const live = await deps.store.getTask(task.id).catch(() => task);
if ((live as TaskDetail).mergeDetails?.mergeConfirmed === true && (live as TaskDetail).column !== await resolveCompleteColumnFor(deps.store, task.id)) {
await deps.finalizeMergeConfirmedWorkflowGraphTask(task.id, "graph-completed");
}
await deps.advanceNoMergeWorkflowToCompleteColumn(live as TaskDetail);
if ((live.graphResumeRetryCount ?? 0) !== 0 || (live.consecutiveToolFailureRetryCount ?? 0) !== 0) {
await deps.store.updateTask(task.id, { graphResumeRetryCount: 0, consecutiveToolFailureRetryCount: 0, executorEscalationAttempted: false, toolFailureDetectorLogCursor: null, toolFailureRetryExhaustedAuditEmitted: false }, deps.getRunContextFor(task.id));
}
}
return;
} finally {
// FNXC:WorkflowGraph 2026-06-20-23:35:
// Terminate child agents spawned by this graph run's coding-mode skill steps.
// U8 registered fn_spawn_agent for coding-mode steps, but the graph path
// returns from execute() at the graphOwned early-return — BEFORE execute()'s
// outer finally that calls terminateAllChildren. Without this, graph-step
// children orphan their sessions/worktrees, and their ids accumulate in the
// per-parent spawn budget (spawnedAgents[taskId]), starving later steps'
// fan-out (e.g. ce-code-review's reviewer panel). Mirror the non-graph
// cleanup; run it before the per-run graph bookkeeping below.
try {
await deps.terminateAllChildren(task.id);
} catch (err) {
executorLog.warn(`terminateAllChildren failed for graph task ${task.id}: ${err instanceof Error ? err.message : String(err)}`);
}
if (hadPreHeldExecutorSlot) {
deps.outerConcurrencyClaims.delete(task.id);
/*
FNXC:GlobalConcurrencyControls 2026-07-19-17:40 (U10b):
Always release. The `transferPreHeldToLegacy` branch — which re-registered the reserved
global slot for a legacy execute path to pick up — died with that path: the graph can no
longer decline ownership, so there is no second executor to hand the slot to. Holding the
registration with nothing left to claim it would permanently reduce global capacity.
*/
deps.options.semaphore?.release();
}
for (const attemptId of workflowCapacityAttemptIds) {
void deps.workflowAgentCapacity.release(
attemptId,
deps.options.agentStore?.workflowProjectId ?? deps.store.getRootDir(),
);
}
deps.activeWorkflowAuthorities.delete(task.id);
deps.activeWorkflowPrincipals.delete(task.id);
if (graphAbortController && deps.activeWorkflowGraphAbortControllers.get(task.id) === graphAbortController) {
deps.activeWorkflowGraphAbortControllers.delete(task.id);
}
deps.graphRouting.delete(task.id);
deps.graphToolFailureRunCursors.delete(task.id);
// Clear per-run step-inversion pins (KTD-8: pinned only for the run's life).
deps.graphStepSessionPinned.delete(task.id);
deps.graphStepRunOnce.delete(task.id);
// Clear per-run column-agent seam wiring (U4): the resolver and any dangling
// governing-node-id are scoped to this run only.
deps.graphColumnAgentResolver.delete(task.id);
deps.graphUnattendedRuns.delete(task.id);
deps.graphSeamGoverningNodeId.delete(task.id);
deps.graphSeamThinkingLevel.delete(task.id);
deps.graphSeamSkillName.delete(task.id);
deps.graphExecuteSelfRequeued.delete(task.id);
// Per-instance keys: clear every instance slot owned by this task.
const ctxPrefix = `${task.id}:`;
for (const key of deps.graphStepActiveContext.keys()) {
if (key.startsWith(ctxPrefix)) deps.graphStepActiveContext.delete(key);
}
for (const key of deps.graphRethinkNarrations.keys()) {
if (key.startsWith(ctxPrefix)) deps.graphRethinkNarrations.delete(key);
}
}
}

867
packages/engine/src/executor/execute-workflow-step.ts Normal file
View File

@@ -0,0 +1,867 @@
/**
* FNXC:CodeOrganization 2026-08-03-15:20:
* executeWorkflowStep peeled from TaskExecutor (U4).
*
* Runs a single workflow step (prompt/skill/review) as an agent session with
* structured verdict parsing, browser-verification probing, and await-input
* sentinel handling.
*/
import { exec } from "node:child_process";
import { promisify } from "node:util";
import type {
AgentStore,
Settings,
Task,
TaskStore,
WorkflowStep,
} from "@fusion/core";
import {
finalizePlanningSegment,
resolveExecutorFallbackModel,
resolvePersistAgentThinkingLog,
resolveValidatorFallbackModel,
startPlanningSegment,
} from "@fusion/core";
import type { AgentSession, ToolDefinition } from "@earendil-works/pi-coding-agent";
import { createTaskPromptWriteTool } from "./shared-worker-tools.js";
import type { PluginRunner } from "../plugins/plugin-runner.js";
import { AgentLogger } from "../agents/agent-logger.js";
import { buildSystemPromptWithInstructions } from "../agents/agent-instructions.js";
import {
createResolvedAgentSession,
extractRuntimeHint,
resolveExecutorFallbackThinkingLevel,
resolveExecutorSessionModel,
resolveExecutorThinkingLevel,
resolveValidatorFallbackThinkingLevel,
resolveValidatorSessionModel,
resolveValidatorThinkingLevel,
} from "../agents/agent-session-helpers.js";
import {
buildUserCommentsPromptSection,
selectUserCommentsForAgentContext,
} from "../agents/agent-user-comments.js";
import { buildSessionSkillContext } from "../cli-runtime/session-skill-context.js";
import { checkSessionError } from "../errors/usage-limit-detector.js";
import {
requiredArtifactMissingValue,
requiredArtifactReadFailedValue,
} from "../execution/required-workflow-artifacts.js";
import { accumulateSessionTokenUsage } from "../execution/session-token-usage.js";
import { createStreamingDeltaNormalizer } from "../execution/streaming-delta.js";
import { describeModel, formatModelMarkerDetails, promptWithFallback } from "../pi.js";
import {
detectExternalIntegrationEvidenceGaps,
formatExternalIntegrationEvidenceDiagnostic,
} from "../spec-validation/external-integration-evidence.js";
import { createRunAuditor, type EngineRunContext } from "../util/run-audit.js";
import {
ReadonlyViolationError,
filterCustomToolsForReadonly,
} from "../workflows/workflow-step-tool-policy.js";
import { executorLog } from "../logger.js";
import { parseAwaitInputQuestionToolCall } from "./await-input-parse.js";
import {
augmentSessionSkillsForBrowserStep,
formatAgentBrowserAvailabilityLog,
probeAgentBrowserAvailability,
type AgentBrowserExec,
} from "./browser-probe.js";
import { isWorkflowStepSkillDiscoverable, mergeAdditionalSkillPaths } from "./skill-path-helpers.js";
import { createSeenSteeringIds } from "./task-predicates.js";
import {
parseWorkflowStepOutput,
type WorkflowStepOutcome,
} from "./workflow-step-verdict.js";
import { resolveDiffBaseRef } from "./worktree-git-refs.js";
const execAsync = promisify(exec);
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- mirror TaskExecutor method/map surface
type AnyFn = (...args: any[]) => any;
export type ExecuteWorkflowStepDeps = {
store: TaskStore;
rootDir: string;
options: {
pluginRunner?: PluginRunner;
agentStore?: AgentStore | null;
onAgentText?: (taskId: string, delta: string) => void;
onAgentTool?: (taskId: string, toolName: string, detail?: string) => void;
[k: string]: unknown;
};
activePlanningWorkflowSessions: Set<string>;
activeWorkflowStepSessions: Map<string, AgentSession>;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
captureModifiedFiles: AnyFn;
createSpawnAgentTool: AnyFn;
/** FNXC:CodeOrganization 2026-08-03-22:25: plan-review prompt-write uses shared free factory */
sharedWorkerTools: import("./shared-worker-tools.js").SharedWorkerToolsDeps;
deleteActiveWorkflowStepSession: AnyFn;
getAssignedAgentRuntimeConfig: AnyFn;
getAuthoritativeAssignedAgent: AnyFn;
readTaskArtifact: AnyFn;
resolveInstructionsForRole: AnyFn;
resolveMcpServers: AnyFn;
setActiveWorkflowStepSession: AnyFn;
};
export async function executeWorkflowStep(
deps: ExecuteWorkflowStepDeps,
task: Task,
workflowStep: WorkflowStep,
worktreePath: string,
settings: Settings,
taskEnv?: NodeJS.ProcessEnv,
stepOptions?: { unattended?: boolean },
): Promise<WorkflowStepOutcome> {
let toolMode: "coding" | "readonly" = workflowStep.toolMode || "readonly";
// (U3) Genuinely-unattended run — set FUSION_HEADLESS=1 below so skills record
// assumptions and proceed instead of parking on a question. Explicit opt-in
// only (default false = board run); see runGraphCustomNode / KTD-3.
const unattended = stepOptions?.unattended === true;
const isPlanReviewStep = workflowStep.id === "graph:plan-review-step" || workflowStep.name === "Plan Review";
/*
FNXC:WorkflowReviewFindings 2026-08-05-06:29:
reviewKind is carried from graph synthesis (cfg.reviewKind / optional-group context) so prompt
nodes that classify as plan/code review emit the structured findings schema and return
normalized findings on the step outcome for the Review tab.
*/
const workflowStepMetadata = workflowStep as WorkflowStep & {
optionalGroupId?: string;
reviewKind?: "plan" | "code";
reviewCanFixInline?: boolean;
requireExternalIntegrationEvidence?: boolean;
};
const optionalGroupId = workflowStepMetadata.optionalGroupId;
const isReviewTypeWorkflowStep =
isPlanReviewStep
|| workflowStepMetadata.reviewCanFixInline === true
|| /(?:^|\b)(?:review|verification)(?:\b|$)/i.test(workflowStep.name)
|| optionalGroupId === "plan-review"
|| optionalGroupId === "code-review"
|| optionalGroupId === "browser-verification";
const reviewerInlineFixesEnabled = (settings as Settings & { reviewerInlineFixes?: boolean }).reviewerInlineFixes !== false;
const allowReviewerInlineFixes = reviewerInlineFixesEnabled && isReviewTypeWorkflowStep && workflowStep.mode === "prompt";
const allowPlanReviewPromptWrite = allowReviewerInlineFixes && isPlanReviewStep;
if (allowReviewerInlineFixes && !isPlanReviewStep) {
/*
* FNXC:WorkflowReviewers 2026-07-01-12:36:
* Review-type workflow nodes can now repair their own findings when the workflow setting `reviewerInlineFixes` is on. Use coding tools for implementation review sessions so Code Review, Browser Verification, and custom review/verification gates do not have to bounce through executor remediation for issues they can safely fix inline. Plan Review stays on a narrow PROMPT.md writer because it runs before implementation.
*/
toolMode = "coding";
}
const requireExternalIntegrationEvidence =
workflowStepMetadata.requireExternalIntegrationEvidence === true;
/*
* FNXC:WorkflowReviewSpecInjection 2026-07-18-18:15:
* FN-7561 established that review agents cannot reliably locate the project-root PROMPT.md from a task worktree. Load it once through the store and embed it for every review-type node. FN-8288 extends that invariant beyond Plan Review: approved planning revisions are authoritative, the original task description is historical, and a failed artifact read must stay visible instead of silently restoring superseded scope.
*/
let workflowReviewSpecArtifact: string | undefined;
if (isReviewTypeWorkflowStep) {
try {
workflowReviewSpecArtifact = await deps.readTaskArtifact(task.id, "PROMPT.md");
} catch (error) {
const diagnostic = `PROMPT.md could not be read because task storage failed; ${workflowStep.name} must retry without replanning. ${error instanceof Error ? error.message : String(error)}`;
await deps.store.logEntry(task.id, `[pre-merge] ${workflowStep.name} artifact read failed: ${diagnostic}`);
return {
success: false,
error: diagnostic,
output: diagnostic,
failureValue: requiredArtifactReadFailedValue("PROMPT.md"),
};
}
}
const workflowReviewSpecText = typeof workflowReviewSpecArtifact === "string" ? workflowReviewSpecArtifact : "";
const planReviewSpecText = isPlanReviewStep ? workflowReviewSpecText : "";
/*
FNXC:PlanReview 2026-07-21-16:30:
Review steps must never approve or execute against an unavailable contract. Confirmed missing or whitespace-only PROMPT.md fails closed before reviewer creation; typed recovery routes ownership back to planning without spending the review-revision budget.
*/
if (isReviewTypeWorkflowStep && !workflowReviewSpecText.trim()) {
const diagnostic = `PROMPT.md could not be loaded; ${workflowStep.name} cannot approve without the authoritative task contract.`;
await deps.store.logEntry(
task.id,
`[pre-merge] ${workflowStep.name} refused to run without PROMPT.md: ${diagnostic}`,
);
return {
success: false,
revisionRequested: true,
output: `REVISE: ${diagnostic}`,
verdict: "REVISE",
notes: diagnostic,
failureValue: requiredArtifactMissingValue(["PROMPT.md"]),
};
}
if (isPlanReviewStep && requireExternalIntegrationEvidence) {
/*
* FNXC:PlanValidation 2026-06-30-09:03:
* Coding (per-step review) intentionally keeps external-integration evidence as a Plan Review gate. Enforce it here, not in triage, so only workflows that set `requireExternalIntegrationEvidence` block and failures route through the graph's normal plan-replan loop.
*/
const evidenceGaps = detectExternalIntegrationEvidenceGaps({
promptContent: planReviewSpecText,
});
if (evidenceGaps.length > 0) {
const diagnostic = formatExternalIntegrationEvidenceDiagnostic(evidenceGaps);
const output = `REVISE: ${diagnostic}`;
await deps.store.logEntry(
task.id,
`[pre-merge] Plan Review deterministic external-integration evidence check requested revision: ${diagnostic}`,
);
return {
success: false,
revisionRequested: true,
output,
verdict: "REVISE",
notes: diagnostic,
};
}
}
// Compute the diff scope so the workflow step agent reviews only what THIS
// task changed — not unrelated files it might wander into. Without this,
// open-ended review prompts (e.g. "verify visual polish") have been
// observed to spend the entire timeout budget reading pre-existing files
// that match the task description's keywords. See FN-3327 post-mortem.
const scopedFiles = await deps.captureModifiedFiles(worktreePath, task.baseCommitSha, task.id, undefined, "workflow-step-handler");
let diffShortstat: string | undefined;
try {
const baseRef = await resolveDiffBaseRef(worktreePath, task.baseCommitSha);
if (baseRef) {
const { stdout } = await execAsync(`git diff --shortstat ${baseRef}..HEAD`, {
cwd: worktreePath,
encoding: "utf-8",
});
diffShortstat = stdout.trim() || undefined;
}
} catch {
// best-effort — fall through with no shortstat
}
const MAX_SCOPE_FILES = 100;
const scopeFileBlock = scopedFiles.length === 0
? "(no modified files detected for this task — review the worktree directly, but do NOT browse unrelated files)"
: scopedFiles.length > MAX_SCOPE_FILES
? `${scopedFiles.slice(0, MAX_SCOPE_FILES).map((f: string) => `- ${f}`).join("\n")}\n- ... (${scopedFiles.length - MAX_SCOPE_FILES} more files truncated)`
: scopedFiles.map((f: string) => `- ${f}`).join("\n");
/*
* FNXC:PlanReviewScope 2026-06-29-00:57:
* Plan Review validates the planned PROMPT.md before execution. It must not
* inherit the generic workflow-step diff scope, because dirty worktrees or
* unrelated local commits can make a plan-only gate reject implementation
* state and loop back to triage after the planner already approved the spec.
*/
const approvedContractBlock = isReviewTypeWorkflowStep && !isPlanReviewStep
? `
Approved Task Contract:
- PROMPT.md is the authoritative current contract for this review. It includes any approved planning revisions and scope decisions.
- The Task Description is historical input only. Do not enforce superseded requirements from the original Task Description when they conflict with PROMPT.md.
- Do not request behavior that PROMPT.md explicitly defers, excludes, or forbids. Review the implementation against the approved contract reproduced below.
- Scope exclusions do not waive security, correctness, or data-integrity defects in the approved implementation.
--- BEGIN APPROVED PROMPT.md ---
${workflowReviewSpecText}
--- END APPROVED PROMPT.md ---`
: "";
const scopeBlock = isPlanReviewStep
? `Plan Review Scope:
- Review the task plan artifact (PROMPT.md), reproduced verbatim below, and task metadata only.
- The plan is embedded in this prompt — do NOT go looking for a PROMPT.md file in the worktree; it lives at the project root (\`.fusion/tasks/${task.id}/PROMPT.md\`), outside this worktree, so review the embedded copy.
- Do NOT judge current implementation diffs, uncommitted worktree changes, or unrelated repository changes.
- If the plan is internally consistent, complete, scoped, and verifiable, approve even when the worktree contains unrelated changes from another task.
--- BEGIN PROMPT.md ---
${planReviewSpecText}
--- END PROMPT.md ---`
: `Diff Scope (files changed by THIS task vs base):
${scopeFileBlock}${diffShortstat ? `\nDiff stat: ${diffShortstat}` : ""}
CRITICAL SCOPING RULES — read before doing anything else:
- Review ONLY the files listed above. Do NOT analyze unmodified files or unrelated parts of the codebase.
- If NONE of the files in the diff scope are relevant to your review category (e.g. a UX/design reviewer with no UI/CSS/component files in scope, a security reviewer with no auth/network code in scope, an a11y reviewer with no markup changes), respond IMMEDIATELY with a single short approval line such as "No relevant changes in scope — approved." and STOP. Do not start exploring the codebase.
- Your wall-clock budget is short. Spending it browsing unmodified files will cause this step to time out and block merge.${approvedContractBlock}`;
const latestTaskForUserComments = await deps.store.getTask(task.id).catch(() => task);
const workflowStepUserComments = selectUserCommentsForAgentContext(latestTaskForUserComments, { limit: null });
const workflowStepUserCommentSection = buildUserCommentsPromptSection(workflowStepUserComments);
/*
* FNXC:AgentSteering 2026-06-30-14:08:
* Prompt/custom workflow-step reviewers, including Browser Verification agents, do not call reviewStep. They still gate quality, so their system prompt must carry the same canonical uncapped user comments plus legacy steering selected from a fresh task snapshot.
*/
// (KTD-6) Verdict-contract reconciliation. The trailing-verdict JSON is the
// gate-parsing contract — it only matters for steps that gate merge. A skill
// step that isn't a gate (e.g. ce-plan / ce-work / ce-compound) produces
// skill-native output (and may emit a ===FUSION_AWAIT_INPUT=== sentinel and
// stop), so forcing a verdict would contradict the U2 preamble. Require the
// verdict only for gate steps (and skill-less prompt steps, which keep the
// legacy reviewer contract); relax it for non-gate skill steps. The executor
// runs parseAwaitInputSentinel on output regardless, so the await-input
// sentinel always takes priority when present.
const isSkillStep = typeof workflowStep.skillName === "string" && workflowStep.skillName.trim().length > 0;
const isSummaryProjectionStep = (workflowStep as WorkflowStep & { summaryTarget?: string }).summaryTarget === "task";
const requireVerdict = !isSummaryProjectionStep && (workflowStep.gateMode === "gate" || !isSkillStep);
const reviewFindingsContract = workflowStepMetadata.reviewKind === "plan" || workflowStepMetadata.reviewKind === "code";
const verdictBlock = requireVerdict
? `
## Feedback Format
When your review is complete, your final line MUST be a single JSON object (no markdown fences):
${reviewFindingsContract
? "{\"verdict\":\"APPROVE|APPROVE_WITH_NOTES|REVISE\",\"notes\":\"...\",\"findings\":[{\"id\":\"stable-id\",\"title\":\"concise issue\",\"body\":\"actionable detail\",\"filePath\":\"optional/path\",\"line\":1,\"severity\":\"low|medium|high|critical\"}]}"
: "{\"verdict\":\"APPROVE|APPROVE_WITH_NOTES|REVISE\",\"notes\":\"...\"}"}
Rules:
- Output exactly one trailing JSON object and stop.
- verdict must be exactly APPROVE, APPROVE_WITH_NOTES, or REVISE.
- notes should be concise and actionable. Use an empty string when there are no notes.
- For out-of-scope fast-bail responses, use: {"verdict":"APPROVE","notes":"out of scope: no UI files changed"}
Backward compat fallback: if JSON is unavailable, you may still begin output with REQUEST REVISION to request changes.`
: `
## Output Format
Follow the skill's own output conventions. You are NOT required to end with a
verdict JSON object — this step does not gate merge. If you need to ask the user
a question, emit a single ===FUSION_AWAIT_INPUT=== block and stop (see the
workflow-step conventions in your instructions).`;
const inlineFixBlock = allowReviewerInlineFixes
? `
## Same-Session Fix Policy
This review-type node may fix issues it finds before returning a final verdict.
- If you find an in-scope issue you can fix safely, edit the relevant files in this same session, run the smallest relevant verification, and then return APPROVE or APPROVE_WITH_NOTES.
- Return REVISE only when the issue is still present, cannot be safely fixed in this reviewer session, needs broader executor remediation, or needs user input.
- Plan Review may use fn_task_prompt_write to replace the task's PROMPT.md with the complete revised plan. Do not implement product code from Plan Review.
- Code Review and Browser Verification may fix implementation issues inside the assigned task worktree and should mention the fix in notes.`
: "";
const systemPrompt = `You are a workflow step agent executing: ${workflowStep.name}
Task Context:
- Task ID: ${task.id}
- Task Description: ${task.description}
- Worktree: ${worktreePath}
${scopeBlock}${workflowStepUserCommentSection ? `\n\n${workflowStepUserCommentSection}` : ""}
Your role:
- Execute this workflow step exactly as scoped.
- Prioritize high-impact correctness/risk findings over stylistic nits.
- Keep feedback actionable and directly tied to evidence in files/outputs.
Your Instructions:
${workflowStep.prompt}
You have access to the file system to review changes.${inlineFixBlock}${verdictBlock}`;
const agentLogger = new AgentLogger({
store: deps.store,
taskId: task.id,
agent: "reviewer",
persistAgentToolOutput: settings.persistAgentToolOutput,
// Review-in-executor sessions are task-scoped ephemeral workers.
persistAgentThinkingLog: resolvePersistAgentThinkingLog(settings, { ephemeral: true }),
onAgentText: (taskId, delta) => {
deps.options.onAgentText?.(taskId, delta);
},
onAgentTool: (taskId, toolName, detail) => {
deps.options.onAgentTool?.(taskId, toolName, detail);
},
});
// Determine primary model and an explicit fallback. Review-type workflow
// steps use the validator lane; ordinary workflow prompts use the executor
// lane. A complete per-step override remains authoritative for either lane.
// FNXC:ModelResolution 2026-06-25-12:00: FN-7039 requires ordinary workflow
// steps to inherit project execution-lane model settings before defaults.
// Review gates are independent validation surfaces and must not silently use
// the same implementation model merely because they execute in this method.
const assignedRuntimeConfig = await deps.getAssignedAgentRuntimeConfig(task.assignedAgentId);
const laneModel = isReviewTypeWorkflowStep
? resolveValidatorSessionModel(
task.validatorModelProvider,
task.validatorModelId,
settings,
assignedRuntimeConfig,
task.validatorCredentialInstanceId,
)
: resolveExecutorSessionModel(
task.modelProvider,
task.modelId,
settings,
assignedRuntimeConfig,
task.credentialInstanceId,
);
const useOverride = !!(workflowStep.modelProvider && workflowStep.modelId);
const primaryProvider = useOverride ? workflowStep.modelProvider : laneModel.provider;
const primaryModelId = useOverride ? workflowStep.modelId : laneModel.modelId;
// FNXC:ProviderAuth 2026-08-01-08:39: A workflow-step model override has no paired instance selection, so only the resolved primary task lane may carry its requested credential instance. Fallback attempts must retain their provider-default behavior rather than inheriting a primary-provider identity.
const primaryCredentialInstanceId = useOverride ? undefined : laneModel.credentialInstanceId;
const workflowFallback = isReviewTypeWorkflowStep
? resolveValidatorFallbackModel(settings)
: resolveExecutorFallbackModel(settings);
const fallback = workflowFallback.provider && workflowFallback.modelId
&& (workflowFallback.provider !== primaryProvider || workflowFallback.modelId !== primaryModelId)
? workflowFallback
: undefined;
const fallbackSettingsHint = isReviewTypeWorkflowStep
? "settings.validatorFallbackProvider/validatorFallbackModelId or fallbackProvider/fallbackModelId"
: "settings.executionFallbackProvider/executionFallbackModelId or fallbackProvider/fallbackModelId";
const fallbackLaneLabel = isReviewTypeWorkflowStep ? "validator" : "executor";
const timeoutMs = Math.max(60_000, settings.workflowStepTimeoutMs ?? 900_000);
const runOnce = async (
provider: string | undefined,
modelId: string | undefined,
attemptLabel: string,
): Promise<WorkflowStepOutcome> => {
const stepInstructions = await deps.resolveInstructionsForRole("executor", settings);
const stepSystemPrompt = buildSystemPromptWithInstructions(systemPrompt, stepInstructions);
// Build skill selection context for workflow step session
const skillContext = await buildSessionSkillContext({
agentStore: deps.options.agentStore!,
task,
sessionPurpose: "executor",
projectRootDir: deps.rootDir,
pluginRunner: deps.options.pluginRunner,
});
const workflowAgent = await deps.getAuthoritativeAssignedAgent(task.assignedAgentId);
const workflowRuntimeHint = extractRuntimeHint(workflowAgent?.runtimeConfig);
// Signal to skills running in this step (e.g. compound-engineering ce-plan /
// ce-work) that they are inside a Fusion autonomous workflow step, NOT an
// interactive Claude Code session. There is no synchronous blocking-question
// tool here, so a skill must surface user questions via the await-input
// convention (which the dashboard / task card renders) instead of calling
// AskUserQuestion into the void. Scoped to the step session — the main
// executor session deliberately does not carry it.
// (U3) FUSION_HEADLESS=1 marks a genuinely-unattended run (LFG/pipeline) so
// skills record assumptions and proceed instead of parking. Set ONLY when
// the explicit `unattended` flag is true; absent on a board run.
const stepEnv: NodeJS.ProcessEnv = {
...(taskEnv ?? process.env),
FUSION_WORKFLOW_STEP: "1",
};
// FNXC:WorkflowSteps 2026-06-21-06:30:
// Default-safe invariant (KTD-3): a board run must NEVER be headless. Since
// stepEnv spreads taskEnv/process.env, an inherited FUSION_HEADLESS (e.g. an
// outer pipeline exported it) would otherwise leak in and silently skip user
// questions. Set it ONLY on an explicit opt-in; strip any inherited value
// otherwise so absence of the flag always yields a board run.
if (unattended) {
stepEnv.FUSION_HEADLESS = "1";
} else {
delete stepEnv.FUSION_HEADLESS;
}
// (U1) Load the step's named skill into THIS session. The interactive fix
// proved the resolver works when fed BOTH a requested name AND a discovery
// path (compound-engineering-skill-resolution.test.ts). Here we mirror it:
// merge the step's skillName (both namespaced `compound-engineering:ce-work`
// and bare `ce-work` — the resolver matches bare names case-insensitively)
// into the resolved requestedSkillNames, and pass the CE install root (from
// the injected FUSION_CE_SKILLS_DIR env) as additionalSkillPaths so the
// loader can actually discover the bundled SKILL.md. Without both halves the
// named skill was only prompt text pointing at a skill the session never had.
let effectiveSkillSelection = skillContext.skillSelectionContext;
const ceSkillsDir = typeof stepEnv.FUSION_CE_SKILLS_DIR === "string" && stepEnv.FUSION_CE_SKILLS_DIR.trim()
? stepEnv.FUSION_CE_SKILLS_DIR.trim()
: undefined;
if (workflowStep.skillName && workflowStep.skillName.trim()) {
const namespaced = workflowStep.skillName.trim();
const bare = namespaced.includes(":") ? namespaced.slice(namespaced.lastIndexOf(":") + 1) : namespaced;
const existing = effectiveSkillSelection?.requestedSkillNames ?? [];
const mergedNames = [...new Set([...existing, namespaced, bare])];
effectiveSkillSelection = {
projectRootDir: effectiveSkillSelection?.projectRootDir ?? deps.rootDir,
...(effectiveSkillSelection?.sessionPurpose ? { sessionPurpose: effectiveSkillSelection.sessionPurpose } : { sessionPurpose: "executor" }),
requestedSkillNames: mergedNames,
};
}
const additionalSkillPaths = mergeAdditionalSkillPaths(skillContext.additionalSkillPaths, ceSkillsDir ? [ceSkillsDir] : undefined);
// FNXC:WorkflowSteps 2026-07-30-21:40:
// FN-8461 / GitHub #2388: workflow steps resolve skills from enabled-plugin
// body directories and the optional CE install root. Warn only after merging
// those sources when THIS named skill remains undiscoverable: a non-empty path
// array for another skill is not viable, while an actual plugin body makes CE
// env absence expected rather than misleading operator-facing noise.
if (
workflowStep.skillName?.trim()
&& !isWorkflowStepSkillDiscoverable(workflowStep.skillName.trim(), additionalSkillPaths, ceSkillsDir)
) {
await deps.store.logEntry(
task.id,
`[skill-load] Workflow step '${workflowStep.name}' requests skill '${workflowStep.skillName}' but it cannot be discovered from configured plugin body directories or FUSION_CE_SKILLS_DIR; the step runs with role-fallback skills only.`,
);
}
const logBrowserVerificationActivity = async (message: string) => {
await deps.store.logEntry(task.id, message);
await deps.store.appendAgentLog(task.id, message, "status", undefined, "reviewer");
};
if (workflowStep.requiresBrowser === true) {
effectiveSkillSelection = augmentSessionSkillsForBrowserStep(effectiveSkillSelection, deps.rootDir);
await logBrowserVerificationActivity(`[browser-verification] starting browser verification for task ${task.id} using step '${workflowStep.name}'`);
const browserProbe = await probeAgentBrowserAvailability(execAsync as AgentBrowserExec, {
cwd: worktreePath,
env: stepEnv,
timeoutMs: 5_000,
});
await logBrowserVerificationActivity(formatAgentBrowserAvailabilityLog(browserProbe));
}
// (U8b) Coding-mode skill steps fan out to ce-<persona> subagents via
// fn_spawn_agent (read the persona def, pass its body as systemPromptOverride).
// That tool is registered only in the main executor session — never here —
// so coding mode granted write/edit but NOT spawn. Register it for
// coding-mode steps now; readonly steps keep no spawn (filterCustomToolsForReadonly
// strips it). The spawn tool inherits the injected env so children also see
// FUSION_CE_AGENTS_DIR.
//
// (U9 / KTD-4, Risk-1) ACCEPTED WRITE-CAPABILITY POSTURE: coding mode also
// exposes write/edit. The CE plan/code-review steps run coding ONLY to gain
// spawn (they are not supposed to mutate the tree), but the tool policy is
// binary today — coding is the only mode that carries fn_spawn_agent. There
// is NO engine guard preventing those steps from writing; the only protection
// is skill discipline plus the U6 no-diff detection assertion. The proper fix
// (a dedicated readonly-plus-spawn tool mode) is deferred; this is a
// knowingly-accepted gap, not a closed one — re-evaluate before enabling the
// CE workflow for genuinely-unattended (FUSION_HEADLESS) LFG/pipeline runs.
const planReviewPromptTools: ToolDefinition[] = allowPlanReviewPromptWrite
? [createTaskPromptWriteTool(deps.sharedWorkerTools, task.id)]
: [];
const codingCustomTools: ToolDefinition[] = toolMode === "coding"
? [deps.createSpawnAgentTool(task.id, worktreePath, settings, stepEnv)]
: [];
const workflowCustomTools = [...planReviewPromptTools, ...codingCustomTools];
const readonlyCustomTools = toolMode === "readonly"
? filterCustomToolsForReadonly(workflowCustomTools, {
allowTool: (tool) => allowPlanReviewPromptWrite && tool.name === "fn_task_prompt_write",
})
: { allowed: workflowCustomTools, denied: [] as string[] };
if (toolMode === "readonly" && readonlyCustomTools.denied.length > 0) {
await deps.store.logEntry(
task.id,
`[readonly-violation] Workflow step '${workflowStep.name}' dropped denied custom tools: ${readonlyCustomTools.denied.join(", ")}`,
);
}
/*
* FNXC:Settings-ThinkingLevel 2026-07-10-00:00:
* WorkflowStep sessions resolve reasoning effort as node/step `thinkingLevel` first, then the task override for their selected model lane, then settings defaults/lane fallbacks.
*
* FNXC:Settings-ThinkingLevel 2026-07-10-14:20:
* The step's own `fallback` attempt already swaps to a distinct model (validator fallback OR global fallback pair) — it must honor THAT model's fallback thinking level, not silently reuse the primary lane's thinking level. Route by which candidate `fallback.label` actually matched instead of only special-casing `validatorFallback`.
*/
const workflowStepThinkingSource = workflowStep.thinkingLevel
?? (isReviewTypeWorkflowStep ? task.validatorThinkingLevel ?? task.thinkingLevel : task.thinkingLevel);
const workflowStepThinkingLevel = attemptLabel === "fallback"
? isReviewTypeWorkflowStep
? resolveValidatorFallbackThinkingLevel(workflowStepThinkingSource, settings)
: resolveExecutorFallbackThinkingLevel(workflowStepThinkingSource, settings)
: isReviewTypeWorkflowStep
? resolveValidatorThinkingLevel(workflowStepThinkingSource, settings)
: resolveExecutorThinkingLevel(workflowStepThinkingSource, settings);
const workflowStepFallbackThinkingLevel = isReviewTypeWorkflowStep
? resolveValidatorFallbackThinkingLevel(workflowStepThinkingSource, settings)
: resolveExecutorFallbackThinkingLevel(workflowStepThinkingSource, settings);
const { session } = await createResolvedAgentSession({
sessionPurpose: "executor",
runtimeHint: workflowRuntimeHint,
pluginRunner: deps.options.pluginRunner,
cwd: worktreePath,
systemPrompt: stepSystemPrompt,
tools: toolMode,
defaultProvider: provider,
defaultModelId: modelId,
...(attemptLabel !== "fallback" && primaryCredentialInstanceId
? { credentialInstanceId: primaryCredentialInstanceId }
: {}),
fallbackProvider: workflowFallback.provider,
fallbackModelId: workflowFallback.modelId,
fallbackThinkingLevel: workflowStepFallbackThinkingLevel,
defaultThinkingLevel: workflowStepThinkingLevel,
runAuditor: createRunAuditor(deps.store, deps.getRunContextFor(task.id)),
settings,
taskEnv: stepEnv,
mcpServers: await deps.resolveMcpServers(undefined),
// FNXC:SessionRouting 2026-06-24-11:20:
// #1675: propagate task id so workflow-step requests carry the same
// X-Session-Id/X-Session-Affinity as the primary session.
taskId: task.id,
// FNXC:PluginSkills 2026-07-12-00:00: Workflow-step sessions union plugin skill body dirs with CE's FUSION_CE_SKILLS_DIR so neither plugin-package nor compound-engineering skills are overwritten.
// Skill selection: assigned-agent / role-fallback skills, plus the step's own named skill (U1) made discoverable via additionalSkillPaths.
...(effectiveSkillSelection ? { skillSelection: effectiveSkillSelection } : {}),
...(additionalSkillPaths ? { additionalSkillPaths } : {}),
...(readonlyCustomTools.allowed.length > 0 ? { customTools: readonlyCustomTools.allowed } : {}),
});
const workflowModelDetails = formatModelMarkerDetails(
describeModel(session),
workflowStepThinkingLevel,
[
useOverride && attemptLabel === "primary" ? "workflow step override" : "",
attemptLabel === "fallback" ? "fallback after timeout" : "",
],
);
executorLog.debug(`${task.id}: workflow step '${workflowStep.name}' using model ${workflowModelDetails}`);
await deps.store.logEntry(
task.id,
`Workflow step '${workflowStep.name}' using model: ${workflowModelDetails}`,
);
deps.setActiveWorkflowStepSession(task.id, session, worktreePath, createSeenSteeringIds(task));
// FNXC:TaskTiming 2026-07-30-21:40: graph-owned Plan Review is the only
// post-spec planning lane. Start before prompting and finalize in finally before any replan handoff.
const ownsPlanningSegment = workflowStep.id === "graph:plan-review-step" || workflowStep.name === "Plan Review";
if (ownsPlanningSegment) {
deps.activePlanningWorkflowSessions.add(task.id);
const planningStart = startPlanningSegment(task);
try {
if (planningStart.planningStartedAt) await deps.store.updateTask(task.id, planningStart);
} catch (error) {
deps.activePlanningWorkflowSessions.delete(task.id);
throw error;
}
}
let output = "";
const deltaNormalizer = createStreamingDeltaNormalizer();
let detectedQuestion: string | null = null;
let resolveQuestion: ((value: "await-input") => void) | undefined;
const questionPromise = new Promise<"await-input">((resolve) => {
resolveQuestion = resolve;
});
session.subscribe((event) => {
if (event.type === "message_update") {
const msgEvent = event.assistantMessageEvent;
if (msgEvent.type === "text_delta") {
// Repair dropped sentence-boundary spaces at the shared engine delta chokepoint,
// including tool-call cross-message boundaries (see streaming-delta.ts).
const delta = deltaNormalizer.normalize(msgEvent.partial, msgEvent.contentIndex, msgEvent.delta, "text");
output += delta;
agentLogger.onText(delta);
} else if (msgEvent.type === "thinking_delta") {
// Repair dropped sentence-boundary spaces at the shared engine delta chokepoint,
// including tool-call cross-message boundaries (see streaming-delta.ts).
const delta = deltaNormalizer.normalize(msgEvent.partial, msgEvent.contentIndex, msgEvent.delta, "thinking");
agentLogger.onThinking(delta);
}
}
if (event.type === "tool_execution_start") {
agentLogger.onToolStart(event.toolName, event.args as Record<string, unknown> | undefined);
if (!unattended && detectedQuestion === null) {
const question = parseAwaitInputQuestionToolCall(
event.toolName,
event.args as Record<string, unknown> | undefined,
);
if (question) {
detectedQuestion = question;
resolveQuestion?.("await-input");
}
}
}
if (event.type === "tool_execution_end") {
agentLogger.onToolEnd(event.toolName, event.isError, event.result);
}
});
let timedOut = false;
let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
const timeoutPromise = new Promise<"timeout">((resolveTimeout) => {
timeoutHandle = setTimeout(() => {
timedOut = true;
resolveTimeout("timeout");
}, timeoutMs);
});
try {
const promptPromise = promptWithFallback(
session,
`Execute the workflow step "${workflowStep.name}" for task ${task.id}.\n\n` +
`Review the work done in this worktree and evaluate it against the criteria in your instructions.`,
);
const outcome = await Promise.race([
promptPromise.then(() => "completed" as const),
timeoutPromise,
questionPromise,
]);
if (outcome === "await-input" && detectedQuestion) {
try { session.dispose(); } catch { /* best-effort */ }
await agentLogger.flush();
return {
success: true,
output: `===FUSION_AWAIT_INPUT===\n${detectedQuestion}\n===END_FUSION_AWAIT_INPUT===`,
};
}
if (outcome === "timeout") {
executorLog.warn(`${task.id}: workflow step '${workflowStep.name}' (${attemptLabel}) timed out after ${timeoutMs}ms — disposing session`);
await deps.store.logEntry(
task.id,
`Workflow step '${workflowStep.name}' ${attemptLabel === "primary" ? "primary" : "fallback"} model timed out after ${Math.round(timeoutMs / 1000)}s — aborting session`,
);
if (workflowStep.requiresBrowser === true) {
await logBrowserVerificationActivity(`[browser-verification] finished browser verification for task ${task.id}: timed out`);
}
// FNXC:TaskCost 2026-07-30-21:40: Plan Review tokens are task cost;
// snapshot before timeout disposal just like normal completion.
await accumulateSessionTokenUsage(deps.store, task.id, session, { agentId: task.assignedAgentId ?? undefined, role: "executor" });
try { session.dispose(); } catch { /* best-effort */ }
await agentLogger.flush();
return { success: false, error: `workflow step timed out after ${timeoutMs}ms`, timedOut: true };
}
// Completed within the timeout — let any post-completion errors surface.
checkSessionError(session);
await accumulateSessionTokenUsage(deps.store, task.id, session, {
agentId: task.assignedAgentId ?? undefined,
role: "executor",
});
session.dispose();
await agentLogger.flush();
/*
FNXC:PlanReviewNoOp 2026-08-09-22:10:
Thread optionalGroupId so Plan Review CLOSE_NO_OP is accepted only for that group.
*/
const parsed = requireVerdict
? parseWorkflowStepOutput(output, { optionalGroupId })
: parseWorkflowStepOutput(output, { requireVerdict: false, optionalGroupId });
if (parsed.verdict) {
const revisionRequested = parsed.verdict === "REVISE";
if (workflowStep.requiresBrowser === true) {
await logBrowserVerificationActivity(`[browser-verification] finished browser verification for task ${task.id}: verdict ${parsed.verdict}`);
}
return {
success: !revisionRequested,
revisionRequested,
output: parsed.output,
verdict: parsed.verdict,
notes: parsed.notes,
...(parsed.findings ? { findings: parsed.findings } : {}),
};
}
if (parsed.malformed) {
// FNXC:ReviewLeniency 2026-07-02-00:30: malformed output (after the
// fallback-model retry) is recorded as a NON-BLOCKING advisory, not a
// hard gate block — see runGraphCustomNode's outcome mapping.
await deps.store.logEntry(
task.id,
`[pre-merge] Workflow step '${workflowStep.name}' produced malformed output (no parseable verdict) — recorded as non-blocking advisory`,
);
if (workflowStep.requiresBrowser === true) {
await logBrowserVerificationActivity(`[browser-verification] finished browser verification for task ${task.id}: malformed output`);
}
return {
success: false,
output: parsed.output,
error: "malformed output — no verdict extracted",
notes: undefined,
malformed: true,
};
}
if (workflowStep.requiresBrowser === true) {
await logBrowserVerificationActivity(`[browser-verification] finished browser verification for task ${task.id}: completed`);
}
return { success: true, output: parsed.output };
} catch (err: unknown) {
await agentLogger.flush();
// Persist the delta before error disposal so graph-owned planning reviews
// cannot disappear from operator cost totals.
await accumulateSessionTokenUsage(deps.store, task.id, session, { agentId: task.assignedAgentId ?? undefined, role: "executor" });
try { session.dispose(); } catch { /* best-effort */ }
if ((err instanceof ReadonlyViolationError) || ((err as { code?: string } | null)?.code === "READONLY_VIOLATION")) {
const violation = err as ReadonlyViolationError;
const deniedTool = violation.toolName || "unknown";
await deps.store.logEntry(
task.id,
`[readonly-violation] Workflow step '${workflowStep.name}' attempted denied tool '${deniedTool}'`,
);
if (workflowStep.requiresBrowser === true) {
await logBrowserVerificationActivity(`[browser-verification] finished browser verification for task ${task.id}: readonly violation`);
}
return { success: false, error: `[readonly-violation] ${violation.message}` };
}
const errorMessage = err instanceof Error ? err.message : String(err);
if (workflowStep.requiresBrowser === true) {
await logBrowserVerificationActivity(`[browser-verification] finished browser verification for task ${task.id}: failed — ${errorMessage}`);
}
return { success: false, error: errorMessage };
} finally {
if (timeoutHandle) clearTimeout(timeoutHandle);
if (ownsPlanningSegment) {
try {
const livePlanningTask = await deps.store.getTask(task.id);
if (livePlanningTask) {
const planningEnd = finalizePlanningSegment(livePlanningTask);
if (planningEnd.planningStartedAt === null) await deps.store.updateTask(task.id, planningEnd);
}
} finally {
// Finalize before releasing Plan Review ownership so triage can only
// begin a subsequent, non-overlapping planning segment.
deps.activePlanningWorkflowSessions.delete(task.id);
}
}
const activeWorkflowStepSession = deps.activeWorkflowStepSessions.get(task.id);
if (activeWorkflowStepSession === session) {
deps.deleteActiveWorkflowStepSession(task.id, worktreePath);
}
// Suppress unused-variable warning; `timedOut` documents intent.
void timedOut;
}
};
const primaryOutcome = await runOnce(primaryProvider, primaryModelId, "primary");
/*
FNXC:ReviewLeniency 2026-07-02-00:30:
Retry the fallback model on a MALFORMED (unparseable-verdict) primary response, not only on a timeout. A single fumbled response — reasoning with no trailing verdict — should get one more attempt on the fallback model before the gate result is recorded, mirroring the reviewer path's UNAVAILABLE retry. If no fallback is configured the malformed primary is returned as-is (and is treated as a non-blocking advisory downstream, see runGraphCustomNode).
*/
const primaryMalformed = (primaryOutcome as { malformed?: boolean }).malformed === true;
if (!primaryOutcome.timedOut && !primaryMalformed) return primaryOutcome;
if (!fallback) {
/*
* FNXC:ReviewLeniency 2026-07-05-17:24:
* FN-7561: when NO fallback model is configured, a MALFORMED primary (unparseable verdict — a single fumbled response) still deserves one retry so a transient formatting fumble does not feed the plan-review replan loop. Self-retry once on the SAME primary model. Timeouts are NOT self-retried — they would likely just time out again and burn another full budget. If the self-retry is still malformed it is returned as a non-blocking advisory downstream.
*/
if (primaryMalformed && !primaryOutcome.timedOut) {
executorLog.log(`${task.id}: workflow step '${workflowStep.name}' produced malformed output and no fallback is configured — retrying once on the primary model`);
const retryOutcome = await runOnce(primaryProvider, primaryModelId, "primary-retry");
const retryMalformed = (retryOutcome as { malformed?: boolean }).malformed === true;
if (!retryMalformed) return retryOutcome;
await deps.store.logEntry(
task.id,
`Workflow step '${workflowStep.name}' produced malformed output on both the primary attempt and one self-retry — no fallback model configured (set ${fallbackSettingsHint})`,
);
return retryOutcome;
}
const reason = primaryOutcome.timedOut ? "timed out" : "produced malformed output";
executorLog.warn(`${task.id}: workflow step '${workflowStep.name}' ${reason} and no fallback model is configured`);
await deps.store.logEntry(
task.id,
`Workflow step '${workflowStep.name}' ${reason} — no fallback model configured (set ${fallbackSettingsHint})`,
);
return primaryOutcome;
}
executorLog.log(`${task.id}: retrying workflow step '${workflowStep.name}' with ${fallbackLaneLabel} fallback ${fallback.provider}/${fallback.modelId} after primary ${primaryOutcome.timedOut ? "timeout" : "malformed output"}`);
return runOnce(fallback.provider, fallback.modelId, "fallback");
}

293
packages/engine/src/executor/execution-prompt.ts Normal file
View File

@@ -0,0 +1,293 @@
/**
* FNXC:CodeOrganization 2026-08-03-12:45:
* Execution prompt builders peeled from executor.ts (U4 Slice A pure helpers).
* Public API stays re-exported from executor.ts for deep import/mock stability.
*/
import type {
AgentMemoryInclusionMode,
Settings,
TaskDetail,
WorkflowFieldDefinition,
} from "@fusion/core";
import { buildExecutionMemoryInstructions, type WorkspaceConfig } from "@fusion/core";
import { executorLog } from "../logger.js";
import type { PluginRunner } from "../plugins/plugin-runner.js";
import { parseReviewLevelFromPrompt } from "./prompt-derived-eligibility.js";
/**
* Format a timestamp for display in steering comments.
* Returns relative time for recent comments, absolute date for older ones.
*/
export function formatTimestamp(iso: string): string {
const date = new Date(iso);
const now = new Date();
const diffMs = now.getTime() - date.getTime();
const diffMin = Math.floor(diffMs / 60000);
const diffHr = Math.floor(diffMin / 60);
const diffDay = Math.floor(diffHr / 24);
if (diffMin < 1) return "just now";
if (diffMin < 60) return `${diffMin}m ago`;
if (diffHr < 24) return `${diffHr}h ago`;
if (diffDay < 7) return `${diffDay}d ago`;
return date.toLocaleDateString();
}
// Project commands are injected here (for reliability) and also in the PROMPT.md (by triage).
// This ensures the executor agent always sees the authoritative commands from settings,
// even if the PROMPT.md was written manually or before commands were configured.
export function scopePromptToWorktree(
prompt: string | undefined,
rootDir?: string,
worktreePath?: string,
workspaceConfig?: WorkspaceConfig | null,
): string {
/*
* FNXC:ExecutorPrompts 2026-06-29-13:55:
* Some legacy direct-dispatch tests and recovered task rows can lack a persisted prompt. Treat a missing prompt as empty before worktree path scoping so prompt construction cannot fail before pause-abort and graph-path recovery code handles the task state.
*/
const promptText = prompt ?? "";
// FNXC:Workspace 2026-06-21-12:00: KTD1 — in workspace mode the session is rooted at the workspace root itself (worktreePath === rootDir) and path rewriting to a per-task root worktree is meaningless: edits happen in per-sub-repo worktrees the agent acquires, not at the root. No-op the rewrite. (The rootDir === worktreePath guard below already covers this, but gate explicitly so intent survives future refactors.)
if (workspaceConfig) {
return promptText;
}
if (!rootDir || !worktreePath || rootDir === worktreePath || !promptText.includes(rootDir)) {
return promptText;
}
return promptText
.replaceAll(`${rootDir}/`, `${worktreePath}/`)
.replaceAll(`${worktreePath}/.fusion/`, `${rootDir}/.fusion/`);
}
export function buildSourceIssueRef(sourceIssue: TaskDetail["sourceIssue"]): string {
if (!sourceIssue || sourceIssue.provider !== "github" || !sourceIssue.repository) {
return "";
}
const issueNumber = sourceIssue.issueNumber
?? Number.parseInt(sourceIssue.externalIssueId ?? "", 10);
if (!Number.isInteger(issueNumber) || issueNumber < 1) {
return "";
}
return `${sourceIssue.repository}#${issueNumber}`;
}
export function buildExecutionPrompt(
task: TaskDetail,
rootDir?: string,
settings?: Settings,
worktreePath?: string,
_pluginRunner?: PluginRunner,
customFieldDefs?: WorkflowFieldDefinition[],
workspaceConfig?: WorkspaceConfig | null,
options?: { pluginTaskContributions?: string },
): string {
const prompt = scopePromptToWorktree(task.prompt, rootDir, worktreePath, workspaceConfig);
const reviewLevel = parseReviewLevelFromPrompt(prompt);
/*
* FNXC:WorkflowReviewGates 2026-06-29-20:41:
* Default Coding and other workflow-graph tasks run review gates as graph nodes, so the executor prompt must not ask implementation agents to call legacy per-step review tools. This keeps Plan Review once-before-execution and Code Review once-before-merge unless a workflow explicitly adds a step-review node.
*/
// Build co-author trailer arg for git commits based on settings. The user's
// configured git identity remains the primary author; Fusion is appended as
// a `Co-authored-by` trailer for shared credit (recognized by GitHub).
// FNXC:CommitAttribution 2026-06-26-12:48: this prompt hint is best-effort for humans/agents reading commit examples; the worktree commit-msg hook is the authoritative deterministic source for the co-author trailer.
const authorArg = settings?.commitAuthorEnabled !== false
? ` -m "Co-authored-by: ${settings?.commitAuthorName || "Fusion"} <${settings?.commitAuthorEmail || "noreply@runfusion.ai"}>"`
: "";
const sourceIssueRef = buildSourceIssueRef(task.sourceIssue);
// Build step progress for resume
const hasProgress = task.steps.length > 0 && task.steps.some((s) => s.status !== "pending");
let progressSection = "";
if (hasProgress) {
const doneSteps = task.steps
.map((s, i) => ({ ...s, index: i }))
.filter((s) => s.status === "done");
const currentStep = task.currentStep;
const currentStepInfo = task.steps[currentStep];
progressSection = `
## ⚠️ RESUMING — Previous progress exists
This task was already partially executed. DO NOT redo completed steps.
### Step status:
${task.steps.map((s, i) => `- Step ${i} (${s.name}): **${s.status}**`).join("\n")}
### Resume from: Step ${currentStep}${currentStepInfo ? ` (${currentStepInfo.name})` : ""}
${doneSteps.length > 0 ? `Steps ${doneSteps.map((s) => s.index).join(", ")} are already complete — skip them entirely.` : ""}
Check the git log to understand what was already implemented:
\`\`\`bash
git log --oneline
\`\`\`
`;
}
// Build attachments section
let attachmentsSection = "";
if (task.attachments && task.attachments.length > 0 && rootDir) {
const IMAGE_MIMES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
const lines = ["## Attachments", ""];
for (const att of task.attachments) {
const absPath = `${rootDir}/.fusion/tasks/${task.id}/attachments/${att.filename}`;
if (IMAGE_MIMES.has(att.mimeType)) {
lines.push(`- **${att.originalName}** (screenshot): \`${absPath}\``);
} else {
lines.push(`- **${att.originalName}** (${att.mimeType}): \`${absPath}\` — read for context`);
}
}
attachmentsSection = "\n" + lines.join("\n") + "\n";
}
// Build project commands section from settings
let commandsSection = "";
if (settings?.testCommand || settings?.buildCommand) {
const lines = ["## Project Commands"];
if (settings.testCommand) lines.push(`- **Test:** \`${settings.testCommand}\``);
if (settings.buildCommand) lines.push(`- **Build:** \`${settings.buildCommand}\``);
commandsSection = "\n" + lines.join("\n") + "\n";
}
// Build project memory section from settings
// When enabled, agents consult and update project memory for durable project learnings.
// Backend-aware: instructions branch based on memoryBackendType (file, readonly, qmd)
const memoryEnabled = settings?.memoryEnabled !== false;
const memoryMode: AgentMemoryInclusionMode = settings?.agentMemoryInclusionMode ?? "full";
let memorySection = "";
if (memoryEnabled && rootDir && memoryMode !== "off") {
memorySection = memoryMode === "index"
? "\n## Project Memory (Index Only)\n\nUse fn_memory_search first to find relevant memory, then fn_memory_get for specific excerpts.\n"
: "\n" + buildExecutionMemoryInstructions(rootDir, settings);
}
// Build steering comments section (last 10 comments only to avoid context bloat)
let steeringSection = "";
if (task.steeringComments && task.steeringComments.length > 0) {
const recentComments = [...task.steeringComments].slice(-10);
const lines = [
"",
"## Steering Comments",
"",
"The following comments were added by the user during execution. Consider adjusting your approach or replanning remaining steps based on this feedback.",
"",
];
for (const comment of recentComments) {
const timestamp = formatTimestamp(comment.createdAt);
lines.push(`**${comment.author}** — ${timestamp}`);
lines.push(`> ${comment.text}`);
lines.push("");
}
steeringSection = lines.join("\n");
}
// Build custom fields section (KTD-13): when the task's workflow declares
// custom fields, the executor agent can write them via fn_task_update
// (custom_fields) — but without the schema it is writing blind. List each
// field's id/name/type, enum options, required flag, and current value so
// the write is informed and self-correcting. Compact: one line per field.
let customFieldsSection = "";
if (customFieldDefs && customFieldDefs.length > 0) {
const current = task.customFields ?? {};
const lines = [
"",
"## Custom fields",
"",
"This task's workflow declares custom fields. Set them with `fn_task_update(custom_fields={...})` keyed by field id (pass null to clear).",
"",
];
for (const f of customFieldDefs) {
const parts = [`- \`${f.id}\` (${f.name}) — type: ${f.type}`];
if ((f.type === "enum" || f.type === "multi-enum") && f.options && f.options.length > 0) {
const opts = f.options.map((o) => (o.label && o.label !== o.value ? `${o.value} (${o.label})` : o.value)).join(", ");
parts.push(`options: [${opts}]`);
}
if (f.required) parts.push("required");
const hasValue = Object.prototype.hasOwnProperty.call(current, f.id) && current[f.id] !== null && current[f.id] !== undefined;
parts.push(`current: ${hasValue ? JSON.stringify(current[f.id]) : "unset"}`);
lines.push(parts.join("; "));
}
customFieldsSection = lines.join("\n") + "\n";
}
const pluginTaskContributions = options?.pluginTaskContributions ?? "";
if (pluginTaskContributions) {
executorLog.debug(`${task.id}: applied plugin prompt contributions for executor-task surface`);
}
const executionPrompt = `Execute this task.
## Task: ${task.id}
${task.title ? `**${task.title}**` : ""}
${task.dependencies.length > 0 ? `Dependencies: ${task.dependencies.join(", ")}` : ""}
## PROMPT.md
${prompt}
${attachmentsSection}${commandsSection}${memorySection}${progressSection}${steeringSection}${customFieldsSection}
## Review level: ${reviewLevel}
Workflow review gates are handled by the workflow graph outside this implementation session. Do not request per-step plan review or per-step code review from inside execution; complete the implementation steps and let the graph run enabled Plan Review, Browser Verification, and Code Review nodes at their configured positions.
${pluginTaskContributions ? `
${pluginTaskContributions}
` : ""}
## Worktree Boundaries
You are running in an **isolated git worktree**. This means:
- **All code changes must be made inside the current worktree directory.** Do not modify files outside the worktree.
- **Exception — Project memory:** You MAY read and write to files under \`.fusion/memory/\` at the project root to save durable project learnings.
- **Exception — Task attachments:** You MAY read files under \`.fusion/tasks/{taskId}/attachments/\` at the project root for context.
- **Exception — Sibling task specs:** You MAY read \`.fusion/tasks/{taskId}/PROMPT.md\` and \`.fusion/tasks/{taskId}/task.json\` at the project root (read-only) to consult dependency tasks' specifications. If those files do not exist, the dependency has been archived — call \`fn_task_show\` with its ID to load the spec from the archive.
- **Shell commands** run inside the worktree by default. Avoid using \`cd\` to navigate outside the worktree.
## Begin
${hasProgress
? `Resume from Step ${task.currentStep}. Do NOT redo completed steps.`
: "Start with Step 0 (Preflight). Work through each step in order."}
Use \`fn_task_update\` to report progress on every step transition; its \`step\` value is 0-based and equals the \`### Step N:\` number in PROMPT.md.
Use \`fn_task_log\` for important actions and decisions.
Use \`fn_task_create\` for truly separate follow-up work, including unrelated/pre-existing broad-suite failures.
Commit at step boundaries: \`git commit -m "feat(${task.id}): complete Step N — <short summary>"${sourceIssueRef ? ` -m "Ref: ${sourceIssueRef}"` : ""}${authorArg}\`
The \`<short summary>\` is required — replace it with a concrete 5–10 word description of what the step changed.
When all steps are complete: call \`fn_task_done()\`
If a build command is configured, run that exact command in this worktree before calling \`fn_task_done()\`.
Treat a non-zero exit code as a blocking failure. Do not claim success without a real passing run.
Run impacted/package-scoped tests before completion. Run the configured workspace test command only when the task/workflow explicitly requires it or after impacted checks pass for final integration. If any broad command fails, classify the failure before editing: caused-by-this-task failures are blocking; unrelated or pre-existing failures should be logged and split into a follow-up instead of expanding this task.
If the repo has a lint command (e.g. \`pnpm lint\`, \`npm run lint\`), run it before \`fn_task_done()\` and fix any failures it reports.
If the repo has a typecheck command, run it before \`fn_task_done()\` and fix any failures it reports.
Use \`fn_task_create\` for truly separate follow-up work, including unrelated/pre-existing broad-suite failures.
If lint is configured and failing, fix that too before completion.
Do not repeatedly rerun a broad failing or hanging workspace command without a new hypothesis and a narrower confirming command.`;
if (workspaceConfig && workspaceConfig.repos.length > 0) {
return executionPrompt + `\n\n## Workspace mode\n` +
`This project is a workspace containing multiple git repositories.\n` +
`Available repos:\n` +
workspaceConfig.repos.map((r: string) => `- \`${r}\``).join("\n") +
`\n\nBefore editing files in any sub-repo, call \`fn_acquire_repo_worktree\` ` +
`with the repo name to get an isolated worktree path. ` +
`Work exclusively inside that returned path — never edit the repo's main checkout directly.\n`;
}
return executionPrompt;
}
/**
* Format a comment for injection into a running agent session.
* Used for real-time steering during task execution.
*/
export function formatCommentForInjection(comment: import("@fusion/core").SteeringComment): string {
const timestamp = formatTimestamp(comment.createdAt);
return `📣 **New feedback** — ${timestamp} (${comment.author}):\n\n${comment.text}\n\nPlease adjust your approach based on this feedback.`;
}

26
packages/engine/src/executor/executor-constants.ts Normal file
View File

@@ -0,0 +1,26 @@
/**
* FNXC:CodeOrganization 2026-08-04-02:05:
* Module-level TaskExecutor tuning constants peeled from executor.ts preamble (U4).
* Facades and free peels import from here so the class file is not a constants host.
*
* FNXC:SessionContention 2026-07-25-21:30:
* The contention ladder is deliberately long and slow compared with the provider-failure budget (2 fast
* retries): a lease is held for as long as the holder's own work takes — minutes, not milliseconds. Ten
* attempts backing off 5s→60s covers ~8 minutes of waiting, after which the task is left queued for
* ordinary re-dispatch rather than parked. (Backoff values live on the session-contention peel; this
* file keeps the sibling watchdog/retry ceilings that share the same "slow recovery" posture.)
*/
/** Maximum retry attempts for workflow step hard failures before giving up */
export const MAX_WORKFLOW_STEP_RETRIES = 3;
/** How long to wait before recovering a completed task still stuck in in-progress. */
export const COMPLETED_TASK_WATCHDOG_MS = 60_000;
/** How long to wait before retrying a workflow rerun handoff that never reached in-progress. */
export const WORKFLOW_RERUN_WATCHDOG_MS = 15_000;
export const MAX_WORKTREE_RETRIES = 3;
export const WORKTREE_RETRY_DELAYS = [100, 500, 1000] as const; // ms
export const MAX_AUTO_RECOVERY_ATTEMPTS = 3;
export const BRANCH_CONFLICT_TRIPWIRE_THRESHOLD = 5;

33
packages/engine/src/executor/executor-method-docs.ts Normal file
View File

@@ -0,0 +1,33 @@
/**
* FNXC:CodeOrganization 2026-08-04-07:05:
* Non-FNXC method/section docs relocated from TaskExecutor (U4 line-count ratchet).
*
* - Returns the set of task IDs currently being executed.
* - FN-5256: register in-flight disposal so re-dispatch awaits prior session reap.
* - Fast-path completed task → in-review without a new agent session.
* - Defer execute when permanent agent has active heartbeat and allowParallelExecution=false.
* - Column-agent U5/R6: effective principal matches agentId (fail-soft → false).
* - Resume orphaned in-progress tasks after crash/restart (complete → in-review fast path).
* - FN-4811 process-wide graph routing (cross-instance execute() races).
* - Graph foreach instance persistence (KTD-6); undefined on pre-CRUD stores.
* - KTD-12 parse-steps artifact/parser for graph-owned step lists (undefined = legacy).
* - KTD-13 workflow custom field defs for prompt surface (fail-soft → undefined).
* - Task artifact by key (PROMPT.md falls back to task PROMPT content).
* - KTD-15/U14 code-node runner (worktree cwd, artifact pre-read, customFields).
* - Active foreach instance for graph-owned task (undefined outside foreach body).
* - Public authoritative-driver seam factory (same real lifecycle seams as internal graph runner).
* - Await-input node: park awaiting-user-input; resume consumes steering as answer.
* - Run an arbitrary (approved) CLI command in the task worktree, supervised.
* - Column-agent U3 adoption for custom nodes (R8 fail-soft → undefined).
* - Plugin-injected taskEnv (scoped; never mutates process.env). Shared by agentWork + graph skill steps.
* - Custom (non-seam) graph node via WorkflowStep machinery; columnBinding U3/R precedence.
* - U7 CLI handoff: graceful PTY reap as completed (best-effort; never blocks advancement).
* - Shared resumeLanesMemo: one snapshot for handleGraphFailure recovery paths (avoid disagreeing re-resolve).
* - Terminal graph failure: park in review for human action (never leave invisible in-progress).
* - Execute a script-mode workflow step (scriptName → project settings command in worktree).
* - Remove only this executor's store-scoped lifecycle disposer registrations.
* - Stuck-kill: reset done steps when branch has no unique commits (lost uncommitted work).
* - Run a spawned child agent's task to completion (state transitions + cleanup).
*/
export {};

21
packages/engine/src/executor/executor-product-fnxc.ts Normal file
View File

@@ -0,0 +1,21 @@
/**
* FNXC:CodeOrganization 2026-08-04-07:00:
* Product-domain FNXC notes relocated from TaskExecutor (U4). Side-effect imported from executor.ts.
* Field/method declarations remain on TaskExecutor; this module preserves greppable requirement history.
*
* FNXC:Workspace 2026-06-21-15:00: F5/F8 workspace-path helpers are consumed via free peels / pure-bindings, not direct imports here.
* FNXC:TaskTiming 2026-07-30-21:40: graph-owned Plan Review sessions only (self-healing liveness).
* FNXC:ReviewArtifacts 2026-07-19-10:00: best-effort feature-video before review handoff (never delays transition).
* FNXC:TaskTiming 2026-07-30-21:40: Plan Review liveness (narrower than isTaskActive).
* FNXC:GlobalConcurrencyControls 2026-07-14-18:30: share scheduler pre-held global slot; no second top-level acquire under full cap.
* FNXC:PlannerOversight 2026-07-13-23:05: session-advisor flush setter (options captured at construct).
* FNXC:TokenBudget 2026-07-16-00:00: persist-time budget enforcement for all executor token writes.
* FNXC:TokenAnalytics 2026-07-17-14:00: persistTokenUsage sole central writer; baselines feed that delta seam (no double-credit).
* FNXC:ProactiveChatStatus 2026-07-16-12:30: RETHINK summary held until rework reset succeeds.
* FNXC:Settings-ThinkingLevel 2026-07-10-00:00: per-run thinking pin for execute/step-execute seams.
* FNXC:WorkflowStepSkills 2026-07-22-00:00: FN-8490 skill pin for pass-initiating foreach instance.
* FNXC:WorkflowMerge 2026-07-27-12:00: FN-8601 checklist/foreach merge admission gate.
* FNXC:Workspace 2026-06-21-12:00: KTD2 flat-map each task Set to holder rows; reaper keys taskId (idempotent multi-row).
*/
export {};

7
packages/engine/src/executor/executor-reexports.ts Normal file
View File

@@ -0,0 +1,7 @@
/**
* FNXC:CodeOrganization 2026-08-04-08:00:
* Single re-export barrel for TaskExecutor public surface (U4). executor.ts
* only needs one `export *` line instead of public + free barrels.
*/
export * from "./public-reexports.js";
export * from "./free-reexports.js";

13
packages/engine/src/executor/executor-side-effect-hosts.ts Normal file
View File

@@ -0,0 +1,13 @@
/**
* FNXC:CodeOrganization 2026-08-04-07:15:
* Single side-effect import for TaskExecutor FNXC/doc hosts (U4) so executor.ts
* does not spend a line per host module. isBackwardMoveOutOfPlanning body stays
* on TaskExecutor for inert-sync-lane (2 guards).
*/
import "./is-backward-move-out-of-planning.js";
import "./task-executor-fields.js";
import "./facade-fnxc-pointers.js";
import "./executor-product-fnxc.js";
import "./executor-method-docs.js";
export {};

66
packages/engine/src/executor/facade-fnxc-pointers.ts Normal file
View File

@@ -0,0 +1,66 @@
/**
* FNXC:CodeOrganization 2026-08-04-06:50:
* Inventory of TaskExecutor facade FNXC pointers relocated from executor.ts (U4 line-count ratchet).
* Method bodies remain thin facades; requirement history for each peel lives on the named host module.
*
* - 2026-08-04-03:15: activeWorktrees SET semantics FNXC lives on active-worktrees.ts.
* - 2026-08-04-03:15: Pause/abort provenance FNXC lives on paused-abort-provenance.ts.
* - 2026-08-04-03:15: completionFinalizedTaskIds FNXC lives on pause-abort-markers.ts.
* - 2026-08-04-03:15: safeLogEntry FN-7335 breadcrumb FNXC lives on safe-log-entry.ts.
* - 2026-08-04-03:00: Full Workspace/PlanReviewWorktree FNXC lives on session-registry-path.ts.
* - 2026-08-04-03:00: Full SessionContention FNXC lives on acquire-session-registry-path.ts.
* - 2026-08-04-03:35: handoffTaskToReview reason/failure FNXC lives on handoff-task-to-review.ts.
* - 2026-08-04-06:15: isTaskLiveForOverseerRetry FNXC lives on is-task-live-for-overseer-retry.ts.
* - 2026-08-04-03:40: abortAllSessionBash FNXC lives on abort-all-session-bash.ts.
* - 2026-08-04-06:20: isBackward body stays here (inert-sync 2); FNXC host is-backward-move-out-of-planning.ts.
* - 2026-08-04-03:35: signalTaskComplete FN-7528 FNXC lives on signal-task-complete.ts.
* - 2026-08-04-03:40: clearTerminalStepFailures ReviewLeniency FNXC lives on clear-terminal-step-failures-for-retry.ts.
* - 2026-08-04-03:30: recoverFailedPreMerge FNXC lives on recover-failed-pre-merge-step.ts.
* - 2026-08-04-03:15: listWipLaneTasks resume-sweep FNXC lives on list-wip-lane-tasks.ts.
* - 2026-08-04-03:20: graphCompletion U5d/U5e FNXC lives on task-executor-options.ts.
* - 2026-08-04-03:15: no-merge complete-column + IR pin FNXC lives on no-merge-complete-column.ts.
* - 2026-08-04-03:15: column-boundary hooks FNXC lives on build-column-boundary-hooks.ts.
* - 2026-08-04-03:20: runImplementationPhase U5e FNXC lives on run-implementation-phase.ts.
* - 2026-08-04-03:20: step-inversion driver FNXC lives on run-graph-task-step.ts.
* - 2026-08-04-03:20: projected step worktree-gating FNXC lives on run-projected-graph-task-step.ts.
* - 2026-08-04-03:30: column-agent seam FNXC lives on resolve-seam-column-agent.ts / resolve-effective-principal-id.ts / is-agent-effectively-executing.ts.
* - 2026-08-04-03:25: planning worktree acquisition FNXC lives on ensure-task-worktree-for-planning.ts.
* - 2026-08-04-03:30: session-contention hold FNXC lives on session-contention-hold.ts.
* - 2026-08-04-06:15: hasLiveTaskSessionSurface FNXC lives on has-live-task-session-surface host peel.
* - 2026-08-04-06:15: isRemediationGraphNode FNXC lives on remediation-graph-node.ts.
* - 2026-08-04-06:15: isPreMergeRemediationGraphNode FNXC lives on remediation-graph-node.ts.
* - 2026-08-04-03:05: Full Phase C resume-eligibility FNXC lives on resolve-resume-lanes.ts.
* - 2026-08-04-03:25: ephemeral-off dispatch guard FNXC lives on block-outer-dispatch-when-ephemeral-disabled.ts.
* - 2026-08-04-03:25: execute wrapper + executeCore routing FNXC lives on execute-core.ts.
* - 2026-08-04-03:25: runImplementation U5e/U10b/U8 FNXC lives on run-implementation.ts.
* - 2026-08-04-03:40: recoverApprovedSteps FNXC lives on recover-approved-steps-on-resume.ts.
* - 2026-08-04-03:40: reconcileStepsFromGitHistory FNXC lives on reconcile-steps-from-git-history.ts.
* - 2026-08-04-03:40: handleLoopDetected FNXC lives on handle-loop-detected.ts.
* - 2026-08-04-03:30: getWorktreePath KTD2 contract FNXC lives on active-worktrees helpers / free peel.
* - 2026-08-03-20:50: Public non-Free re-exports in executor/public-reexports.ts.
* - 2026-08-04-06:15: Executor tunables via namespace import (U4).
* - 2026-08-04-06:15: Pure free-helpers via namespace import (U4).
* - 2026-08-04-06:05: Impl bindings via namespace import (U4).
* - 2026-08-03-20:40: Free re-exports live in executor/free-reexports.ts (U4 barrel).
* - 2026-08-04-06:05: Deps-bag builders via namespace import (U4).
* - 2026-08-04-02:35: Orphan await-input/conventions JSDoc removed — lives on await-input-parse.ts + workflow-step-verdict.ts peels.
* - 2026-08-03-21:00: Options/types live in executor/task-executor-options.ts.
* - 2026-08-04-03:10: Rebound/guard Phase C FNXC lives on lifecycle-columns.ts; GraphCompletionCallback U5d/U5e on task-executor-options.ts.
* - 2026-08-04-03:35: effectiveColumnAgentByTask semantics on is-agent-effectively-executing.ts.
* - 2026-08-04-03:15: hasLiveSessionSurface / clearPhantom FNXC on has-live-session-surface.ts + clear-phantom-executor-binding.ts.
* - 2026-08-04-02:10: awaitAbort / abortAllInFlight thin facades (U4).
* - 2026-08-04-04:00: constructor wiring via buildWireExecutorLifecycleDeps (U4).
* - 2026-08-04-02:25: shared store + getRunContextFor deps bag for free-fn facades.
* - 2026-08-03-09:25: pure token helper facades for prototype/instance call sites after free peel.
* - 2026-08-04-03:20: optional-step budget + replan-cap FNXC on request-pre-merge-optional-step-fix.ts + park-plan-review-replan-cap.ts.
* - 2026-08-03-16:20: worktree invariant facades (U4 Slice B).
* - 2026-08-03-16:05: branch-conflict reclaim/handle facades (U4 Slice B).
* - 2026-08-03-14:20: thin free-helper facades for vi.spyOn surfaces (U4 Slice B).
* - 2026-08-03-14:50: stale-lock / reclaim / remove-own facades (U4 Slice B).
* - 2026-08-04-03:45: worktree create/conflict deps bag + binders (U4).
* - 2026-08-03-15:20: outer worktree create path facades (U4 Slice B).
* - 2026-08-03-12:35: get/set totalSpawnedCount so capacity tests mutating priv.totalSpawnedCount still drive free-fn path.
* - 2026-08-03-22:25: shared free-tool deps bag for runImplementation + executeWorkflowStep.
*/
export {};

54
packages/engine/src/executor/facade-methods.ts Normal file
View File

@@ -0,0 +1,54 @@
/**
* FNXC:CodeOrganization 2026-08-03-21:25:
* Compact TaskExecutor facade deps wiring (U4).
*
* Large free-function peels take many host methods as deps callbacks. Writing each as
* `(...args) => (this as any).name(...args)` bloats the facade. This helper builds the
* same bound bag from a name list so facades stay thin without changing call semantics.
*
* FNXC:CodeOrganization 2026-08-03-21:40:
* Returns `any` deliberately so spread into typed deps bags does not force `as any` at
* every call site (eslint no-explicit-any would fire on each cast). The host methods are
* private TaskExecutor members; the free-fn deps types are the real contract.
*
* FNXC:CodeOrganization 2026-08-04-04:15:
* FacadeRestArgs strips the leading deps bag from a free-fn signature so multi-arg
* TaskExecutor facades can forward with `...args` instead of re-declaring long parameter
* lists (defaults remain on the free function).
*/
/** Args after the deps bag for a free function of shape `(deps, ...args) => R`. */
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- free-fn deps bag is always first
export type FacadeRestArgs<F> = F extends (deps: any, ...args: infer A) => any ? A : never;
/** Args after the first positional arg (store / rootDir / worktreePath) for free peels. */
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- first positional is host-owned
export type FacadeAfterFirst<F> = F extends (first: any, ...args: infer A) => any ? A : never;
/** Args after two fixed host positionals (rootDir, store). */
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- first two positionals are host-owned
export type FacadeAfterSecond<F> = F extends (a: any, b: any, ...args: infer A) => any ? A : never;
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- see FNXC above
export function facadeMethods(host: object, names: readonly string[]): any {
const out: Record<string, (...args: unknown[]) => unknown> = {};
for (const name of names) {
out[name] = (...args: unknown[]) =>
(host as Record<string, (...a: unknown[]) => unknown>)[name](...args);
}
return out;
}
/*
FNXC:CodeOrganization 2026-08-03-22:15:
Pick host fields by name for free-fn deps bags. Complements facadeMethods for
the field-heavy executeWorkflowGraph / handleGraphFailure / runImplementation facades.
Returns any for the same spread-into-typed-deps reason as facadeMethods.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- see FNXC above
export function facadeFields(host: object, names: readonly string[]): any {
const out: Record<string, unknown> = {};
for (const name of names) {
out[name] = (host as Record<string, unknown>)[name];
}
return out;
}

54
packages/engine/src/executor/finalize-already-reviewed-task.ts Normal file
View File

@@ -0,0 +1,54 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:00:
* finalizeAlreadyReviewedTask peeled from TaskExecutor (U4).
*
* When a completed task is already in the review lane, finalize merge if no merge
* blocker remains; otherwise log deferral. Uses resolved resume lanes (not literals).
*/
import type { TaskStore } from "@fusion/core";
import { getTaskMergeBlocker } from "@fusion/core";
import type { EngineRunContext } from "../util/run-audit.js";
import type { ResumeLanes } from "./resolve-resume-lanes.js";
export type FinalizeAlreadyReviewedTaskDeps = {
store: TaskStore;
getRunContextFor: (taskId: string) => EngineRunContext | undefined;
resolveResumeLanes: (taskId: string, memo?: { lanes?: ResumeLanes }) => Promise<ResumeLanes>;
};
export async function finalizeAlreadyReviewedTask(
deps: FinalizeAlreadyReviewedTaskDeps,
taskId: string,
): Promise<"merged" | "blocked" | "missing"> {
const latestTask = await deps.store.getTask(taskId);
/* FNXC:WorkflowLifecycleColumns 2026-07-30-21:40 (fleet): the board's own review lane. Spelled as the
literal, this reported "missing" — a word that reads as "the task is gone" — for a card sitting in
review on a renamed board, and the already-reviewed finalize never ran. */
if (!latestTask || latestTask.column !== (await deps.resolveResumeLanes(taskId)).review) {
return "missing";
}
/*
FNXC:WorkflowResolvedColumns 2026-07-30-14:40 (outer question resolved, inner one not):
The guard directly above compares against `(await deps.resolveResumeLanes(taskId)).review`, then this
call re-asked with the literal — so a card that just PASSED the resolved lane check was refused by the
unresolved blocker on any renamed board.
*/
const resumeReviewLane = (await deps.resolveResumeLanes(taskId)).review;
const blocker = getTaskMergeBlocker(latestTask, {
reviewColumns: new Set([resumeReviewLane ?? "in-review"]),
});
if (blocker) {
await deps.store.logEntry(taskId, "Task already in-review; merge deferred", blocker, deps.getRunContextFor(taskId));
return "blocked";
}
await deps.store.logEntry(
taskId,
"Task already in-review after completion — finalizing merge",
undefined,
deps.getRunContextFor(taskId),
);
await deps.store.mergeTask(taskId);
return "merged";
}

34
packages/engine/src/executor/foreach-active-for-task.ts Normal file
View File

@@ -0,0 +1,34 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:30:
* foreachActiveForTask peeled from TaskExecutor (U4).
*
* Read the active foreach instance context for a graph-owned task so the step driver can
* honor deferDoneToReview.
*/
import type { ForeachActiveContext } from "../workflows/workflow-node-handlers.js";
import { graphActiveContextKey } from "./task-predicates.js";
export type ForeachActiveForTaskDeps = {
graphStepActiveContext: Map<string, ForeachActiveContext>;
};
export function foreachActiveForTask(
deps: ForeachActiveForTaskDeps,
taskId: string,
instanceId?: string,
): ForeachActiveContext | undefined {
if (typeof instanceId === "string") {
const byInstance = deps.graphStepActiveContext.get(graphActiveContextKey(taskId, instanceId));
if (byInstance) return byInstance;
}
// Fallback (single-instance / no instanceId threaded): return the sole slot
// owned by this task if exactly one exists.
const prefix = `${taskId}:`;
let only: ForeachActiveContext | undefined;
for (const [key, value] of deps.graphStepActiveContext) {
if (!key.startsWith(prefix)) continue;
if (only) return undefined; // ambiguous: more than one instance active
only = value;
}
return only;
}

237
packages/engine/src/executor/free-reexports.ts Normal file
View File

@@ -0,0 +1,237 @@
/**
* FNXC:CodeOrganization 2026-08-03-20:40:
* Barrel of U4 Free re-exports peeled from executor.ts preamble.
* TaskExecutor facades keep Impl imports; public Free symbols live here.
*/
export {
tryCreateWorktree as tryCreateWorktreeFree,
handleWorktreeConflict as handleWorktreeConflictFree,
} from "./worktree-create-conflict.js";
export { cleanupConflictingWorktree as cleanupConflictingWorktreeFree } from "./worktree-cleanup-conflicting.js";
export {
createWorktree as createWorktreeFree,
squashImportDepIntoWorktree as squashImportDepIntoWorktreeFree,
rebaseNewWorktreeOntoRemote as rebaseNewWorktreeOntoRemoteFree,
resolveWorktreeStartPoint as resolveWorktreeStartPointFree,
} from "./worktree-create-outer.js";
export {
reclaimExistingWorktree as reclaimExistingWorktreeFree,
handleBranchConflict as handleBranchConflictFree,
} from "./worktree-branch-conflict-handle.js";
export { recoverMissingWorktreeSessionStartFailure as recoverMissingWorktreeSessionStartFailureFree } from "./worktree-missing-session-recovery.js";
export {
verifyWorktreeInvariants as verifyWorktreeInvariantsFree,
emitWorktreeReanchoredAudit as emitWorktreeReanchoredAuditFree,
} from "./worktree-verify-invariants.js";
export { evaluateTaskDoneScopeLeak as evaluateTaskDoneScopeLeakFree } from "./worktree-task-done-scope-leak.js";
export {
captureModifiedFiles as captureModifiedFilesFree,
captureWorkspaceModifiedFiles as captureWorkspaceModifiedFilesFree,
captureUncommittedModifiedFiles as captureUncommittedModifiedFilesFree,
} from "./worktree-capture-modified-files.js";
export { executeScriptWorkflowStep as executeScriptWorkflowStepFree } from "./workflow-script-step.js";
export { reviewWorkspacePerRepo as reviewWorkspacePerRepoFree } from "./workspace-review-per-repo.js";
export {
workflowInputRepliesAfterWatermark as workflowInputRepliesAfterWatermarkFree,
resolveWorkflowInputMarkerForGraphNode as resolveWorkflowInputMarkerForGraphNodeFree,
} from "./workflow-input-markers.js";
export {
parkCompletedBlockedTask as parkCompletedBlockedTaskFree,
getCompletedTaskFinalizationDecision as getCompletedTaskFinalizationDecisionFree,
shouldFinalizeCompletedTask as shouldFinalizeCompletedTaskFree,
} from "./completion-finalization.js";
export {
handleNonContinuableSessionError as handleNonContinuableSessionErrorFree,
handleNonContinuableSessionRetry as handleNonContinuableSessionRetryFree,
} from "./non-continuable-session.js";
export { createTaskAddDepTool as createTaskAddDepToolFree } from "./task-add-dep-tool.js";
export {
handleImplicitTaskDoneRefusal as handleImplicitTaskDoneRefusalFree,
MAX_TASK_DONE_REQUEUE_RETRIES,
} from "./task-done-refusal-handler.js";
export { handleDepAbortCleanup as handleDepAbortCleanupFree } from "./dep-abort-cleanup.js";
export { reopenLastStepForRevision as reopenLastStepForRevisionFree } from "./reopen-last-step-for-revision.js";
export { runExecutorDeterministicVerification as runExecutorDeterministicVerificationFree } from "./deterministic-verification.js";
export { injectWorkflowStepFailureInstructions as injectWorkflowStepFailureInstructionsFree } from "./workflow-step-failure-injection.js";
export { sendTaskBackForFix as sendTaskBackForFixFree } from "./send-task-back-for-fix.js";
export {
clearStalePauseAbortBeforeDispatch as clearStalePauseAbortBeforeDispatchFree,
clearPauseAbortStateForManualRetry as clearPauseAbortStateForManualRetryFree,
} from "./stale-pause-abort.js";
export { blockOuterDispatchWhenDependenciesUnmet as blockOuterDispatchWhenDependenciesUnmetFree } from "./dependency-dispatch-gate.js";
export { finalizeMergeConfirmedWorkflowGraphTask as finalizeMergeConfirmedWorkflowGraphTaskFree } from "./merge-confirmed-finalize.js";
export {
holdForSessionContention as holdForSessionContentionFree,
MAX_SESSION_CONTENTION_HOLD_RETRIES,
SESSION_CONTENTION_HOLD_BACKOFF_MS,
SESSION_CONTENTION_HOLD_MAX_BACKOFF_MS,
} from "./session-contention-hold.js";
export {
runAwaitInputNode as runAwaitInputNodeFree,
pauseForCliApproval as pauseForCliApprovalFree,
} from "./await-input-node.js";
export { recoverApprovedStepsOnResume as recoverApprovedStepsOnResumeFree } from "./recover-approved-steps-on-resume.js";
export { tryBootstrapMisbindingRecovery as tryBootstrapMisbindingRecoveryFree } from "./bootstrap-misbinding-recovery.js";
export { advanceNoMergeWorkflowToCompleteColumn as advanceNoMergeWorkflowToCompleteColumnFree } from "./no-merge-complete-column.js";
export { applyGraphRethinkReset as applyGraphRethinkResetFree } from "./graph-rethink-reset.js";
export { disposeSubagentsForTask as disposeSubagentsForTaskFree } from "./dispose-subagents.js";
export { ensureWorkflowMergeBoundaryTask as ensureWorkflowMergeBoundaryTaskFree } from "./workflow-merge-boundary.js";
export { scheduleCompletedTaskWatchdog as scheduleCompletedTaskWatchdogFree } from "./completed-task-watchdog.js";
export { scheduleWorkflowRerun as scheduleWorkflowRerunFree } from "./workflow-rerun-watchdog.js";
export {
recoverMissingRequiredArtifacts as recoverMissingRequiredArtifactsFree,
isRequiredArtifactRecoveryProtected as isRequiredArtifactRecoveryProtectedFree,
} from "./required-artifact-recovery.js";
export { performWorkflowRerunBounce as performWorkflowRerunBounceFree } from "./workflow-rerun-bounce.js";
export { dispatchUnpauseResume as dispatchUnpauseResumeFree } from "./unpause-resume.js";
export {
persistTaskTokenUsage as persistTaskTokenUsageFree,
captureExecutorTokenUsageBaseline as captureExecutorTokenUsageBaselineFree,
persistTokenUsage as persistTokenUsageFree,
} from "./persist-token-usage.js";
export { resetMergeStateIfNeeded as resetMergeStateIfNeededFree } from "./reset-merge-state.js";
export { recoverFailedPreMergeWorkflowStep as recoverFailedPreMergeWorkflowStepFree } from "./recover-failed-pre-merge-step.js";
export { reconcileStepsFromGitHistory as reconcileStepsFromGitHistoryFree } from "./reconcile-steps-from-git-history.js";
export { clearPhantomExecutorBinding as clearPhantomExecutorBindingFree } from "./clear-phantom-executor-binding.js";
export { cleanupMergeStateForReverification as cleanupMergeStateForReverificationFree } from "./cleanup-merge-state.js";
export { clearResumeFailureState as clearResumeFailureStateFree } from "./clear-resume-failure-state.js";
export { executeReviewHandoff as executeReviewHandoffFree } from "./execute-review-handoff.js";
export { shouldDeferForHeartbeat as shouldDeferForHeartbeatFree } from "./should-defer-for-heartbeat.js";
export { parkPlanReviewReplanCapExhausted as parkPlanReviewReplanCapExhaustedFree } from "./park-plan-review-replan-cap.js";
export { resumeTaskForAgent as resumeTaskForAgentFree } from "./resume-task-for-agent.js";
export { buildActionGateContext as buildActionGateContextFree } from "./build-action-gate-context.js";
export { buildPermanentAgentGatingContext as buildPermanentAgentGatingContextFree } from "./build-permanent-agent-gating-context.js";
export { resolveInstructionsForRole as resolveInstructionsForRoleFree } from "./resolve-instructions-for-role.js";
export {
signalTaskComplete as signalTaskCompleteFree,
triggerPostTaskReflectionCapture as triggerPostTaskReflectionCaptureFree,
} from "./signal-task-complete.js";
export { listWipLaneTasks as listWipLaneTasksFree } from "./list-wip-lane-tasks.js";
export { resolveSeamColumnAgent as resolveSeamColumnAgentFree } from "./resolve-seam-column-agent.js";
export { resumeOrphaned as resumeOrphanedFree } from "./resume-orphaned.js";
export { handleLoopDetected as handleLoopDetectedFree, LOOP_COMPACTION_TIMEOUT_MS } from "./handle-loop-detected.js";
export { recoverCompletedTask as recoverCompletedTaskFree } from "./recover-completed-task.js";
export { markStuckAborted as markStuckAbortedFree } from "./mark-stuck-aborted.js";
export { awaitAbortInFlightTaskWork as awaitAbortInFlightTaskWorkFree } from "./await-abort-in-flight.js";
export { abortAllInFlight as abortAllInFlightFree } from "./abort-all-in-flight.js";
export { maybeDispatchWorkflowWorkEngine as maybeDispatchWorkflowWorkEngineFree } from "./maybe-dispatch-workflow-work-engine.js";
export { executeCore as executeCoreFree } from "./execute-core.js";
export {
runCliAgentNode as runCliAgentNodeFree,
reapCliTaskSessionForHandoff as reapCliTaskSessionForHandoffFree,
} from "./run-cli-agent-node.js";
export { adoptColumnAgentForNode as adoptColumnAgentForNodeFree } from "./adopt-column-agent-for-node.js";
export { runSpawnedChild as runSpawnedChildFree } from "./run-spawned-child.js";
export { getAutoRecoveryDispatcher as getAutoRecoveryDispatcherFree } from "./get-auto-recovery-dispatcher.js";
export { prepareGraphNodeExecution as prepareGraphNodeExecutionFree } from "./prepare-graph-node-execution.js";
export { transitionReviewAddressing as transitionReviewAddressingFree } from "./transition-review-addressing.js";
export { runGraphTaskStep as runGraphTaskStepFree } from "./run-graph-task-step.js";
export { getAuthoritativeAssignedAgent as getAuthoritativeAssignedAgentFree } from "./get-authoritative-assigned-agent.js";
export { shouldDeferWorkflowStepCompletion as shouldDeferWorkflowStepCompletionFree } from "./should-defer-workflow-step-completion.js";
export { runProjectedGraphTaskStep as runProjectedGraphTaskStepFree } from "./run-projected-graph-task-step.js";
export { buildCodeNodeRunner as buildCodeNodeRunnerFree } from "./build-code-node-runner.js";
export { routeResetParsePinMismatchToRetry as routeResetParsePinMismatchToRetryFree } from "./route-reset-parse-pin-mismatch.js";
export { ensureGraphCustomNodeWorktree as ensureGraphCustomNodeWorktreeFree } from "./ensure-graph-custom-node-worktree.js";
export { taskEffectiveAgentMatches as taskEffectiveAgentMatchesFree } from "./task-effective-agent-matches.js";
export { runRawCliCommand as runRawCliCommandFree } from "./run-raw-cli-command.js";
export { resetStepsIfWorkLost as resetStepsIfWorkLostFree } from "./reset-steps-if-work-lost.js";
export { routeRetryableRemediationGraphFailureToPreMergeFix as routeRetryableRemediationGraphFailureToPreMergeFixFree } from "./route-retryable-remediation.js";
export { buildForeachWorktreeDeps as buildForeachWorktreeDepsFree } from "./build-foreach-worktree-deps.js";
export { requestPreMergeOptionalStepFix as requestPreMergeOptionalStepFixFree } from "./request-pre-merge-optional-step-fix.js";
export { createSpawnAgentTool as createSpawnAgentToolFree, spawnAgentParams as spawnAgentParamsFree } from "./create-spawn-agent-tool.js";
export { createTaskUpdateTool as createTaskUpdateToolFree } from "./create-task-update-tool.js";
export { attemptExecutorVerificationFix as attemptExecutorVerificationFixFree } from "./attempt-executor-verification-fix.js";
export { createTaskDoneTool as createTaskDoneToolFree } from "./create-task-done-tool.js";
export { resetLostWorkStepProgress as resetLostWorkStepProgressFree } from "./reset-lost-work-step-progress.js";
export { resolveResumeLanes as resolveResumeLanesFree } from "./resolve-resume-lanes.js";
export { isReentrantPausedAbortedInFlightNode as isReentrantPausedAbortedInFlightNodeFree } from "./is-reentrant-paused-aborted-in-flight-node.js";
export { routeGraphFailureToExecutionResume as routeGraphFailureToExecutionResumeFree } from "./route-graph-failure-to-execution-resume.js";
export { reenterPausedAbortedWorkflowNode as reenterPausedAbortedWorkflowNodeFree } from "./reenter-paused-aborted-workflow-node.js";
export { isRetryableBenignMergePauseAbort as isRetryableBenignMergePauseAbortFree } from "./is-retryable-benign-merge-pause-abort.js";
export { isBenignManualMergeHoldPauseAbort as isBenignManualMergeHoldPauseAbortFree } from "./is-benign-manual-merge-hold-pause-abort.js";
export { handleStaleInReviewPlanPauseAbortReplay as handleStaleInReviewPlanPauseAbortReplayFree } from "./handle-stale-in-review-plan-pause-abort-replay.js";
export { handleStaleInReviewParsePauseAbortReplay as handleStaleInReviewParsePauseAbortReplayFree } from "./handle-stale-in-review-parse-pause-abort-replay.js";
export { routeGraphMergeFailureToRetry as routeGraphMergeFailureToRetryFree } from "./route-graph-merge-failure-to-retry.js";
export { routeImplementationIncompleteMergeGraphFailure as routeImplementationIncompleteMergeGraphFailureFree } from "./route-implementation-incomplete-merge-graph-failure.js";
export { evaluateTaskVerdictProviders as evaluateTaskVerdictProvidersFree } from "./evaluate-task-verdict-providers.js";
export { blockOuterDispatchWhenEphemeralDisabled as blockOuterDispatchWhenEphemeralDisabledFree } from "./block-outer-dispatch-when-ephemeral-disabled.js";
export { routeUnusableWorktreeGraphFailureToRecovery as routeUnusableWorktreeGraphFailureToRecoveryFree } from "./route-unusable-worktree-graph-failure-to-recovery.js";
export { hasLiveTaskSessionSurface as hasLiveTaskSessionSurfaceFree } from "./has-live-task-session-surface.js";
export { isRemediationGraphNode as isRemediationGraphNodeFree, isPreMergeRemediationGraphNode as isPreMergeRemediationGraphNodeFree } from "./remediation-graph-node.js";
export { resolveFailedPreMergeWorkflowStepBudget as resolveFailedPreMergeWorkflowStepBudgetFree } from "./resolve-failed-pre-merge-workflow-step-budget.js";
export { hasTrailingConsecutiveToolFailures as hasTrailingConsecutiveToolFailuresFree } from "./has-trailing-consecutive-tool-failures.js";
export { isLiveSharedBranchGroupMember as isLiveSharedBranchGroupMemberFree } from "./is-live-shared-branch-group-member.js";
export { resolveEffectivePrincipalId as resolveEffectivePrincipalIdFree } from "./resolve-effective-principal-id.js";
export { createAuthoritativeWorkflowPrimitivesFromExecutor as createAuthoritativeWorkflowPrimitivesFromExecutorFree } from "./create-authoritative-workflow-primitives.js";
export { createAuthoritativeWorkflowSeams as createAuthoritativeWorkflowSeamsFree } from "./create-authoritative-workflow-seams.js";
export { executeWorkflowGraph as executeWorkflowGraphFree } from "./execute-workflow-graph.js";
export { runGraphCustomNode as runGraphCustomNodeFree } from "./run-graph-custom-node.js";
export { handleGraphFailure as handleGraphFailureFree } from "./handle-graph-failure.js";
export { executeWorkflowStep as executeWorkflowStepFree } from "./execute-workflow-step.js";
export { handoffTaskToReview as handoffTaskToReviewFree } from "./handoff-task-to-review.js";
export { cleanupTaskWorktree as cleanupTaskWorktreeFree } from "./cleanup-task-worktree.js";
export { getAssignedAgentRuntimeConfig as getAssignedAgentRuntimeConfigFree } from "./get-assigned-agent-runtime-config.js";
export { runImplementationPhase as runImplementationPhaseFree } from "./run-implementation-phase.js";
export { runImplementation as runImplementationFree } from "./run-implementation.js";
export { finalizeAlreadyReviewedTask as finalizeAlreadyReviewedTaskFree } from "./finalize-already-reviewed-task.js";
export { isTaskLiveForOverseerRetry as isTaskLiveForOverseerRetryFree } from "./is-task-live-for-overseer-retry.js";
export { abortAllSessionBash as abortAllSessionBashFree } from "./abort-all-session-bash.js";
export { runWithExecutorSemaphore as runWithExecutorSemaphoreFree } from "./run-with-executor-semaphore.js";
export { buildParseStepsDeps as buildParseStepsDepsFree } from "./build-parse-steps-deps.js";
export { releasePreExecutionWorktree as releasePreExecutionWorktreeFree } from "./release-pre-execution-worktree.js";
export { terminateChildAgent as terminateChildAgentFree } from "./terminate-child-agent.js";
export {
evaluateWorkflowMergeBoundary as evaluateWorkflowMergeBoundaryFree,
getWorkflowMergeImplementationProofFailure as getWorkflowMergeImplementationProofFailureFree,
} from "./evaluate-workflow-merge-boundary.js";
export { renewTaskLease as renewTaskLeaseFree } from "./renew-task-lease.js";
export { readTaskArtifact as readTaskArtifactFree } from "./read-task-artifact.js";
export { getExecutionPauseLabel as getExecutionPauseLabelFree } from "./get-execution-pause-label.js";
export {
resolveMergeBoundaryColumn as resolveMergeBoundaryColumnFree,
loadMergeBoundaryInstances as loadMergeBoundaryInstancesFree,
shouldCompleteChecklistAtWorkflowMerge as shouldCompleteChecklistAtWorkflowMergeFree,
} from "./workflow-merge-boundary-helpers.js";
export { markPausedAborted as markPausedAbortedFree } from "./mark-paused-aborted.js";
export { acquireSessionRegistryPath as acquireSessionRegistryPathFree } from "./acquire-session-registry-path.js";
export { shouldDeferCompletionForGlobalPause as shouldDeferCompletionForGlobalPauseFree } from "./should-defer-completion-for-global-pause.js";
export { parkApprovalSuspension as parkApprovalSuspensionFree } from "./park-approval-suspension.js";
export { resumeApprovalAfterUnwindIfNeeded as resumeApprovalAfterUnwindIfNeededFree } from "./resume-approval-after-unwind.js";
export { ensureTaskWorktreeForPlanning as ensureTaskWorktreeForPlanningFree } from "./ensure-task-worktree-for-planning.js";
export { foreachActiveForTask as foreachActiveForTaskFree } from "./foreach-active-for-task.js";
export { buildBranchPersistence as buildBranchPersistenceFree } from "./build-branch-persistence.js";
export {
buildBranchConflictHandleDeps as buildBranchConflictHandleDepsFree,
buildWorktreeCreateConflictDeps as buildWorktreeCreateConflictDepsFree,
buildWorktreeInvariantDeps as buildWorktreeInvariantDepsFree,
buildNonContinuableSessionDeps as buildNonContinuableSessionDepsFree,
} from "./deps-bags.js";
export { sessionRegistryPath as sessionRegistryPathFree } from "./session-registry-path.js";
export { addActiveWorktree as addActiveWorktreeFree, getActiveWorktreePaths as getActiveWorktreePathsFree } from "./active-worktrees.js";
export { setActiveSession as setActiveSessionFree, markGraphExecuteSelfRequeued as markGraphExecuteSelfRequeuedFree, deleteActiveSession as deleteActiveSessionFree, setActiveStepExecutor as setActiveStepExecutorFree, deleteActiveStepExecutor as deleteActiveStepExecutorFree, setActiveWorkflowStepSession as setActiveWorkflowStepSessionFree, deleteActiveWorkflowStepSession as deleteActiveWorkflowStepSessionFree } from "./active-session-bookkeeping.js";
export { markCompletionFinalized as markCompletionFinalizedFree, clearPausedAborted as clearPausedAbortedFree } from "./pause-abort-markers.js";
export { updateStepGraph as updateStepGraphFree } from "./update-step-graph.js";
export { buildColumnBoundaryHooks as buildColumnBoundaryHooksFree } from "./build-column-boundary-hooks.js";
export { trackTaskDisposal as trackTaskDisposalFree } from "./track-task-disposal.js";
export { registerConfiguredCommandController as registerConfiguredCommandControllerFree, unregisterConfiguredCommandController as unregisterConfiguredCommandControllerFree } from "./configured-command-controllers.js";
export { safeLogEntry as safeLogEntryFree } from "./safe-log-entry.js";
export { awaitFeatureVideoBounded as awaitFeatureVideoBoundedFree, generateCompletionFeatureVideo as generateCompletionFeatureVideoFree } from "./completion-feature-video.js";
export { getExecutingTaskIds as getExecutingTaskIdsFree, hasActivePlanningWorkflowSession as hasActivePlanningWorkflowSessionFree, isTaskActive as isTaskActiveFree } from "./task-liveness.js";
export { clearCompletedTaskWatchdog as clearCompletedTaskWatchdogFree } from "./clear-completed-task-watchdog.js";
export { terminateAllChildren as terminateAllChildrenFree } from "./terminate-all-children.js";
export { clearTerminalStepFailuresForRetry as clearTerminalStepFailuresForRetryFree } from "./clear-terminal-step-failures-for-retry.js";
export { resolveTaskCustomFieldDefs as resolveTaskCustomFieldDefsFree } from "./resolve-task-custom-field-defs.js";
export { disposeStoreLifecycleDisposers as disposeStoreLifecycleDisposersFree } from "./dispose-store-lifecycle-disposers.js";
export { registerSubagentSession as registerSubagentSessionFree, unregisterSubagentSession as unregisterSubagentSessionFree } from "./subagent-session-registry.js";
export { clearWorkflowRerunWatchdog as clearWorkflowRerunWatchdogFree } from "./clear-workflow-rerun-watchdog.js";
export { getModelRegistry as getModelRegistryFree } from "./get-model-registry.js";
export { hasLiveSessionSurface as hasLiveSessionSurfaceFree } from "./has-live-session-surface.js";
export { listWorktreeHolders as listWorktreeHoldersFree } from "./list-worktree-holders.js";
export { isAgentEffectivelyExecuting as isAgentEffectivelyExecutingFree } from "./is-agent-effectively-executing.js";
export { getWorktreePath as getWorktreePathFree } from "./get-worktree-path.js";
export { buildInjectedRuntimeEnv as buildInjectedRuntimeEnvFree } from "./build-injected-runtime-env.js";
export { getApprovalRequestStore as getApprovalRequestStoreFree } from "./get-approval-request-store.js";
export { isEphemeralDeletionPending as isEphemeralDeletionPendingFree, disposeEphemeralTimers as disposeEphemeralTimersFree } from "./ephemeral-deletion-pending.js";
export { buildStepInstancePersistence as buildStepInstancePersistenceFree } from "./build-step-instance-persistence.js";
export { resolveMcpServers as resolveMcpServersFree } from "./resolve-mcp-servers.js";

26
packages/engine/src/executor/get-approval-request-store.ts Normal file
View File

@@ -0,0 +1,26 @@
/**
* FNXC:CodeOrganization 2026-08-03-20:15:
* approvalRequestStore lazy getter peeled from TaskExecutor (U4).
*
* FNXC:PostgresSatelliteCutover 2026-07-14-17:30:
* Runtime approval persistence is PostgreSQL-only; never reopen the removed project SQLite database.
*/
import { ApprovalRequestStore } from "@fusion/core";
import type { TaskStore } from "@fusion/core";
export type GetApprovalRequestStoreState = {
getCache: () => ApprovalRequestStore | undefined;
setCache: (value: ApprovalRequestStore) => void;
store: TaskStore;
};
export function getApprovalRequestStore(state: GetApprovalRequestStoreState): ApprovalRequestStore {
const existing = state.getCache();
if (existing) return existing;
const layer = state.store.getAsyncLayer();
if (!layer) throw new Error("Executor TaskStore is missing its PostgreSQL AsyncDataLayer");
/* FNXC:PostgresSatelliteCutover 2026-07-14-17:30: Runtime approval persistence is PostgreSQL-only; never reopen the removed project SQLite database when backend wiring is incomplete. */
const created = new ApprovalRequestStore(null, { asyncLayer: layer });
state.setCache(created);
return created;
}

20
packages/engine/src/executor/get-assigned-agent-runtime-config.ts Normal file
View File

@@ -0,0 +1,20 @@
/**
* FNXC:CodeOrganization 2026-08-03-15:40:
* getAssignedAgentRuntimeConfig peeled from TaskExecutor (U4).
*
* Thin lookup: authoritative assigned agent → runtimeConfig bag.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- mirror TaskExecutor method surface
type AnyFn = (...args: any[]) => any;
export type GetAssignedAgentRuntimeConfigDeps = {
getAuthoritativeAssignedAgent: AnyFn;
};
export async function getAssignedAgentRuntimeConfig(
deps: GetAssignedAgentRuntimeConfigDeps,
assignedAgentId: string | null | undefined,
): Promise<Record<string, unknown> | undefined> {
const agent = await deps.getAuthoritativeAssignedAgent(assignedAgentId);
return (agent?.runtimeConfig ?? undefined) as Record<string, unknown> | undefined;
}

51
packages/engine/src/executor/get-authoritative-assigned-agent.ts Normal file
View File

@@ -0,0 +1,51 @@
/**
* FNXC:CodeOrganization 2026-08-03-11:55:
* getAuthoritativeAssignedAgent peeled from TaskExecutor (U4).
*
* FNXC:ModelResolution 2026-07-10-00:00:
* Task execution sessions must honor the assigned permanent agent's runtimeConfig like chat sessions do. If the live executor was handed an agents-less worktree AgentStore, fall back to the authoritative project `.fusion` AgentStore.
*
* FNXC:PostgresOnlyDataAccess 2026-07-17-14:20 / 16:10:
* Fallback AgentStore MUST inherit TaskStore AsyncDataLayer. Do not memoize a layer-less store.
*/
import { join } from "node:path";
import type { Agent, AgentStore as AgentStoreType, TaskStore } from "@fusion/core";
import { AgentStore } from "@fusion/core";
import { executorLog } from "../logger.js";
export type GetAuthoritativeAssignedAgentDeps = {
store: TaskStore;
rootDir: string;
agentStore?: AgentStoreType | null;
getAuthoritativeAssignedAgentStore: () => AgentStoreType | null | undefined;
setAuthoritativeAssignedAgentStore: (store: AgentStoreType) => void;
};
export async function getAuthoritativeAssignedAgent(
deps: GetAuthoritativeAssignedAgentDeps,
assignedAgentId: string | null | undefined,
): Promise<Agent | null> {
const normalizedId = assignedAgentId?.trim();
if (!normalizedId) return null;
const configuredAgent = await deps.agentStore?.getAgent(normalizedId).catch(() => null) ?? null;
if (configuredAgent) return configuredAgent;
try {
const authoritativeAgentLayer = deps.store.getAsyncLayer();
let authoritativeStore = deps.getAuthoritativeAssignedAgentStore();
if (!authoritativeStore || (authoritativeAgentLayer && !authoritativeStore.backendMode)) {
authoritativeStore = new AgentStore({
rootDir: join(deps.rootDir, ".fusion"),
taskStore: deps.store,
...(authoritativeAgentLayer ? { asyncLayer: authoritativeAgentLayer } : {}),
});
deps.setAuthoritativeAssignedAgentStore(authoritativeStore);
}
await authoritativeStore.init();
return await authoritativeStore.getAgent(normalizedId).catch(() => null);
} catch (err: unknown) {
executorLog.warn(`Failed to read assigned agent ${normalizedId} from authoritative project AgentStore: ${err instanceof Error ? err.message : String(err)}`);
return null;
}
}

65
packages/engine/src/executor/get-auto-recovery-dispatcher.ts Normal file
View File

@@ -0,0 +1,65 @@
/**
* FNXC:CodeOrganization 2026-08-03-11:45:
* getAutoRecoveryDispatcher peeled from TaskExecutor (U4).
* Builds the default AutoRecoveryDispatcher with file-scope, branch-worktree, and contamination handlers.
*/
import type { ProjectSettings, TaskStore } from "@fusion/core";
import { AutoRecoveryDispatcher } from "../healing/auto-recovery.js";
import { createFileScopeAutoRecoveryHandler } from "../auto-recovery-handlers/file-scope.js";
import { BranchWorktreeAutoRecoveryHandler } from "../auto-recovery-handlers/branch-worktree.js";
import { ContaminationAutoRecoveryHandler } from "../auto-recovery-handlers/contamination.js";
import { executorLog } from "../logger.js";
import type { RunAuditor } from "../util/run-audit.js";
export type GetAutoRecoveryDispatcherDeps = {
store: TaskStore;
rootDir: string;
autoRecoveryDispatcher?: AutoRecoveryDispatcher | null;
};
export function getAutoRecoveryDispatcher(
deps: GetAutoRecoveryDispatcherDeps,
audit: RunAuditor,
): AutoRecoveryDispatcher {
if (deps.autoRecoveryDispatcher) return deps.autoRecoveryDispatcher;
const fileScopeHandler = createFileScopeAutoRecoveryHandler({
taskStore: deps.store,
runAudit: audit,
logger: executorLog,
spawnAgent: async () => ({ agentId: "unavailable" }),
classifyPatchIds: async () => ({ unique: [], alreadyUpstream: [] }),
settings: () => ({ autoRecovery: { mode: "deterministic-only", maxRetries: 3 } } as ProjectSettings),
});
const branchWorktreeHandler = new BranchWorktreeAutoRecoveryHandler({
taskStore: deps.store,
runAudit: audit,
logger: executorLog,
});
const contaminationHandler = new ContaminationAutoRecoveryHandler({
taskStore: deps.store,
runAudit: audit,
logger: executorLog,
repoDir: deps.rootDir,
});
return new AutoRecoveryDispatcher({
taskStore: deps.store,
auditEmitter: audit,
handlers: {
issueRetry: async (failure, decision, ctx) => {
if (failure.class === "branch-cross-contamination") {
return contaminationHandler.issueRetry(failure, decision, ctx);
}
if (failure.class === "branch-conflict-unrecoverable") {
return branchWorktreeHandler.issueRetry(failure, decision, ctx);
}
return fileScopeHandler.issueRetry(failure, decision, ctx);
},
spawnAiRecovery: async (failure, decision, ctx) => {
if (failure.class === "branch-conflict-unrecoverable") {
return branchWorktreeHandler.spawnAiRecovery(failure, decision, ctx);
}
return fileScopeHandler.spawnAiRecovery(failure, decision, ctx);
},
},
});
}

18
packages/engine/src/executor/get-execution-pause-label.ts Normal file
View File

@@ -0,0 +1,18 @@
/**
* FNXC:CodeOrganization 2026-08-03-17:15:
* getExecutionPauseLabel peeled from TaskExecutor (U4).
*/
import type { TaskStore } from "@fusion/core";
export type GetExecutionPauseLabelDeps = {
store: TaskStore;
};
export async function getExecutionPauseLabel(
deps: GetExecutionPauseLabelDeps,
): Promise<"global pause" | "engine pause" | null> {
const settings = await deps.store.getSettings();
if (settings.globalPause) return "global pause";
if (settings.enginePaused) return "engine pause";
return null;
}

22
packages/engine/src/executor/get-model-registry.ts Normal file
View File

@@ -0,0 +1,22 @@
/**
* FNXC:CodeOrganization 2026-08-03-19:00:
* getModelRegistry peeled from TaskExecutor (U4).
*
* Lazy ModelRegistry construction via Fusion auth storage.
*/
import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
import { createFusionAuthStorage, createFusionModelRegistry } from "../auth/auth-storage.js";
export type GetModelRegistryState = {
getModelRegistryCache: () => Promise<ModelRegistry> | undefined;
setModelRegistryCache: (value: Promise<ModelRegistry>) => void;
};
export function getModelRegistry(state: GetModelRegistryState): Promise<ModelRegistry> {
const existing = state.getModelRegistryCache();
if (existing) return existing;
const authStorage = createFusionAuthStorage();
const created = createFusionModelRegistry(authStorage);
state.setModelRegistryCache(created);
return created;
}

Some files were not shown because too many files have changed in this diff Show More