fix(agent): serialize detached managed snapshots

[Yeachan-Heo]

Summary

• validate and byte-measure the detached managed snapshot rather than trusting the live payload's JSON serialization
• sanitize the detached clone when structuredClone removes a payload class toJSON() and exposes JSON-hostile bigint state
• surface residual local snapshot diagnostics once without same-model retry amplification

Reproducer

A provider payload class with prototype toJSON() and an own bigint field serialized live, but structuredClone erased the serializer while retaining the bigint. The previously accepted callback and terminal snapshots then failed JSON.stringify at providerPayload.envelope.sequence.

Verification

• bun test packages/agent/test/managed-attempt-transaction.test.ts packages/coding-agent/test/agent-session-fallback-attempt-transaction.test.ts
• bun test packages/ai/test/model-fallback-transport-facts.test.ts packages/ai/test/google-gemini-cli-alignment.test.ts packages/ai/test/openai-codex-stream.test.ts
• bun --cwd=packages/agent run check
• bun --cwd=packages/coding-agent run check
• bun run build
• affected PR planner and all selected tasks

Closes #4578

gajae.pr-review-verdict.v1 merge-approved sha256:b91f17b7e83c76c77079aa15f76de1796831a53bb6df621f73e0353f3d6fb856 reviewer:human reviewer-id:probepark evidence:#4580 (review)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[Yeachan-Heo]

Signed supersession evidence for issue #4578

• Supersedes stale head faaa44a0137d23afded337cb48a16cd3fcc9bb93 / digest b97d0db7a32741cf5db83fff357c2491bc232e14fd240d60e5607a10c407c61a.
• Exact target base: 2e3ccb5895568ffec709b3adba25bc919d6d248b.
• Rebased exact head: a13677f761485c63d7188f7520e70d9d0cdecb73.
• Canonical base...head binary diff digest: 84aa792794969dedd9ed2e86ad55102da98ee04541576541ead2464c75a558fe.
• Six-file scope preserved across merged feat(ai,coding-agent): add commandcode-goat model profile #4577; commandcode-goat changelog entry retained.
• Fresh exact-head verification: reproducer 1/1; managed/fallback 70/70; Managed fallback chain wedges sessions with "The object can not be cloned." when a provider error carries response headers #2408 AI cohort 71/71; agent and coding-agent checks pass; workspace build passes; affected planner selected suites/builds pass.
• Generated native declaration drift restored; worktree clean before push.

Signed-by: Yeachan-Heo
Reviewed-head: a13677f

[Yeachan-Heo]

Signed supersession evidence for canonical issue #4578 recovery

• Supersedes canonical head a13677f761485c63d7188f7520e70d9d0cdecb73 / digest 84aa792794969dedd9ed2e86ad55102da98ee04541576541ead2464c75a558fe.
• Integrated ONLY duplicate PR fix(agent): stop managed snapshot failure retry looping #4581 docs commit 04be9224886a8cdcdba123cd8643cc1354e8a6f4; the six implementation files are byte-identical to prior canonical head and duplicate implementation.
• Exact base: 2e3ccb5895568ffec709b3adba25bc919d6d248b.
• New seven-file exact head: a03dde8d675de017781a547c876c26a022a1d105.
• Canonical binary diff digest: 12c4d839cb47894f7ba00361f67279c4e868ef67c8feeb4ed9e6a5f7dc5d2407.
• Docs now match code/tests: local_snapshot_failure and local_buffer_overflow surface immediately, never retry, never charge/advance provider fallback, and never rotate credentials.
• Fresh verification: reproducer 1/1; managed/fallback 70/70; agent and coding-agent checks pass; docs-index 5/5 after canonical local regeneration; seven-file affected planner selected suites/builds pass.
• Generated native declaration drift restored; tracked worktree clean before push.

Signed-by: Yeachan-Heo
Reviewed-head: a03dde8

[snowykr]

Independent reproduction on an affected macOS host confirms the serialization primitive described by this PR.

class Envelope {
  sequence = 1n;

  toJSON() {
    return { sequence: String(this.sequence) };
  }
}

const live = { providerPayload: { envelope: new Envelope() } };
console.log(JSON.stringify(live)); // succeeds

const detached = structuredClone(live);
console.log(detached.providerPayload.envelope.constructor.name); // Object
console.log(typeof detached.providerPayload.envelope.sequence); // bigint
JSON.stringify(detached); // throws

Observed with Bun on the affected macOS host:

live {"providerPayload":{"envelope":{"sequence":"1"}}}
cloneClass Object sequenceType bigint
reproduced TypeError JSON.stringify cannot serialize BigInt.

