[Bug] Missing attachment object still bricks image-bearing sessions on 0.2.0-rc.2, still reported as TRANSPORT (see #7582)

[541691228-alt]

中文摘要：#7582 已经把机制讲清楚了——会话历史里只存附件 id，每次请求前都要回附件库重读字节，所以 ~/.dsh/attachments 下的对象一旦被删除，含图会话就永久失败，而且被错误归类成可重试的 TRANSPORT。这条只做两件事：在新版本上复现（0.2.0-rc.2，仍存在），以及补代码级证据（真因 cause 至今没有落盘）。分析与修复建议见 #7582，这里不重复。

Summary

#7582 reported this on 0.1.5-rc.2 (2026-09-23) and it is still unfixed. On 0.2.0-rc.2 the failure reproduces unchanged in kind: once an attachment object referenced by a session's durable history is missing, every later request in that session fails permanently, including plain-text messages, and the failure is still surfaced as TRANSPORT even though it dies locally in ~13–15 ms, before any HTTP call.

Environment

Build	DSH desktop 0.2.0-rc.2, Windows x64, nightly channel
Package	@deepseek-ai/dsh-attachment-local 0.2.0-rc.2
Provider / model	deepseek-official, DeepSeek-V41-Flash (reasoning: high)
Session state	image attachments earlier in the history; the corresponding objects were later deleted from <DSH_HOME>/attachments/v1/objects/

What changed between the two reports (and what did not)

	0.1.5-rc.2 (as analyzed in #7582)	0.2.0-rc.2 (observed here)
Image preparation	prepareRequestImages() reading every image ref before the request	renamed, same behavior: prepareImages(history, connection, modelId, attachments, access, signal)
Read failure	attachments.readImageRequest(...) throwing outside any try	readImageFile() throws AttachmentError: ATTACHMENT_NOT_FOUND ("Attachment object is missing."), plus ATTACHMENT_READ_FAILED / ATTACHMENT_CORRUPT for other cases
Misclassification	DeepSeek API stream from <baseURL> failed → TRANSPORT	DeepSeek Messages transport failed → TRANSPORT
Retry policy	DEFAULT_MAX_RETRIES = 5, TRANSPORT retryable	policyKey ["normal",1,["EMPTY_RESPONSE","RATE_LIMIT","SERVER","TIMEOUT","TRANSPORT"],500,10000,0.1] → 1 retry (UI: 已重试模型请求 (1/1))
Outcome	permanent failure; /compact also failed	permanent failure; we did not re-test /compact

So the retry count was lowered from 5 to 1 between the two versions, and the session still dies. Retry count was never the problem; the classification is.

New evidence: the real cause still is not persisted

Suggestion (b) in #7582 — keep the underlying cause — has not landed. In the affected session (9.2 MB, 1156 frames) there are 17 TRANSPORT records and zero occurrences of the string ATTACHMENT. What assistant/attempt and turn/end actually store:

{"type":"assistant/attempt","seq":10809,"time":1791542759036,"data":{"turn":181,"step":4,"stream":[{"type":"chunk","time":1791542759035,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"DeepSeek Messages transport failed","code":"TRANSPORT"}}}}]}}
{"type":"turn/end","seq":10814,"time":1791542759601,"data":{"turn":181,"reason":{"kind":"error","error":{"message":"DeepSeek Messages transport failed","code":"TRANSPORT"}}}}

The persisted failure has message + code only. So from the UI, the log, and the host, a missing local file is indistinguishable from a network outage — which is exactly the wrong direction this sends anyone debugging it.

Minimal reproduction (0.2.0-rc.2)

1. In a session, send one message with an image attachment and let it stay in the history.
2. Delete the matching object: <DSH_HOME>/attachments/v1/objects/<sha256-prefix>/<sha256>.
3. Reopen/resume the session and send any message — text-only is fine.
4. Every turn then fails in ~13–15 ms with TRANSPORT. It never recovers, because the dangling reference is part of the durable history.

Note the asymmetry: the Files path already degrades (FileResolutionFailure → retry inline) and offloaded images are projected to text via projectOffloadedImages(history, ref => offloadedImageText(ref, access(ref))). A missing local object has no equivalent fallback.

