refactor: package code organization (god-file peels, wave 1)

[gsxdsm]

Summary

First wave of package-internal code organization: split oversized modules into domain-named files/folders while preserving public import paths via re-exports, and refresh the line-count ratchet scoreboard.

• Plan: docs/plans/2026-07-14-001-refactor-package-code-organization-plan.md (multi-wave program; this PR lands U1–U4 + first U3/U6 slices)
• Core types: peel types.ts into types/{board,merge-queue,execution-and-ui,merge-policy,workflow-steps}.ts with browser-safe Vite alias preserved
• Core TaskStore: rename remaining-ops-9 → task-commit-associations (domain-named, not ordinal dump)
• Engine executor: peel pure helpers into executor/{browser-probe,requeue-loop,pseudo-pause,workflow-step-failures}.ts
• Engine heartbeat: peel system prompts/procedures into agent-heartbeat-prompts.ts
• Ratchet: one-time baseline truth-up + ratchet-down for touched files

Deferred to follow-up PRs (plan U5, U7–U9 + remaining waves)

• Self-healing folder split
• Further remaining-ops domain peels
• Dashboard legacy.ts / routes / UI monofiles
• CLI extension + TUI peels

Test plan

• pnpm --filter @fusion/core exec tsc --noEmit
• pnpm --filter @fusion/engine exec tsc --noEmit
• Focused vitest: detect-pseudo-pause, executor-browser-verification, clear-terminal-workflow-step-failures
• node scripts/check-file-line-count.mjs clean against updated baseline
• CI merge gate (lint/typecheck/build/gate)
• Browser smoke: N/A for this PR (no dashboard UI route changes)

Residual Review Findings

None. Review autofix applied dual-home wiring for clearTerminalWorkflowStepFailures only.

Summary by CodeRabbit

• New Features
  • Added configurable heartbeat procedures for task and no-task scenarios (including patrol-aware rendering).
  • Improved agent-browser availability verification with clearer availability/status reporting.
  • Added detection for pseudo-pauses and review-handoff requests.
  • Expanded core configuration/contract options for execution/UI/localization, merges, merge queues, and workflow steps.
• Bug Fixes
  • Improved handling of transient execute-requeue and workflow-step retry/cleanup behavior, including better Windows path support.
  • Preserved existing public interfaces during internal restructuring.
• Documentation
  • Added a multi-phase roadmap for future package reorganization.

[coderabbitai]

Warning

Review limit reached

@gsxdsm, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e6c670e2-16db-4767-819a-be11dfa3fa8e

📥 Commits

Reviewing files that changed from the base of the PR and between a911eb1 and bb9306c.

📒 Files selected for processing (5)

• .changeset/friendly-shims-fix.md
• packages/cli/src/__tests__/plugin-sdk-export.test.ts
• packages/cli/src/plugin-sdk-core-runtime-shim.mjs
• packages/cli/src/plugin-sdk-core-runtime-shim.ts
• packages/cli/tsup.config.ts

📝 Walkthrough

Walkthrough

This change documents a multi-wave package refactor, splits core type contracts into domain modules, extracts heartbeat prompts and executor helpers, updates TaskStore imports, adds executor edge-case tests, and refreshes line-count baselines while retaining compatibility re-exports.

Changes

Package organization refactor

