From f94ff68391df9f6bfdeea70a084e6c84c8a4d735 Mon Sep 17 00:00:00 2001
From: gsxdsm <gsxdsm@users.noreply.github.com>
Date: Fri, 31 Jul 2026 11:05:17 -0700
Subject: [PATCH] docs(engine): record that agentParkedColumns is inert at this
 call site (passed-but-unread) (#3212)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes the last entry I could not pin on the #3115 coverage map — by
establishing **why** it cannot be pinned, rather than leaving it open or
forcing a green test around it.

## `agentParkedColumns` is inert at this call site

It influences exactly one output — `shouldPreserveParkedLink` — and
`recoverAgentsRunningOnInactiveTasks` **never reads it**. The gate is:

```ts
if (proof.hasFreshRun || proof.hasActiveExecution) continue;
```

Neither depends on the lane. So passing a resolved set changes nothing
today, and blinding it back to the legacy ids leaves every test green
**because there is no behaviour to observe**. That is not a coverage gap
— there is nothing there to cover.

## Kept, not deleted

- Removing it makes this call site read as **unwired** to the
lane-wiring ratchet, inviting the next worker to "fix" it by re-adding
exactly this.
- If the gate ever adopts `shouldPreserveParkedLink` — the
parked-specific semantics the sibling sweep uses
(`recoverDriftedAgentTaskLinks`, wired in #3208 an hour ago) — the
resolved set is already correct here.

## The shape worth naming

**Passed-but-unread** is the mirror of the **resolved-gate,
literal-branch** defect #3208 fixed. Both read as converted while
deciding nothing — and only one of them is a bug.

A ratchet that counts call sites cannot tell them apart: #3208's site
looked *unwired* and was a live defect; this one looks *wired* and is
dead code. That is why the distinction belongs in a comment at the site
rather than in a baseline number.

## Map status

**21 of 26 pinned**, 1 established as unpinnable-by-construction, 4
remaining with obstacles recorded:
- `reclaimHoldColumns` / `reclaimReviewColumns` — both audit paths emit
the same `branch:auto-reclaim` type, differing only by a `trigger`
string the branch-level scan also produces.
- `completedHoldColumns`, `wsDoneColumns`, `doneMetaColumns` and others
have since gone green from other workers' PRs.

## Verification

`pnpm test:gate` 13 + 161 + 499 + 71 · lint · census `--strict` ·
fnxc-dates (TZ=UTC) — green. Comment-only change.


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

## Summary by CodeRabbit

* **Documentation**
* Added an explanatory note clarifying parked-column handling and its
connection to future parked-link preservation behavior.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 packages/engine/src/self-healing.ts | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/packages/engine/src/self-healing.ts b/packages/engine/src/self-healing.ts
index 46d3ab7b9f..a36bdd8bf9 100644
--- a/packages/engine/src/self-healing.ts
+++ b/packages/engine/src/self-healing.ts
@@ -13179,6 +13179,22 @@ const movedTask = await this.store.moveTask(task.id, completeLane);
         live agent linked to a card resting in a RENAMED hold lane read as not-parked — the safeguard
         that preserves its task link never applied, and the link was dropped.
         */
+        /*
+        FNXC:WorkflowResolvedColumns 2026-07-31-18:05 (INERT HERE, and deliberately kept):
+        `parkedColumns` influences exactly one output — `shouldPreserveParkedLink` — and THIS sweep
+        never reads it. The gate below is `hasFreshRun || hasActiveExecution`, neither of which depends
+        on the lane, so passing a resolved set changes nothing today. Blinding it back to the legacy
+        ids leaves every test green because there is no behaviour to observe.
+
+        Kept rather than deleted for two reasons. Removing it would make this call site read as
+        UNWIRED to the lane-wiring ratchet, inviting the next worker to "fix" it by re-adding exactly
+        this; and if the gate ever adopts `shouldPreserveParkedLink` — which is the parked-specific
+        semantics the sibling sweep uses (see `recoverDriftedAgentTaskLinks`, wired in #3208) — the
+        resolved set is already correct here.
+
+        Recorded because "passed but unread" is the mirror of "resolved gate, literal branch" that
+        #3208 fixed: both read as converted while deciding nothing.
+        */
         parkedColumns: [...agentParkedColumns],
         activeRun,
         hasActiveAgentExecution: this.options.hasActiveAgentExecution,