Suggested fix

Same three as in #7582; if only one gets done, do the first:

1. Wrap the image-preparation call and throw a non-retryable, self-describing error (e.g. ATTACHMENT_MISSING) — this alone stops a deleted file from permanently deadlocking a session.
2. Persist cause.code (plus one stack frame) in assistant/attempt / turn/end failure records.
3. Treat the attachment store as session-durable state: reference counting or reachability GC, refuse deletion while referenced, and degrade dangling references to text placeholders on load instead of failing the session.

Question

Is the attachment store considered durable internal state that tools and cleanup scripts must not touch? If the intended answer is "don't delete it", the app should say so and guard the path — right now nothing does, and the resulting failure is attributed to the network.

[argszero]

Confirmed on the source, with one correction that matters for the retry policy: the TRANSPORT you are seeing is not a mislabelled transport failure — it is a wrapper. In packages/llm/llm-deepseek/src/adapter.ts, the stream generator's catch-all is:

} catch (error) {
  if (timeoutOf(...)) throw new LlmError('DeepSeek Messages stream idle timeout', 'TIMEOUT', { cause: error })
  if (options.signal?.aborted) throw new LlmError('DeepSeek Messages request aborted', 'ABORTED', { cause: error })
  if (error instanceof LlmError) throw error
  throw new LlmError('DeepSeek Messages transport failed', 'TRANSPORT', { cause: error })
}

and prepareImages() — the function that calls attachments.readImageRequest(...) and therefore throws AttachmentError('Attachment object is missing.', 'ATTACHMENT_NOT_FOUND') — runs inside that generator. So a ~13 ms local filesystem miss is rewritten into the very same { message: 'DeepSeek Messages transport failed', code: 'TRANSPORT' } a real socket failure produces, and the default policy then spends a retry on it (one, under your policyKey; five before). The cause survives only on the live Error: LlmError.failure is a closed, frozen projection — { message, code, status?, providerRetryAfterMs?, requestId?, offloadImages? } — so neither agent/request-error nor the session log can see the AttachmentError at all.

That the same string and code carry unrelated causes is not hypothetical: #9266 is a Windows TLS / proxy / system-CA case surfacing the identical DeepSeek Messages transport failed / TRANSPORT. Any recovery keyed on the code alone is therefore unsafe; the discriminator has to be an independent probe.

On the good-news side, the recovery primitive is already there and durable. dsh-compaction-image-offload reacts to IMAGE_OFFLOAD_REQUIRED by recording session.append('image/offload', { targets }); projectOffloadedImages() then replaces each selected occurrence with placeholder text before the adapter touches the store. Offload is exactly the right repair for a vanished object — mark the occurrence and no byte is ever re-read. Nothing about the missing-object case needs new core machinery to recover:

• agent/request-error is a public waterfall whose payload carries agent, so a listener reaches agent.session.surface.nodes and the mounted attachment service;
• attachments.readImage(ref) is a definitive probe: it throws ATTACHMENT_NOT_FOUND — distinct from ATTACHMENT_CORRUPT / ATTACHMENT_READ_FAILED — only when the object is gone;
• the payload's failure is not readonly, and returning { kind: 'retry' } re-derives the request from the surface, so an offload appended inside the listener is already in effect for the retry.

