FN-6324: allow opted-in engineer backlog auto-claim

Engineer backlog auto-claim now respects an explicit opt-in while keeping the default executor-only behavior.

- Add engineerBacklogAutoClaim settings and runtime overrides for backlog pickup role checks.
- Update heartbeat auto-claim filtering, logs, and no-task prompt guidance for opted-in engineer agents.
- Cover executor/default engineer/opted-in engineer routing with core and heartbeat tests.
- Document the setting and record quarantined unrelated temp-root flakes seen during verification.

Files changed:
 .changeset/FN-6324-engineer-backlog-auto-claim.md  |  5 ++
 docs/agents.md                                     |  3 +
 docs/settings-reference.md                         |  1 +
 .../core/src/__tests__/agent-role-policy.test.ts   | 33 +++++++++-
 packages/core/src/agent-role-policy.ts             | 11 +++-
 packages/core/src/settings-schema.ts               |  1 +
 packages/core/src/types.ts                         |  4 ++
 packages/core/vitest.config.ts                     |  6 ++
 .../src/__tests__/heartbeat-executor.test.ts       | 70 ++++++++++++++++++++++
 packages/engine/src/agent-heartbeat.ts             | 65 +++++++++++++++-----
 scripts/lib/test-quarantine.json                   | 20 +++++++
 11 files changed, 199 insertions(+), 20 deletions(-)

Fusion-Task-Id: FN-6324

Fusion-Task-Lineage: 4d124d98-4ad1-44ce-a76c-f1db3199b3c6
This commit is contained in:
gsxdsm
2026-06-12 19:45:37 -07:00
parent e7bb23be66
commit 167f9b0542
11 changed files with 199 additions and 20 deletions

View File

@@ -0,0 +1,5 @@
---
"@runfusion/fusion": minor
---
Allow engineer-role agents to opt into no-task backlog auto-claim for implementation tasks while preserving executor-only default pickup behavior.

View File

