Resident-string blob backing (#1726/#1729): spill pins memory, BigInt path crashes, idle tokens reach session.messages, blob dir growth and cross-process id collisions

[code-yeongyu]

Summary

PR #1726 adds a recoverable on-disk backing for the resident string store and releases materialized views at agent_idle; PR #1729 (stacked) spills resident strings to that backing across compaction. Reading both diffs end to end surfaced six defects/risks that must be fixed before the pair can merge. This issue tracks completing the design to its ideal state and landing both PRs.

Actual (at #1726 head 8359873f, #1729 head 32618a6c)

• A. spillResident() never releases memory. session-resident-store.ts:66-77 deletes from strings but not from the idsByText reverse index; the Map keys are the spilled strings themselves, so every spilled string stays pinned. changes.md:5973 claims the index is "deleted on eviction/spill/clear" — false for spill. feat(coding-agent): spill resident strings to the blob backing across compaction #1729's stated goal (empty the map, keep the backing) is therefore not achieved.
• B. BigInt path now crashes with the wrong error. The explicit TypeError("Do not know how to serialize a BigInt") was removed from transformJsonValue, but a bigint then reaches seen.add(value) on a WeakSet → TypeError: WeakSet values must be objects (verified with Bun 1.4). The PR body's "serializes BigInt values instead of throwing" is not what the code does.
• C. Runtime tokens escape to consumers. Between agent_idle and the next turn, agent.state.messages holds \0senpi-resident-string:v1:<id> tokens (agent-session.ts:1998-2002). The public getter get messages() (agent-session.ts:3445) returns that array unchanged, so any idle-time reader (TUI message selector, interactive-mode.ts:9400 JSON export, extensions, RPC) sees tokens. test/suite/harness.ts had to be changed to materialize through the store — proof that the consumer contract changed despite the PR body's "every existing consumer contract unchanged". This is the same failure class as _getCompactEntries() leaks evicted resident-string refs into resumed image data #1631, introduced into runtime state.
• D. Blob directory growth is unbounded. Ids are a per-process counter; a string hydrated from a blob and re-externalized at the next idle gets a NEW id → a NEW .blob file, and old files are never deleted. The dir is only removed on newSession/branch inside the same process — never on process exit or on reopening the session. feat(coding-agent): spill resident strings to the blob backing across compaction #1729's "bounded by the resident budget" does not hold.
• E. Cross-process id collision. Two processes on one session id share <sessionDir>/resident-blobs/<sessionId>/; both start ids at 0, so N.blob is overwritten with a different text and the other process hydrates the wrong content silently (the envelope is valid JSON).
• F. Per-turn full re-materialization. Caches are dropped on EVERY idle regardless of budget, so any settled-time getEntries() consumer re-materializes the full history each turn — the cost bug(coding-agent): post-compaction entry counting re-materializes the full JSONL history on the settled path #1699 (57a7b5441f) just removed — even though releasing the views frees nothing unless the store has evicted something (resident strings are shared objects).

Expected (ideal state)

• Blob files are content-addressed (id = hash of the text): re-externalizing hydrated text maps to the same blob, no per-turn churn, and two processes writing the same session dir can only ever write identical bytes under a given name. The reverse index becomes unnecessary, which fixes A structurally; spillResident() empties the map and releases the strings.
• BigInt keeps JSON semantics: externalize/materialize throw TypeError matching /BigInt/.
• session.messages and every out-of-turn reader of runtime messages (compaction admission estimates, log-token estimates) always observe real strings; test/suite/harness.ts returns to its pre-PR form.
• The idle release (view drop + in-place tokenization) runs only when the store has evicted something.
• The blob directory is released when the session's writer is disposed and cleared when a persisted session is reopened; newSession/branch removal stays.
• Corrupt blobs are deleted on read so a later eviction rewrites them.

Acceptance criteria

• test/session-resident-store.test.ts: (a) re-externalizing a spilled string makes it resident again and yields the pre-spill token; (b) two stores over one blobsDir with different texts each hydrate their own text; (c) evict→hydrate→re-externalize adds no .blob file; (d) a corrupt blob is removed on read; (e) externalize({ n: 1n }) throws TypeError matching /BigInt/.
• Harness tests: after agent_idle on a persisted over-budget session, session.messages text equals the original; an under-budget session keeps getEntries() identity across idle, an over-budget one does not.
• SessionManager tests: blob dir removed on writer disposal; stale dir cleared on open(); existing newSession/branch removal tests stay green.
• Focused suites + root bun run check green; PR CI green at the final head; changes.md and CHANGELOG.md entries updated.

Related

• feat(coding-agent): recoverable resident-string backing and idle materialized-view release #1726, feat(coding-agent): spill resident strings to the blob backing across compaction #1729 (the PRs; maintainer edits enabled — fixes land on those branches)
• _getCompactEntries() leaks evicted resident-string refs into resumed image data #1631 (resident tokens leaking into image data — same failure class as C)
• /compact grows to ~28 GB on a 16 GB machine and wedges the process (SIGTERM ineffective) #1461 (/compact memory growth), bug(coding-agent): post-compaction entry counting re-materializes the full JSONL history on the settled path #1699 (settled-path re-materialization), Resuming image-heavy sessions stalls the TUI; evicted strings cause repeated full-history reads #1407 / perf(coding-agent): batch evicted resume hydration #1595 (batched evicted recovery)

[code-yeongyu]

Milestone: root causes confirmed, plan settled.

Verified against the PR heads (8359873f, 32618a6c) merged with main@a7dee82bb1 (clean merge, no conflicts):

• A: spillResident() (session-resident-store.ts:66-77) leaves the idsByText Map keys in place — the spilled strings stay reachable.
• B: bun -e 'new WeakSet().add(1n)' → TypeError: WeakSet values must be objects — the path a bigint now takes in transformJsonValue.
• C: get messages() (agent-session.ts:3445) returns the tokenized runtime array between agent_idle and the next turn; the harness change in the PR is the symptom.
• D/E: ids are a per-instance counter; evict → hydrate → re-externalize allocates a new id and writes a new blob; two instances on one dir overwrite each other's N.blob.
• F: the idle release runs unconditionally, so settled-time getEntries() consumers re-materialize the full history each turn even when nothing was ever evicted.

Also found while syncing with main: the PR's four CHANGELOG.md lines merge into the already-released [2026.9.16] section (lines 32-35 after the sync merge) instead of [Unreleased]; will be moved.

Plan: content-addressed blob ids (SHA-256 of the text, reverse index removed), restored BigInt TypeError, a latched _runtimeMessages() accessor behind session.messages and the out-of-turn token estimators, idle release gated on evictedCount > 0, blob dir removed on writer teardown and cleared on reopen, corrupt blobs deleted on read. Each lands as test(session): RED contracts … + fix(session): … commits on the #1726 branch (maintainer edits are enabled); #1729's commit is included so the stack merges as one.

[code-yeongyu]

Milestone: RED captured, GREEN captured, real-surface QA passed. Branch head 7aa61ee75c, pushed to #1726.

Commits (each a RED test commit followed by its fix):

• 9c73d0dfdd test(session): RED contracts for content-addressed resident blobs
• 2b2544399e fix(session): content-address resident blobs and restore BigInt JSON error
• a1b6ec4307 test(session): RED contracts for token-free runtime messages and blob-dir lifecycle
• 4f7897fcef fix(session): keep runtime messages readable and bound the resident blob directory
• 7aa61ee75c docs(coding-agent): record the resident store completion and move its changelog lines to Unreleased

RED excerpts at the pre-fix head:

re-externalizing a spilled string makes it resident again with the same token
AssertionError: expected +0 to be 1            # stale idsByText entry survived spillResident()

stores sharing one backing directory never hydrate each other's text
AssertionError: expected 'bbbb…' to be 'aaaa…' # both stores minted id 0; storeB overwrote 0.blob

session.messages holds real text after agent_idle
AssertionError: expected [ '\u0000senpi-resident-string:v1:70' ] to include 'uuuu…'

idle keeps the materialized views when nothing was evicted
AssertionError: expected "dropMaterializedCaches" to not be called at all, but actually been called 1 times

removes the blob directory when the session manager is disposed
TypeError: session.dispose is not a function

GREEN (my own runs, not the workers'):

test/session-resident-store.test.ts + session-mirror-budget + materialize-cache   Test Files 3 passed  Tests 35 passed
resident-idle-release + session-mirror-budget + materialize-cache
  + stream-start-stall-user-surface + agent-session-apply-compaction              Test Files 5 passed  Tests 30 passed

Real-surface probe against the BUILT dist SessionManager (persisted session, 70 x 1 MiB entries) — 10/10 assertions, against 7/10 on 32618a6c:

PASS blob names are content hashes (64 hex) - 3ac870f4…cc15.blob, 07f31958…6863.blob
PASS re-reads add no blob files - 7 -> 7
PASS reopen clears stale blobs and rewrites only this session's hash-named blobs - foreign removed=true after=7
PASS dispose removes the blob directory
PASS newSession removes the previous blob directory
PASS getEntries hydrates all 70 payloads intact - count=70

The three that failed before the fix: blob names are content hashes (they were 0.blob, 1.blob), reopen clears the stale blob directory, dispose removes the blob directory (SessionManager.dispose did not exist).

test/suite/harness.ts is byte-identical to main again (git diff origin/main -- test/suite/harness.ts is empty), so the consumer contract the PR had worked around is restored rather than papered over. Full-suite coverage runs on the PR's CI.

[code-yeongyu]

Milestone: one more defect found in review, fixed; full local gate green at d4b1802030.

Reviewing the integrated branch I found a sharp edge the original PRs and my first pass both had: the blob directory is keyed by session id, but any single manager's teardown removed it. modes/app-server/threads/registry.ts:299 disposes a duplicate AgentSession when a thread is already loaded, and the stale clear in _setSessionFile had the same shape — either one took the cache a still-live manager was hydrating from. Correctness never broke (the JSONL stays authoritative), but the live session silently fell back to a full history reload per evicted string, which is the cost this whole change exists to remove.

RED:

keeps the blob directory while another live manager still owns the session file
AssertionError: expected false to be true
 ❯ test/session-manager/session-mirror-budget.test.ts:222:32
    220|   sibling.dispose();
    222|   expect(existsSync(blobsDir)).toBe(true);

Fix (0bd3ee0cb2 RED, d4b1802030 GREEN): session-write-reservation.ts gained hasOtherLiveSessionWriter(path, self) — the writer registry already tracks live persisted owners — and both blob releases go through _releaseBlobsDirUnlessShared(). The last owner to let go is the one that clears. The reopen test was rewritten to model an actually-dead writer (dispose, then plant leftovers) instead of keeping a live sibling around, which is what the old version accidentally asserted.

Full local gate at d4b1802030:

bun run --cwd packages/coding-agent build        exit 0
bun run check                                    exit 0
focused suites (7 files)                         Test Files 7 passed   Tests 51 passed
real-surface probe vs built dist                 SUMMARY 13/13 passed
git status --porcelain                           0 lines

The probe now pins the ownership contract end to end: a live sibling's open and its disposal both keep the owner's cache; the last owner's disposal removes the directory; a reopen with no live writer clears a dead process's leftovers; and all 70 payloads stay intact at every step.

[code-yeongyu]

Merged. 62aa59e4f4cbfca5f15e1c6015dce2306946b8e7 on main (PR #1726, carrying #1729's commit as an ancestor — both show merged).

What shipped, against the six defects this issue tracked:

	Fix on main
A	spillResident() releases every spilled string — the idsByText reverse index is gone, because the blob id is now the content hash
B	transformJsonValue throws TypeError("Do not know how to serialize a BigInt") again instead of letting a bigint reach the WeakSet guard
C	get messages(), prepareNextTurnWithContext and the five out-of-turn token estimators read through a latched _runtimeMessages(); test/suite/harness.ts is byte-identical to main again
D	Blob ids are sha256(text), _writeBlob skips an existing file, and the directory is released on dispose, session switch, branch, and reopen
E	A shared backing directory can only ever hold identical bytes under a given name
F	The idle release runs only when evictedCount > 0

Plus two found while completing it: a corrupt blob is deleted on read so the next eviction repairs it, and the blob directory now survives a sibling manager's teardown — the app-server disposes a duplicate AgentSession for an already-loaded thread (modes/app-server/threads/registry.ts:299), which used to take the live manager's cache.

Commits (each a RED test commit then its fix):

9c73d0dfdd test(session): RED contracts for content-addressed resident blobs
2b2544399e fix(session): content-address resident blobs and restore BigInt JSON error
a1b6ec4307 test(session): RED contracts for token-free runtime messages and blob-dir lifecycle
4f7897fcef fix(session): keep runtime messages readable and bound the resident blob directory
7aa61ee75c docs(coding-agent): record the resident store completion and move its changelog lines to Unreleased
0bd3ee0cb2 test(session): RED contract for a shared blob directory across live managers
d4b1802030 fix(session): let the last live owner clear the resident blob directory

Final evidence at d4b1802030:

bun run --cwd packages/coding-agent build        exit 0
bun run check                                    exit 0
focused suites (7 files)                         Test Files 7 passed   Tests 51 passed
real-surface probe vs built dist                 SUMMARY 13/13 passed
git status --porcelain                           0 lines

CI note: the merge went in with Test (coding-agent 1/3) red. That job fails on the same test on main itself (run 35055501202, head fef17495, no PR involved) and failed twice here across a rerun, so it is a main-branch defect no PR can clear — filed as #1751 with the reproduction contrast and a lead. The unrelated Test (coding-agent 3/3) red was the known #1676 flake and went green on rerun. Every other check passed, and the local gates above cover this change's own surface.