bug(session): startup aborts with binding_invalid when a managed scope outgrows the receipt scan limit

[probepark]

Summary

gjc aborts at startup in a long-lived working directory:

[Uncaught Exception] Error: Could not prepare managed session scope (binding_invalid: prepare:binding_publish).
[Uncaught Exception] crash recorded at /Users/probe/.gjc/agent/gjc-crash.log

The message is wrong in a way that actively misleads. The binding is byte-for-byte canonical. What actually failed is a capacity budget, and binding_invalid sends an operator to delete a healthy binding file instead of pruning the directory.

Two separate defects here: the misreporting (1), and the unbounded growth that triggers it (2).

1. Misclassification

The real error is managed_replace_cleanup_receipt_limit_exceeded, thrown at packages/coding-agent/src/session/internal/managed-session-storage.ts:1249-1250 when #reconcileReplacementCleanupReceipts scans more entries than REPLACEMENT_CLEANUP_RECEIPT_SCAN_LIMIT (= MANAGED_ARTIFACT_MAX_FILES, 50,000).

managedScopeErrorCode only recognized content_too_large, so everything else fell through to binding_invalid (managed-session-scope.ts).

There is a second, subtler half. The operator-visible string comes from cause.classification, produced by managedScopeFailureCause, while code comes from managedScopeErrorCode — two different helpers. Fixing only the code path still printed binding_invalid, which is what made this take a while to pin down.

Confirmed by instrumenting the catch at managed-session-scope.ts:1168:

[P4] stage=binding_publish msg=managed_replace_cleanup_receipt_limit_exceeded ctor=Error

Note the existing doc comment on managedScopeErrorCode already warns about exactly this failure mode for content_too_large — the same trap, a different message.

2. Unbounded receipt/placeholder growth

The affected scope for ~/git/Yeachan-Heo/gajae-code:

total entries                        52,796
.gjc-exact-unlink-placeholder-*      26,386
.gjc-receipt-remove-*                13,193
actual session transcripts               ~2
46 MB

So >99.9% of the directory is cleanup bookkeeping that was never collected. remove_exchange_placeholder in crates/pi-natives/src/path_identity.rs:3096-3127 returns RetainedMismatch or RetainedFailure(_, "cleanup_pending") on the identity-match path and never returns Removed, so each cycle leaves another quarantined placeholder behind.

The 50,000 limit is not the bug — the growth is. Raising the limit would only delay this.

Reproduction (clean, from scratch)

mkdir /tmp/capcwd && cd /tmp/capcwd
gjc -p "hi"                       # succeeds, creates the scope
# fill the scope directory past the scan limit
cd ~/.gjc/agent/sessions/v2-<digest-for-that-cwd>
python3 -c "
for i in range(50100):
    open(f'.gjc-exact-unlink-placeholder-fill-{i:06d}','w').write('x')"
cd /tmp/capcwd && gjc -p "hi"     # crashes

Deterministic. Bisected by moving entries out of the real scope: at 26,499 entries still crashed, at 13,283 it started working.

Why this looks intermittent

It only reproduces through the compiled binary, not bun run dev, because the receipt reconciliation path differs. I burned time on that confound; worth knowing before anyone tries to repro from source.

Impact

gjc becomes unusable in the affected directory — every invocation aborts before the session starts. Recovery requires knowing to delete tens of thousands of dotfiles from an internal state directory, and the error text points at the wrong file.

Any long-lived working directory reaches this eventually. Mine took ~2 days of heavy use.

Fix

PR for (1) incoming: both classification helpers share one predicate, so a capacity failure reports capacity_exceeded with its real message instead of a false binding-corruption report. Verified end-to-end through a rebuilt binary — the crash line becomes:

Could not prepare managed session scope (capacity_exceeded: prepare:binding_publish).

(2) is left open deliberately: pruning during startup is the wrong place for an unbounded delete, and raising the limit hides the growth. The placeholder-retention path in path_identity.rs needs its own decision about when a quarantined placeholder becomes collectable.

Environment