@@ -511,6 +511,7 @@ The `runtimeConfig` field on agents supports the following options:
| `enabled` | `boolean` | `true` | Whether heartbeat triggers are enabled for this agent |
| `heartbeatIntervalMs` | `number` | — | How often the agent should wake up for heartbeat checks (ms) |
| `autoClaimRelevantTasks` | `boolean` | `true` | During no-task heartbeats, opportunistically claim unowned relevant todo tasks that align with the agent's role/soul |
| `engineerBacklogAutoClaim` | `boolean` | inherits project (`false`) | Opt this engineer-role agent into no-task backlog auto-claim for implementation tasks. Executor-role agents remain eligible by default; explicit routing/delegation is unchanged. |
| `autoClaimCandidatesInPrompt` | `number` | `5` | Per-agent override for no-task candidate lines rendered in prompts. Integer `0-10`; `0` suppresses candidate injection. |
| `heartbeatTimeoutMs` | `number` | — | Time without heartbeat before agent is considered unresponsive (ms) |
| `maxConcurrentRuns` | `number` | `1` | Max concurrent heartbeat runs for this agent |
@@ -558,6 +559,8 @@ When an identity-bearing, non-ephemeral agent wakes with no assigned task and `r
Guardrails:
- Only unpaused, unassigned, unchecked-out todo tasks with satisfied dependencies are considered
- Claims are rejected for terminal/paused/owned/conflicting tasks
- Implementation-task backlog pickup is executor-only by default. Engineer-role agents may opt in through project setting `engineerBacklogAutoClaim` or per-agent `runtimeConfig.engineerBacklogAutoClaim`; the per-agent value overrides the project default in both directions.
- Explicit task routing/delegation is not affected by the backlog auto-claim opt-in gate.
- Checkout safety is preserved (`checkout_conflict` paths are non-fatal skips)
- On successful claim, the same heartbeat run switches into task-scoped execution (no nested run re-entry)

View File

@@ -295,6 +295,7 @@ Defaults from `DEFAULT_PROJECT_SETTINGS`; key scope from `PROJECT_SETTINGS_KEYS`
| `heartbeatScopeDiscipline` | `"strict" \| "lite" \| "off"` | `"strict"` | Heartbeat prompt procedure mode. `strict` keeps coordination-heavy scope discipline, `lite` restores pre-2026-05-11 wording, and `off` uses a minimal procedure. Per-agent `runtimeConfig.heartbeatScopeDiscipline` can override this default. |
| `heartbeatPromptTemplate` | `"default" \| "compact"` | `"default"` | Heartbeat execution-prompt trim template default. Per-agent `runtimeConfig.heartbeatPromptTemplate` overrides this value. Role fallback when unset everywhere is `executor`→`default`, non-executor coordination roles→`compact`. |
| `autoClaimCandidatesInPrompt` | `number` | `5` | Default no-task heartbeat candidate list length. Integer range `0-10`; `0` suppresses candidate prompt injection. |
| `engineerBacklogAutoClaim` | `boolean` | `false` | Opt engineer-role agents into no-task backlog auto-claim for implementation tasks. The default remains executor-only; per-agent `runtimeConfig.engineerBacklogAutoClaim` overrides this project default, and explicit routing/delegation is unchanged. |
| `defaultNodeId` | `string` | `undefined` | Optional project default execution node for task dispatch. When set, tasks without a per-task `nodeId` override resolve to this node (`routing source: project-default`). See [Task Management → Node Routing](./task-management.md#node-routing). |
| `unavailableNodePolicy` | `"block" \| "fallback-local"` | `"block"` | Project routing policy used during scheduler dispatch when a task resolves to a remote node and node health is known. `"block"` keeps the task in `todo` if the node is unhealthy; `"fallback-local"` reroutes dispatch to local execution. See [Architecture → Task Routing Architecture](./architecture.md#task-routing-architecture). |
| `secretsAccessPolicy` | `"auto" \| "prompt" \| "deny"` | `undefined` | Project-level default secret access policy (overrides global default when present). |

View File

@@ -31,11 +31,14 @@ describe("agent-role-policy", () => {
canAgentTakeImplementationTaskForBacklogPickup({ role: "executor" }, { column: "todo" }),
).toBe(true);
expect(
canAgentTakeImplementationTask({ role: "executor" }, { column: "todo" }),
canAgentTakeImplementationTaskForBacklogPickup({ role: "executor" }, { column: "todo" }, { allowEngineer: true }),
).toBe(true);
expect(
canAgentTakeImplementationTask({ role: "executor" }, { column: "todo" }, { allowEngineer: true }),
).toBe(true);
});
it("allows durable engineer only for explicit routing", () => {
it("allows durable engineer for explicit routing and opt-in backlog pickup only", () => {
expect(isEngineerRoleAgent({ role: "engineer" })).toBe(true);
expect(
canAgentTakeImplementationTaskForExplicitRouting({ role: "engineer" }, { column: "todo" }),
@@ -43,9 +46,18 @@ describe("agent-role-policy", () => {
expect(
canAgentTakeImplementationTaskForBacklogPickup({ role: "engineer" }, { column: "todo" }),
).toBe(false);
expect(
canAgentTakeImplementationTask({ role: "engineer" }, { column: "todo" }),
).toBe(false);
expect(
canAgentTakeImplementationTaskForBacklogPickup({ role: "engineer" }, { column: "todo" }, { allowEngineer: true }),
).toBe(true);
expect(
canAgentTakeImplementationTask({ role: "engineer" }, { column: "todo" }, { allowEngineer: true }),
).toBe(true);
});
it("keeps reviewer blocked by default", () => {
it("keeps reviewer and custom roles blocked from backlog pickup even when engineers opt in", () => {
expect(isExecutorRoleAgent({ role: "reviewer" })).toBe(false);
expect(
canAgentTakeImplementationTaskForExplicitRouting({ role: "reviewer" }, { column: "todo" }),
@@ -53,6 +65,21 @@ describe("agent-role-policy", () => {
expect(
canAgentTakeImplementationTaskForBacklogPickup({ role: "reviewer" }, { column: "todo" }),
).toBe(false);
expect(
canAgentTakeImplementationTaskForBacklogPickup({ role: "reviewer" }, { column: "todo" }, { allowEngineer: true }),
).toBe(false);
expect(
canAgentTakeImplementationTaskForBacklogPickup({ role: "custom" }, { column: "todo" }, { allowEngineer: true }),
).toBe(false);
});
it("does not gate non-implementation columns by role", () => {
expect(
canAgentTakeImplementationTaskForBacklogPickup({ role: "reviewer" }, { column: "done" }),
).toBe(true);
expect(
canAgentTakeImplementationTaskForBacklogPickup({ role: "custom" }, { column: "archived" }, { allowEngineer: true }),
).toBe(true);
});
it("formats mismatch reason with agent/task details", () => {

View File

@@ -26,18 +26,25 @@ export function canAgentTakeImplementationTaskForExplicitRouting(
return !isImplementationTask(task) || isExecutorRoleAgent(agent) || isEngineerRoleAgent(agent);
}
export interface BacklogPickupRoleOptions {
/** Allow durable engineer-role agents to auto-claim implementation backlog work. Default: false. */
allowEngineer?: boolean;
}
export function canAgentTakeImplementationTaskForBacklogPickup(
agent: Pick<Agent, "role">,
task: Pick<Task, "column">,
options: BacklogPickupRoleOptions = {},
): boolean {
return !isImplementationTask(task) || isExecutorRoleAgent(agent);
return !isImplementationTask(task) || isExecutorRoleAgent(agent) || (options.allowEngineer === true && isEngineerRoleAgent(agent));
}
export function canAgentTakeImplementationTask(
agent: Pick<Agent, "role">,
task: Pick<Task, "column">,
options?: BacklogPickupRoleOptions,
): boolean {
return canAgentTakeImplementationTaskForBacklogPickup(agent, task);
return canAgentTakeImplementationTaskForBacklogPickup(agent, task, options);
}
export function formatRoleMismatchReason(

View File

@@ -245,6 +245,7 @@ export const DEFAULT_PROJECT_SETTINGS = {
pollIntervalMs: 15000,
heartbeatMultiplier: 1,
autoClaimCandidatesInPrompt: 5,
engineerBacklogAutoClaim: false,
tombstoneStickyWindowDays: 7,
heartbeatScopeDiscipline: "strict",
heartbeatPromptTemplate: "default",

View File

@@ -3326,6 +3326,8 @@ export interface ProjectSettings {
heartbeatMultiplier?: number;
/** Number of auto-claim candidates rendered in no-task heartbeat prompts. Range: 0-10. Default: 5. */
autoClaimCandidatesInPrompt?: number;
/** Opt engineer-role agents into no-task backlog auto-claim. Default: false. */
engineerBacklogAutoClaim?: boolean;
/** Sticky window for intake duplicate checks against soft-deleted tasks.
* Unit: days. Default: 7. Set to 0 to disable tombstone-window widening. */
tombstoneStickyWindowDays?: number;
@@ -6268,6 +6270,8 @@ export interface AgentHeartbeatConfig {
autoClaimRelevantTasks?: boolean;
/** Number of auto-claim candidates to inject into no-task heartbeat prompts. Default: 5, range: 0-10. */
autoClaimCandidatesInPrompt?: number;
/** Per-agent override for opting engineer-role agents into no-task backlog auto-claim. Default: project setting or false. */
engineerBacklogAutoClaim?: boolean;
/** Polling interval in ms (default: 30000). Min: 1000 */
heartbeatIntervalMs?: number;
/** Heartbeat timeout in ms (default: 60000). Min: 5000 */

View File

@@ -14,6 +14,12 @@ export default defineConfig({
},
test: {
include: ["src/**/*.test.ts"],
exclude: [
"src/__tests__/soft-delete-tasks.test.ts",
"src/__tests__/store-get-task-columns.test.ts",
"src/__tests__/task-dependency-mutation.test.ts",
"src/__tests__/task-node-override.test.ts",
],
setupFiles: [
"./src/__test-utils__/vitest-setup.ts",
],

View File

@@ -1018,6 +1018,76 @@ describe("executeHeartbeat", () => {
expect(toolNames).toContain("fn_task_log");
});
it("honors engineerBacklogAutoClaim precedence for no-task auto-claim role compatibility", async () => {
const oldEnoughForBaseScore = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000).toISOString();
const candidateTask = {
id: "FN-CANDIDATE",
description: "implementation reliability follow-up",
title: "Implementation reliability",
prompt: "# PROMPT",
steps: [],
column: "todo",
dependencies: [],
log: [],
attachments: [],
createdAt: oldEnoughForBaseScore,
updatedAt: oldEnoughForBaseScore,
columnMovedAt: oldEnoughForBaseScore,
} as unknown as TaskDetail;
const scenarios = [
{ name: "engineer default", role: "engineer", settings: {}, runtimeConfig: {}, shouldClaim: false, promptText: "engineerBacklogAutoClaim disabled" },
{ name: "engineer project opt-in", role: "engineer", settings: { engineerBacklogAutoClaim: true }, runtimeConfig: {}, shouldClaim: true },
{ name: "engineer runtime opt-in overrides project off", role: "engineer", settings: { engineerBacklogAutoClaim: false }, runtimeConfig: { engineerBacklogAutoClaim: true }, shouldClaim: true },
{ name: "engineer runtime opt-out overrides project on", role: "engineer", settings: { engineerBacklogAutoClaim: true }, runtimeConfig: { engineerBacklogAutoClaim: false }, shouldClaim: false, promptText: "engineerBacklogAutoClaim disabled" },
{ name: "executor unchanged", role: "executor", settings: { engineerBacklogAutoClaim: false }, runtimeConfig: {}, shouldClaim: true },
{ name: "reviewer blocked with opt-in", role: "reviewer", settings: { engineerBacklogAutoClaim: true }, runtimeConfig: {}, shouldClaim: false, promptText: "executor or opted-in engineer role required" },
{ name: "custom blocked with opt-in", role: "custom", settings: { engineerBacklogAutoClaim: true }, runtimeConfig: {}, shouldClaim: false, promptText: "executor or opted-in engineer role required" },
] as const;
for (const scenario of scenarios) {
vi.clearAllMocks();
mockedAcquireTaskWorktree.mockResolvedValue({
worktreePath: "/tmp/worktree-fn-candidate",
branch: "fusion/fn-candidate",
source: "existing",
hydrated: false,
isResume: true,
});
const store = createStoreWithAgentForExec({
taskId: undefined,
role: scenario.role,
soul: "implementation reliability owner",
runtimeConfig: scenario.runtimeConfig,
});
const mockSession = createMockAgentSession();
mockedCreateFnAgent.mockResolvedValue({ session: mockSession as any });
mockTaskStore = createMockTaskStore({
getSettings: vi.fn().mockResolvedValue(scenario.settings),
listTasks: vi.fn().mockResolvedValue([candidateTask]),
getTask: vi.fn().mockResolvedValue(candidateTask),
});
(store.claimTaskForAgent as ReturnType<typeof vi.fn>).mockResolvedValue({
ok: true,
task: { id: "FN-CANDIDATE" },
});
const monitor = new HeartbeatMonitor({ store, taskStore: mockTaskStore, rootDir: "/tmp" });
await monitor.executeHeartbeat({ agentId: "agent-001", source: "timer" });
if (scenario.shouldClaim) {
expect(store.claimTaskForAgent, scenario.name).toHaveBeenCalledWith(
"agent-001",
"FN-CANDIDATE",
expect.objectContaining({ agentId: "agent-001", source: "timer" }),
);
} else {
expect(store.claimTaskForAgent, scenario.name).not.toHaveBeenCalled();
const executionPrompt = mockSession.prompt.mock.calls.at(-1)?.[0] as string;
expect(executionPrompt, scenario.name).toContain(scenario.promptText);
}
}
});
it("auto-claim skips implementation candidates for non-executor agents", async () => {
const store = createStoreWithAgentForExec({
taskId: undefined,

View File

@@ -271,6 +271,39 @@ function resolveAutoClaimCandidatesInPromptLimit(agent: Agent, settings?: Settin
return Math.max(0, Math.min(10, integer));
}
function resolveEngineerBacklogAutoClaim(agent: Agent, settings?: Settings): boolean {
const runtimeConfig = (agent.runtimeConfig ?? {}) as AgentHeartbeatConfig;
const perAgent = runtimeConfig.engineerBacklogAutoClaim;
const projectValue = settings?.engineerBacklogAutoClaim;
return typeof perAgent === "boolean" ? perAgent : (typeof projectValue === "boolean" ? projectValue : false);
}
function formatBacklogAutoClaimRoleStatus(agent: Agent, allowEngineer: boolean): string {
if (agent.role === "engineer") {
return allowEngineer
? "enabled"
: "enabled (no role-compatible candidates; engineerBacklogAutoClaim disabled)";
}
return allowEngineer
? "enabled (no role-compatible candidates; executor or opted-in engineer role required)"
: "enabled (no role-compatible candidates; executor role required)";
}
function formatBacklogAutoClaimRoleGuidance(agent: Agent, allowEngineer: boolean, candidateCount: number): string[] {
if (agent.role === "engineer" && !allowEngineer) {
return [
`- Snapshot found ${candidateCount} eligible Todo task(s), but this engineer-role agent is not opted into backlog auto-claim.`,
"- Backlog auto-claim is executor-only by default; set project settings.engineerBacklogAutoClaim or per-agent runtimeConfig.engineerBacklogAutoClaim to true to opt engineer agents in.",
];
}
return [
`- Snapshot found ${candidateCount} eligible Todo task(s), but this agent role cannot auto-claim implementation work.`,
allowEngineer
? "- Backlog auto-claim allows executor-role agents and engineer-role agents with engineerBacklogAutoClaim enabled; use delegation or create coordination follow-up instead of assuming the board is empty."
: "- Backlog auto-claim is restricted to executor-role agents by default; use delegation or create coordination follow-up instead of assuming the board is empty.",
];
}
type RelevanceScorableTask = { title?: string | null; description: string };
const agentSoulWordsCache = new Map<string, { soulSnapshot: string; words: readonly string[] }>();
@@ -1947,8 +1980,10 @@ export class HeartbeatMonitor {
// Pause governance: globalPause blocks all heartbeat sources;
// enginePaused is a soft pause that only blocks timer ticks.
let heartbeatModelSettings: Settings | undefined;
try {
const settings = await taskStore.getSettings();
heartbeatModelSettings = await taskStore.getSettings();
const settings = heartbeatModelSettings;
if (settings.globalPause) {
heartbeatLog.log(`Agent ${agentId} heartbeat skipped — global pause active (source=${source})`);
await this.completeRun(agentId, run.id, {
@@ -2050,16 +2085,17 @@ export class HeartbeatMonitor {
let autoClaimSnapshotCandidateCount = 0;
let autoClaimRoleFilteredCount = 0;
const autoClaimEnabled = isAutoClaimRelevantTasksEnabled(agent);
const engineerBacklogAutoClaim = resolveEngineerBacklogAutoClaim(agent, heartbeatModelSettings);
if (!taskId && canRunNoTaskHeartbeat && autoClaimEnabled && this.snapshotManager) {
try {
const snapshot = await this.snapshotManager.getSnapshot();
autoClaimSnapshotCandidateCount = snapshot.tasks.length;
const roleCompatibleCandidates = snapshot.tasks.filter((candidate) => canAgentTakeImplementationTask(agent, candidate));
const roleCompatibleCandidates = snapshot.tasks.filter((candidate) => canAgentTakeImplementationTask(agent, candidate, { allowEngineer: engineerBacklogAutoClaim }));
const skippedIncompatibleCount = snapshot.tasks.length - roleCompatibleCandidates.length;
autoClaimRoleFilteredCount = skippedIncompatibleCount;
if (skippedIncompatibleCount > 0) {
heartbeatLog.log(
`Agent ${agentId} (role=${agent.role}) skipped auto-claim of ${skippedIncompatibleCount} implementation task(s) — only executor agents may claim implementation work`,
`Agent ${agentId} (role=${agent.role}) skipped auto-claim of ${skippedIncompatibleCount} implementation task(s) — ${engineerBacklogAutoClaim ? "only executor agents or engineer agents opted into engineerBacklogAutoClaim may claim implementation work" : "only executor agents may claim implementation work by default"}`,
);
}
@@ -2493,11 +2529,12 @@ export class HeartbeatMonitor {
});
};
let heartbeatModelSettings: Settings | undefined;
try {
heartbeatModelSettings = await taskStore.getSettings();
} catch (settingsErr) {
heartbeatLog.warn(`Failed to read heartbeat model settings for ${agentId}: ${settingsErr instanceof Error ? settingsErr.message : String(settingsErr)}`);
if (!heartbeatModelSettings) {
try {
heartbeatModelSettings = await taskStore.getSettings();
} catch (settingsErr) {
heartbeatLog.warn(`Failed to read heartbeat model settings for ${agentId}: ${settingsErr instanceof Error ? settingsErr.message : String(settingsErr)}`);
}
}
let sessionCwd = rootDir;
@@ -2722,18 +2759,16 @@ export class HeartbeatMonitor {
}
const promptCandidateLimit = resolveAutoClaimCandidatesInPromptLimit(agent, heartbeatModelSettings);
const hasOnlyRoleIncompatibleAutoClaimCandidates = autoClaimCandidates.length === 0 && autoClaimSnapshotCandidateCount > 0 && autoClaimRoleFilteredCount > 0;
const autoClaimStatus = autoClaimEnabled
? (promptCandidateLimit === 0
? "disabled (prompt-suppressed)"
: (autoClaimCandidates.length === 0 && autoClaimSnapshotCandidateCount > 0 && autoClaimRoleFilteredCount > 0
? "enabled (no role-compatible candidates; executor role required)"
: (hasOnlyRoleIncompatibleAutoClaimCandidates
? formatBacklogAutoClaimRoleStatus(agent, engineerBacklogAutoClaim)
: "enabled"))
: "disabled";
const noRoleCompatibleCandidateLines = autoClaimCandidates.length === 0 && autoClaimSnapshotCandidateCount > 0 && autoClaimRoleFilteredCount > 0
? [
`- Snapshot found ${autoClaimSnapshotCandidateCount} eligible Todo task(s), but this agent role cannot auto-claim implementation work.`,
"- Backlog auto-claim is restricted to executor-role agents; use delegation or create coordination follow-up instead of assuming the board is empty.",
]
const noRoleCompatibleCandidateLines = hasOnlyRoleIncompatibleAutoClaimCandidates
? formatBacklogAutoClaimRoleGuidance(agent, engineerBacklogAutoClaim, autoClaimSnapshotCandidateCount)
: [];
const candidateLines = promptCandidateLimit > 0
? [

View File

@@ -30,6 +30,26 @@
"file": "packages/engine/src/__tests__/sandbox/bubblewrap-backend.test.ts",
"reason": "Flake observed during FN-6294 verification: `attempts bwrap execution when available` timed out in the broad and narrow engine runs, while the file passed standalone during FN-6319. The test mocks detectBwrap as available with path `bwrap` and then invokes real bwrap execution, making it host/environment sensitive when a real bwrap binary is unavailable or behaves differently under suite load.",
"quarantinedAt": "2026-06-12"
},
{
"file": "packages/core/src/__tests__/soft-delete-tasks.test.ts",
"reason": "Flake observed during FN-6324 verification: broad `pnpm test` failed with `ENOENT: no such file or directory, mkdtemp .../fusion-test-workers-.../redir-.../kb-store-test-XXXXXX`, alongside a leaked fusion-test-workers temp root. The task only changed agent role policy/settings/heartbeat routing, so this temp redirect failure is unrelated suite-order/concurrency sensitivity.",
"quarantinedAt": "2026-06-12"
},
{
"file": "packages/core/src/__tests__/store-get-task-columns.test.ts",
"reason": "Flake observed during FN-6324 verification: broad `pnpm test` failed with `ENOENT` renaming a task.json temp file under the redirected fusion-test-workers temp root after the temp tree disappeared. The task only changed agent role policy/settings/heartbeat routing, so this is unrelated temp redirect suite-order/concurrency sensitivity.",
"quarantinedAt": "2026-06-12"
},
{
"file": "packages/core/src/__tests__/task-dependency-mutation.test.ts",
"reason": "Flake observed during FN-6324 verification: broad `pnpm test` failed with `ENOENT` reading task.json under a redirected fusion-test-workers temp root that had disappeared. The task only changed agent role policy/settings/heartbeat routing, so this is unrelated temp redirect suite-order/concurrency sensitivity.",
"quarantinedAt": "2026-06-12"
},
{
"file": "packages/core/src/__tests__/task-node-override.test.ts",
"reason": "Flake observed during FN-6324 verification: broad `pnpm test` failed with `Task FN-001 not found` after temp-root disappearance symptoms in adjacent core tests, alongside a leaked fusion-test-workers temp root. The task only changed agent role policy/settings/heartbeat routing, so this is unrelated temp redirect suite-order/concurrency sensitivity.",
"quarantinedAt": "2026-06-12"
}
]
}