Desktop: task refresh fails with opaque persistence_failed; the real transcript error is discarded

[MoonOld]

What happened

Refreshing a task in Maka Desktop fails with a generic toast and an opaque error code, and the real cause is discarded — so the failure cannot be diagnosed from the product's own diagnostics.

Toast:

• Title: 刷新任务失败 (Could not refresh task)
• Body: 任务内容暂时无法刷新，请稍后重试。

Main-process log (4 occurrences over ~25 min):

Error occurred in handler for 'sessions:transcript:open': RuntimeHostOperationError: Session transcript is unavailable
    at #acceptResponse (.../@maka/runtime-host/dist/client/connection.js:408:24)
    at #readResponses (.../@maka/runtime-host/dist/client/connection.js:368:37)
    at process.processTicksAndRejections (node:internal/process/task_queues:104:5) {
  operation: 'session.transcript.page',
  code: 'persistence_failed'
}

Why this is a diagnosability bug

packages/runtime-host/src/server/session-continuity-coordinator.ts, #readTranscriptPage(), funnels every unexpected throw from readSessionTranscriptPage() into one catch-all outcome:

} catch (error) {
  if (error instanceof TranscriptPageRequestError) {
    return { ok: false, error: { code: 'invalid_request', message: error.message } };
  }
  return { ok: false, error: { code: 'persistence_failed', message: 'Session transcript is unavailable' } };
}

Because the handler returns an outcome instead of throwing, the [runtime-host] unexpected <operation> failure: ... log in operation-dispatcher.ts (which is the only place that calls boundedFailureDiagnostic) never runs. As a result the underlying error is not recorded anywhere:

• not in the Runtime Host log,
• not in the desktop diagnostic report,
• not in the Renderer (which only sees persistence_failed).

The Renderer then falls back to generic copy because the error carries no recognized classification (apps/desktop/src/renderer/app-shell-copy.ts → classifiedErrorFallback → copy.errors.messageRefresh).

Failure candidates that all collapse into this one opaque code

packages/runtime-host/src/server/session-transcript-reader.ts throws, and each is swallowed by the catch-all above:

• Durable RuntimeEvent transcript projection is incomplete (a hard read-model diagnostic) — most likely in this report
• Session transcript Turn exceeds its message limit (> 4096 messages)
• Session transcript Turn exceeds its byte limit (> 16 MiB)
• Session transcript projection exceeds its presentation limit
• Session transcript projection scan exceeds its capacity limit (> 16 MiB hidden-row scan)
• any underlying storage read error

Note that several of these are deterministic: "please try again later" is wrong copy for them, since a retry will always fail.

How to reproduce

Not yet reduced to a minimal case — flagging the conditions instead:

1. Run Maka Desktop (nightly) for several hours and work in a large task. In the reported instance the affected workspace store held ~28,851 runtime events for a single session (runtime.sqlite ~456 MB).
2. Trigger a transcript refresh / reload on that task.
3. The toast appears and sessions:transcript:open returns persistence_failed.

Environment

• Maka: 0.2.0-dev.44.20260920 (packaged, nightly)
• OS: macOS darwin 25.4.0 (arm64)
• Electron 43.4.1 · Chrome 150.0.7871.224 · Node 24.18.1
• Surface: Desktop
• Source commit: 2da8a03
• Storage health at the time: runtime.sqlite ~456 MB with integrity_check and quick_check both ok, 152 GiB disk free, Runtime Host ready → not corruption, not disk-full, not a host crash.

Logs / additional context

The full desktop diagnostic report is available; the transcript entries above are its only signal. Related but probably unrelated noise in the same report: a skills:listInvocable → session_archived failure ~6h earlier, and a MaxListenersExceededWarning (11 destroyed listeners on WebContents) ~3.7h earlier.

Suggested fixes

1. Log the real error. In the non-TranscriptPageRequestError branch, emit boundedFailureDiagnostic(error) (plus session/subscription context) to the host log before returning the generic outcome.
2. Separate transient from deterministic failures. Projection/limit violations are not retryable and should not reuse the "try again later" code or copy.
3. Surface a typed, actionable error to the Renderer (e.g. transcript too large / needs repair) instead of the umbrella persistence_failed.

[MoonOld]

Root cause identified — this failure is deterministic, not transient.

The throw comes from the storage layer, which defines a dedicated error for exactly this condition, but nothing in production code handles it:

