gsxdsm 167f9b0542 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

2026-06-12 19:45:37 -07:00

..

__tests__

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

2026-06-12 19:45:37 -07:00

auto-recovery-handlers

fix(engine): un-deadcode bootstrap-misbinding auto-recovery fallback

2026-05-23 02:29:38 -07:00

cli-agent

fix(review): schema-version gate, output-filter escape-bypass, generic double-wrap, follow-up resolution

2026-06-05 03:41:54 -07:00

experiment

FN-5782: wire branch groups into merge routing

2026-05-31 13:50:23 -07:00

external-integrations

feat(FN-5321): add evidence gap detector for external integration manifests

2026-05-20 15:54:44 -07:00

ipc

FN-5703: forward task:deleted events through in-process runtime

2026-05-29 20:05:14 -07:00

notification

FN-6093: fix ntfy workflow notification delivery

2026-06-09 12:50:26 -07:00

providers

FN-5638: migrate pi-ai and pi-coding-agent packages to @earendil-works scope

2026-05-28 21:23:48 -07:00

recovery

feat(FN-5349): add integration branch resolver with auto-recovery fallback

2026-05-21 12:04:58 -07:00

remote-access

feat(FN-5189): complete Step 3 — migrate supervised spawns

2026-05-19 17:19:02 -07:00

research

fix: Replace htmlUrl with url in gh search repos query

2026-05-23 22:09:25 -03:00

runtimes

FN-6284: refire deferred agent assignments

2026-06-12 03:00:45 -07:00

sandbox

fix(FN-6043): recover stuck task processing

2026-06-08 18:14:48 -07:00

spec-validation

feat(FN-5321): add evidence gap detector for external integration manifests

2026-05-20 15:54:44 -07:00

test

…

types/node-pty

feat(engine): extract shared PTY native-asset loader and redactSecrets (U16)

2026-06-04 22:53:02 -07:00

active-session-registry.ts

FN-6244: protect active AI merge worktrees

2026-06-11 15:54:49 -07:00

agent-action-gate.ts

…

agent-assignment.ts

FN-5941: stop missions stalling on incompatible/custom-role agents

2026-06-03 17:14:42 -07:00

agent-heartbeat.ts

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

2026-06-12 19:45:37 -07:00

agent-instructions.ts

…

agent-logger.ts

…

agent-memory-index.ts

…

agent-reflection.ts

…

agent-runtime.ts

FN-5638: migrate pi-ai and pi-coding-agent packages to @earendil-works scope

2026-05-28 21:23:48 -07:00

agent-self-improve.ts

…

agent-session-helpers.ts

FN-6228: prioritize project model overrides

2026-06-11 20:44:52 -07:00

agent-tools.ts

FN-6164: route agent task title summarization through the store

2026-06-09 22:18:48 -07:00

already-merged-detector.ts