The affected session repeatedly terminated with errorKind: "local_snapshot_failure" immediately after managed assistant events. The raw rejected provider event is not persisted after the managed transaction is discarded, so the historical payload cannot be proven byte-for-byte identical; however, the deterministic failure mechanism and rejecting snapshot boundary match this PR's JsonSafeBigIntEnvelope regression exactly.

This also supports removing the bounded same-model retry for this error: replaying an identical serializable-live/unserializable-detached payload deterministically reproduces the same local defect rather than recovering a provider failure.

[probepark]

Approve at a03dde8d6 - and this correctly reverses something I approved

fix(agent): serialize detached managed snapshots, head commit "docs(retry): local snapshot
failures surface immediately, no retry". 7 files, +174, mergeable_state: clean.

It removes the retry branch I approved in #4550

-		if (localSnapshot) {
-			// The provisional charge was already discarded at classification time.
-			outcome = attemptsUsed <= retrySettings.maxRetries ? "retry" : "exhausted";
-		} else {
-			outcome = managedFallback ? controller.onAttemptFailure(...) : ...;
-		}
+		outcome = managedFallback ? controller.onAttemptFailure(...) : ...;

-			if (localSnapshot) {
-				// Bounded local retries exhausted: surface the original local
-				// diagnostic without any provider-fallback attribution.
-				return managedOutcome ? { type: "terminal", terminal: { stopReason: "error", messages: [message] } } : false;
-			}

#4550 gave local snapshot failures their own bounded retry path, and I approved it. The reasoning
there - a local staging limit is not a provider failure, so do not attribute it to provider
fallback - was right about attribution and wrong about retry, and I did not question the second
half.

The docs change states why plainly, and it is correct:

-Unlike snapshot failures, re-streaming the same request reproduces the same oversized response, so it is never retried
+Like snapshot failures, re-streaming the same request reproduces the same oversized response, so it is never retried

Snapshot and buffer-overflow faults are deterministic in the payload: the same response re-staged
hits the same shape rejection or the same size cap. Retrying is pure latency with no path to
success, and it delays the diagnostic the operator actually needs. Buffer overflow was already
treated this way; this makes snapshot failures consistent with it rather than leaving two policies
for one class of fault.

The retry.enabled interaction is also cleaned up:

-This opt-out also covers local snapshot failures on managed chains
+Managed provider-fallback failures keep their own chain policy; local snapshot and buffer-overflow failures surface immediately regardless of this setting

Better: whether a deterministic local fault is surfaced should not depend on a provider-retry
toggle.

Differential

# base 2e3ccb589, with this head's test files applied
(fail) ... > surfaces a typed local snapshot failure without a same-model retry
(fail) ... > surfaces a prefix-classified snapshot failure once on a single-model session
(fail) ... > surfaces one local diagnostic without deterministic snapshot-failure retries

# head a03dde8d6
 70 pass  0 fail
$ bun --cwd=packages/agent run check   -> exit 0

Three failures against three behaviours, and the names encode the policy rather than describing
mechanics - "once", "without a same-model retry", "without deterministic snapshot-failure retries".
Those are the assertions that stop the retry branch from being reintroduced.

Verdict

merge-approved.

Noting for my own record: I approved #4550 on the strength of its safety guard (do not retry a
failure carrying visible content) without asking whether retrying a deterministic failure could ever
succeed. The guard was necessary but the premise underneath it was not examined. Worth remembering
when a change adds a retry - the first question is whether the failure can plausibly resolve on
repeat, not whether the retry is bounded safely.