• gjc/0.12.21, dev at 7858b0ff6
• darwin arm64 (the tree budgets in recovery_fs.rs are #[cfg(target_os = "linux")], so they are not what fires here — the TypeScript scan limit is)

[Yeachan-Heo]

Maintainer investigation and fix work has started. The accepted issue scope remains both parts of the failure: (1) shared, operator-visible capacity classification for the managed receipt scan limit and (2) a safe bounded collection contract for the native exact-unlink placeholders and removal receipts that are growing without bound.

PR #4185 is being reconciled as the existing owner lane. I will independently review its classification change and, where branch permissions and the safety contract allow, extend that same PR rather than opening a duplicate. The growth remediation is not being dropped merely because the current patch is classification-only; any design decision that cannot be landed safely will be recorded explicitly with exact blocker evidence.

Ownership lane: #4185

---

Signed-off-by: Yeachan Heo bellman@gajae-code.dev

[probepark]

Status: half fixed, half blocked by owner direction

Recording the split so the growth half is not silently dropped.

Part 1 — misclassification: fixed in #4185. managedScopeErrorCode and managedScopeFailureCause now agree, so the operator-visible string stops printing binding_invalid for what is really managed_replace_cleanup_receipt_limit_exceeded. Security classification still wins over the capacity predicate, no recovery path is disabled, and genuinely unrecognized failures still classify as binding_invalid.

Part 2 — unbounded growth: blocked, deliberately, on owner direction. #4185 is scoped to classification only.

The reason is a real safety boundary, not deferral:

• POSIX has no descriptor-bound unlink.
• fstatat(..., AT_SYMLINK_NOFOLLOW) for identity followed by unlinkat leaves a pathname race — a same-UID concurrent writer can replace .gjc-exact-unlink-placeholder-<dev>-<ino> between validation and unlink, so cleanup deletes the replacement.
• renameat2 exchange/noreplace on Linux and renameatx_np swap/excl on macOS can isolate names, but the final deletion is still pathname-based and recreates the same race.

So a generic native cleanup cannot ship safely, and the current fail-closed retained/cleanup_pending behavior is the safe generic contract. Raising REPLACEMENT_CLEANUP_RECEIPT_SCAN_LIMIT only delays the crash, and startup is the wrong place for an unbounded delete.

Scale, for whoever picks this up: the affected scope held 52,796 entries — 26,386 orphaned placeholders and 13,193 cleanup receipts against ~2 real transcripts.

What unblocks this

One of these has to be decided before the growth half can be completed in a coherent PR:

1. Declare a cooperative scope-global lease/fence covering every placeholder/receipt producer, then permit fixed-budget, lease-aged, no-follow, identity/evidence-bound collection only inside that fenced owner-only scope. Ambiguous or noncooperative entries still fail capacity.
2. Introduce a distinct private/privileged namespace coordinator providing stronger deletion authority.

Separately, remove_exchange_placeholder (crates/pi-natives/src/path_identity.rs:3096-3127) never returns Removed on the identity-match path. That needs its own decision and is a prerequisite either way.

No unsafe unlink or GC experiment has been committed or pushed.

[Yeachan-Heo]

Partial-fix merge evidence — classification slice landed

Merged PR: #4185
Reviewed/fixed-forward head: 827719d511410d259573ef18a80834c9cd81a399
Merge commit into dev: 9ef8cffcc0893b5e8199211545d8a16a3a344842
Merged at: 2026-08-11T05:59:23Z

The merged correction makes the receipt-scan capacity sentinel report capacity_exceeded consistently in both result.code and the operator-visible cause.classification. Security classifications retain precedence, and unknown failures remain binding_invalid. The unsafe reaping drift introduced during rebase was removed before final review and merge; the final PR delta was confined to the classifier and its regression test.

Still open: bounded-growth remediation

This issue remains open. The underlying receipt-growth/remediation half is not solved by #4185 and is deliberately held under the recorded owner direction: retain fail-closed capacity behavior while a bounded cleanup design is produced.

Bounded owner/design hold: no unlink, GC, pruning, or receipt-remediation implementation may proceed until a design explicitly defines authority, race resistance, descriptor/path guarantees, failure behavior, bounded work, and dedicated adversarial validation. The owner/design decision must be recorded before implementation; this is not a closure or a claim that growth is fixed.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[Yeachan-Heo]

Both halves are now on dev; closing.

Part 1 — misclassification: #4185 (merged as 9ef8cff) makes managedScopeErrorCode and managedScopeFailureCause share the capacity predicate, so an over-budget receipt scan reports capacity_exceeded: prepare:binding_publish instead of the false binding_invalid corruption report. #4214 (merged as d6c36b4) completed the landing: it aligned the newer #3596-lane quarantine-rejection test with the corrected taxonomy (classification now mirrors the recognized code; display-only, nothing branches on binding_invalid) and reverted 827719d's accidental removal of dev's own remnant-reaper calls, which had re-broken the growth fix and left dev CI red.

Part 2 — unbounded growth: 7d6cc21 (#4205) reaps zero-length single-link remnant-prefixed files older than 15 minutes at scope preparation, removing the placeholder/receipt accumulation (observed 52k+ entries) that drives the scan past REPLACEMENT_CLEANUP_RECEIPT_SCAN_LIMIT in the first place. Non-zero entries stay as evidence and in-flight protocol steps remain untouchable.

Verified on the merged tree: managed-scope-capacity-classification.test.ts fails pre-fix / passes post-fix; session-manager/session-directory.test.ts 65/65 (was 63/2 immediately after the #4185 merge).