I intend to ship that as a plugin. It extends the existing @argszero/cordis-plugin-image-offload-fallback (v0.1.0 already translates a provider's "this image cannot be decoded" rejection into this same offload path), so v0.2.0 adds a probe-based detector: on a failed request, enumerate the retained image occurrences, probe them, and only when an object is provably missing append the durable offload and retry. The honest boundaries, since they are the design:

• it keys on the probe, never on TRANSPORT, so the [Bug][Windows Desktop 0.2.0-rc.2] Generic transport failure persists across reinstall/reset due to Node CA, stale state, and Electron UI cache #9266 shape is left untouched;
• an offloaded occurrence is never sent to any route again until the surface changes: the image is gone for good and the session survives. For an object that was actually deleted that is the only truthful outcome — silently substituting bytes would be worse;
• the retry needs dsh-compaction-image-offload's image/offload projection mounted (the shipped base mounts it); without it the plugin will say so loudly rather than pretend to have recovered.

What stays core, and I am not claiming otherwise:

1. the classification — generate()'s catch-all turning a non-retryable local failure into retryable TRANSPORT, i.e. retries spent on something a retry cannot fix;
2. prevention — the adapter should degrade a missing object the way the Files path degrades (FileResolutionFailure → retry inline): project the occurrence to text instead of failing the request;
3. the missing object itself — nothing in the sessions/attachments layer notices that durable history still references an object the store no longer holds.

Your /compact observation follows directly from (3): compaction replays the same prefix, so it re-reads the same missing object.

[541691228-alt]

更新一下这条帖子的状态，也顺便记一个可复现的结论。

#7834 那份降级补丁在当前的 master（0.2.1-alpha.2，d7432673，2026-10-09）上已经打不上了 —— 上游把 readRequestImage() 包裹函数删掉，prepareImages() 改成直接调用 attachments.readImageRequest(...)。我们照同样的思路重做了适配版，并在本地克隆上跑通了全部验证：

• 红 → 绿：未打补丁时 prepareImages() 在 packages/llm/llm-deepseek/src/images.ts:55 抛 AttachmentError: attachment object is missing（随后被适配器兜底改写成 TRANSPORT，会话就此永久卡死）；打上补丁后探针测试转绿。
• vitest run packages/llm/llm/tests packages/llm/llm-deepseek/tests → 29 files / 830 tests passed。
• tsc -b（两个包 + tsconfig.host.json）exit 0；oxlint 对改动 4 文件 0 warning / 0 error；补丁往返（git apply -R → 树干净 → git apply → diff 一致 → 复跑）通过。
• 改动 4 文件 +153/−7：三个「附件读不出来」的错误码（ATTACHMENT_NOT_FOUND / ATTACHMENT_READ_FAILED / ATTACHMENT_CORRUPT）降级为文字占位，请求照常发出；集合之外的 AttachmentError 仍然抛出，且保留自己的 code 与 cause。

明细、适配后的完整 diff 和实测表格都写在 #7834 的评论里了：

#7834 (comment)

如果维护者希望走正式流程，我可以按仓库门禁再跑一遍完整套件。

[541691228-alt]

Thanks — this is the most useful correction we've gotten on this, and it matches what we measured independently.

Both of your corrections check out from our side: the ~13 ms ENOENT → TRANSPORT wrapping is exactly what we saw (attempts returning in under 50 ms with zero HTTP), and LlmError.failure being a closed projection is why our session log holds 17 TRANSPORT entries and not a single ATTACHMENT string across 9.2 MB / 1156 frames. The #9266 point is well taken — we had been calling this a mislabelled transport failure; "wrapper, and unsafe to key on the code" is the better framing.

On (2), the core-side prevention you say stays core: we have it implemented and verified on current master, and it is now posted as a comment on #7834 — #7834 (comment) — with the full diff inline.

• Base d743267388641bc76f17c45ce8b4c231aed1d32c (0.2.1-alpha.2). The earlier diff no longer applies because readRequestImage() was inlined into prepareImages().
• prepareImages() gains an unavailable set: ATTACHMENT_NOT_FOUND / ATTACHMENT_READ_FAILED / ATTACHMENT_CORRUPT are projected to unavailableImageText(ref) through projectUnavailableImages() before assertImagesFit(), so no image block is left dangling for the later as RequestImageAttachment casts.
• AttachmentErrors outside that set are re-wrapped as new LlmError(..., error.code, { cause: error }). That is the (1) half, narrowly scoped: the failure now carries ATTACHMENT_NOT_FOUND, which is not in the default retry set (EMPTY_RESPONSE / RATE_LIMIT / SERVER / TIMEOUT / TRANSPORT), so the policy stops spending a retry it cannot fix. We deliberately did not touch the general catch-all in adapter.ts — everything else is still rewritten there.
• Red → green: unpatched, prepareImages() throws from packages/llm/llm-deepseek/src/images.ts:55; patched, the request assembles with the placeholder. vitest run packages/llm/llm/tests packages/llm/llm-deepseek/tests → 29 files / 830 tests passed; both tsc -b targets exit 0; oxlint clean on the four changed files.

Two things about your plugin design I would like your read on:

1. If both halves ship, the adapter degrades first and your probe never sees a failure. Is that the intent — core prevention makes the plugin the fallback for routes/versions without the patch — or do you expect the probe path to stay primary?
2. attachments.readImage(ref) as the discriminator: it separates NOT_FOUND from CORRUPT / READ_FAILED, but a probe can also fail transiently (EACCES, EIO, a file locked by another process on Windows). Do you treat any non-NOT_FOUND probe error as "do not recover", or do you re-probe before giving up?

(3) is the unclaimed one, agreed. For what it is worth: the session that bricked on our machine now references 51 objects, all 51 present and sha256-consistent — but only because we edited the durable log by hand to replace six dead references with text placeholders. Nothing in dsh would have noticed, or told us which references were dead.

[541691228-alt]

跟一条检索结果，跟我们前面那份适配补丁直接相关，也和 @argszero 的 v0.2.0 计划相关。

我们把仓库 .agents/notes/ 过了一遍（#7619 的重点就是提醒这件事），发现这个问题上游已经有 proposed 设计：proposed/bug-fix/2026-08-20-attachment-read-quarantine.md（Status: proposed）。它把「历史图片读不出来时怎么办」写得很完整 —— 派发前记录 attachment/quarantine、投影换成确定性文本、后续请求跳过 readImage()、只有 digest+metadata 校验通过才 attachment/recovered、重启/fork 从日志重建、幂等与并发去重，连验收标准都有。

关键约束是它的归属条款：共享的 request-projection 消费方持有这条策略，provider adapter 不得自造独立占位符或恢复状态；被否方案里明确点名 "Catch the error independently in each adapter"，理由是 unlogged placeholder 会让 replay 依赖当时恰好存在的 adapter 与存储状态。

据此两点自我修正（详细版贴在 #7834）：

1. 我们那份适配版应定位为临时缓解：它修的是「不可重试的本地失败被兜底 catch-all 包装成可重试 TRANSPORT」这一半，但占位文本不落日志，属于笔记明确否决的形态，quarantine 落地后应撤掉。
2. @argszero 你规划的 v0.2.0 走的是 session.append('image/offload', { targets }) + projectOffloadedImages()，也就是有持久事件的路径，比在 adapter 里临时造占位更贴近笔记的归属规则；不过笔记说的持有者是共享的 request-projection 消费方而非插件。如果你还没读到这份笔记，建议先看它，再判断探针 + {kind:'retry'} 的形态要不要按它的验收标准（错误分类、幂等、取消、重试、恢复、嵌套 tool-result 图片）收敛一遍。

我们这边的证据（0.2.0-rc.2 仍复现、9.2 MB/1156 帧里 17 条 TRANSPORT 而 ATTACHMENT 零命中、51 个引用对象 0 缺失）也一并补到 #7834 那条评论里了。

[argszero]

Since my previous comment, the plugin is published — including the half that this thread is about:

@argszero/cordis-plugin-image-offload-fallback@0.2.0 — https://www.npmjs.com/package/@argszero/cordis-plugin-image-offload-fallback

npm install @argszero/cordis-plugin-image-offload-fallback

The package ships its own cordis.patch.yml, so mounting is one entry (and a bundle reading dsh.bundle.patch picks it up without you writing it):

- insert:
    - id: image-offload-fallback
      name: '@argszero/cordis-plugin-image-offload-fallback'

0.2.0 adds the missing-object path to the decode-rejection translation that was already there. On each failed request it walks the same surface offloadOldestImages walks (user/message and tool/result nodes, image indexes counted in model-visible order, already-offloaded occurrences included in the count), asks the attachment store about every distinct retained reference, and records one durable image/offload event naming exactly the occurrences whose read raised ATTACHMENT_NOT_FOUND, then returns { kind: 'retry' }. It is not an adapter-level placeholder: the event is logged, and the text the model sees is produced by the same registration the executor publishes (ctx.sessions.registerMessageProjection). test/real-executor.spec.mjs runs the shipped projection against the selection the plugin records, so the claim that the two agree is tested rather than asserted.

Now your two questions.

1. If both halves ship, the adapter degrades first and the probe never sees a failure — is that the intent?

Yes. The plugin is the fallback for deployments, routes and versions that do not have the core change, and it should become dead weight the moment the assembly-time fix lands. Two reasons it is built that way rather than as a second opinion:

• A plugin cannot legitimately hold this policy. It has no assembly-time seam — by the time agent/request-error fires, the request has already been assembled and dispatched, so the only thing a plugin can do is repair the session and pay a retry. Repairing at assembly is strictly better: no failed provider call, no retry budget, no TRANSPORT in the log.
• Concretely, if you ship your prepareImages() patch, our probe path still runs on each failure but finds nothing missing (every reference now resolves), so it stays silent. The decode path is unaffected either way — that half is a different failure the note's design does not cover.

So the intended end state is: core owns the policy, this plugin is uninstalled or inert. That is also why 0.2.0 deliberately does not touch the catch-all in adapter.ts, which is your (1) half: the misclassification is real, but re-wrapping failures from a plugin would be the same duplicated policy the note rejects, one layer out.

2. Transient probe errors — treat any non-NOT_FOUND as "do not recover", or re-probe?

Treat as "do not recover", and no second probe inside the same attempt, on purpose:

• The probe asks the store the same question the failing request just asked, through the same readImage(). If that read reported EACCES, EIO or a Windows sharing violation, the request that just failed hit the same thing. Re-probing immediately would ask a store that has already given its answer, and a transient error read as evidence would cost the user an image over a flaky filesystem.
• Only codes that mean the bytes cannot be served at all count. ATTACHMENT_NOT_FOUND is the default set; ATTACHMENT_CORRUPT and ATTACHMENT_READ_FAILED are outside it and must be opted into with missingAttachmentCodes, precisely because they are the ones a retry can still fix. Your advisory version of this is the correct place for the retry-once-with-cancellation behaviour.
• There is a natural second chance, just not one the plugin owns: a failure we decline to repair goes back to the retry policy, and if that policy retries, the next attempt re-enters the handler and re-probes then. A deployment with no retry budget for the code gets a plain failure instead of a wrong repair, which is the failure direction we preferred. Cancellation is propagated, never read as evidence — test/missing-attachment.spec.mjs covers that arm.

On the proposed note — thank you for pointing at proposed/bug-fix/2026-08-20-attachment-read-quarantine.md; I had not read it, and it is the right frame for this. Measured against it, a durable logged transition applied by the shared request-projection consumer is what we do, and these are the parts of its acceptance criteria we meet without change:

• one durable transition per missing object, and later requests do not read it or fail because of it (the projection replaces the occurrence before any adapter touches the store);
• idempotency (an offloaded occurrence leaves the enumeration, and the projection refuses a repeated selection) and cancellation;
• restart and fork reconstruct from the log, because the decision is an event and not adapter state;
• nested tool/result images, since the node walk is not limited to user/message.

And these are the parts where our shape is a deliberate subset, which I would not want left implicit:

• The placeholder is not informative. We reuse image/offload's text, which does not name the attachment or the failure class, where the note's attachment/quarantine would. A reader of the transcript cannot tell "you deleted the file" from "the request was too large".
• No retry-once for a general read failure, per the question above.
• Concurrency is delegated. Two overlapping failures can both observe the same missing object; the projection's append-time validation makes the second transition fail loudly (the plugin logs once and does not retry), but the note's "one effective transition" is enforced there rather than here.

That is the honest description of a fallback, not a competing design. If the note is implemented, the plugin's missing-object path should be deleted rather than ported; the decode half is the part worth keeping, since a route that cannot decode an encoding never reaches an attachment read at all.

(test/contract.spec.mjs pins the two mirrored code strings — IMAGE_OFFLOAD_REQUIRED and ATTACHMENT_NOT_FOUND — against the installed harness packages — IMAGE_OFFLOAD_REQUIRED from @deepseek-ai/dsh-llm, ATTACHMENT_NOT_FOUND from the store's own readImageFile on an absent object — so a rename fails in development instead of silently turning the plugin into a no-op.)