packages/storage/src/runtime-transcript-query.ts:430

if (count === limits.maxEvents) {
  throw new RuntimeTranscriptOversizedTurnError(
    `Turn ${invocationId} holds more RuntimeEvents than a transcript page may read`,
  );
}

RuntimeTranscriptOversizedTurnError is referenced only by tests and the test-only in-memory runtime (whole-repo grep). It therefore falls straight into the catch-all in session-continuity-coordinator.ts and surfaces as persistence_failed.

Triggering condition: a single oversized Turn

The cap comes from session-transcript-reader.ts:53:

const TRANSCRIPT_TURN_MAX_MESSAGES = 4_096;
const TRANSCRIPT_SOURCE_MAX_EVENTS = TRANSCRIPT_TURN_MAX_MESSAGES * 2; // 8192

and is passed to storage as maxEvents by readRun.

Counting the reporter's runtime.sqlite, exactly one Turn in the whole workspace exceeds it — the runner-up is only 5944, so this is not a systemic size problem, it is a single long autonomous run that grew past the cap:

Session	4974ff21-acfc-41ae-bdee-f1678734f638
Turn (invocation/run)	9eb0707d-4a59-42c4-a9fb-9eb30e78937d
Events	9382 (over 8192 by 1190, ~14.5%)
Span	2026-09-21T10:14:43Z → 11:00:42Z (~46 min inside one Turn)
Composition	441 function_call/function_response pairs (441 tool calls), 7618 runtime_fact, 220 text, 219 thinking

Why it takes down the whole session

readRun pushes every event of the Turn into the projection, and paging in scan() walks Turn by Turn (run.firstOrdinal … run.lastOrdinal). Any page overlapping that Turn must project all of it, so it always throws.

The timeline matches: the Turn ended at 11:00:42Z, and the failing refreshes are at 12:18Z and 12:43Z.

Impact: the session's transcript is permanently unreadable and retry can never succeed — yet the copy shown is "try again later". This is a concrete instance of the retryable-vs-deterministic point in the issue body.

Note on how the limit is derived

TRANSCRIPT_SOURCE_MAX_EVENTS is derived from a message budget (TRANSCRIPT_TURN_MAX_MESSAGES * 2), but a Turn's event count is not bounded by its message count (441 tool calls → 9382 events). The two quantities do not share a source, which is how a Turn can pass the message check and still blow the event check.

Fix directions

1. Log the real error, as described in the issue body.
2. Degrade instead of failing the whole session: project what fits and append a truncation notice — there is precedent, the read model already reduces large Bash streams to a bounded terminal preview.
3. Larger change: let a page cut inside an oversized Turn at an ordinal boundary rather than requiring Turn boundaries; this touches the endsAtTurnBoundary / spliceability assumptions.
4. Write-side prevention: force a new Turn/invocation once a Turn's event count crosses a threshold.

[MoonOld]

Correction to the root-cause comment above — an independent review pass (3 read-only reviewers) confirmed the chain but showed two of my statements were too strong. The direction holds; the specifics need fixing.

1. Off-by-one in the threshold. runtime-transcript-query.ts:430 evaluates if (count === limits.maxEvents) at the top of each iteration before yielding that row, so a Turn with exactly 8192 events passes and the throw happens on the 8193rd. The predicate is > 8192, not >= 8192. The measured 9382 still clears it.