fix(FN-branch-group): address PR review feedback (#1357)

2026-06-03 13:51:13 -07:00

auth-storage.ts

FN-5924: throttle OAuth expiry alerts across restarts

2026-06-02 23:13:16 -07:00

auto-claim-snapshot.ts

fix(FN-5137): complete Step 2-3 — guard deleted tasks in snapshot and executor

2026-05-19 07:45:12 -07:00

auto-merge-fact-providers.ts

feat(engine): add workflow extension plugin seams

2026-06-07 20:43:44 -07:00

auto-recovery.ts

feat(FN-5348): remove cwd-main integration mode fallback

2026-05-21 12:49:50 -07:00

backlog-pressure-reporter.ts

feat(FN-5009): merge fusion/fn-5009

2026-05-18 12:31:21 -07:00

base-commit-capture.ts

fix(engine): capture baseCommitSha against local main, not origin/main

2026-06-03 15:24:03 -07:00

branch-attribution.ts

fix(FN-5304): guard against silent no-op landed-file attribution mismatches

2026-05-20 08:23:40 -07:00

branch-autocorrect.ts

fix(FN-5456): tidy autocorrect shell quoting and disambiguate checkout

2026-05-23 00:03:12 -07:00

branch-conflicts.ts

FN-6139: remove unused _baseSha parameter

2026-06-09 15:21:39 -07:00

cli-agent-validator.ts

feat(engine): cli-agent one-shot sessions for validator, planning, and CE (U9)

2026-06-05 00:15:57 -07:00

code-node-runner.ts

fix: address PR review feedback (#1424)

2026-06-04 16:16:50 -07:00

concurrency.ts

fix(FN-6043): address stuck task PR feedback

2026-06-08 20:29:37 -07:00

context-limit-detector.ts

…

cron-runner.ts

…

custom-providers.ts

FN-5833: fix custom Responses API model lookup

2026-06-01 08:23:02 -07:00

dependency-blocked-todo-reporter.ts

fix(FN-5091): harden maxAutoMergeRetries settings parsing

2026-05-19 03:21:18 -07:00

effective-node.ts

…

effective-settings.ts

feat(engine): per-task effective workflow settings — resolver, two-tier entry merge, fallback alignment

2026-06-04 22:37:51 -07:00

engine-errors.ts

fix: address PR review feedback (#1467)

2026-06-07 23:03:38 -07:00

engine-singleton-lock.ts

feat(engine): guard one engine per project per machine

2026-05-19 22:50:39 -07:00

ephemeral-worker-manager.ts

…

error-classifier.ts

…

eval-followups.ts

feat(FN-5232): add deterministic verification-followup deduplication to pre

2026-05-19 19:28:05 -07:00

evaluator-evidence.ts

FN-5697: retry transient auto-merge failures and fix migration versioning

2026-05-29 10:23:59 -07:00

evaluator.ts

…

executor.ts

FN-6294: collapse workflow merge primitives

2026-06-12 14:21:18 -07:00

experiment-executor.ts

…

fallback-model-observer.ts

…

gating-classifications.ts

FN-5977: expose goal retrieval tools across engine agents

2026-06-07 18:51:46 -07:00

goal-anchoring-audit.ts

FN-5758: add cited-goal audit aggregation and runtime route

2026-05-30 22:53:24 -07:00

goal-context-injector.ts

FN-5651: add single-seam goal-context injector for system prompts

2026-05-29 07:11:00 -07:00

goal-injection-diagnostics.ts

FN-5959: bridge task goal provenance from mission links

2026-06-03 15:32:29 -07:00

gridlock-detector.ts

…

group-merge-coordinator.ts

fix(FN-branch-group): repair CI failures — execFile mock compatibility, TaskCard narrowing, e2e memo race

2026-06-03 17:57:00 -07:00

heartbeat-procedure-resolver.ts

…

heartbeat-prompt-trim.ts

…

hold-release.ts

fix(FN-6082): restore workflow overlap blocking

2026-06-09 08:02:56 -07:00

hybrid-executor-gate.ts

perf(dashboard): speed up startup and eliminate API request storms

2026-05-26 21:57:31 -07:00

hybrid-executor.ts

feat(FN-4813): complete Step 5 — add isolation transition runtime restart path

2026-05-16 17:31:09 -07:00

index.ts

feat(FN-000): claim workflow work in scheduler substrate

2026-06-09 20:44:45 -07:00

integration-branch.ts

feat(FN-5349): add integration branch resolver with auto-recovery fallback

2026-05-21 12:04:58 -07:00

interactive-ai-session.ts

feat(engine): cli-agent one-shot sessions for validator, planning, and CE (U9)

2026-06-05 00:15:57 -07:00

logger.ts

feat(pr): node-agnostic PR reconcile + hold-release firing (U4)

2026-06-05 20:05:29 -07:00

merge-trait.ts

fix(core): shared workflow-IR resolver, prod branch persistence + pruning, latest-run JOIN, sweep reservation-leak fix (#1402 #1407 #1412 #1413)

2026-06-04 07:34:02 -07:00

merger-ai.ts

FN-6295: move AI merge clean rooms into worktrees

2026-06-12 12:49:34 -07:00

merger-audit-recovery.ts

…

merger-auto-prerebase.ts

fix(FN-5627): always rebase behind branches before squash (safety fallback)

2026-05-28 15:04:41 -07:00

merger-bare-subject.ts

fix(engine): harden merge finalize SQLite bind and recover bare merge subjects

2026-05-26 21:57:31 -07:00

merger-diff-volume-gate.ts

…

merger-integration-worktree.ts

FN-6278: preflight reusable merge worktree cwd

2026-06-11 20:27:29 -07:00

merger-orphan-rehome.ts

feat(merger): auto-rehome FF-recoverable orphan commits in contamination recovery

2026-05-23 09:59:50 -07:00

merger-overlap-guard.ts

…

merger-ref-update-advance.ts

fix(FN-5627): close merger TOCTOU + add fast-path reachability gate

2026-05-28 13:02:30 -07:00

merger-scope-auto-widen.ts

feat(FN-5226): add scope auto-widen layer 2.5 to merger for attribution-bas

2026-05-21 16:30:31 -07:00

merger-squash-audit.ts

…

merger.ts

FN-6241: rescue quarantined engine tests

2026-06-11 22:17:55 -07:00

mesh-lease-manager.ts

fix(FN-4826): complete Step 6 — stabilize audit emission and tests

2026-05-16 23:45:17 -07:00

mission-autopilot.ts

FN-5941: stop missions stalling on incompatible/custom-role agents

2026-06-03 17:14:42 -07:00

mission-execution-loop.ts

FN-6219: prefer fresh agent model settings for automatic runs

2026-06-11 09:21:23 -07:00

mission-feature-sync.ts

FN-5715: gate mission feature completion on assertion validation

2026-05-30 09:43:02 -07:00

node-dispatch-validation.ts

…

node-health-monitor.ts

…

node-routing-policy.ts

feat(FN-4813): complete Step 3 — add owning-node handoff policy

2026-05-16 17:31:09 -07:00

notifier.ts

FN-6093: fix ntfy workflow notification delivery

2026-06-09 12:50:26 -07:00

peer-exchange-service.ts

…

permanent-agent-gating.ts

…

pi.ts

FN-6218: restore pi upgrade compatibility

2026-06-11 09:51:49 -07:00

plugin-parser-adapter.ts

feat(engine): U12e+U14 — parse-steps node handler, plugin parser adapter, code node runner (esbuild + child-process harness)

2026-06-04 12:44:43 -07:00

plugin-runner.ts

fix(engine): address workflow extension PR feedback

2026-06-07 21:19:10 -07:00

plugin-trait-adapter.ts

fix(core): shared workflow-IR resolver, prod branch persistence + pruning, latest-run JOIN, sweep reservation-leak fix (#1402 #1407 #1412 #1413)

2026-06-04 07:34:02 -07:00

plugin-workflow-extension-adapter.ts

fix(engine): address workflow extension PR feedback

2026-06-07 21:19:10 -07:00

pr-comment-handler.ts

feat(FN-5232): add deterministic verification-followup deduplication to pre

2026-05-19 19:28:05 -07:00

pr-monitor-gh.ts

…

pr-monitor.ts

…

pr-nodes.ts

fix(lint): empty-interface PrSourceDescriptor → type alias, drop unused eslint-disable directives

2026-06-06 00:15:28 -07:00

pr-reconcile.ts

feat(pr): node-agnostic PR reconcile + hold-release firing (U4)

2026-06-05 20:05:29 -07:00

pr-response-run-ops.ts

fix(review): apply autofix feedback

2026-06-05 22:49:39 -07:00

pr-response-run.ts

feat(pr): security-hardened review-response run — pr-respond body (U5)

2026-06-05 20:20:25 -07:00

project-engine-manager.ts

feat(pr): node-agnostic PR reconcile + hold-release firing (U4)

2026-06-05 20:05:29 -07:00

project-engine.ts

fix(FN-6035): address workflow primitive review feedback

2026-06-08 21:16:32 -07:00

project-manager.ts

FN-5703: forward task:deleted events through in-process runtime

2026-05-29 20:05:14 -07:00

project-runtime.ts

merge: main (workflow editor 109 / cli_sessions 110-111 / workflow_settings 112) — renumber PR-entity migration to 113, union core exports, TaskCard prNode + cliSessionState badges, executor PrNodeDeps + CliAgentRuntime options

2026-06-05 23:06:46 -07:00

prompt-layers.ts

FN-6235: source reviewer prompts from workflow IR

2026-06-11 21:00:23 -07:00

pty-native.ts

feat(engine): extract shared PTY native-asset loader and redactSecrets (U16)

2026-06-04 22:53:02 -07:00

rate-limit-retry.ts

…

recovery-policy.ts

…

research-dispatcher.ts

…

research-orchestrator.ts

…

research-step-runner.ts

…

restart-recovery-coordinator.ts

perf(dashboard): cache gh CLI checks and defer SQLite integrity scan

2026-05-26 23:41:28 -07:00

retry-burned-logger.ts

…

retry-with-backoff.ts

fix: address PR review feedback (#1467)

2026-06-07 23:03:38 -07:00

reviewer.ts

FN-6235: source reviewer prompts from workflow IR

2026-06-11 21:00:23 -07:00

room-ambiguity.ts

feat(FN-4861): merge fusion/fn-4861

2026-05-17 02:08:01 -07:00

room-coordination.ts

feat(FN-5425): add coordination notice system for multi-agent room task fil

2026-05-21 00:17:33 -07:00

routine-runner.ts

…

routine-scheduler.ts

…

run-audit.ts

FN-6227: handle non-empty worktree removals

2026-06-11 16:15:07 -07:00

run-verification-tool.ts

fix(FN-6043): address stuck task PR feedback

2026-06-08 20:29:37 -07:00

runtime-primitives.ts

feat(FN-6035): route execution through workflow primitives

2026-06-08 19:13:14 -07:00

runtime-resolution.ts

FN-5638: migrate pi-ai and pi-coding-agent packages to @earendil-works scope

2026-05-28 21:23:48 -07:00

scheduler.ts

FN-6292: prevent dependency-blocking file leases

2026-06-12 10:49:02 -07:00

secrets-env-writer.ts

chore: minor cleanups — docs index, test-project fixture, empty catches, triage timestamp guard

2026-05-19 14:22:11 -07:00

self-healing.ts

FN-6295: move AI merge clean rooms into worktrees

2026-06-12 12:49:34 -07:00

session-skill-context.ts

…

session-token-usage.ts

FN-5638: migrate pi-ai and pi-coding-agent packages to @earendil-works scope

2026-05-28 21:23:48 -07:00

shell-utils.ts

…

skill-resolver.ts

FN-6140: downgrade missing skill diagnostics to info

2026-06-09 15:50:53 -07:00

smart-pull.ts

feat(engine): export smartPull() library for stash-aware fast-forward

2026-05-23 14:26:57 -07:00

spec-staleness.ts

fix(engine): preserve parked progress through stale-spec checks

2026-05-30 21:53:00 -07:00

stale-task-reporter.ts

…

step-integration.ts

fix(review): apply code-review fixes — runId/foreachNodeId wiring, worktree-leak cleanup, rework re-execution, instance pruning, SIGKILL fallback, type dedup, board memo split, agent-native field-schema context + fn_workflow_get

2026-06-04 14:01:55 -07:00

step-runner.ts

feat(engine,core): U5+U6+U12core — step-review verdict handler, graph-source projection discipline, pluggable step-parser registry

2026-06-04 12:26:05 -07:00

step-session-executor.ts

FN-6117: expose task attachments in workflow step prompts

2026-06-09 13:31:30 -07:00

streaming-delta.ts

FN-5803: normalize streamed sentence spacing across message boundaries

2026-05-31 23:24:53 -07:00

stuck-task-detector.ts

fix(FN-5994): prevent verification hangs

2026-06-08 09:44:00 -07:00

task-agent-sync.ts

…

task-completion.ts

…

token-budget-enforcer.ts

…

token-cap-detector.ts

FN-5638: migrate pi-ai and pi-coding-agent packages to @earendil-works scope

2026-05-28 21:23:48 -07:00

tool-availability.ts

FN-5638: migrate pi-ai and pi-coding-agent packages to @earendil-works scope

2026-05-28 21:23:48 -07:00

transient-error-detector.ts

FN-6158: handle Codex auth-tier model incompatibility

2026-06-09 21:16:42 -07:00

transient-merge-error-classifier.ts

FN-6246: move AI merge clean rooms into repo storage

2026-06-12 06:49:29 -07:00

triage-preflight.ts

fix(FN-4892): harden intake auto-archive fail-open behavior

2026-05-18 00:53:23 -07:00

triage.ts

FN-6236: move fast triage into workflow settings

2026-06-12 14:39:51 -07:00

unlinked-missions-advisory-reporter.ts

FN-6050: stop re-emitting existing mission advisories

2026-06-09 03:53:34 -07:00

usage-limit-detector.ts

…

verification-followup-dedup.ts

feat(FN-5232): add deterministic verification-followup deduplication to pre

2026-05-19 19:28:05 -07:00

verification-utils.ts

…

web-fetch.ts

…

workflow-authoritative-driver.ts

fix(FN-6035): model pre-merge workflow steps in builtin coding

2026-06-08 22:02:26 -07:00

workflow-graph-branches.ts

fix(core): shared workflow-IR resolver, prod branch persistence + pruning, latest-run JOIN, sweep reservation-leak fix (#1402 #1407 #1412 #1413)

2026-06-04 07:34:02 -07:00

workflow-graph-executor.ts

FN-6294: collapse workflow merge primitives

2026-06-12 14:21:18 -07:00

workflow-graph-foreach.ts

FN-6087: skip completed foreach steps on resume

2026-06-09 09:00:46 -07:00

workflow-graph-loop.ts

fix(FN-0000): address workflow loop review feedback

2026-06-08 00:19:50 -07:00

workflow-graph-task-runner.ts

FN-6031: add workflow notification nodes

2026-06-09 01:57:16 -07:00

workflow-node-handlers.ts

FN-6031: add workflow notification nodes

2026-06-09 01:57:16 -07:00

workflow-parity-observer.ts

FN-5768: add dual-observe workflow parity instrumentation

2026-05-31 08:32:01 -07:00

workflow-step-tool-policy.ts

FN-5638: migrate pi-ai and pi-coding-agent packages to @earendil-works scope

2026-05-28 21:23:48 -07:00

workflow-task-runtime.ts

fix(FN-6035): address workflow primitive review feedback

2026-06-08 21:16:32 -07:00

workflow-work-scheduler.ts

feat(FN-000): claim workflow work in scheduler substrate

2026-06-09 20:44:45 -07:00

worktree-acquisition.ts

FN-5818: fix shared-branch-group execution to use per-task working branches

2026-06-01 01:37:25 -07:00

worktree-backend.ts

FN-6227: handle non-empty worktree removals

2026-06-11 16:15:07 -07:00

worktree-db-hydrate.ts

feat(FN-5128): complete Step 2 — add soft-delete guard to hydration

2026-05-19 05:57:57 -07:00

worktree-desktop-artifacts.ts

feat(FN-4938): complete Step 2 — add helper and wire cleanup

2026-05-18 01:50:22 -07:00

worktree-hooks.ts

feat(FN-5519): merge fusion/fn-5519

2026-05-22 22:43:26 -07:00

worktree-names.ts

feat(engine): U10 — parallel step execution: dependency scheduler, per-instance worktrees, ordered integration, conflict→rework (KTD-11)

2026-06-04 13:04:15 -07:00

worktree-paths.ts

FN-6295: move AI merge clean rooms into worktrees

2026-06-12 12:49:34 -07:00

worktree-pool.ts

FN-6295: move AI merge clean rooms into worktrees

2026-06-12 12:49:34 -07:00

worktree-prune.ts

feat(FN-5058): merge fusion/fn-5058

2026-05-18 11:01:32 -07:00

worktree-ref-sync.ts

fix(engine,dashboard): close 7 review findings on merger auto-sync

2026-05-23 15:13:17 -07:00

worktree-stale-lock.ts

feat(FN-4830): complete Step 1 — add stale lock helper

2026-05-16 20:54:33 -07:00

worktree-stale-registration.ts

feat(FN-5063): merge fusion/fn-5063

2026-05-18 15:51:01 -07:00

worktrunk-failure-handler.ts

feat(FN-4626): complete Step 5 — align worktrunk failure payload shape

2026-05-15 22:18:09 -07:00

worktrunk-installer.ts

feat(FN-5321): add evidence gap detector for external integration manifests

2026-05-20 15:54:44 -07:00