Layer / File(s)	Summary
Refactor plan and guardrails docs/plans/*	Documents behavior-preserving refactor waves, export stability requirements, verification rules, ratchets, and implementation units.
Core type domain extraction packages/core/src/types.ts, packages/core/src/types/*	Moves board, merge queue, execution/UI, merge policy, workflow-step, and notification contracts into dedicated modules while preserving facade re-exports.
Task-store domain import migration packages/core/src/store.ts, packages/core/src/task-store/task-commit-associations.ts	Points TaskStore association helpers to the named task-commit-associations module and updates its organization note.
Heartbeat prompt extraction packages/engine/src/agent-heartbeat*	Moves heartbeat prompts and procedure variants into a dedicated module while preserving heartbeat exports and patrol-disabled rendering.
Executor helper extraction and validation packages/engine/src/executor*, packages/engine/src/__tests__/*	Extracts browser probing, requeue handling, pseudo-pause detection, and workflow failure clearing behind executor re-exports, with additional Windows-path and sibling-worktree tests.
Line-count baseline updates scripts/line-count-baseline.json	Refreshes tracked paths and baseline values for reorganized source and test files.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• Runfusion/Fusion#1698: Updates line-count baseline ceilings and guardrail enforcement connected to this baseline change.
• Runfusion/Fusion#2081: Refactors heartbeat prompt composition in the same subsystem.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.47% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the refactor-focused package code organization changes and the first-wave scope.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/code-organization

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR reorganizes large core and engine modules while keeping their public entry points stable. The main changes are:

• Splits core types into domain-focused modules with re-exports from types.ts.
• Renames the TaskStore commit-association module.
• Extracts executor helpers and heartbeat prompts into focused modules.
• Adds a source-bundled CLI runtime shim for PostgreSQL schemas.
• Refreshes the file-size baseline and adds the multi-wave organization plan.

Confidence Score: 5/5

This looks safe to merge.

• The latest fixes preserve the existing parent-module exports and runtime call sites.
• The workflow-step cleanup helper has one correctly wired implementation.
• No blocking issue tied to the earlier review was found in the updated code.

Important Files Changed

Filename	Overview
packages/cli/src/plugin-sdk-core-runtime-shim.mjs	Adds a runtime-only shim that bundles the core PostgreSQL schema from source.
packages/cli/tsup.config.ts	Points plugin SDK and bundled-plugin builds at the new runtime shim.
packages/core/src/types.ts	Preserves the existing type entry point while re-exporting domain modules.
packages/engine/src/executor.ts	Moves pure executor helpers into focused modules and retains parent-module exports.
packages/engine/src/executor/workflow-step-failures.ts	Provides the extracted workflow-step failure cleanup helper.
packages/engine/src/agent-heartbeat.ts	Moves heartbeat prompts and procedures into a dedicated module.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  CoreTypes[core/types.ts] --> TypeModules[core/types modules]
  Store[core/store.ts] --> Associations[task commit associations]
  Executor[engine/executor.ts] --> ExecutorHelpers[executor helpers]
  Heartbeat[engine/agent-heartbeat.ts] --> Prompts[heartbeat prompts]
  PluginBuild[CLI plugin build] --> Shim[runtime core shim]
  Shim --> Schema[core PostgreSQL schema source]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart LR
  CoreTypes[core/types.ts] --> TypeModules[core/types modules]
  Store[core/store.ts] --> Associations[task commit associations]
  Executor[engine/executor.ts] --> ExecutorHelpers[executor helpers]
  Heartbeat[engine/agent-heartbeat.ts] --> Prompts[heartbeat prompts]
  PluginBuild[CLI plugin build] --> Shim[runtime core shim]
  Shim --> Schema[core PostgreSQL schema source]

Loading

_{Reviews (4): Last reviewed commit: "fix(ci): bundle plugin schema shim from ..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

docs/plans/2026-07-14-001-refactor-package-code-organization-plan.md (1)

43-44: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Specify the required FNXC comment format.

As per coding guidelines, FNXC comments must begin with FNXC:Area-of-product and include the change date in yyyy-MM-dd-hh:mm format. It would be helpful to explicitly mention this format here to ensure implementers adhere to it during extraction.

📝 Proposed update

-- R4. FNXC requirement comments move with the owning behavior (dated, greppable). Facades must not keep the only copy of requirement text after extraction.
+- R4. FNXC requirement comments move with the owning behavior (must begin with `FNXC:Area-of-product` and include the date in `yyyy-MM-dd-hh:mm` format). Facades must not keep the only copy of requirement text after extraction.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/plans/2026-07-14-001-refactor-package-code-organization-plan.md` around
lines 43 - 44, Update the R4 requirement in the refactor plan to specify that
moved FNXC comments must begin with “FNXC:Area-of-product” and include the
change date in yyyy-MM-dd-hh:mm format, while retaining the requirement that
comments move with their owning behavior and facades do not retain the only
copy.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/engine/src/agent-heartbeat.ts`:
- Around line 457-470: Remove the unused constants from the import block in
agent-heartbeat.ts, including HEARTBEAT_CRITICAL_RULES,
HEARTBEAT_SYSTEM_PROMPT_NO_TASK, and HEARTBEAT_PROCEDURE, while retaining only
imports referenced locally in the file.

In `@packages/engine/src/executor.ts`:
- Around line 287-293: Remove the unused local imports
AGENT_BROWSER_NAVIGATION_SKILL_ID, probeAgentBrowserAvailability, and
formatAgentBrowserAvailabilityLog from the executor.ts import block, while
preserving the public re-exports and the still-used
augmentSessionSkillsForBrowserStep import.

In `@packages/engine/src/executor/requeue-loop.ts`:
- Around line 69-94: Update isTransientMissingTaskJsonError and
TRANSIENT_WORKTREE_TASK_JSON_ENOENT_PATTERN to support both POSIX and Windows
path separators when matching task.json ENOENT messages. Replace the hard-coded
`${normalizedWorktree}/` prefix check with separator-agnostic path containment,
preferably using path.relative(), while preserving task ID and worktree
validation.

---

Nitpick comments:
In `@docs/plans/2026-07-14-001-refactor-package-code-organization-plan.md`:
- Around line 43-44: Update the R4 requirement in the refactor plan to specify
that moved FNXC comments must begin with “FNXC:Area-of-product” and include the
change date in yyyy-MM-dd-hh:mm format, while retaining the requirement that
comments move with their owning behavior and facades do not retain the only
copy.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fb30d568-dbbb-4778-8a1c-f76da165fe44

📥 Commits

Reviewing files that changed from the base of the PR and between 49a459a and f6e95a4.

📒 Files selected for processing (17)

• docs/plans/2026-07-14-001-refactor-package-code-organization-plan.md
• packages/core/src/store.ts
• packages/core/src/task-store/task-commit-associations.ts
• packages/core/src/types.ts
• packages/core/src/types/board.ts
• packages/core/src/types/execution-and-ui.ts
• packages/core/src/types/merge-policy.ts
• packages/core/src/types/merge-queue.ts
• packages/core/src/types/workflow-steps.ts
• packages/engine/src/agent-heartbeat-prompts.ts
• packages/engine/src/agent-heartbeat.ts
• packages/engine/src/executor.ts
• packages/engine/src/executor/browser-probe.ts
• packages/engine/src/executor/pseudo-pause.ts
• packages/engine/src/executor/requeue-loop.ts
• packages/engine/src/executor/workflow-step-failures.ts
• scripts/line-count-baseline.json

[coderabbitai]

🧹 Nitpick comments (1)

packages/engine/src/executor/requeue-loop.ts (1)

18-26: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Prevent implicit TypeError during JSON parsing.

If signature is the string "null", JSON.parse returns null. Accessing .terminalStepCount on null throws a TypeError, which is then implicitly caught by the block to return null. While functionally correct, explicitly checking for null or non-object types is safer and avoids relying on exceptions for normal control flow.

♻️ Proposed refactor

 function parseExecuteRequeueLoopProgressSignature(signature: string | null | undefined): { terminalStepCount: number; totalSteps: number } | null {
   if (!signature) return null;
   try {
-    const parsed = JSON.parse(signature) as { terminalStepCount?: unknown; totalSteps?: unknown };
+    const parsed = JSON.parse(signature) as Record<string, unknown> | null;
+    if (!parsed || typeof parsed !== "object") return null;
     if (typeof parsed.terminalStepCount !== "number" || typeof parsed.totalSteps !== "number") return null;
     return {
       terminalStepCount: parsed.terminalStepCount,

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/engine/src/executor/requeue-loop.ts` around lines 18 - 26, Update
parseExecuteRequeueLoopProgressSignature to validate that the JSON.parse result
is a non-null object before accessing terminalStepCount or totalSteps; return
null for primitive, array, or null results, while preserving the existing
numeric-field validation and parsed progress return.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/engine/src/executor/requeue-loop.ts`:
- Around line 18-26: Update parseExecuteRequeueLoopProgressSignature to validate
that the JSON.parse result is a non-null object before accessing
terminalStepCount or totalSteps; return null for primitive, array, or null
results, while preserving the existing numeric-field validation and parsed
progress return.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: eb9ff444-35c0-48f5-9e5f-843fc51c4205

📥 Commits

Reviewing files that changed from the base of the PR and between c1eb39c and a911eb1.

📒 Files selected for processing (18)

• docs/plans/2026-07-14-001-refactor-package-code-organization-plan.md
• packages/core/src/store.ts
• packages/core/src/task-store/task-commit-associations.ts
• packages/core/src/types.ts
• packages/core/src/types/board.ts
• packages/core/src/types/execution-and-ui.ts
• packages/core/src/types/merge-policy.ts
• packages/core/src/types/merge-queue.ts
• packages/core/src/types/workflow-steps.ts
• packages/engine/src/__tests__/executor-missing-task-json-transient.test.ts
• packages/engine/src/agent-heartbeat-prompts.ts
• packages/engine/src/agent-heartbeat.ts
• packages/engine/src/executor.ts
• packages/engine/src/executor/browser-probe.ts
• packages/engine/src/executor/pseudo-pause.ts
• packages/engine/src/executor/requeue-loop.ts
• packages/engine/src/executor/workflow-step-failures.ts
• scripts/line-count-baseline.json

🚧 Files skipped from review as they are similar to previous changes (12)

• packages/core/src/store.ts
• packages/core/src/types/board.ts
• packages/core/src/task-store/task-commit-associations.ts
• scripts/line-count-baseline.json
• packages/core/src/types/execution-and-ui.ts
• packages/core/src/types/merge-queue.ts
• packages/engine/src/executor/workflow-step-failures.ts
• packages/engine/src/executor.ts
• packages/core/src/types.ts
• packages/core/src/types/merge-policy.ts
• packages/engine/src/agent-heartbeat.ts
• packages/core/src/types/workflow-steps.ts