_{Reviewed by @probepark - method: source diff against the base to identify the removed retry branch, docs rationale read for the determinism argument, fresh-worktree run and agent typecheck at the exact head, separate clean base worktree with the head's test files to prove the differential.}

[Yeachan-Heo]

Signed freshness supersession for issue #4578

• Dev advanced from 2e3ccb5895568ffec709b3adba25bc919d6d248b to f024ded61408ee77c1fbcb20539146081a28e08d via fix(tui): adapt iTerm pet to terminal geometry #4579 before merge.
• Supersedes stale authorized head a03dde8d675de017781a547c876c26a022a1d105, approval review 4943425134, and digest 12c4d839cb47894f7ba00361f67279c4e868ef67c8feeb4ed9e6a5f7dc5d2407.
• New exact head: 08fcf92df788a949b0cf41ee4f2d09de5a94aba7.
• New canonical binary diff digest: 31897d48568c2598cf6d847ceacd4204b1c9058893c7e4883a0d0f964ea134c0.
• fix(tui): adapt iTerm pet to terminal geometry #4579 iTerm pet changelog/source changes are retained; canonical bug(agent): managed fallback snapshot sanitizer still reaches residual serialization failure #4578 remains exactly seven changed files.
• Fresh verification on the new base: reproducer 1/1; managed/fallback 70/70; Managed fallback chain wedges sessions with "The object can not be cloned." when a provider error carries response headers #2408 AI cohort 71/71; agent and coding-agent checks pass; workspace build passes; seven-file affected planner and docs-index selection pass.
• Generated native declaration drift restored; tracked worktree clean before push.

Signed-by: Yeachan-Heo
Reviewed-head: 08fcf92

[Yeachan-Heo]

Signed freshness supersession for issue #4578

• Dev advanced again from f024ded61408ee77c1fbcb20539146081a28e08d to f35cf0e3a2e585e3b9f3b67badca8388675cb536 via fix(sdk): broadcast positioned session events live to attached subscribers #4570 before authorization.
• Supersedes stale head 08fcf92df788a949b0cf41ee4f2d09de5a94aba7 and digest 31897d48568c2598cf6d847ceacd4204b1c9058893c7e4883a0d0f964ea134c0.
• New exact head: d6540a7f176018b4e1cc5d83a2c9e504b833c215.
• New canonical binary diff digest: b91f17b7e83c76c77079aa15f76de1796831a53bb6df621f73e0353f3d6fb856.
• fix(sdk): broadcast positioned session events live to attached subscribers #4570 SDK broadcast and prior fix(tui): adapt iTerm pet to terminal geometry #4579/feat(ai,coding-agent): add commandcode-goat model profile #4577 changes are retained; canonical bug(agent): managed fallback snapshot sanitizer still reaches residual serialization failure #4578 remains exactly seven changed files.
• Fresh verification: reproducer 1/1; managed/fallback 70/70; Managed fallback chain wedges sessions with "The object can not be cloned." when a provider error carries response headers #2408 AI cohort 71/71; agent and coding-agent checks pass; workspace build passes; docs-index and seven-file affected planner pass.
• Generated native declaration drift restored; tracked worktree clean before push.

Signed-by: Yeachan-Heo
Reviewed-head: d6540a7

[Yeachan-Heo]

Signed freshness supersession for issue #4578 after warned dependency merge

• Dev advanced from f35cf0e3a2e585e3b9f3b67badca8388675cb536 to 70e1f5be10fc146a54311502a4b27042fb38ee7f via the explicitly watched fix(browser): stabilize Chrome default-root refusal #4575 before authorization.
• Supersedes stale head d6540a7f176018b4e1cc5d83a2c9e504b833c215; prior digest remains canonically identical because fix(browser): stabilize Chrome default-root refusal #4575 is outside the seven-file patch.
• New exact head: 184b85a5e5bd41e68f7e99f56dfb1d9c05ed2ee1.
• Canonical binary diff digest: b91f17b7e83c76c77079aa15f76de1796831a53bb6df621f73e0353f3d6fb856.
• fix(browser): stabilize Chrome default-root refusal #4575 browser fix plus fix(sdk): broadcast positioned session events live to attached subscribers #4570/fix(tui): adapt iTerm pet to terminal geometry #4579/feat(ai,coding-agent): add commandcode-goat model profile #4577 remain intact; bug(agent): managed fallback snapshot sanitizer still reaches residual serialization failure #4578 diff remains exactly seven files.
• Fresh verification: reproducer 1/1; managed/fallback 70/70; Managed fallback chain wedges sessions with "The object can not be cloned." when a provider error carries response headers #2408 AI cohort 71/71; agent and coding-agent checks pass; workspace build passes; docs-index and seven-file affected planner pass.
• Generated native declaration drift restored; tracked worktree clean before push.

Signed-by: Yeachan-Heo
Reviewed-head: 184b85a

[Yeachan-Heo]

Signed exact merge evidence

• PR fix(agent): serialize detached managed snapshots #4580 merged by squash from approved head 184b85a5e5bd41e68f7e99f56dfb1d9c05ed2ee1 onto exact base 70e1f5be10fc146a54311502a4b27042fb38ee7f.
• Independent exact-head approval: probepark review 4943425134 (write authority).
• Canonical binary full-index digest: b91f17b7e83c76c77079aa15f76de1796831a53bb6df621f73e0353f3d6fb856.
• Merge-authorized terminal CI: https://github.com/Yeachan-Heo/gajae-code/actions/runs/31879337596 — all contract and product gates green.
• Squash merge/current dev: 45885ea28793b0ace3523272b41f7ad07b1e88e5.
• Post-merge agent check, coding-agent check, and workspace build all pass on the merge commit.
• Issue bug(agent): managed fallback snapshot sanitizer still reaches residual serialization failure #4578 closed completed; duplicate fix(agent): stop managed snapshot failure retry looping #4581 closed unmerged; no release/tag.

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