2. The storage layer is not necessarily the thrower. The reader has its own guard on projected messages (session-transcript-reader.ts:561-566: messageCount > 4096 || messageBytes > 16 MiB). Projected messages can outpace raw events, so that guard can fire before storage reaches its 8193rd event. Both sites collapse into the same persistence_failed, so the log cannot distinguish them. The accurate statement is: the throw comes from one of the Turn-size guards (storage RuntimeTranscriptOversizedTurnError, or the reader's presentation-limit guard) — not provably from storage.

3. "Any page overlapping the Turn must project all of it" is false. RuntimeTranscriptQuery.events() has no lower ordinal bound (WHERE e.invocation_id = ? AND o.ordinal <= ?), so when a page's snapshot ends inside the Turn (throughOrdinal < Turn.lastOrdinal) only a prefix is yielded — no throw, and scan filters it: silent partial-Turn truncation. Full projection (and therefore the throw) happens when throughOrdinal >= Turn.lastOrdinal. So the impact is "pages/refreshes that reach that Turn fail", not "the whole session is permanently unreadable".

4. A second Turn is close to the other limit. The largest per-Turn raw payload total is 16,487,316 bytes (45e20c3e-…/49fd903a-…, 4410 events) — within ~1.7% of TRANSCRIPT_TURN_MAX_BYTES = 16,777,216. Worth treating as a second landmine.

Limit arithmetic for completeness:

• TRANSCRIPT_SOURCE_MAX_RECORD_BYTES = 16,777,216 * 2 + 262,144 = 33,816,576 — never tripped by this data.
• TRANSCRIPT_SOURCE_MAX_BYTES = 8192 * 33,816,576 ≈ 258 GiB — never tripped.
• Terminology: storage groups a Turn by turn_id, and one Turn can span multiple invocations; the limit applies per invocation_id (WHERE e.invocation_id = ?). The 9382 figure is per invocation.

Alternative causes on the same session that this data does NOT rule out — all mapped to the same persistence_failed, which is precisely the diagnosability problem in this issue:

• a hard read-model diagnostic in projectTurn (session-transcript-reader.ts:161): unsupported_event, incomplete_event, tool_use_id_mismatch
• ensureTranscriptLedger throwing ("Imported Session history is still being prepared")
• readCanonicalPermissionOutcomes (session-transcript-reader.ts:528-533) — called unwrapped, so any read/repair error propagates
• PAGE_HIDDEN_SCAN_MAX_BYTES RangeError (:422)
• readTranscriptTurnCrossing and general SQLite errors

Fix review outcome:

• Direction 1 (log the real error) — sound, minimal. Log directly via boundedFailureDiagnostic in the coordinator. Do not route it through onPublicationFailure: that is positionally wired to context.requestDrain (execution-composition.ts:925), not a logger — which is also why the bootstrap path leaves no stack today.
• Direction 2 — risky/underspecified as written: storage throws inside the generator before yielding row maxEvents+1, and the reader's limits equal storage's, so storage always wins; a naive prefix also drops the Turn's opening/terminal facts and trips projectTurn's "projection is incomplete", which is an integrity signal, not a size signal.
• Direction 3 — wrong layer: storage run() always reports the full Turn extent, and it contradicts pinned tests (session-transcript-reader.test.ts:1022-1088, :1059, :1133).
• Direction 4 — right invariant, large change; prior art exists: tool_step_cap_reached already ends a Turn on a bound and appends a notice.
• Suggested instead: degrade at Turn granularity — emit one deterministic, Turn-aligned synthetic system_note placeholder for an oversized Turn, reusing the buildArchivedToolResultPlaceholder / projectTranscriptToolResult semantics, implemented in session-transcript-reader.ts. That keeps endsAtTurnBoundary === true, needs no cursor version bump and no storage contract change, and breaks no existing test.

[MoonOld]

A second blind spot on the same path (found while preparing the minimal fix)

The page path is not the only place a transcript failure loses its cause. The bootstrap path has the same shape, with a subtler defect — the comment claims a trace that does not exist:

packages/runtime-host/src/server/session-continuity-coordinator.ts:966-973

} catch (error) {
  // The client can only retry, but a projection that outgrew its
  // bounds is a Host defect and has to leave a trace here.
  this.onPublicationFailure(error);
  return {
    ok: false as const,
    code: 'persistence_failed' as const,
    message: 'Session transcript is unavailable',
  };
}

onPublicationFailure is positionally wired to context.requestDrain (packages/runtime-host/src/server/execution-composition.ts:925, consumed in context-coordinator.ts:59) — a drain trigger, not a logger. So the trace the comment promises is never emitted.

Worth noting for triage: subscription.open with kind: 'tail' returns the same persistence_failed / "Session transcript is unavailable" pair, so this issue's symptom can equally originate on the bootstrap path. That is the same diagnosability gap as the page path, at a second entry point.

Minimal fix for the page path — ready to submit

#readTranscriptPage now records the cause before returning the generic outcome:

console.error(
  `[runtime-host] session.transcript.page failed: ${boundedFailureDiagnostic(error)}`,
);

plus a regression test that injects a page-only reader failure (bootstrap requests carry no position, pages always do) and asserts the outcome is unchanged while the cause is logged. Locally: tsc --noEmit clean, biome clean, session-continuity-coordinator.test.ts 47/47 pass. Happy to open a PR if that is useful — say whether to include the bootstrap path in the same change.