From bb7827ba664b3ba73e04812b289c5008b48a01d3 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:02:48 -0400
Subject: [PATCH 1/2] feat(chat,cli): auto-resume after usage limits, ade
 triage, attachment overhaul

Three features plus dev-loop hardening:
- Chats arm a durable, cancellable auto-resume when a provider usage limit
  reports a reset time (Claude, Codex); capped at two consecutive arms,
  cancelled by user activity, visible on the recovery card and in Chat info.
- ade triage builds a redacted context + maintained playbook and hands a
  broken install to the user's own agent CLI; --agent mode prints the
  handoff for an already-running agent.
- Attachments: 50MB any-file staging with a path-copy leg (local), a
  ticketed HTTP upload leg (remote, hello_ok attachmentUploadV1), chip UI
  in the composer, and a universal preview modal reusing the Files viewers.
- AGENTS.md surface checklist + hazards + PR house style; quality rule 11
  surface sweep; receipts-not-sleeps test doctrine; ship-lane PR template.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .agents/skills/quality/SKILL.md               |   3 +-
 .../quality/references/ade-review-rules.md    |  27 +
 .agents/skills/test/SKILL.md                  |   1 +
 .gitignore                                    |   6 +
 AGENTS.md                                     |  40 +-
 CLAUDE.md                                     |  35 +-
 apps/ade-cli/README.md                        |  41 +
 apps/ade-cli/src/bootstrap.ts                 |   5 +
 apps/ade-cli/src/cli.test.ts                  |  11 +
 apps/ade-cli/src/cli.ts                       | 103 +++
 apps/ade-cli/src/commands/reportIssue.ts      |  12 +
 apps/ade-cli/src/commands/triage.test.ts      | 872 ++++++++++++++++++
 apps/ade-cli/src/commands/triage.ts           | 277 ++++++
 apps/ade-cli/src/commands/triageContext.ts    | 287 ++++++
 apps/ade-cli/src/commands/triageErrors.ts     |  18 +
 apps/ade-cli/src/commands/triageLaunch.ts     | 238 +++++
 apps/ade-cli/src/commands/triagePlaybook.ts   | 304 ++++++
 apps/ade-cli/src/services/imageAttachment.ts  |  40 +-
 .../personalChats/personalChatScope.ts        |   5 +-
 .../sync/attachmentUploadService.test.ts      | 221 +++++
 .../services/sync/attachmentUploadService.ts  | 369 ++++++++
 .../src/services/sync/sharedSyncListener.ts   |  22 +
 .../src/services/sync/syncHostService.ts      |  64 ++
 .../sync/syncRemoteCommandService.test.ts     | 104 ++-
 .../services/sync/syncRemoteCommandService.ts |  48 +-
 .../src/tuiClient/__tests__/adeApi.test.ts    |  29 +
 apps/ade-cli/src/tuiClient/adeApi.ts          |  18 +-
 apps/desktop/package.json                     |   4 +
 apps/desktop/resources/ade-cli-help.txt       |  72 +-
 apps/desktop/scripts/regen-ade-cli-help.cjs   |   1 +
 .../scripts/validate-mac-artifacts.mjs        |   6 +
 .../scripts/validate-win-artifacts.mjs        |   6 +
 apps/desktop/src/main/main.ts                 |   5 +
 .../main/services/adeActions/registry.test.ts | 101 ++
 .../src/main/services/adeActions/registry.ts  |  82 +-
 .../analytics/agentTurnProductAnalytics.ts    |  23 +
 .../analytics/productAnalyticsPolicy.ts       |  10 +
 .../analytics/productAnalyticsService.test.ts |  23 +
 .../services/chat/agentChatService.test.ts    | 610 ++++++++++++
 .../main/services/chat/agentChatService.ts    | 143 ++-
 .../services/chat/attachmentInlineGuard.ts    |  45 +
 .../chat/buildClaudeV2Message.test.ts         |  38 +
 .../services/chat/buildClaudeV2Message.ts     |  11 +
 .../chat/chatAutoResumeCoordinator.test.ts    | 179 ++++
 .../chat/chatAutoResumeCoordinator.ts         | 489 ++++++++++
 .../chat/chatScheduledWorkScheduler.ts        |  12 +
 .../services/chat/heicAttachmentConverter.ts  |  10 +-
 .../services/chat/workerAttachmentImages.ts   |  12 +-
 .../src/main/services/ipc/ipcTimeouts.ts      |   7 +
 .../src/main/services/ipc/registerIpc.ts      |  84 +-
 .../src/main/services/ipc/runtimeBridge.ts    |  43 +
 .../attachmentUploadClient.test.ts            |  75 ++
 .../remoteRuntime/attachmentUploadClient.ts   | 135 +++
 .../attachmentUploadRoute.test.ts             |  80 ++
 .../remoteRuntime/attachmentUploadRoute.ts    |  54 ++
 .../remoteRuntime/remoteConnectionPool.ts     |  29 +
 .../remoteConnectionService.test.ts           | 176 +++-
 .../remoteRuntime/remoteConnectionService.ts  |  78 ++
 .../storage/storageInsightsService.ts         |   3 +-
 apps/desktop/src/preload/global.d.ts          |  13 +-
 apps/desktop/src/preload/preload.ts           |  63 +-
 apps/desktop/src/renderer/browserMock.ts      |   9 +
 .../chat/AgentChatComposer.test.tsx           |  15 +-
 .../components/chat/AgentChatComposer.tsx     | 189 ++--
 .../components/chat/AgentChatMessageList.tsx  |  10 +-
 .../components/chat/AgentChatPane.test.tsx    | 293 ++++++
 .../components/chat/AgentChatPane.tsx         |  93 +-
 .../chat/ChatAttachmentPreviewModal.tsx       | 234 +++++
 .../chat/ChatAttachmentTray.test.tsx          | 141 ++-
 .../components/chat/ChatAttachmentTray.tsx    | 311 ++++---
 .../chat/ProviderFailureRecoveryCard.tsx      |  86 +-
 .../chat/UserMessageIssueContext.tsx          |   8 +
 .../chat/attachmentViewerTarget.test.ts       |  99 ++
 .../components/chat/attachmentViewerTarget.ts |  71 ++
 .../chat/chatAttachmentStaging.test.ts        | 145 +++
 .../components/chat/chatAttachmentStaging.ts  | 169 ++++
 .../renderer/webclient/adapter/agentChat.ts   |  13 +
 .../src/shared/chatAttachmentLimits.ts        |  71 ++
 .../shared/chatAttachmentStagingFs.test.ts    | 221 +++++
 .../src/shared/chatAttachmentStagingFs.ts     | 163 ++++
 .../desktop/src/shared/chatAutoResume.test.ts | 135 +++
 apps/desktop/src/shared/chatAutoResume.ts     | 156 ++++
 apps/desktop/src/shared/ipc.ts                |   3 +
 apps/desktop/src/shared/types/chat.ts         |  39 +
 apps/desktop/src/shared/types/sync.ts         |  15 +
 .../Views/Work/WorkChatAttachmentTray.swift   |   4 +
 apps/ios/ADETests/ADETests.swift              |  58 ++
 docs/ARCHITECTURE.md                          |  20 +-
 docs/features/chat/README.md                  |  59 +-
 docs/features/chat/composer-and-ui.md         |  58 +-
 docs/features/storage-and-recovery/README.md  |  53 ++
 docs/features/sync-and-multi-device/README.md | 106 ++-
 docs/logging.md                               |  37 +
 docs/playbooks/ship-lane.md                   |  10 +
 docs/triage/PLAYBOOK.md                       | 327 +++++++
 reference/cli.mdx                             |   2 +
 reference/troubleshooting.mdx                 |   2 +
 97 files changed, 9015 insertions(+), 332 deletions(-)
 create mode 100644 apps/ade-cli/src/commands/triage.test.ts
 create mode 100644 apps/ade-cli/src/commands/triage.ts
 create mode 100644 apps/ade-cli/src/commands/triageContext.ts
 create mode 100644 apps/ade-cli/src/commands/triageErrors.ts
 create mode 100644 apps/ade-cli/src/commands/triageLaunch.ts
 create mode 100644 apps/ade-cli/src/commands/triagePlaybook.ts
 create mode 100644 apps/ade-cli/src/services/sync/attachmentUploadService.test.ts
 create mode 100644 apps/ade-cli/src/services/sync/attachmentUploadService.ts
 create mode 100644 apps/desktop/src/main/services/chat/attachmentInlineGuard.ts
 create mode 100644 apps/desktop/src/main/services/chat/chatAutoResumeCoordinator.test.ts
 create mode 100644 apps/desktop/src/main/services/chat/chatAutoResumeCoordinator.ts
 create mode 100644 apps/desktop/src/main/services/remoteRuntime/attachmentUploadClient.test.ts
 create mode 100644 apps/desktop/src/main/services/remoteRuntime/attachmentUploadClient.ts
 create mode 100644 apps/desktop/src/main/services/remoteRuntime/attachmentUploadRoute.test.ts
 create mode 100644 apps/desktop/src/main/services/remoteRuntime/attachmentUploadRoute.ts
 create mode 100644 apps/desktop/src/renderer/components/chat/ChatAttachmentPreviewModal.tsx
 create mode 100644 apps/desktop/src/renderer/components/chat/attachmentViewerTarget.test.ts
 create mode 100644 apps/desktop/src/renderer/components/chat/attachmentViewerTarget.ts
 create mode 100644 apps/desktop/src/renderer/components/chat/chatAttachmentStaging.test.ts
 create mode 100644 apps/desktop/src/renderer/components/chat/chatAttachmentStaging.ts
 create mode 100644 apps/desktop/src/shared/chatAttachmentLimits.ts
 create mode 100644 apps/desktop/src/shared/chatAttachmentStagingFs.test.ts
 create mode 100644 apps/desktop/src/shared/chatAttachmentStagingFs.ts
 create mode 100644 apps/desktop/src/shared/chatAutoResume.test.ts
 create mode 100644 apps/desktop/src/shared/chatAutoResume.ts
 create mode 100644 docs/triage/PLAYBOOK.md

diff --git a/.agents/skills/quality/SKILL.md b/.agents/skills/quality/SKILL.md
index 0dcc5dc417..1710d127ee 100644
--- a/.agents/skills/quality/SKILL.md
+++ b/.agents/skills/quality/SKILL.md
@@ -197,7 +197,8 @@ Apply all three reference files:
    null services on bypassed IPC routes, daemon action-domain wiring, cr-sqlite
    CRR constraints, mobile-host compatibility, IPC/preload/shared/renderer
    contract drift, fast-tier loading, Node/test-env gotchas, worktree path
-   discipline.
+   discipline, and the surface coverage sweep (entry points, clients,
+   providers, reverse states, connection modes — rule 11).
 3. **`references/windows-quirks.md`** — the Windows failure classes ADE has
    actually hit and the named helper that resolves each one. Windows parity is
    a default requirement (see **Windows parity rules** above), so this file
diff --git a/.agents/skills/quality/references/ade-review-rules.md b/.agents/skills/quality/references/ade-review-rules.md
index 696ac8a20b..1e082ba68c 100644
--- a/.agents/skills/quality/references/ade-review-rules.md
+++ b/.agents/skills/quality/references/ade-review-rules.md
@@ -156,6 +156,33 @@ these foundation-specific checks apply on top of the default review:
   reboot/restart, installed updates, and GUI artifacts as external proof. Code
   or mocked tests cannot close those gates.
 
+## 11. Surface coverage sweep
+
+**Class:** A change that works on the one path the author tested and is missing
+everywhere else — the single most common defect shape in multi-client, 
+multi-provider repos. This is the review-side enforcement of the AGENTS.md
+"Hit every ADE surface" checklist.
+
+**Check:** For each behavior the diff adds or changes, walk the checklist and
+demand an answer per entry — present, deliberately excluded (where is that
+recorded?), or missed:
+
+- **Entry points:** desktop UI, `ade` CLI, `ade code` TUI, deeplinks, command
+  palette, keybindings. A behavior wired into one entry point but reachable
+  from others is a finding.
+- **Clients:** desktop, hosted web, iOS, TUI. Logic duplicated into one client
+  instead of the shared service/type layer is a finding.
+- **Providers:** Claude / Codex / Cursor / OpenCode / Droid. A provider-shaped
+  feature needs a per-adapter decision; silence for an adapter is a finding,
+  an explicit capability gate is not.
+- **Reverse states:** every new way in needs the way out and the way to see it
+  (snooze/unsnooze, settle/unsettle, link/unlink). A one-way door is a finding.
+- **Connection modes:** local runtime, remote runtime, relay, offline,
+  phone-newer-than-host. A feature that assumes local-only must say so.
+
+Raise one finding per missed surface, severity by reachability: a reachable
+crash or dead control is High; a missing deliberate-exclusion record is Low.
+
 ---
 
 ## Output
diff --git a/.agents/skills/test/SKILL.md b/.agents/skills/test/SKILL.md
index ae34a22880..d362479b55 100644
--- a/.agents/skills/test/SKILL.md
+++ b/.agents/skills/test/SKILL.md
@@ -265,6 +265,7 @@ Rules:
 - Mock only at process boundaries: file system, network, child processes, Electron APIs, IPC.
 - Tests must FAIL LOUDLY — assert preconditions explicitly.
 - Use `node` environment unless DOM is genuinely required.
+- Wait on events, receipts, resolved promises, or fake timers — never on wall-clock sleeps. A test that needs a real `sleep` or a raised timeout to pass is testing a race, not a contract; fix the seam (expose the completion signal) instead of padding the wait.
 
 ### 3d. Run as you write
 
diff --git a/.gitignore b/.gitignore
index bee1ac68c5..06f1075c7d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -104,3 +104,9 @@ apps/web/public/images/updatedImages/
 # Windows CI runner — the checkout, not a test. Ignore them so a broad
 # `git add -A` cannot sweep them in when a test throws before its cleanup.
 *\\*
+
+# Agent work artifacts: research notes an agent writes at the repo root while
+# investigating. They are scratch for one task, never product, and a broad
+# `git add -A` would otherwise sweep them into a PR (AGENTS.md work-artifacts
+# rule). Anything worth keeping goes under docs/.
+T3CODE_RESEARCH_*.md
diff --git a/AGENTS.md b/AGENTS.md
index 9d6847b43b..e7dbacf566 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,8 @@ Day-to-day work follows a five-stage loop, each stage an agent-folder skill unde
 - **/test** — test steward: prune/consolidate/add + docs/mobile/CLI/TUI parity + CI-mirrored shards; records a named regression test or exact alternate verification for every accepted correctness finding.
 - **/ship** — autonomous PR→merge loop (poll → fix → rebase → merge). Run baseline `/quality` and `/test` first; after any ship-loop mutation, ship reruns commit-bound `/quality` revalidation before pushing or merging. Wraps `docs/playbooks/ship-lane.md`.
 
+**"Run the dev loop"** — when the user says this (or "dev loop") after work is implemented, it names one task, not a suggestion: invoke `/quality`, then `/test`, then `/ship`, in that order. Actually invoke each skill — approximating one (running tests is not `/test`; green CI is not `/quality`) does not count. Print each skill's summary, then continue to the next without stopping; stop early only for a genuine blocker (a failing gate or a decision only the user can make) and name it.
+
 Utilities (run when relevant, not part of the core loop): **/audit** (targeted bug hunt), **/finalize** (optional pre-push local-CI gate), **/optimize** (perf profiling), **/release** (cut a release).
 
 ## Playbooks
@@ -28,6 +30,19 @@ Utilities (run when relevant, not part of the core loop): **/audit** (targeted b
 - `docs/playbooks/ship-lane.md` — autonomous PR-to-merge driver (poll → fix → rebase → merge). Baseline `/quality` and `/test` run before it; mutation-specific commit-bound quality revalidation runs inside it. Any agent CLI can follow it directly; Claude Code invokes it via the `/ship` skill.
 - `docs/playbooks/windows-signed-release.md` — maintainer handoff for taking the gated Windows x64 build through signing, clean-host and installed-update proof, draft verification, publication, and website enablement without changing the macOS or iOS release paths.
 
+## Hit every ADE surface
+
+The most common defect class in this repo is a change that works on the path you tested and is missing everywhere else. Before you call a change done (and again in `/quality`), walk this list and state which entries applied:
+
+- **Entry points.** A behavior reachable from the desktop UI is usually also reachable from the `ade` CLI, the `ade code` TUI, deeplinks, the command palette, and keybindings. Fixing one entry point is not fixing the feature.
+- **Clients.** Desktop (Electron), hosted web, iOS, and the TUI attach to the same brain. Shared logic belongs in shared services and types, not re-implemented per client.
+- **Providers.** Claude, Codex, Cursor, OpenCode, and Droid each have an adapter with different capabilities. A provider-shaped feature needs a decision per adapter, even when the decision is "not supported here" — record it in the capability gate, not by silence.
+- **Contracts.** Anything crossing a boundary is typed once: main-process handler, `src/shared` types, preload exposure, renderer caller, daemon action domain, tests/mocks. Change the contract and all of them move together.
+- **Reverse states.** If you add a way in, add the way out and the way to see it. Snooze needs unsnooze; settle needs unsettle; a link needs unlink. A one-way door is a bug.
+- **Connection modes.** Local runtime, remote runtime, and relay behave differently. Multi-device and offline cases are real; the phone can be newer than the host.
+- **Windows.** Parity is part of "done" for all new code, never a follow-up.
+- **Docs.** User-visible behavior changes update the matching `docs/features/` doc in present tense.
+
 ## Working norms
 
 - Preserve existing desktop app patterns before introducing new abstractions.
@@ -37,6 +52,28 @@ Utilities (run when relevant, not part of the core loop): **/audit** (targeted b
 - For computer-use changes, treat policy enforcement and artifact ownership as hard requirements, not prompt guidance.
 - `ade search "<query>" --text` searches everything in ADE (chats, terminal scrollback, PRs, commits, branches, lanes, files, Linear) instead of grepping `.ade/` internals; see the ade-search skill.
 
+## Ways to hurt yourself
+
+These are the operational hazards of developing ADE from inside ADE. Each one has caused real damage.
+
+1. **Killing by pattern.** Do not `pkill -f`, `pgrep | kill`, or kill a PID you found by matching a name or path. Your own agent process carries this worktree's path in its argv, `pgrep -f xcodebuild` also matches xcodebuildmcp and its wrapper shell, and this machine runs the real ADE brain plus other dev runtimes. Kill only a PID you captured at spawn time, after confirming its cwd is your worktree.
+2. **Writing to live state.** The project root's `.ade/` (database, secrets, artifacts) and the installed brain are the developer's real, in-use ADE instance. Read from them for realistic data; never point a dev server at them, never open them read-write, never "clean them up". Isolated dev state belongs under your worktree or a temp directory.
+3. **Editing outside the lane worktree.** Every edit targets `.ade/worktrees/<lane>/...`, never the project-root checkout. Search tools may print root-checkout paths — translate them before editing, or the change lands on the wrong branch.
+4. **Restarting shared runtimes casually.** `ensureRuntime`-style commands can restart a brain another session is using. Check what is running before starting or restarting sockets, brains, or dev servers.
+
+## Work artifacts
+
+- Keep implementation plans, research notes, and agent scratch files out of the repository. They are inputs to the work, not project documentation. The merged PR is the implementation record.
+- Docs describe the present tense. When behavior changes, update the matching `docs/features/` doc in the same branch. A task-tracking list in a feature doc must be kept current by the branch that changes the feature, or deleted — a stale checklist misleads every later agent.
+- Track future work in Linear (see the ade-linear skill), not in committed TODO files.
+
+## Pull requests
+
+- Conventional commit titles in plain language: `fix(desktop): new chats no longer spike CPU`.
+- Body house style, in order: **Problem** (a sentence or two), **Cause** (when known), **Change and boundary** (what moved, what deliberately did not), **Verification** (the exact focused tests/typechecks run and their counts). End with the model and harness that did the work.
+- UI changes need before/after images. Motion or timing needs a short video. Upload evidence to GitHub; never commit screenshots or PR-only assets to the repo.
+- One concern per PR. If the description says "also", consider splitting it.
+
 ## Validation
 
 - Desktop checks:
@@ -48,8 +85,9 @@ Utilities (run when relevant, not part of the core loop): **/audit** (targeted b
   - `npm --prefix apps/ade-cli run typecheck`
   - `npm --prefix apps/ade-cli run test`
   - `npm --prefix apps/ade-cli run build`
-- Run the smallest relevant subset first when iterating, then finish with the broader checks that cover the touched surfaces.
+- **Smallest proof first.** Run the narrowest check that proves the change: the touched test files, a scoped typecheck, one shard. Do not run full local suites by default — CI owns the full matrix, and `/finalize` is the opt-in local full gate before a push.
 - Run full desktop tests with the root `npm run test:desktop:sharded` command; use single-file or single-shard Vitest commands for iteration.
+- Tests wait on events, receipts, and promises — never on wall-clock sleeps. A test that needs a `sleep` or a raised timeout to pass is wrong; fix the seam instead.
 - Installing deps: use `npm run install:apps` from the repo root, or `cd apps/<app> && npm install`. Never `npm --prefix apps/<app> install`. `--prefix` only redirects where npm writes `node_modules`; the package npm treats as "the one being installed" is still the one in the *current working directory*. From the repo root that is the root package `ade`, so npm installs the repo into the sub-app: it writes `"ade": "file:../.."` into the app's `package.json` and `package-lock.json` and leaves an `apps/<app>/node_modules/ade` symlink back to the root. Revert that churn if you hit it. `npm --prefix apps/<app> run <script>` and `npm --prefix apps/<app> exec` do not install anything and are unaffected -- but note `exec` runs Vitest with the *current* working directory, so run whole suites as `cd apps/<app> && npx vitest run` or the app's own `npm run test`.
 
 ## Terminology
diff --git a/CLAUDE.md b/CLAUDE.md
index a93e9ff074..f46de5b606 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,34 +1,5 @@
-## Picking the right models for work delegation
+## Model roles (Claude-specific)
 
-**Applicability — read this first.** Everything below describes the *Fable-orchestrated* workflow:
-Fable 5 does the thinking and writes specs, gpt-5.6-sol executes them. **It applies only when the
-orchestrating agent is Fable 5.** If you are any other model — Opus, Sonnet, or anything else —
-this section does not govern your delegation, and you should not route work to Codex/gpt-5.6-sol
-on its account. Check what model you are before applying any of it.
+If you are Fable 5, you are always the PM/coordinator. You research, decide, and write the specs; you do not implement by default. Delegate the implementation to Claude Opus 5 subagents — medium effort for routine tasks, high effort for hard ones. Judge each result on its merits; if a subagent's output misses the bar, tighten the spec or raise the effort and redo it.
 
-**If you are not Fable:** do the work yourself, and delegate to `opus` subagents (Claude Opus 5)
-when you need parallelism, an independent review perspective, or a second opinion. Sonnet is
-acceptable only for genuinely trivial mechanical subtasks; never use Haiku. You may still use
-Codex deliberately — for an independent review via `codex review`, or when the user asks for it —
-but not as your default implementation path.
-
-### The Fable-orchestrated tiers
-
-Three tiers. Fable 5 for thinking, gpt-5.6-sol for building, Opus 5 for everything in between.
-With a tight, self-contained prompt Opus also handles implementation well when gpt-5.6-sol is
-unavailable.
-
-| model    | use for |
-|----------|---------|
-| fable-5  | Deep research, architecture/design decisions, hard debugging, anything requiring sustained reasoning or judgment. Also the orchestrator: it writes the specs and prompts the other models execute. |
-| gpt-5.6-sol (high/xhigh) | Pure implementation once a strong, self-contained prompt exists: clear-spec features, migrations, mechanical refactors, test writing, data analysis. Effectively free — use liberally. |
-| opus-5 | Everything else: reviews, moderate-complexity tasks, user-facing polish, second opinions. |
-
-How to apply:
-- The division of labor is think-then-delegate: Fable does the research and produces a detailed spec; gpt-5.6-sol executes it. Never hand gpt-5.6-sol an underspecified task — it can't ask clarifying questions mid-run, so the prompt must contain all context, file paths, constraints, and acceptance criteria.
-- These are defaults, not limits. If a model's output doesn't meet the bar, redo the work with a smarter model without asking. Judge the output, not the price tag.
-- Mechanics for gpt-5.6-sol: it's only reachable through the Codex CLI. Run `codex exec -m gpt-5.6-sol "<self-contained prompt>"` via Bash — my ~/.codex/config.toml defaults to gpt-5.6-sol at xhigh reasoning; pass `-m gpt-5.6-sol` (and `-c model_reasoning_effort=xhigh`) explicitly whenever the config default differs. Use `codex exec -s read-only` for investigation/analysis; use `codex exec resume --last` to iterate on a prior run. `codex review` for an independent review perspective.
-- Invoking codex from an agent shell (IMPORTANT): always close stdin and write output to a log file — `codex exec "<prompt>" </dev/null >"$LOG" 2>&1`, backgrounded. In non-interactive shells stdin is an open pipe and codex blocks forever on "Reading additional input from stdin..." before doing any work; piping stdout through `tail`/`head` buffers everything so you can't see progress. Verify it's actually working by checking the log grows and a new session file appears under `~/.codex/sessions/<date>/`; no session file after ~2 min = wedged, kill and relaunch.
-- Mechanics for Claude models: use the Agent/Workflow `model` parameter (`fable`, `opus`).
-- Inside Workflows (where the model parameter only takes Claude models), reach gpt-5.6-sol via a thin wrapper: spawn an `opus` agent whose prompt says "run the following via `codex exec` in Bash and return its output verbatim, then verify the result compiles/passes tests before returning."
-- Reviews of anything that ships: fable-5 or opus-5, optionally `codex review` as an extra independent perspective.
+If you are any other Claude model, do the work yourself, and use Opus 5 subagents when you need parallelism or an independent second opinion.
diff --git a/apps/ade-cli/README.md b/apps/ade-cli/README.md
index bb50217ddd..03dd9b042d 100644
--- a/apps/ade-cli/README.md
+++ b/apps/ade-cli/README.md
@@ -472,6 +472,9 @@ ade doctor --online --text                        # also check the latest deskto
 ade report-issue --text                           # print a redacted diagnostic report + a prefilled GitHub issue URL (local files only; no brain needed)
 ade report-issue --open                           # also copy the report to the clipboard and open that issue URL in the browser
 ade report-issue --send                           # also upload the same redacted report to ADE and print its reference id
+ade triage                                        # build a redacted context.md + repair playbook and hand them to your first installed agent CLI
+ade triage --provider codex                       # pick the agent CLI (claude | codex | cursor-agent | opencode | droid)
+ade triage --agent --json                         # launch nothing: print contextPath, playbookPath, playbookSource, suggestedPrompt, detected agents
 ade tools status --text                           # pinned agent CLIs: installed version + entry path per tool, plus the machine tools root
 ade tools ensure --text                           # fetch whatever this build pins and is missing (no names = all); streams progress to stderr
 ade tools ensure codex --text                     # one tool; an unknown name is a usage error listing the pinned set
@@ -565,6 +568,7 @@ ade session clear-woke session-id                           # drop the "woke ear
 ade session actions --text                                  # raw session service actions
 ade chat schedules session-id --pause              # pause this agent session's durable wakeups/cron/loops (omit flag to inspect, --resume to re-arm)
 ade chat scheduled-work list [session-id] --all     # list durable jobs; --all includes recent terminal history
+                                                   # a row ADE armed itself carries source:"auto_resume_limit"; user- and agent-created rows carry no source
 ade chat scheduled-work create --in 12m --prompt "Check CI and report" --reason "CI check" --session session-id              # safest one-shot form; omit --session inside the bound agent
 ade chat scheduled-work create --at "2026-07-23T01:05:00-04:00" --prompt "Check CI and report"                           # absolute one-shot; explicit offset or Z required
 ade chat scheduled-work create --cron "9,29,49 * * * *" --prompt "Check CI and report" --once                         # five-field cron uses the ADE brain machine's local timezone
@@ -809,6 +813,43 @@ file the issue by hand. With `--json`, `sent` is present only when `--send` was
 asked for, as `{ ok: true, reference }` or `{ ok: false, reason }`, so a script
 can tell "not requested" from "requested and failed".
 
+`ade triage` is the third step after those two: `doctor` says which check
+failed, `report-issue` produces something to file, and `triage` hands the repair
+to the user's own coding agent. It runs the same doctor checks and the same
+redacted diagnostic collection, writes them as a single `context.md` into a
+fresh temp directory (`ade-triage-<timestamp>-<random>/`) alongside a repair
+playbook, and then launches the first agent CLI it finds — `claude`, `codex`,
+`cursor-agent`, `opencode`, `droid`, in that order, resolved through the same
+PATHEXT-aware lookup ADE uses everywhere, so a Windows `codex.cmd` shim is
+found and an unlaunchable extension-less sibling is not. The agent inherits
+stdio, so the user talks to it directly; `ade triage` exits with the agent's
+exit code and prints nothing on stdout in that mode (both paths are printed on
+stderr before the launch). `--provider <name>` picks one. OpenCode is launched
+bare because its positional argument is a project directory rather than a
+prompt, and the prompt is printed for pasting instead.
+
+The playbook is `docs/triage/PLAYBOOK.md` in this repository — safety rules
+first (read-only diagnosis before mutation, never delete anything under `.ade/`
+or `$ADE_HOME`, never kill by name or pattern, ask before destructive steps),
+then a failure class per doctor row with the exact read-only command to run.
+It is fetched from `main` on each run with a 3s timeout so a fix does not have
+to wait for an ADE release, falling back to the copy on this machine and finally
+to a reduced built-in one; `playbookSource` (`remote` / `local`) and
+`playbookOrigin` say which won. `ADE_TRIAGE_NO_FETCH=1` skips the fetch,
+`ADE_TRIAGE_PLAYBOOK=<path>` overrides the local copy.
+
+`ade triage --agent` launches nothing: it prints `mode`, `contextPath`,
+`playbookPath`, `playbookSource`, `playbookOrigin`, `suggestedPrompt`, the
+detected agent CLIs and a `message`, and exits 0. That is the mode for an agent
+that is already running — an ADE Work chat triaging its own machine — and a
+machine with no agent CLI installed gets the same payload unasked, with a
+message saying so, rather than a failure. Branch on `mode`, not on the exit
+code: `agent` was asked for, `no-provider` means nothing was installed to
+launch, and `launch` means an agent ran — that last one prints nothing on
+stdout and exits with the agent's own code. The context file is redacted with
+the same rules as `ade report-issue`: it never contains credentials, and it is
+written to a temp directory rather than into the project.
+
 There is no `ade recovery diagnose` / `ade recovery repair`: those are
 Electron-main IPC (`ade.recovery.diagnose` / `ade.recovery.repair`) backed by
 the desktop's local-runtime connection pool, which does not exist in a headless
diff --git a/apps/ade-cli/src/bootstrap.ts b/apps/ade-cli/src/bootstrap.ts
index 105ef174d5..38652980a2 100644
--- a/apps/ade-cli/src/bootstrap.ts
+++ b/apps/ade-cli/src/bootstrap.ts
@@ -135,6 +135,7 @@ import {
 } from "../../desktop/src/main/services/analytics/dailyUsageAnalytics";
 import {
   captureAgentTurnSettledAnalytics,
+  captureChatAutoResumeAnalytics,
   captureChatMentionsExpandedAnalytics,
   captureSessionMetadataRegeneratedAnalytics,
 } from "../../desktop/src/main/services/analytics/agentTurnProductAnalytics";
@@ -1427,6 +1428,10 @@ export async function createAdeRuntime(args: {
           projectId,
           event,
         }),
+        onAutoResumeOutcome: (properties) => captureChatAutoResumeAnalytics({
+          analytics: productAnalyticsService,
+          properties,
+        }),
         onSessionEnded: (event) => {
           pushEvent("runtime", { type: "agent_chat_session_ended", ...event });
         },
diff --git a/apps/ade-cli/src/cli.test.ts b/apps/ade-cli/src/cli.test.ts
index 777cd3b072..9cfc1240bc 100644
--- a/apps/ade-cli/src/cli.test.ts
+++ b/apps/ade-cli/src/cli.test.ts
@@ -6666,6 +6666,17 @@ describe("ADE CLI", () => {
     expect(buildCliPlan(["doctor", "--online"])).toEqual({ kind: "doctor", online: true });
   });
 
+  // `ade triage` is the command for a machine where the brain is down, so its
+  // parse must stay local: no socket, no project, and a bad `--provider` has to
+  // surface as usage ("Run 'ade help'") rather than a stack trace.
+  it("builds triage locally and resolves provider aliases at parse time", () => {
+    expect(buildCliPlan(["triage"])).toEqual({ kind: "triage", agent: false, provider: null });
+    expect(buildCliPlan(["triage", "--agent", "--provider", "cursor"]))
+      .toEqual({ kind: "triage", agent: true, provider: "cursor-agent" });
+    expect(() => buildCliPlan(["triage", "--provider", "gemini"]))
+      .toThrow(/Unknown provider 'gemini'/);
+  });
+
   it.skipIf(process.platform === "win32")("bounds doctor when a dead socket accepts a connection but never responds", async () => {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), "ade-cli-doctor-dead-sock-"));
     const socketPath = path.join(root, "ade.sock");
diff --git a/apps/ade-cli/src/cli.ts b/apps/ade-cli/src/cli.ts
index 8475802f1b..2cda981a64 100644
--- a/apps/ade-cli/src/cli.ts
+++ b/apps/ade-cli/src/cli.ts
@@ -41,6 +41,15 @@ import {
   saveDiagnosticReportCopy,
   sendDiagnosticReport,
 } from "./commands/reportIssue";
+import {
+  formatTriageText,
+  parseTriageProviderName,
+  runTriageCommand,
+  TRIAGE_NO_FETCH_ENV,
+  TriageCommandError,
+  TriageUsageError,
+  type TriageProviderName,
+} from "./commands/triage";
 import { redactDiagnosticText } from "./services/diagnostics/diagnosticReport";
 export { readInstalledDesktopVersion };
 import {
@@ -444,6 +453,7 @@ type CliPlan =
   | { kind: "connect"; rest: string[] }
   | { kind: "doctor"; online: boolean }
   | { kind: "report-issue"; open: boolean; send: boolean }
+  | { kind: "triage"; agent: boolean; provider: TriageProviderName | null }
   | { kind: "serve"; rest: string[] }
   | { kind: "rpc-stdio"; rest: string[] }
   | { kind: "pty-host-worker" }
@@ -743,6 +753,7 @@ const TOP_LEVEL_HELP = `${ADE_BANNER}
     $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor [--online]                         Inspect installed app and machine-brain health
     $ ade report-issue [--open] [--send]            Print a redacted diagnostic report; --send hands it to ADE
+    $ ade triage [--agent] [--provider <name>]      Build a triage context + playbook and hand the repair to your coding agent
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
     $ ade operations status | wait                  Poll operation/test/chat/run status
@@ -1296,6 +1307,42 @@ const IOS_SIMULATOR_HELP_ALIASES: Record<string, string> = {
 };
 
 const HELP_BY_COMMAND: Record<string, string> = {
+  triage: `${ADE_BANNER}
+  ADE Triage
+
+  Hand a broken ADE install to your own coding agent. Runs the same checks as
+  "ade doctor" and collects the same redacted diagnostics as "ade report-issue",
+  writes them plus a maintained repair playbook into a fresh temp directory, and
+  then starts whichever agent CLI is installed so you can work the fix with it.
+
+  The playbook is fetched from GitHub when the network allows (3s timeout) and
+  falls back to the copy shipped with this build; the output says which won.
+
+    $ ade triage                          Launch the first installed agent CLI
+    $ ade triage --provider codex         Launch a specific one
+    $ ade triage --agent --json           Print the handoff for an agent already running
+    $ ade triage --agent --text           The same, human-readable
+
+  Flags:
+    --agent                Launch nothing; print contextPath, playbookPath,
+                           playbookSource, suggestedPrompt and the detected
+                           agent CLIs. Use this from inside an agent session.
+    --provider <name>      claude | codex | cursor-agent | opencode | droid.
+    --text                 Human-readable output.
+    --json                 Structured JSON output (default).
+
+  Notes:
+    Detection order is claude, codex, cursor-agent, opencode, droid. With no
+    agent CLI installed, triage prints the --agent output and exits 0 — the
+    files are the deliverable, the launch is a convenience.
+    When an agent is launched the terminal belongs to it: the file paths are
+    printed on stderr before it starts, stdout stays empty, and triage exits
+    with the agent's own exit code.
+    The context file is redacted with the same rules as "ade report-issue"; it
+    never contains credentials, and it is written to a temp directory, not into
+    your project.
+    Set ${TRIAGE_NO_FETCH_ENV}=1 to skip the playbook fetch entirely.
+`,
   connect: `${ADE_BANNER}
   ADE Connect
 
@@ -13085,6 +13132,19 @@ function buildCliPlan(
       send: readFlag(args, ["--send"]),
     };
   }
+  if (primary === "triage") {
+    const provider = readValue(args, ["--provider", "--agent-cli"]);
+    try {
+      return {
+        kind: "triage",
+        agent: readFlag(args, ["--agent"]),
+        provider: provider == null ? null : parseTriageProviderName(provider),
+      };
+    } catch (error) {
+      if (error instanceof TriageUsageError) throw new CliUsageError(error.message);
+      throw error;
+    }
+  }
   if (primary === "auth") {
     const sub = firstPositional(args) ?? "status";
     if (sub !== "status")
@@ -23242,6 +23302,49 @@ async function runCli(
         exitCode: 0,
       };
     }
+    if (plan.kind === "triage") {
+      const { projectRoot } = resolveRoots(parsed.options);
+      const { payload, exitCode } = await runTriageCommand(
+        { agent: plan.agent, provider: plan.provider },
+        {
+          cliVersion: VERSION,
+          projectRoot: fs.existsSync(path.join(projectRoot, ".ade")) ? projectRoot : null,
+          // The same probe `ade doctor` runs. It may fail outright — that is the
+          // machine this command exists for — and `runTriageCommand` records the
+          // failure in the context file instead of taking the handoff down.
+          runDoctor: () =>
+            runDoctorCommand(false, parsed.options, {
+              resolveMachineRuntimeSocketPath,
+              connectRuntime: (socketPath, timeoutMs, label) =>
+                SocketJsonRpcClient.connect(socketPath, timeoutMs, label),
+              buildInitializeParams,
+              readMachineRuntimeInfo,
+              resolveExpectedMachineRuntimeBuildHash,
+              machineRuntimeMismatchReason,
+              unwrapActionEnvelope,
+            }),
+        },
+      ).catch((error: unknown) => {
+        // A full temp directory or an agent CLI that will not start is a
+        // failure of this command, not a crash: print the sentence that names
+        // the path, not a stack trace, to the person whose machine is already
+        // broken.
+        if (error instanceof TriageCommandError) throw new CliToolError(error.message, undefined);
+        throw error;
+      });
+      // Nothing on stdout once an agent has been launched: the terminal was
+      // handed to it, and printing a JSON blob (the default format) after the
+      // user quits their session is noise. The pre-launch notice on stderr
+      // already named both files. `--agent` is the machine-readable path.
+      if (payload.mode === "launch") return { output: "", exitCode };
+      if (parsed.options.text) {
+        return { output: formatTriageText(payload), exitCode };
+      }
+      return {
+        output: formatOutput(payload, parsed.options, undefined),
+        exitCode,
+      };
+    }
     if (plan.kind === "doctor") {
       const result = await runDoctorCommand(plan.online, parsed.options, {
         resolveMachineRuntimeSocketPath,
diff --git a/apps/ade-cli/src/commands/reportIssue.ts b/apps/ade-cli/src/commands/reportIssue.ts
index 0eba785030..413e2a3a1e 100644
--- a/apps/ade-cli/src/commands/reportIssue.ts
+++ b/apps/ade-cli/src/commands/reportIssue.ts
@@ -6,6 +6,7 @@ import {
   buildDiagnosticReport,
   diagnosticReportFilePath,
   writeDiagnosticReportFile,
+  type DiagnosticRedactionContext,
 } from "../services/diagnostics/diagnosticReport";
 import {
   collectMachineDiagnosticSources,
@@ -60,6 +61,16 @@ export type ReportIssueResult = {
    * sender saves to, so the desktop toast's "View" reaches a CLI report too.
    */
   reportsDir: string;
+  /**
+   * The redaction rules this report was built with — this machine's home
+   * directory, account name, host name, project roots.
+   *
+   * Returned so a caller that writes its own sections beside the report
+   * (`ade triage` builds a context file around it) redacts them with the same
+   * rules rather than inventing a second, weaker set. Collection is what makes
+   * these expensive; handing them back costs nothing.
+   */
+  redaction: DiagnosticRedactionContext;
 };
 
 /**
@@ -138,6 +149,7 @@ function finishCliDiagnosticReport(
     appVersion: options.cliVersion ?? null,
     secretsDir: sources.layout.secretsDir,
     reportsDir: path.join(sources.layout.adeDir, "diagnostic-reports"),
+    redaction: sources.redaction,
     issueUrl: buildDiagnosticIssueUrl({
       surface,
       headline: options.headline?.trim().slice(0, 300) || null,
diff --git a/apps/ade-cli/src/commands/triage.test.ts b/apps/ade-cli/src/commands/triage.test.ts
new file mode 100644
index 0000000000..9ed1fb7b4f
--- /dev/null
+++ b/apps/ade-cli/src/commands/triage.test.ts
@@ -0,0 +1,872 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { resolveExecutableFromKnownLocations } from "../../../desktop/src/main/services/ai/cliExecutableResolver";
+import type { DoctorCommandResult } from "./doctor";
+import type { ReportIssueResult } from "./reportIssue";
+import { runTriageCommand } from "./triage";
+import {
+  buildTriageContext,
+  buildTriagePrompt,
+  createTriageBundleDir,
+  extractRecentErrorLines,
+  orderTriageDoctorRows,
+} from "./triageContext";
+import {
+  buildTriageLaunchPlan,
+  defaultTriageExecutableResolver,
+  detectTriageProviders,
+  parseTriageProviderName,
+  TRIAGE_PROVIDERS,
+  type DetectedTriageProvider,
+  type TriageLaunchPlan,
+} from "./triageLaunch";
+import { TriageUsageError } from "./triageErrors";
+import {
+  readLocalTriagePlaybook,
+  resolveTriagePlaybook,
+  TRIAGE_NO_FETCH_ENV,
+  TRIAGE_PLAYBOOK_PATH_ENV,
+  TRIAGE_PLAYBOOK_REMOTE_URL,
+} from "./triagePlaybook";
+
+const tempDirs: string[] = [];
+
+function tempDir(prefix = "ade-triage-test-"): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const AT = new Date("2026-08-29T10:00:00.000Z");
+
+function doctorResult(overrides: Partial<DoctorCommandResult> = {}): DoctorCommandResult {
+  return {
+    ok: false,
+    checkedAt: AT.toISOString(),
+    online: false,
+    rows: [
+      { key: "app", label: "App", status: "ok", detail: "1.2.68 installed" },
+      { key: "storage", label: "Storage", status: "warn", detail: "Project on iCloud Drive" },
+      { key: "brain", label: "Brain", status: "fail", detail: "Not responding on the socket" },
+    ],
+    app: {
+      installedVersion: "1.2.68",
+      latestKnownVersion: "1.2.68",
+      path: "/Applications/ADE.app",
+      online: false,
+    },
+    brain: {
+      running: false,
+      version: null,
+      buildHash: null,
+      pid: null,
+      uptimeMs: null,
+      mismatchReason: null,
+      error: "connect ENOENT",
+    },
+    wedge: null,
+    syncPort: null,
+    portDiagnoses: [],
+    publishHealth: null,
+    relayHealth: null,
+    account: { signedIn: null, source: null, error: null },
+    credentials: null,
+    storage: null as unknown as DoctorCommandResult["storage"],
+    diagnostics: { enabled: true, sendsInWindow: 0, limit: 3 },
+    ...overrides,
+  };
+}
+
+function reportResult(overrides: Partial<ReportIssueResult> = {}): ReportIssueResult {
+  const adeDir = tempDir("ade-triage-home-");
+  return {
+    report: "# ADE diagnostic report\n\nEverything nominal.\n",
+    issueUrl: "https://github.com/arul28/ADE/issues/new",
+    installId: "install-1",
+    appVersion: "1.2.68",
+    secretsDir: path.join(adeDir, "secrets"),
+    reportsDir: path.join(adeDir, "diagnostic-reports"),
+    redaction: { homeDir: "/Users/ada", username: "ada", hostname: "ada-mbp", projectRoots: [] },
+    ...overrides,
+  };
+}
+
+function contextInput(
+  overrides: Partial<Parameters<typeof buildTriageContext>[0]> = {},
+): Parameters<typeof buildTriageContext>[0] {
+  return {
+    generatedAt: AT,
+    cliVersion: "1.2.68",
+    platform: "darwin",
+    arch: "arm64",
+    osRelease: "25.3.0",
+    nodeVersion: "22.13.0",
+    projectRoot: null,
+    adeHome: "/Users/ada/.ade",
+    socketPath: "/Users/ada/.ade/sock/ade.sock",
+    layoutError: null,
+    doctor: doctorResult(),
+    doctorError: null,
+    report: "# ADE diagnostic report\n\nnothing here\n",
+    reportError: null,
+    redaction: { homeDir: "/Users/ada", username: "ada", hostname: "ada-mbp", projectRoots: [] },
+    playbook: { source: "local", origin: "/repo/docs/triage/PLAYBOOK.md", path: "/tmp/x/PLAYBOOK.md" },
+    ...overrides,
+  };
+}
+
+describe("buildTriageContext", () => {
+  it("puts failing doctor rows first and names the install", () => {
+    const context = buildTriageContext(contextInput());
+
+    const failIndex = context.indexOf("| Brain |");
+    const warnIndex = context.indexOf("| Storage |");
+    const okIndex = context.indexOf("| App |");
+    expect(failIndex).toBeGreaterThan(-1);
+    expect(failIndex).toBeLessThan(warnIndex);
+    expect(warnIndex).toBeLessThan(okIndex);
+    expect(context).toContain("1 failing row(s), listed first");
+    expect(context).toContain("ADE CLI version: 1.2.68");
+    expect(context).toContain("platform: darwin arm64");
+    expect(context).toContain("node: 22.13.0");
+    expect(context).toContain("responding: no");
+    expect(context).toContain("PLAYBOOK.md");
+  });
+
+  // The context file is written for someone to hand to a third-party agent, so
+  // the redaction that protects `ade report-issue` has to cover everything this
+  // command adds around it — including doctor row details, which are built by
+  // doctor.ts and never passed through the report's own redaction pass.
+  it("redacts home paths, account names, emails and tokens from every section", () => {
+    const context = buildTriageContext(contextInput({
+      doctor: doctorResult({
+        rows: [
+          {
+            key: "credentials",
+            label: "Credentials",
+            status: "fail",
+            detail: "Could not read /Users/ada/.ade/secrets/credentials.json.enc",
+          },
+        ],
+      }),
+      report: [
+        "# ADE diagnostic report",
+        "",
+        "signed in as ada@example.com on ada-mbp",
+        "authorization: Bearer sk-ant-api03-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        "error: open /Users/ada/.ade/ade.db failed",
+      ].join("\n"),
+    }));
+
+    expect(context).not.toContain("/Users/ada");
+    expect(context).not.toContain("ada@example.com");
+    expect(context).not.toContain("ada-mbp");
+    expect(context).not.toContain("sk-ant-api03-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA");
+    // Still useful: the redacted shape keeps the fact, drops the identity.
+    expect(context).toContain("credentials.json.enc");
+  });
+
+  it("records a doctor probe that could not run instead of implying the checks passed", () => {
+    const context = buildTriageContext(contextInput({
+      doctor: null,
+      doctorError: "runtime socket unavailable",
+    }));
+
+    expect(context).toContain("could not complete: runtime socket unavailable");
+    expect(context).toContain("not probed");
+  });
+
+  it("says the diagnostic report could not be collected instead of showing an empty one", () => {
+    const context = buildTriageContext(contextInput({
+      report: "",
+      reportError: "ENOSPC: no space left on device",
+    }));
+
+    expect(context).toContain("could not be collected: ENOSPC: no space left on device");
+    // The absent report must not read as a clean one.
+    expect(context).not.toContain("versions, service");
+  });
+
+  it("says the ADE home could not be resolved instead of printing a guessed path", () => {
+    const context = buildTriageContext(contextInput({
+      adeHome: null,
+      socketPath: null,
+      layoutError: "EACCES reading the home directory",
+    }));
+
+    expect(context).toContain("ADE home: unknown");
+    expect(context).toContain("could not be resolved: EACCES reading the home directory");
+  });
+});
+
+describe("orderTriageDoctorRows / extractRecentErrorLines", () => {
+  it("orders fail, then warn, then ok", () => {
+    const ordered = orderTriageDoctorRows(doctorResult().rows);
+    expect(ordered.map((row) => row.status)).toEqual(["fail", "warn", "ok"]);
+  });
+
+  it("keeps only error-shaped lines, most recent last", () => {
+    const lines = extractRecentErrorLines(
+      [
+        "all good",
+        "brain.jsonl: EADDRINUSE 0.0.0.0:8787",
+        "# heading with error in it",
+        "database is locked",
+      ].join("\n"),
+    );
+    expect(lines).toEqual(["brain.jsonl: EADDRINUSE 0.0.0.0:8787", "database is locked"]);
+  });
+});
+
+describe("resolveTriagePlaybook", () => {
+  function localOnlyOptions(): {
+    cwd: string;
+    dirname: string;
+    argv1: null;
+    resourcesPath: null;
+    env: NodeJS.ProcessEnv;
+  } {
+    // Point every search root at empty directories so the repo's own committed
+    // copy cannot satisfy a test that is about the fallback.
+    const empty = tempDir("ade-triage-empty-");
+    return { cwd: empty, dirname: empty, argv1: null, resourcesPath: null, env: {} };
+  }
+
+  /** A minimal ADE install tree: `<root>/apps/ade-cli/dist` + the doc. */
+  function installTree(): { entryDir: string; playbookPath: string } {
+    const root = tempDir("ade-triage-install-");
+    const entryDir = path.join(root, "apps", "ade-cli", "dist");
+    fs.mkdirSync(entryDir, { recursive: true });
+    const playbookPath = path.join(root, "docs", "triage", "PLAYBOOK.md");
+    fs.mkdirSync(path.dirname(playbookPath), { recursive: true });
+    fs.writeFileSync(playbookPath, "# install playbook\n", "utf8");
+    return { entryDir, playbookPath };
+  }
+
+  it("prefers the copy on GitHub main and records it as remote", async () => {
+    const fetchImpl = vi.fn(async () => new Response("# remote playbook\n", { status: 200 }));
+
+    const playbook = await resolveTriagePlaybook({
+      ...localOnlyOptions(),
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(playbook.source).toBe("remote");
+    expect(playbook.origin).toBe(TRIAGE_PLAYBOOK_REMOTE_URL);
+    expect(playbook.text).toContain("remote playbook");
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it("refuses to follow a redirect off the pinned URL", async () => {
+    const dir = tempDir();
+    const localPath = path.join(dir, "PLAYBOOK.md");
+    fs.writeFileSync(localPath, "# local playbook\n", "utf8");
+    let seenRedirect: RequestRedirect | undefined;
+    // This is the text a coding agent is about to be pointed at, so a proxy or
+    // a hijacked DNS answer must not be able to substitute its own.
+    const fetchImpl = vi.fn(async (_url: string, init?: RequestInit) => {
+      seenRedirect = init?.redirect;
+      if (init?.redirect === "error") throw new TypeError("unexpected redirect");
+      return new Response("# attacker playbook\n", { status: 200 });
+    });
+
+    const playbook = await resolveTriagePlaybook({
+      ...localOnlyOptions(),
+      env: { [TRIAGE_PLAYBOOK_PATH_ENV]: localPath },
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(seenRedirect).toBe("error");
+    expect(playbook.source).toBe("local");
+    expect(playbook.text).toContain("local playbook");
+  });
+
+  it("falls back to the local copy when the fetch fails", async () => {
+    const dir = tempDir();
+    const localPath = path.join(dir, "PLAYBOOK.md");
+    fs.writeFileSync(localPath, "# local playbook\n", "utf8");
+    const fetchImpl = vi.fn(async () => {
+      throw new Error("getaddrinfo ENOTFOUND raw.githubusercontent.com");
+    });
+
+    const playbook = await resolveTriagePlaybook({
+      ...localOnlyOptions(),
+      env: { [TRIAGE_PLAYBOOK_PATH_ENV]: localPath },
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(playbook.source).toBe("local");
+    expect(playbook.origin).toBe(localPath);
+    expect(playbook.text).toContain("local playbook");
+  });
+
+  it("falls back to the local copy on a non-200 response", async () => {
+    const dir = tempDir();
+    const localPath = path.join(dir, "PLAYBOOK.md");
+    fs.writeFileSync(localPath, "# local playbook\n", "utf8");
+
+    const playbook = await resolveTriagePlaybook({
+      ...localOnlyOptions(),
+      env: { [TRIAGE_PLAYBOOK_PATH_ENV]: localPath },
+      fetchImpl: (async () => new Response("nope", { status: 404 })) as unknown as typeof fetch,
+    });
+
+    expect(playbook.source).toBe("local");
+    expect(playbook.text).toContain("local playbook");
+  });
+
+  it("refuses an oversized body before reading it", async () => {
+    const dir = tempDir();
+    const localPath = path.join(dir, "PLAYBOOK.md");
+    fs.writeFileSync(localPath, "# local playbook\n", "utf8");
+    const readBody = vi.fn(async () => "x");
+
+    const playbook = await resolveTriagePlaybook({
+      ...localOnlyOptions(),
+      env: { [TRIAGE_PLAYBOOK_PATH_ENV]: localPath },
+      fetchImpl: (async () => ({
+        ok: true,
+        headers: { get: () => String(64 * 1024 * 1024) },
+        text: readBody,
+      })) as unknown as typeof fetch,
+    });
+
+    expect(readBody).not.toHaveBeenCalled();
+    expect(playbook.source).toBe("local");
+  });
+
+  it("aborts the fetch on its own timeout rather than hanging the command", async () => {
+    let seenSignal: AbortSignal | null = null;
+    const fetchImpl = vi.fn((_url: string, init?: RequestInit) => {
+      seenSignal = init?.signal ?? null;
+      return new Promise<Response>((_resolve, reject) => {
+        init?.signal?.addEventListener("abort", () => reject(new Error("aborted")));
+      });
+    });
+
+    const playbook = await resolveTriagePlaybook({
+      ...localOnlyOptions(),
+      timeoutMs: 1,
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(seenSignal).not.toBeNull();
+    expect(playbook.source).toBe("local");
+  });
+
+  it("skips the network entirely when the kill switch is set", async () => {
+    const fetchImpl = vi.fn(async () => new Response("# remote", { status: 200 }));
+
+    const playbook = await resolveTriagePlaybook({
+      ...localOnlyOptions(),
+      env: { [TRIAGE_NO_FETCH_ENV]: "1" },
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(fetchImpl).not.toHaveBeenCalled();
+    expect(playbook.source).toBe("local");
+  });
+
+  it("still produces a playbook when this build shipped without the doc and the network is gone", async () => {
+    const playbook = await resolveTriagePlaybook({
+      ...localOnlyOptions(),
+      fetchImpl: null,
+    });
+
+    expect(playbook.source).toBe("local");
+    expect(playbook.origin).toBe("built into this ADE CLI");
+    // The reduced copy is still a playbook: the safety rules survive.
+    expect(playbook.text).toContain("Never kill processes by name or pattern");
+    expect(playbook.text).toContain("ade doctor --text");
+  });
+
+  it("finds the copy committed in this repository", () => {
+    const playbook = readLocalTriagePlaybook({ env: {} });
+    expect(playbook.origin.endsWith(path.join("docs", "triage", "PLAYBOOK.md"))).toBe(true);
+    expect(playbook.text).toContain("ADE triage playbook");
+  });
+
+  it("ranks the packaged copy above whatever repository the shell is sitting in", () => {
+    // `ade triage` is run from wherever the user happens to be. An old clone, a
+    // fork, or a vendored copy must not out-rank the playbook this build ships.
+    const resourcesPath = tempDir("ade-triage-resources-");
+    const packaged = path.join(resourcesPath, "docs", "triage", "PLAYBOOK.md");
+    fs.mkdirSync(path.dirname(packaged), { recursive: true });
+    fs.writeFileSync(packaged, "# packaged playbook\n", "utf8");
+    const cwd = tempDir("ade-triage-cwd-");
+    const checkedOut = path.join(cwd, "docs", "triage", "PLAYBOOK.md");
+    fs.mkdirSync(path.dirname(checkedOut), { recursive: true });
+    fs.writeFileSync(checkedOut, "# some other checkout\n", "utf8");
+
+    const playbook = readLocalTriagePlaybook({ env: {}, cwd, dirname: cwd, resourcesPath });
+
+    expect(playbook.origin).toBe(packaged);
+    expect(playbook.text).toContain("packaged playbook");
+  });
+
+  it("still lets the explicit override beat the packaged copy", () => {
+    const resourcesPath = tempDir("ade-triage-resources-");
+    const packaged = path.join(resourcesPath, "docs", "triage", "PLAYBOOK.md");
+    fs.mkdirSync(path.dirname(packaged), { recursive: true });
+    fs.writeFileSync(packaged, "# packaged playbook\n", "utf8");
+    const overridePath = path.join(tempDir(), "PLAYBOOK.md");
+    fs.writeFileSync(overridePath, "# my working copy\n", "utf8");
+
+    const playbook = readLocalTriagePlaybook({
+      env: { [TRIAGE_PLAYBOOK_PATH_ENV]: overridePath },
+      cwd: resourcesPath,
+      dirname: resourcesPath,
+      resourcesPath,
+    });
+
+    expect(playbook.origin).toBe(overridePath);
+    expect(playbook.text).toContain("my working copy");
+  });
+
+  it("looks for exactly one packaged path, the one packaging actually ships", () => {
+    // A second guessed layout would mask a packaging change instead of failing
+    // loudly, so `<resources>/triage/PLAYBOOK.md` must not be consulted.
+    const resourcesPath = tempDir("ade-triage-resources-");
+    const speculative = path.join(resourcesPath, "triage", "PLAYBOOK.md");
+    fs.mkdirSync(path.dirname(speculative), { recursive: true });
+    fs.writeFileSync(speculative, "# speculative layout\n", "utf8");
+    const empty = tempDir("ade-triage-empty-");
+
+    const playbook = readLocalTriagePlaybook({
+      env: {},
+      cwd: empty,
+      dirname: empty,
+      resourcesPath,
+    });
+
+    expect(playbook.origin).toBe("built into this ADE CLI");
+  });
+
+  it("ranks the copy in the install this CLI runs from above the shell's working directory", () => {
+    // The rung the whole ordering rests on: cwd is last, and an ADE checkout
+    // the shell happens to be sitting in must not out-rank the install's own
+    // playbook. Nothing else in this describe block pins that boundary.
+    const install = installTree();
+    const cwd = tempDir("ade-triage-cwd-");
+    const checkedOut = path.join(cwd, "docs", "triage", "PLAYBOOK.md");
+    fs.mkdirSync(path.dirname(checkedOut), { recursive: true });
+    fs.writeFileSync(checkedOut, "# some other checkout\n", "utf8");
+
+    const playbook = readLocalTriagePlaybook({
+      env: {},
+      cwd,
+      dirname: install.entryDir,
+      argv1: null,
+      resourcesPath: null,
+    });
+
+    expect(playbook.origin).toBe(fs.realpathSync(install.playbookPath));
+    expect(playbook.text).toContain("install playbook");
+  });
+
+  it("falls back to the entry script when the bundle has no __dirname", () => {
+    // `tsx src/cli.ts` and any ESM loader leave `__dirname` undefined, so
+    // `argv[1]` is the only thing pointing at the install. Every other test
+    // pins `dirname`, which suppresses this rung entirely.
+    const install = installTree();
+    const cwd = tempDir("ade-triage-cwd-");
+    const checkedOut = path.join(cwd, "docs", "triage", "PLAYBOOK.md");
+    fs.mkdirSync(path.dirname(checkedOut), { recursive: true });
+    fs.writeFileSync(checkedOut, "# some other checkout\n", "utf8");
+
+    const playbook = readLocalTriagePlaybook({
+      env: {},
+      cwd,
+      dirname: tempDir("ade-triage-empty-"),
+      argv1: path.join(install.entryDir, "cli.cjs"),
+      resourcesPath: null,
+    });
+
+    expect(playbook.origin).toBe(fs.realpathSync(install.playbookPath));
+    expect(playbook.text).toContain("install playbook");
+  });
+
+  it("refuses a playbook from an ancestor that is not an ADE install", () => {
+    // The walk used to climb eight unmarked levels, which from an npm-global
+    // install reaches the home directory: a `~/docs/triage/PLAYBOOK.md` anyone
+    // could drop there would have become the instructions a coding agent
+    // follows while repairing this machine. No ADE marker, no candidate.
+    const home = tempDir("ade-triage-home-walk-");
+    const planted = path.join(home, "docs", "triage", "PLAYBOOK.md");
+    fs.mkdirSync(path.dirname(planted), { recursive: true });
+    fs.writeFileSync(planted, "# planted playbook\n", "utf8");
+    const entryDir = path.join(home, ".npm-global", "lib", "node_modules", "someones-cli", "dist");
+    fs.mkdirSync(entryDir, { recursive: true });
+
+    const playbook = readLocalTriagePlaybook({
+      env: {},
+      cwd: tempDir("ade-triage-empty-"),
+      dirname: entryDir,
+      argv1: null,
+      resourcesPath: null,
+    });
+
+    expect(playbook.text).not.toContain("planted playbook");
+    expect(playbook.origin).toBe("built into this ADE CLI");
+  });
+
+  it("finds the packaged copy beside the unpacked CLI in an installed app", () => {
+    // `<Resources>/ade-cli/cli.cjs` with `<Resources>/docs/triage` beside it is
+    // what `extraResources` actually ships, and a plain node process has no
+    // `process.resourcesPath` to shortcut it — the walk has to reach it.
+    const resources = tempDir("ade-triage-resources-");
+    const entryDir = path.join(resources, "ade-cli");
+    fs.mkdirSync(entryDir, { recursive: true });
+    const packaged = path.join(resources, "docs", "triage", "PLAYBOOK.md");
+    fs.mkdirSync(path.dirname(packaged), { recursive: true });
+    fs.writeFileSync(packaged, "# packaged playbook\n", "utf8");
+
+    const playbook = readLocalTriagePlaybook({
+      env: {},
+      cwd: tempDir("ade-triage-empty-"),
+      dirname: entryDir,
+      argv1: null,
+      resourcesPath: null,
+    });
+
+    expect(playbook.origin).toBe(fs.realpathSync(packaged));
+    expect(playbook.text).toContain("packaged playbook");
+  });
+});
+
+describe("detectTriageProviders", () => {
+  it("returns installed agents in the documented detection order", () => {
+    const installed = new Set(["droid", "codex", "opencode"]);
+    const detected = detectTriageProviders({
+      env: {},
+      resolve: (command) =>
+        installed.has(command) ? { path: `/fake/bin/${command}`, source: "path" } : null,
+    });
+
+    expect(detected.map((provider) => provider.name)).toEqual(["codex", "opencode", "droid"]);
+    expect(detected[0]?.path).toBe("/fake/bin/codex");
+  });
+
+  it("treats a resolver failure as 'not installed' instead of failing the command", () => {
+    const detected = detectTriageProviders({
+      env: {},
+      resolve: (command) => {
+        if (command === "claude") throw new Error("EACCES reading a PATH entry");
+        return command === "codex" ? { path: "/fake/bin/codex", source: "path" } : null;
+      },
+    });
+
+    expect(detected.map((provider) => provider.name)).toEqual(["codex"]);
+  });
+
+  // Windows cannot execute an extension-less file, so detection must go through
+  // the shared PATHEXT-aware resolver rather than an `fs.existsSync` of the bare
+  // name — that probe finds `codex` (an sh script) and never `codex.cmd`.
+  it("resolves through the shared PATHEXT-aware executable resolver", () => {
+    const env = { PATHEXT: ".COM;.EXE;.CMD" };
+    const seen: string[] = [];
+    const detected = detectTriageProviders({
+      env,
+      resolve: (command, resolverEnv) => {
+        seen.push(command);
+        expect(resolverEnv).toBe(env);
+        return command === "claude"
+          ? { path: "C:\\Users\\ada\\AppData\\Roaming\\npm\\claude.cmd", source: "path" }
+          : null;
+      },
+    });
+
+    expect(seen).toEqual(TRIAGE_PROVIDERS.map((provider) => provider.command));
+    expect(detected[0]?.path).toBe("C:\\Users\\ada\\AppData\\Roaming\\npm\\claude.cmd");
+    expect(defaultTriageExecutableResolver("claude", env))
+      .toEqual(resolveExecutableFromKnownLocations("claude", env));
+  });
+
+  it("rejects an unknown --provider and accepts the documented aliases", () => {
+    expect(parseTriageProviderName("cursor")).toBe("cursor-agent");
+    expect(parseTriageProviderName("Claude-Code")).toBe("claude");
+    expect(() => parseTriageProviderName("gemini")).toThrow(TriageUsageError);
+  });
+});
+
+describe("buildTriageLaunchPlan", () => {
+  function provider(name: DetectedTriageProvider["name"]): DetectedTriageProvider {
+    const spec = TRIAGE_PROVIDERS.find((entry) => entry.name === name)!;
+    return { ...spec, path: `/fake/bin/${spec.command}` };
+  }
+
+  it("passes the prompt as the trailing positional argument", () => {
+    const prompt = buildTriagePrompt({ contextPath: "/tmp/t/context.md", playbookPath: "/tmp/t/PLAYBOOK.md" });
+    const plan = buildTriageLaunchPlan(provider("claude"), prompt, {}, "darwin");
+
+    expect(plan.command).toBe("/fake/bin/claude");
+    expect(plan.args).toEqual([prompt]);
+    expect(plan.promptDelivered).toBe(true);
+  });
+
+  // `opencode [project]` takes a DIRECTORY, not a prompt: passing one there
+  // launches OpenCode in a folder that does not exist.
+  it("launches OpenCode bare, because its positional argument is a project directory", () => {
+    const plan = buildTriageLaunchPlan(provider("opencode"), "prompt text", {}, "darwin");
+
+    expect(plan.args).toEqual([]);
+    expect(plan.promptDelivered).toBe(false);
+  });
+
+  it("spawns a Windows .exe directly and keeps the prompt on argv", () => {
+    const prompt = "line one\nline two";
+    const plan = buildTriageLaunchPlan(
+      { ...provider("claude"), path: "C:\\Program Files\\claude\\claude.exe" },
+      prompt,
+      { ComSpec: "C:\\Windows\\system32\\cmd.exe" },
+      "win32",
+    );
+
+    expect(plan.command).toBe("C:\\Program Files\\claude\\claude.exe");
+    expect(plan.args).toEqual([prompt]);
+    expect(plan.promptDelivered).toBe(true);
+  });
+
+  // A `.cmd` shim can only be launched through `cmd.exe /d /s /c`, which
+  // rewrites the command line before the CLI sees argv: newlines flatten to
+  // spaces and `%VAR%` expands. The triage prompt is multi-line and full of
+  // paths, so it must not ride there.
+  it("keeps the prompt off the command line when Windows has to wrap the launch", () => {
+    const plan = buildTriageLaunchPlan(
+      { ...provider("claude"), path: "C:\\Users\\ada\\AppData\\Roaming\\npm\\claude.cmd" },
+      "line one\nline two",
+      { ComSpec: "C:\\Windows\\system32\\cmd.exe" },
+      "win32",
+    );
+
+    expect(plan.promptDelivered).toBe(false);
+    expect(plan.command).toBe("C:\\Windows\\system32\\cmd.exe");
+    expect(plan.args.join(" ")).not.toContain("line one");
+    expect(plan.args.join(" ")).toContain("claude.cmd");
+    expect(plan.windowsVerbatimArguments).toBe(true);
+  });
+});
+
+describe("runTriageCommand", () => {
+  function dependencies(overrides: Record<string, unknown> = {}) {
+    const home = tempDir("ade-triage-home-");
+    return {
+      cliVersion: "1.2.68",
+      projectRoot: null,
+      runDoctor: async () => doctorResult(),
+      buildReport: async () => reportResult(),
+      resolvePlaybook: async () => ({
+        text: "# playbook\n",
+        source: "local" as const,
+        origin: "/repo/docs/triage/PLAYBOOK.md",
+      }),
+      detectProviders: () => [] as DetectedTriageProvider[],
+      now: () => AT,
+      env: { ADE_HOME: home },
+      tmpRoot: tempDir("ade-triage-root-"),
+      platform: "darwin" as NodeJS.Platform,
+      writeNotice: () => {},
+      ...overrides,
+    };
+  }
+
+  it("--agent writes the bundle, prints the handoff, and launches nothing", async () => {
+    const spawnAgent = vi.fn(async () => 0);
+
+    const { payload, exitCode } = await runTriageCommand(
+      { agent: true, provider: null },
+      dependencies({
+        spawnAgent,
+        detectProviders: () => [
+          { ...TRIAGE_PROVIDERS[0]!, path: "/fake/bin/claude" },
+        ] as DetectedTriageProvider[],
+      }),
+    );
+
+    expect(spawnAgent).not.toHaveBeenCalled();
+    expect(exitCode).toBe(0);
+    expect(payload.mode).toBe("agent");
+    expect(payload.playbookSource).toBe("local");
+    expect(payload.playbookOrigin).toBe("/repo/docs/triage/PLAYBOOK.md");
+    expect(payload.providers).toEqual([
+      { name: "claude", label: "Claude Code", path: "/fake/bin/claude" },
+    ]);
+    expect(payload.suggestedPrompt).toContain(payload.contextPath);
+    expect(payload.suggestedPrompt).toContain(payload.playbookPath);
+
+    expect(path.basename(payload.contextPath)).toBe("context.md");
+    expect(path.basename(path.dirname(payload.contextPath)).startsWith("ade-triage-")).toBe(true);
+    expect(fs.readFileSync(payload.contextPath, "utf8")).toContain("# ADE triage context");
+    expect(fs.readFileSync(payload.playbookPath, "utf8")).toContain("# playbook");
+
+    // The JSON body is what an already-running agent consumes; it must survive
+    // a round trip with every field the caller was promised.
+    const parsed = JSON.parse(JSON.stringify(payload)) as typeof payload;
+    expect(parsed.contextPath).toBe(payload.contextPath);
+    expect(parsed.playbookSource).toBe("local");
+  });
+
+  it("falls back to the embedded playbook when the resolver rejects", async () => {
+    // Every other collector in this command is wrapped in `settle` because the
+    // machine running triage is by definition broken. The playbook resolver is
+    // no different: it reads the same disk, and an unhandled rejection here
+    // used to take the whole bundle — context file included — down with it.
+    const { payload, exitCode } = await runTriageCommand(
+      { agent: true, provider: null },
+      dependencies({
+        resolvePlaybook: async () => {
+          throw new Error("EIO: playbook read failed");
+        },
+      }),
+    );
+
+    expect(exitCode).toBe(0);
+    expect(payload.playbookSource).toBe("local");
+    expect(payload.playbookOrigin).toBe("built into this ADE CLI");
+    expect(fs.readFileSync(payload.playbookPath, "utf8")).toContain("ADE triage playbook");
+    // The rest of the handoff still has to be there — that is the whole point.
+    expect(fs.readFileSync(payload.contextPath, "utf8")).toContain("# ADE triage context");
+  });
+
+  it("keeps the handoff (and exit 0) when no agent CLI is installed", async () => {
+    const spawnAgent = vi.fn(async () => 0);
+
+    const { payload, exitCode } = await runTriageCommand(
+      { agent: false, provider: null },
+      dependencies({ spawnAgent }),
+    );
+
+    expect(spawnAgent).not.toHaveBeenCalled();
+    expect(exitCode).toBe(0);
+    expect(payload.mode).toBe("no-provider");
+    expect(payload.message).toContain("No agent CLI found");
+    expect(fs.existsSync(payload.contextPath)).toBe(true);
+  });
+
+  it("launches the first detected agent and exits with its status", async () => {
+    const plans: TriageLaunchPlan[] = [];
+    const notices: string[] = [];
+
+    const { payload, exitCode } = await runTriageCommand(
+      { agent: false, provider: null },
+      dependencies({
+        detectProviders: () => [
+          { ...TRIAGE_PROVIDERS[1]!, path: "/fake/bin/codex" },
+          { ...TRIAGE_PROVIDERS[4]!, path: "/fake/bin/droid" },
+        ] as DetectedTriageProvider[],
+        spawnAgent: async (plan: TriageLaunchPlan) => {
+          plans.push(plan);
+          return 3;
+        },
+        writeNotice: (text: string) => notices.push(text),
+      }),
+    );
+
+    expect(exitCode).toBe(3);
+    expect(payload.mode).toBe("launch");
+    expect(payload.launched).toEqual({ provider: "codex", label: "Codex", promptDelivered: true });
+    expect(plans).toHaveLength(1);
+    expect(plans[0]?.command).toBe("/fake/bin/codex");
+    expect(plans[0]?.args[0]).toContain(payload.contextPath);
+    // The launch replaces this process's stdio, so both paths have to be said
+    // before it starts or they are never said at all.
+    expect(notices.join("")).toContain(payload.contextPath);
+    expect(notices.join("")).toContain(payload.playbookPath);
+  });
+
+  it("honours --provider and tells the truth when that one is missing", async () => {
+    const spawnAgent = vi.fn(async () => 0);
+
+    const { payload, exitCode } = await runTriageCommand(
+      { agent: false, provider: "claude" },
+      dependencies({
+        spawnAgent,
+        detectProviders: () => [
+          { ...TRIAGE_PROVIDERS[1]!, path: "/fake/bin/codex" },
+        ] as DetectedTriageProvider[],
+      }),
+    );
+
+    expect(spawnAgent).not.toHaveBeenCalled();
+    expect(exitCode).toBe(0);
+    expect(payload.mode).toBe("no-provider");
+    expect(payload.message).toContain("claude is not installed");
+  });
+
+  it("pastes the prompt into the notice for an agent that cannot take it on argv", async () => {
+    const notices: string[] = [];
+
+    const { payload } = await runTriageCommand(
+      { agent: false, provider: "opencode" },
+      dependencies({
+        detectProviders: () => [
+          { ...TRIAGE_PROVIDERS[3]!, path: "/fake/bin/opencode" },
+        ] as DetectedTriageProvider[],
+        spawnAgent: async () => 0,
+        writeNotice: (text: string) => notices.push(text),
+      }),
+    );
+
+    expect(payload.launched?.promptDelivered).toBe(false);
+    expect(notices.join("")).toContain("Paste this in:");
+    expect(notices.join("")).toContain(payload.playbookPath);
+  });
+
+  it("still produces the handoff when the doctor probe itself fails", async () => {
+    const { payload, exitCode } = await runTriageCommand(
+      { agent: true, provider: null },
+      dependencies({
+        runDoctor: async () => {
+          throw new Error("runtime socket unavailable");
+        },
+      }),
+    );
+
+    expect(exitCode).toBe(0);
+    expect(fs.readFileSync(payload.contextPath, "utf8"))
+      .toContain("could not complete: runtime socket unavailable");
+  });
+
+  // The report reads files on the disk that may be the thing that is broken.
+  // Losing it costs the log tails; taking the command down with it costs the
+  // handoff, which is the entire product of `ade triage`.
+  it("still produces the handoff when the diagnostic report cannot be collected", async () => {
+    const { payload, exitCode } = await runTriageCommand(
+      { agent: true, provider: null },
+      dependencies({
+        buildReport: async () => {
+          throw new Error("EROFS: read-only file system, open '/Users/ada/.ade/logs/brain.jsonl'");
+        },
+      }),
+    );
+
+    expect(exitCode).toBe(0);
+    const context = fs.readFileSync(payload.contextPath, "utf8");
+    expect(context).toContain("could not be collected");
+    expect(context).toContain("read-only file system");
+    // The report carries the redaction rules; without it they are derived here,
+    // so the failure message cannot become the one unredacted path in the file.
+    expect(context).not.toContain("/Users/ada/.ade/logs");
+    // The doctor rows still made it: one failed collector is not all of them.
+    expect(context).toContain("| Brain |");
+  });
+});
+
+describe("createTriageBundleDir", () => {
+  it("names the directory for the run and never reuses one", () => {
+    const root = tempDir("ade-triage-root-");
+    const first = createTriageBundleDir(AT, root);
+    const second = createTriageBundleDir(AT, root);
+
+    expect(path.basename(first)).toMatch(/^ade-triage-2026-08-29T10-00-00-000Z-/);
+    expect(first).not.toBe(second);
+    expect(fs.statSync(first).isDirectory()).toBe(true);
+  });
+});
diff --git a/apps/ade-cli/src/commands/triage.ts b/apps/ade-cli/src/commands/triage.ts
new file mode 100644
index 0000000000..22a3902133
--- /dev/null
+++ b/apps/ade-cli/src/commands/triage.ts
@@ -0,0 +1,277 @@
+import os from "node:os";
+import path from "node:path";
+
+import { resolveMachineAdeLayout } from "../services/projects/machineLayout";
+import { diagnosticRedactionContext } from "../services/diagnostics/diagnosticSources";
+import type { DiagnosticRedactionContext } from "../services/diagnostics/diagnosticReport";
+import type { DoctorCommandResult } from "./doctor";
+import { buildCliDiagnosticReportAsync, type ReportIssueResult } from "./reportIssue";
+import {
+  buildTriageContext,
+  buildTriagePrompt,
+  createTriageBundleDir,
+  writeTriageBundle,
+  TRIAGE_PLAYBOOK_FILE_NAME,
+} from "./triageContext";
+import {
+  buildTriageLaunchPlan,
+  describeTriageProviders,
+  detectTriageProviders,
+  spawnTriageAgent,
+  triageLaunchNotice,
+  TRIAGE_PROVIDERS,
+  type DetectedTriageProvider,
+  type TriageAgentSpawner,
+  type TriageProviderName,
+} from "./triageLaunch";
+import {
+  embeddedTriagePlaybook,
+  resolveTriagePlaybook,
+  type TriagePlaybook,
+  type TriagePlaybookSource,
+} from "./triagePlaybook";
+
+/**
+ * `ade triage` — hand a broken install to the user's own coding agent.
+ *
+ * `ade doctor` says which check failed and `ade report-issue` produces something
+ * to file. Neither fixes anything, and the person staring at either one is
+ * usually the person least able to act on it. This command builds the two files
+ * an agent needs — a redacted machine context and a maintained playbook — and
+ * then gets out of the way: it launches whichever agent CLI is installed and
+ * lets the user talk to it directly, or, with `--agent`, prints the paths for an
+ * agent that is already running (an ADE Work chat, say) to pick up.
+ *
+ * Everything here is deliberately CLI-only and brain-free. The machine this runs
+ * on is the machine where ADE will not come up, so nothing may depend on the
+ * brain answering, and there is no desktop/TUI/iOS surface to mirror: those
+ * clients cannot help when the thing that hosts them is down.
+ *
+ * The pieces live next door: `triagePlaybook.ts` resolves the playbook,
+ * `triageContext.ts` assembles and writes the two files, `triageLaunch.ts`
+ * detects and starts the agent. This file only sequences them.
+ */
+
+// Re-exported for `cli.ts`, which is the only non-test consumer of this module.
+export { parseTriageProviderName } from "./triageLaunch";
+export type { TriageProviderName } from "./triageLaunch";
+export { TRIAGE_NO_FETCH_ENV } from "./triagePlaybook";
+export { TriageCommandError, TriageUsageError } from "./triageErrors";
+
+export type TriageMode = "agent" | "launch" | "no-provider";
+
+export type TriagePayload = {
+  ok: boolean;
+  mode: TriageMode;
+  contextPath: string;
+  playbookPath: string;
+  playbookSource: TriagePlaybookSource;
+  playbookOrigin: string;
+  suggestedPrompt: string;
+  providers: Array<{ name: TriageProviderName; label: string; path: string }>;
+  launched: { provider: TriageProviderName; label: string; promptDelivered: boolean } | null;
+  message: string;
+};
+
+export type TriageCommandOptions = {
+  /** `--agent`: print the handoff, launch nothing. */
+  agent: boolean;
+  /** `--provider <name>`: override the detection order. */
+  provider: TriageProviderName | null;
+};
+
+export type TriageCommandDependencies = {
+  /** Runs the doctor checks. A rejection is recorded, not fatal. */
+  runDoctor: () => Promise<DoctorCommandResult>;
+  cliVersion: string | null;
+  projectRoot: string | null;
+  buildReport?: () => Promise<ReportIssueResult>;
+  resolvePlaybook?: () => Promise<TriagePlaybook>;
+  detectProviders?: () => DetectedTriageProvider[];
+  spawnAgent?: TriageAgentSpawner;
+  /**
+   * Where the pre-launch notice goes. stderr by default: the agent takes over
+   * stdout the moment it starts, and this is the only chance to say where the
+   * files are.
+   */
+  writeNotice?: (text: string) => void;
+  now?: () => Date;
+  env?: NodeJS.ProcessEnv;
+  tmpRoot?: string;
+  platform?: NodeJS.Platform;
+};
+
+export function formatTriageText(payload: TriagePayload): string {
+  const lines = [
+    payload.message,
+    "",
+    `context:  ${payload.contextPath}`,
+    `playbook: ${payload.playbookPath}  (${payload.playbookSource}: ${payload.playbookOrigin})`,
+    `agents:   ${payload.providers.length === 0
+      ? "none found on PATH"
+      : payload.providers.map((provider) => provider.name).join(", ")}`,
+  ];
+  if (payload.mode !== "launch") {
+    lines.push("", "Prompt:", "", payload.suggestedPrompt, "");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Every collector this command runs is allowed to fail.
+ *
+ * The doctor probe talks to a brain that may be hung, the report reads files on
+ * a disk that may be full, and the layout resolver reads an `ADE_HOME` that may
+ * be unset or unreadable — on this machine, by definition, something is broken.
+ * A rejection becomes a section in `context.md` saying so, because the handoff
+ * is the product: an agent with a partial context can still work, an agent that
+ * never got a context cannot.
+ */
+async function settle<T>(work: Promise<T>): Promise<{ value: T | null; error: string | null }> {
+  try {
+    return { value: await work, error: null };
+  } catch (error) {
+    return { value: null, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function settleSync<T>(work: () => T): { value: T | null; error: string | null } {
+  try {
+    return { value: work(), error: null };
+  } catch (error) {
+    return { value: null, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export async function runTriageCommand(
+  options: TriageCommandOptions,
+  dependencies: TriageCommandDependencies,
+): Promise<{ payload: TriagePayload; exitCode: number }> {
+  const env = dependencies.env ?? process.env;
+  const platform = dependencies.platform ?? process.platform;
+  const now = dependencies.now ?? (() => new Date());
+  const generatedAt = now();
+
+  const buildReport = dependencies.buildReport
+    ?? (() => buildCliDiagnosticReportAsync({
+      surface: "cli-triage",
+      projectRoot: dependencies.projectRoot,
+      cliVersion: dependencies.cliVersion,
+      env,
+      now,
+    }));
+  const resolvePlaybook = dependencies.resolvePlaybook ?? (() => resolveTriagePlaybook({ env }));
+  const detectProviders = dependencies.detectProviders ?? (() => detectTriageProviders({ env }));
+
+  // The doctor probe talks to the brain and the report reads local files; the
+  // playbook fetch is network. None of them need each other, and the brain is
+  // exactly what may be hanging, so they run together rather than in series.
+  const [doctorResult, reportResult, playbookResult] = await Promise.all([
+    settle(dependencies.runDoctor()),
+    settle(buildReport()),
+    settle(resolvePlaybook()),
+  ]);
+  // `resolveTriagePlaybook` already swallows fetch failures, but it also reads
+  // the disk — the same disk that may be the reason triage is running — and an
+  // unhandled rejection here would take the whole bundle down. The embedded
+  // copy is the floor, and the context records that it is what the agent got.
+  const playbook = playbookResult.value ?? embeddedTriagePlaybook();
+
+  const layout = settleSync(() => resolveMachineAdeLayout(env, platform));
+  // The report carries the redaction rules it was built with. Without it, they
+  // are derived here instead — a failed collection must not turn the context
+  // file into the one unredacted copy of this machine's paths and names.
+  const redaction: DiagnosticRedactionContext = reportResult.value?.redaction
+    ?? diagnosticRedactionContext(dependencies.projectRoot);
+
+  const dir = createTriageBundleDir(generatedAt, dependencies.tmpRoot);
+  const playbookPath = path.join(dir, TRIAGE_PLAYBOOK_FILE_NAME);
+  const context = buildTriageContext({
+    generatedAt,
+    cliVersion: dependencies.cliVersion,
+    platform,
+    arch: process.arch,
+    osRelease: os.release(),
+    nodeVersion: process.versions.node ?? null,
+    projectRoot: dependencies.projectRoot,
+    adeHome: layout.value?.adeDir ?? null,
+    socketPath: layout.value?.socketPath ?? null,
+    layoutError: layout.error,
+    doctor: doctorResult.value,
+    doctorError: doctorResult.error,
+    report: reportResult.value?.report ?? "",
+    reportError: reportResult.error,
+    redaction,
+    playbook: { source: playbook.source, origin: playbook.origin, path: playbookPath },
+  });
+  const bundle = writeTriageBundle({ dir, context, playbook });
+  const suggestedPrompt = buildTriagePrompt({
+    contextPath: bundle.contextPath,
+    playbookPath: bundle.playbookPath,
+  });
+
+  const detected = detectProviders();
+  const providers = detected.map((provider) => ({
+    name: provider.name,
+    label: provider.label,
+    path: provider.path,
+  }));
+
+  const base: Omit<TriagePayload, "mode" | "message" | "launched"> = {
+    ok: true,
+    contextPath: bundle.contextPath,
+    playbookPath: bundle.playbookPath,
+    playbookSource: bundle.playbookSource,
+    playbookOrigin: bundle.playbookOrigin,
+    suggestedPrompt,
+    providers,
+  };
+
+  if (options.agent) {
+    return {
+      payload: {
+        ...base,
+        mode: "agent",
+        launched: null,
+        message:
+          "Triage context ready. Read the playbook, then the context, then follow the prompt below.",
+      },
+      exitCode: 0,
+    };
+  }
+
+  const chosen = options.provider
+    ? detected.find((provider) => provider.name === options.provider) ?? null
+    : detected[0] ?? null;
+
+  if (!chosen) {
+    // Requirement of this command, not an accident: a machine with no agent CLI
+    // still gets the handoff, and exits 0. The files are the deliverable; the
+    // launch is a convenience.
+    const message = options.provider
+      ? `${options.provider} is not installed on this machine. Everything an agent needs is written out — paste the prompt below into whatever agent you do have.`
+      : `No agent CLI found (looked for ${TRIAGE_PROVIDERS.map((p) => p.name).join(", ")}). Everything an agent needs is written out — paste the prompt below into whatever agent you do have.`;
+    return {
+      payload: { ...base, mode: "no-provider", launched: null, message },
+      exitCode: 0,
+    };
+  }
+
+  const plan = buildTriageLaunchPlan(chosen, suggestedPrompt, env, platform);
+  const writeNotice = dependencies.writeNotice
+    ?? ((text: string) => {
+      process.stderr.write(text);
+    });
+  writeNotice(triageLaunchNotice(bundle, plan, suggestedPrompt));
+  const spawnAgent = dependencies.spawnAgent ?? spawnTriageAgent;
+  const exitCode = await spawnAgent(plan);
+  return {
+    payload: {
+      ...base,
+      mode: "launch",
+      launched: { provider: chosen.name, label: chosen.label, promptDelivered: plan.promptDelivered },
+      message: `Handed triage to ${chosen.label} (${describeTriageProviders(detected)} available).`,
+    },
+    exitCode,
+  };
+}
diff --git a/apps/ade-cli/src/commands/triageContext.ts b/apps/ade-cli/src/commands/triageContext.ts
new file mode 100644
index 0000000000..e601821ed8
--- /dev/null
+++ b/apps/ade-cli/src/commands/triageContext.ts
@@ -0,0 +1,287 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  redactDiagnosticText,
+  type DiagnosticRedactionContext,
+} from "../services/diagnostics/diagnosticReport";
+import type { DoctorCommandResult, DoctorRow } from "./doctor";
+import { TriageCommandError } from "./triageErrors";
+import type { TriagePlaybook, TriagePlaybookSource } from "./triagePlaybook";
+
+/**
+ * The two files `ade triage` writes, and the prompt that points at them.
+ *
+ * Everything here assembles markdown from already-collected material; nothing
+ * here probes the machine. The collectors run in the command orchestrator, and
+ * every one of them is allowed to fail — a section saying "this could not be
+ * collected" is worth more than a command that dies on the broken machine it
+ * exists for.
+ */
+
+/** Failures first, then warnings, then the rows that are fine. */
+export function orderTriageDoctorRows(rows: readonly DoctorRow[]): DoctorRow[] {
+  const rank = (row: DoctorRow): number =>
+    row.status === "fail" ? 0 : row.status === "warn" ? 1 : 2;
+  return [...rows].sort((left, right) => rank(left) - rank(right));
+}
+
+const ERROR_LINE_PATTERN =
+  /\b(error|fatal|panic|exception|traceback|denied|refused|unauthorized|forbidden|timed? ?out|corrupt|malformed|locked|EACCES|EPERM|ENOENT|EADDRINUSE|EDEADLK|ECONNREFUSED|ENOSPC)\b/i;
+
+/**
+ * The lines an agent should read first, pulled out of the already-redacted
+ * report so this cannot become a second, unredacted path for the same bytes.
+ */
+export function extractRecentErrorLines(reportText: string, limit = 40): string[] {
+  const matches: string[] = [];
+  for (const rawLine of reportText.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#") || line.startsWith("|")) continue;
+    if (line.length > 500) continue;
+    if (!ERROR_LINE_PATTERN.test(line)) continue;
+    matches.push(line);
+  }
+  return matches.slice(-limit);
+}
+
+export type TriageContextInput = {
+  generatedAt: Date;
+  cliVersion: string | null;
+  platform: NodeJS.Platform;
+  arch: string;
+  osRelease: string;
+  nodeVersion: string | null;
+  projectRoot: string | null;
+  /** Null when the ADE layout could not be resolved; see `layoutError`. */
+  adeHome: string | null;
+  socketPath: string | null;
+  /** Why the ADE home/socket paths are missing, if they are. */
+  layoutError: string | null;
+  doctor: DoctorCommandResult | null;
+  doctorError: string | null;
+  report: string;
+  /** Why the diagnostic report is missing, if it is. */
+  reportError: string | null;
+  redaction: DiagnosticRedactionContext;
+  playbook: { source: TriagePlaybookSource; origin: string; path: string };
+};
+
+function bullet(label: string, value: unknown): string {
+  const text = value == null || value === "" ? "unknown" : String(value);
+  return `- ${label}: ${text}`;
+}
+
+function describeBrain(doctor: DoctorCommandResult | null): string[] {
+  if (!doctor) return ["- brain: not probed (ade doctor did not run — see the error above)"];
+  const brain = doctor.brain;
+  return [
+    bullet("responding", brain.running ? "yes" : "no"),
+    bullet("starting", brain.starting === true ? `yes (${brain.startingAgeMs ?? "?"} ms old)` : "no"),
+    bullet("version", brain.version),
+    bullet("build hash", brain.buildHash),
+    bullet("pid", brain.pid),
+    bullet("uptime ms", brain.uptimeMs),
+    bullet("build mismatch", brain.mismatchReason ?? "none"),
+    bullet("error", brain.error ?? "none"),
+    bullet("sync port", doctor.syncPort),
+  ];
+}
+
+/**
+ * The whole file is passed through {@link redactDiagnosticText} on the way out,
+ * for the same reason the diagnostic report is: a section added later cannot
+ * leak by forgetting to call it. The pass is idempotent, so the embedded report
+ * — already redacted by its own builder — is unchanged by it. Collection error
+ * messages ride the same pass, which is why they are written into the document
+ * rather than printed raw.
+ */
+export function buildTriageContext(input: TriageContextInput): string {
+  const doctorRows = input.doctor ? orderTriageDoctorRows(input.doctor.rows) : [];
+  const failing = doctorRows.filter((row) => row.status === "fail");
+  const lines: string[] = [
+    "# ADE triage context",
+    "",
+    `Generated ${input.generatedAt.toISOString()} by \`ade triage\`.`,
+    "",
+    "This file is redacted: home directories, user and host names, emails, IP",
+    "addresses and token-shaped strings have been replaced with placeholders.",
+    "Keep it that way — do not paste unredacted logs into it, and do not print",
+    "the contents of anything under the secrets directory.",
+    "",
+    `Playbook: ${input.playbook.path} (${input.playbook.source}, from ${input.playbook.origin})`,
+    "",
+    "## Install",
+    "",
+    bullet("ADE CLI version", input.cliVersion),
+    bullet("desktop app version", input.doctor?.app.installedVersion ?? null),
+    bullet("latest known desktop version", input.doctor?.app.latestKnownVersion ?? null),
+    bullet("platform", `${input.platform} ${input.arch}`),
+    bullet("OS release", input.osRelease),
+    bullet("node", input.nodeVersion),
+    bullet("ADE home", input.adeHome),
+    bullet("brain endpoint", input.socketPath),
+    bullet("project", input.projectRoot ?? "none open"),
+    "",
+  ];
+
+  if (input.layoutError) {
+    lines.push(
+      `The ADE home and brain endpoint could not be resolved: ${input.layoutError}`,
+      "",
+      "That is itself a finding — an unreadable or unset ADE home explains most of",
+      "what follows. Ask the user where their ADE home is before assuming a path.",
+      "",
+    );
+  }
+
+  lines.push("## Health checks (ade doctor)", "");
+
+  if (input.doctorError) {
+    lines.push(
+      `\`ade doctor\` could not complete: ${input.doctorError}`,
+      "",
+      "Treat that as the first failure to explain — the checks below are missing,",
+      "not passing.",
+      "",
+    );
+  }
+  if (doctorRows.length > 0) {
+    lines.push(
+      failing.length === 0
+        ? "Overall: no failing rows."
+        : `Overall: ${failing.length} failing row(s), listed first.`,
+      "",
+      "| check | status | detail |",
+      "| --- | --- | --- |",
+      ...doctorRows.map((row) =>
+        `| ${row.label} | ${row.status} | ${row.detail.replace(/\|/g, "\\|").replace(/\r?\n/g, " ")} |`),
+      "",
+    );
+  } else if (!input.doctorError) {
+    lines.push("No health checks were returned.", "");
+  }
+
+  lines.push("## Brain", "", ...describeBrain(input.doctor), "");
+
+  const errorLines = extractRecentErrorLines(input.report);
+  lines.push("## Recent errors", "");
+  if (errorLines.length === 0) {
+    lines.push("No error-shaped lines were found in the collected logs.", "");
+  } else {
+    lines.push(
+      "Pulled from the redacted diagnostic report below, most recent last.",
+      "",
+      "```",
+      ...errorLines,
+      "```",
+      "",
+    );
+  }
+
+  lines.push("## Full diagnostic report", "");
+  if (input.reportError) {
+    lines.push(
+      `The diagnostic report could not be collected: ${input.reportError}`,
+      "",
+      "Nothing below it was gathered — no log tails, no service definition, no disk",
+      "space. `ade report-issue --text` reproduces the same collection by hand and",
+      "will fail the same way; that failure is a finding, not a detour.",
+      "",
+    );
+  } else {
+    lines.push(
+      "The same redacted report `ade report-issue` prints: versions, service",
+      "definition, log tails, disk space, and storage environment.",
+      "",
+      input.report.trimEnd(),
+      "",
+    );
+  }
+
+  return redactDiagnosticText(lines.join("\n"), input.redaction);
+}
+
+// ---------------------------------------------------------------------------
+// Prompt
+// ---------------------------------------------------------------------------
+
+export function buildTriagePrompt(args: { contextPath: string; playbookPath: string }): string {
+  return [
+    "My ADE install is broken and I need you to fix it on this machine.",
+    "",
+    `1. Read the playbook first: ${args.playbookPath}`,
+    `2. Then read the machine context: ${args.contextPath}`,
+    "",
+    "Follow the playbook's safety rules exactly. In short: diagnose with the",
+    "read-only commands first; never delete anything under ~/.ade, $ADE_HOME, or a",
+    "project's .ade/ directory; never kill processes by name or pattern; prefer the",
+    "`ade` command over the raw OS command; and tell me what you are about to run and",
+    "what it changes before you run anything that mutates state.",
+    "",
+    "Start by telling me which doctor rows are failing and what you think the cause",
+    "is, then propose the fix and wait for me to say go.",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Bundle
+// ---------------------------------------------------------------------------
+
+export const TRIAGE_CONTEXT_FILE_NAME = "context.md";
+export const TRIAGE_PLAYBOOK_FILE_NAME = "PLAYBOOK.md";
+
+/**
+ * A fresh directory per run, named for the moment it was made.
+ *
+ * `mkdtemp` rather than a bare `mkdir` of the timestamp: the temp directory is
+ * world-writable on POSIX, and a predictable name there is something another
+ * user can create first as a symlink. The random suffix also means two runs in
+ * the same second cannot collide.
+ */
+export function createTriageBundleDir(at: Date, tmpRoot: string = os.tmpdir()): string {
+  const stamp = at.toISOString().replace(/[:.]/g, "-");
+  try {
+    return fs.mkdtempSync(path.join(tmpRoot, `ade-triage-${stamp}-`));
+  } catch (error) {
+    // A full or read-only temp directory is a plausible state on exactly the
+    // machine this command is for, and the raw errno with no path attached
+    // would send the user hunting for the wrong disk.
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new TriageCommandError(
+      `Could not create a triage directory under ${tmpRoot}: ${detail}`,
+    );
+  }
+}
+
+export type TriageBundle = {
+  dir: string;
+  contextPath: string;
+  playbookPath: string;
+  playbookSource: TriagePlaybookSource;
+  playbookOrigin: string;
+};
+
+export function writeTriageBundle(args: {
+  dir: string;
+  context: string;
+  playbook: TriagePlaybook;
+}): TriageBundle {
+  const contextPath = path.join(args.dir, TRIAGE_CONTEXT_FILE_NAME);
+  const playbookPath = path.join(args.dir, TRIAGE_PLAYBOOK_FILE_NAME);
+  try {
+    fs.writeFileSync(contextPath, args.context, "utf8");
+    fs.writeFileSync(playbookPath, args.playbook.text, "utf8");
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new TriageCommandError(`Could not write the triage files to ${args.dir}: ${detail}`);
+  }
+  return {
+    dir: args.dir,
+    contextPath,
+    playbookPath,
+    playbookSource: args.playbook.source,
+    playbookOrigin: args.playbook.origin,
+  };
+}
diff --git a/apps/ade-cli/src/commands/triageErrors.ts b/apps/ade-cli/src/commands/triageErrors.ts
new file mode 100644
index 0000000000..e2b22b5199
--- /dev/null
+++ b/apps/ade-cli/src/commands/triageErrors.ts
@@ -0,0 +1,18 @@
+/**
+ * The two failures `ade triage` reports to the user, kept in their own module
+ * so every triage module can throw them without importing each other.
+ *
+ * Both are structured on purpose: `cli.ts` maps them onto its own error types,
+ * which print the message alone. A bare `Error` reaches the catch-all instead
+ * and prints a stack trace over the wording — on the one machine whose owner is
+ * least able to read one.
+ */
+
+/** A bad `--provider` and friends: usage, mapped to `CliUsageError`. */
+export class TriageUsageError extends Error {}
+
+/**
+ * The command could not produce the handoff — the temp directory is full or
+ * read-only, or the agent CLI could not be spawned. Mapped to `CliToolError`.
+ */
+export class TriageCommandError extends Error {}
diff --git a/apps/ade-cli/src/commands/triageLaunch.ts b/apps/ade-cli/src/commands/triageLaunch.ts
new file mode 100644
index 0000000000..a4ce650776
--- /dev/null
+++ b/apps/ade-cli/src/commands/triageLaunch.ts
@@ -0,0 +1,238 @@
+import { spawn } from "node:child_process";
+
+import {
+  resolveExecutableFromKnownLocations,
+  type ResolvedExecutable,
+} from "../../../desktop/src/main/services/ai/cliExecutableResolver";
+import { resolveCliSpawnInvocation } from "../../../desktop/src/main/services/shared/processExecution";
+import type { TriageBundle } from "./triageContext";
+import { TriageCommandError, TriageUsageError } from "./triageErrors";
+
+/**
+ * Which coding agent CLI `ade triage` hands the machine to, and how.
+ *
+ * Detection order, prompt delivery, the Windows wrapper rule and the spawn
+ * itself all live here; the command orchestrator only picks one and runs it.
+ */
+
+/**
+ * How each CLI accepts the prompt we want it to start with.
+ *
+ * `positional` is verified against each CLI's own `--help`: claude, codex,
+ * cursor-agent and droid all document a trailing `[prompt]` that starts an
+ * interactive session seeded with it. OpenCode is the exception — its
+ * positional argument is the *project directory* (`opencode [project]`), so
+ * passing a prompt there would silently launch it in a nonexistent folder. It
+ * is launched bare and the prompt is printed for the user to paste.
+ */
+type TriagePromptDelivery = "positional" | "paste";
+
+export type TriageProviderName =
+  | "claude"
+  | "codex"
+  | "cursor-agent"
+  | "opencode"
+  | "droid";
+
+export type TriageProviderSpec = {
+  name: TriageProviderName;
+  label: string;
+  command: string;
+  promptDelivery: TriagePromptDelivery;
+};
+
+/** Detection order. First installed one wins unless `--provider` overrides it. */
+export const TRIAGE_PROVIDERS: readonly TriageProviderSpec[] = [
+  { name: "claude", label: "Claude Code", command: "claude", promptDelivery: "positional" },
+  { name: "codex", label: "Codex", command: "codex", promptDelivery: "positional" },
+  { name: "cursor-agent", label: "Cursor CLI", command: "cursor-agent", promptDelivery: "positional" },
+  { name: "opencode", label: "OpenCode", command: "opencode", promptDelivery: "paste" },
+  { name: "droid", label: "Droid", command: "droid", promptDelivery: "positional" },
+];
+
+export type DetectedTriageProvider = TriageProviderSpec & {
+  /** Absolute path to the executable, as spelled on disk. */
+  path: string;
+};
+
+type TriageExecutableResolver = (
+  command: string,
+  env: NodeJS.ProcessEnv,
+) => ResolvedExecutable | null;
+
+/**
+ * The shared resolver, not a bare `fs.existsSync(path.join(dir, name))`.
+ *
+ * On Windows an extension-less file is not launchable at all: `npm i -g codex`
+ * drops `codex` (an sh script), `codex.cmd` and `codex.ps1` side by side, and
+ * only the latter two can run. `resolveExecutableFromKnownLocations` resolves
+ * the way Windows does — PATHEXT, then the known install directories — and
+ * reports the on-disk casing.
+ */
+export const defaultTriageExecutableResolver: TriageExecutableResolver = (command, env) =>
+  resolveExecutableFromKnownLocations(command, env);
+
+export function detectTriageProviders(
+  options: {
+    env?: NodeJS.ProcessEnv;
+    resolve?: TriageExecutableResolver;
+    providers?: readonly TriageProviderSpec[];
+  } = {},
+): DetectedTriageProvider[] {
+  const env = options.env ?? process.env;
+  const resolve = options.resolve ?? defaultTriageExecutableResolver;
+  const detected: DetectedTriageProvider[] = [];
+  for (const spec of options.providers ?? TRIAGE_PROVIDERS) {
+    let resolved: ResolvedExecutable | null = null;
+    try {
+      resolved = resolve(spec.command, env);
+    } catch {
+      // A resolver that throws (an unreadable directory on PATH) must not take
+      // the whole command down; that provider is simply not available.
+      resolved = null;
+    }
+    if (resolved?.path) detected.push({ ...spec, path: resolved.path });
+  }
+  return detected;
+}
+
+export function parseTriageProviderName(value: string): TriageProviderName {
+  const normalized = value.trim().toLowerCase();
+  const aliases: Record<string, TriageProviderName> = {
+    claude: "claude",
+    "claude-code": "claude",
+    codex: "codex",
+    cursor: "cursor-agent",
+    "cursor-agent": "cursor-agent",
+    "cursor-cli": "cursor-agent",
+    opencode: "opencode",
+    droid: "droid",
+    factory: "droid",
+  };
+  const match = aliases[normalized];
+  if (!match) {
+    throw new TriageUsageError(
+      `Unknown provider '${value}'. Known providers: ${TRIAGE_PROVIDERS.map((p) => p.name).join(", ")}.`,
+    );
+  }
+  return match;
+}
+
+export function describeTriageProviders(providers: readonly DetectedTriageProvider[]): string {
+  if (providers.length === 0) return "none";
+  return providers.map((provider) => provider.name).join(", ");
+}
+
+export type TriageLaunchPlan = {
+  provider: TriageProviderName;
+  label: string;
+  command: string;
+  args: string[];
+  windowsVerbatimArguments: boolean;
+  /** False for OpenCode, whose positional argument is a directory, not a prompt. */
+  promptDelivered: boolean;
+};
+
+export function buildTriageLaunchPlan(
+  provider: DetectedTriageProvider,
+  prompt: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): TriageLaunchPlan {
+  const wanted = provider.promptDelivery === "positional";
+  const invocation = resolveCliSpawnInvocation(
+    provider.path,
+    wanted ? [prompt] : [],
+    env,
+    platform,
+  );
+  // A wrapped invocation means Windows could not spawn this executable directly
+  // — a `.cmd`/`.bat` shim goes through `cmd.exe /d /s /c`, a `.ps1` through
+  // PowerShell — and both rewrite the command line before the CLI sees argv:
+  // `%USERPROFILE%` expands unescapably and embedded newlines flatten to
+  // spaces. The triage prompt is multi-line and contains paths, so it would
+  // arrive corrupted. Keep it off the command line and have the user paste it,
+  // the same choice ADE's PTY launch builders make for the same reason.
+  const wrapped = invocation.command !== provider.path;
+  if (wanted && wrapped) {
+    const bare = resolveCliSpawnInvocation(provider.path, [], env, platform);
+    return {
+      provider: provider.name,
+      label: provider.label,
+      command: bare.command,
+      args: bare.args,
+      windowsVerbatimArguments: bare.windowsVerbatimArguments === true,
+      promptDelivered: false,
+    };
+  }
+  return {
+    provider: provider.name,
+    label: provider.label,
+    command: invocation.command,
+    args: invocation.args,
+    windowsVerbatimArguments: invocation.windowsVerbatimArguments === true,
+    promptDelivered: wanted,
+  };
+}
+
+export type TriageAgentSpawner = (plan: TriageLaunchPlan) => Promise<number>;
+
+/**
+ * stdio is inherited, so the user is talking to their agent directly — this
+ * process is only the launcher. It exits with whatever the agent exited with.
+ */
+export const spawnTriageAgent: TriageAgentSpawner = (plan) =>
+  new Promise<number>((resolve, reject) => {
+    const child = spawn(plan.command, plan.args, {
+      stdio: "inherit",
+      windowsVerbatimArguments: plan.windowsVerbatimArguments,
+      // A `.cmd` shim is launched through `cmd.exe`, which pops its own console
+      // window on Windows. stdio is inherited, so the agent is already talking
+      // in this terminal; a second empty window is pure noise.
+      windowsHide: true,
+    });
+    // The files are already written, so a failed spawn is a launch problem and
+    // nothing more — say which command failed and let the user paste the prompt
+    // somewhere else, rather than printing a stack over the paths.
+    child.once("error", (error: unknown) => {
+      const detail = error instanceof Error ? error.message : String(error);
+      reject(new TriageCommandError(
+        `Could not start ${plan.label} (${plan.command}): ${detail}. `
+        + "The triage files are already written — paste the prompt into any agent.",
+      ));
+    });
+    child.once("close", (code, signal) => {
+      if (typeof code === "number") resolve(code);
+      else resolve(signal ? 1 : 0);
+    });
+  });
+
+/**
+ * What the user sees on stderr just before the agent takes over the terminal.
+ *
+ * Printed for every provider, because the launch replaces this process's stdio
+ * and there is no other moment to say where the files are. For OpenCode it
+ * carries the prompt itself: its positional argument is a project directory, so
+ * the prompt cannot be passed on the command line and has to be pasted.
+ */
+export function triageLaunchNotice(
+  bundle: TriageBundle,
+  plan: TriageLaunchPlan,
+  prompt: string,
+): string {
+  const lines = [
+    `Starting ${plan.label} for triage.`,
+    `  context:  ${bundle.contextPath}`,
+    `  playbook: ${bundle.playbookPath} (${bundle.playbookSource})`,
+  ];
+  if (!plan.promptDelivered) {
+    lines.push(
+      "",
+      `${plan.label} starts empty here — this install cannot take the prompt on its`,
+      "command line without mangling it. Paste this in:",
+      "",
+      prompt,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
diff --git a/apps/ade-cli/src/commands/triagePlaybook.ts b/apps/ade-cli/src/commands/triagePlaybook.ts
new file mode 100644
index 0000000000..6997a3eb9b
--- /dev/null
+++ b/apps/ade-cli/src/commands/triagePlaybook.ts
@@ -0,0 +1,304 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { DIAGNOSTIC_ISSUE_REPO } from "../services/diagnostics/diagnosticReport";
+
+/**
+ * Where `ade triage` gets the playbook it hands to a coding agent.
+ *
+ * Preference order: an explicit override, the copy this build shipped, the ADE
+ * checkout this CLI is actually installed in, then the working directory. The
+ * maintained copy on `main` is fetched first when the network answers quickly.
+ */
+
+const TRIAGE_PLAYBOOK_REPO_SEGMENTS = ["docs", "triage", "PLAYBOOK.md"] as const;
+const TRIAGE_PLAYBOOK_REPO_PATH = TRIAGE_PLAYBOOK_REPO_SEGMENTS.join("/");
+export const TRIAGE_PLAYBOOK_REMOTE_URL =
+  `https://raw.githubusercontent.com/${DIAGNOSTIC_ISSUE_REPO}/main/${TRIAGE_PLAYBOOK_REPO_PATH}`;
+/** Short on purpose: a broken machine is often a machine with no network. */
+const TRIAGE_PLAYBOOK_FETCH_TIMEOUT_MS = 3_000;
+/** The playbook is prose. Anything larger than this is not the playbook. */
+const TRIAGE_PLAYBOOK_MAX_BYTES = 512 * 1024;
+/** Environment kill switch for the network fetch (air-gapped hosts, tests). */
+export const TRIAGE_NO_FETCH_ENV = "ADE_TRIAGE_NO_FETCH";
+/** Explicit local playbook override, for development and for packagers. */
+export const TRIAGE_PLAYBOOK_PATH_ENV = "ADE_TRIAGE_PLAYBOOK";
+/** How far up from the entry point an ADE checkout may be. Matches bootstrap. */
+const TRIAGE_PLAYBOOK_WALK_MAX_DEPTH = 8;
+
+export type TriagePlaybookSource = "remote" | "local";
+
+export type TriagePlaybook = {
+  text: string;
+  source: TriagePlaybookSource;
+  /** The URL or file path the text actually came from, for the record. */
+  origin: string;
+};
+
+/**
+ * The last-resort copy, used when this build shipped without the doc and the
+ * network is unreachable. It is deliberately not a second copy of the playbook
+ * — a stale duplicate would be worse than a short one — it is the safety rules
+ * plus where to read the real thing.
+ */
+const EMBEDDED_TRIAGE_PLAYBOOK = `# ADE triage playbook (built-in minimum)
+
+The full playbook could not be read from this machine or fetched from GitHub, so
+this is the reduced copy compiled into the ADE CLI. Read the full one at
+${TRIAGE_PLAYBOOK_REMOTE_URL} when you have a network.
+
+## Safety rules
+
+1. Diagnose read-only first. \`ade doctor --text\`, \`ade brain status --text\`,
+   \`ade runtime service-status --text\`, \`ade sync status --text\`,
+   \`ade auth status --text\` and \`ade tools status --text\` all change nothing.
+2. Propose every mutation before running it, and say how to undo it.
+3. Never delete anything under \`~/.ade\` / \`$ADE_HOME\` or under a project's
+   \`.ade/\` — databases, secrets, artifacts, transcripts. Never delete
+   \`ade.db\`, \`ade.db-wal\` or \`ade.db-shm\`.
+4. Never kill processes by name or pattern. Use \`ade brain stop\` /
+   \`ade brain restart\`, or an exact PID whose command line you verified.
+5. Prefer the ADE command over the OS command: \`ade brain restart\` over
+   \`launchctl\`, \`ade runtime install-service\` over editing a plist,
+   \`ade brain repair-credentials\` over touching the keychain.
+6. Never print secrets. Report whether a file is readable, never its contents.
+7. One change at a time, then re-run \`ade doctor --text\` and report what moved.
+
+## First moves
+
+\`\`\`bash
+ade doctor --text            # one ok/warn/fail row per check
+ade brain status --text      # endpoint, service, sync, last failure
+ade runtime status --text    # reports \`starting: true\` while the brain boots
+\`\`\`
+
+A brain reported as \`starting\` is coming up, not broken: wait, do not restart.
+If a row still fails and nothing explains it, \`ade report-issue --open\` files a
+redacted report.
+`;
+
+function readPlaybookFile(candidate: string): string | null {
+  try {
+    const stat = fs.statSync(candidate);
+    if (!stat.isFile() || stat.size === 0 || stat.size > TRIAGE_PLAYBOOK_MAX_BYTES) return null;
+    const text = fs.readFileSync(candidate, "utf8");
+    return text.trim() ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The file, canonicalized, only if it really sits inside `boundary`.
+ *
+ * Mirrors `canonicalDirectoryWithin` in `apps/ade-cli/src/bootstrap.ts` (the
+ * helper behind `trustedAgentSkillsRootForCliEntry`), for a file rather than a
+ * directory: `realpath` both ends first, so a symlink planted inside an
+ * accepted tree cannot point the CLI at a playbook outside it.
+ */
+function canonicalFileWithin(file: string | null, boundary: string | null): string | null {
+  if (!file || !boundary) return null;
+  try {
+    const canonicalFile = fs.realpathSync(file);
+    const canonicalBoundary = fs.realpathSync(boundary);
+    if (!fs.statSync(canonicalFile).isFile()) return null;
+    const relative = path.relative(canonicalBoundary, canonicalFile);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return null;
+    return canonicalFile;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The playbook belonging to the ADE install this CLI was launched from, or
+ * nothing.
+ *
+ * This is the anchored walk from `trustedAgentSkillsRootForCliEntry` in
+ * `apps/ade-cli/src/bootstrap.ts`, applied to the same problem. An unanchored
+ * "try `docs/triage/PLAYBOOK.md` at every ancestor" walk climbs straight out of
+ * an npm-global install into `$HOME`, where any `~/docs/triage/PLAYBOOK.md`
+ * would out-rank the shipped copy — and this file becomes instructions a coding
+ * agent follows on a machine its owner is trying to repair. So: stop at the
+ * first `ade-cli` ancestor, take the playbook that belongs to it, and
+ * containment-check the result. No marker, no candidate.
+ */
+function anchoredPlaybookForEntryDir(startDir: string | null): string | null {
+  if (!startDir) return null;
+  let current: string;
+  try {
+    current = fs.realpathSync(startDir);
+  } catch {
+    return null;
+  }
+  for (let depth = 0; depth < TRIAGE_PLAYBOOK_WALK_MAX_DEPTH; depth += 1) {
+    if (path.basename(current) === "ade-cli") {
+      const parent = path.dirname(current);
+      // `apps/ade-cli` is the repo layout: the doc lives at the repo root.
+      if (path.basename(parent) === "apps") {
+        const repoRoot = path.dirname(parent);
+        return canonicalFileWithin(
+          path.join(repoRoot, ...TRIAGE_PLAYBOOK_REPO_SEGMENTS),
+          repoRoot,
+        );
+      }
+      // The packaged layout: the CLI is unpacked at `<Resources>/ade-cli` and
+      // `extraResources` ships `docs/triage` beside it. One level, contained —
+      // the same sibling lookup `trustedAgentSkillsRootForCliEntry` does for
+      // `<Resources>/agent-skills`.
+      return canonicalFileWithin(
+        path.join(parent, ...TRIAGE_PLAYBOOK_REPO_SEGMENTS),
+        parent,
+      );
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+export type TriagePlaybookLookupOptions = {
+  env?: NodeJS.ProcessEnv;
+  cwd?: string | null;
+  /** The module directory. Defaults to `__dirname` when the bundle has one. */
+  dirname?: string | null;
+  /**
+   * The entry script (`process.argv[1]`). Only consulted by default when no
+   * `dirname` was passed — an explicit `dirname` means the caller is pinning
+   * the install root and a stray entry script must not reopen it — but a test
+   * can pass it directly to exercise this rung on its own.
+   */
+  argv1?: string | null;
+  resourcesPath?: string | null;
+};
+
+/**
+ * Where a local copy of the playbook can be, in preference order: an explicit
+ * override, the copy this build shipped, the ADE install this CLI is running
+ * from, then the working directory.
+ *
+ * The packaged and install-anchored copies outrank the working directory on
+ * purpose. `ade triage` is run from wherever the user's shell happens to be,
+ * and any checkout that carries a `docs/triage/PLAYBOOK.md` — an old ADE clone,
+ * a fork, a vendored copy — would otherwise silently out-rank the playbook this
+ * build was tested with. `ADE_TRIAGE_PLAYBOOK` stays first so a developer can
+ * still point at their working copy deliberately.
+ */
+function triagePlaybookLocalCandidates(options: TriagePlaybookLookupOptions = {}): string[] {
+  const env = options.env ?? process.env;
+  const candidates: string[] = [];
+  const push = (value: string | null | undefined): void => {
+    const trimmed = value?.trim();
+    if (!trimmed) return;
+    if (!candidates.includes(trimmed)) candidates.push(trimmed);
+  };
+
+  push(env[TRIAGE_PLAYBOOK_PATH_ENV]);
+
+  // One packaged path, matching the single `extraResources` entry that ships
+  // `docs/triage`. A second guessed layout would only ever mask a packaging
+  // change that should fail loudly instead.
+  const resourcesPath = options.resourcesPath
+    ?? (process as NodeJS.Process & { resourcesPath?: string }).resourcesPath
+    ?? null;
+  if (resourcesPath) push(path.join(resourcesPath, ...TRIAGE_PLAYBOOK_REPO_SEGMENTS));
+
+  // Two entry points, because neither covers both builds: `__dirname` is the
+  // bundled `dist/` in a release CLI but is absent under an ESM loader, and
+  // `argv[1]` is the entry script, which is what a `tsx src/cli.ts` run has
+  // instead. Both are walked to their ADE install root and no further, and
+  // both rank ABOVE cwd so a checkout the shell happens to sit in cannot
+  // out-rank the playbook this install ships.
+  const entryDirs = [
+    options.dirname ?? (typeof __dirname !== "undefined" ? __dirname : null),
+    (options.argv1 !== undefined
+      ? options.argv1
+      : (options.dirname === undefined ? process.argv[1] ?? null : null)),
+  ];
+  for (const [index, entry] of entryDirs.entries()) {
+    if (!entry) continue;
+    // The first entry is already a directory; the second is a script path.
+    push(anchoredPlaybookForEntryDir(index === 0 ? entry : path.dirname(entry)));
+  }
+
+  const cwd = options.cwd ?? process.cwd();
+  if (cwd) push(path.join(cwd, ...TRIAGE_PLAYBOOK_REPO_SEGMENTS));
+
+  return candidates;
+}
+
+/**
+ * The last-resort playbook: no disk read, no network, no way to fail.
+ *
+ * Exported so the triage command can reach for the same value when its own
+ * resolver rejects, rather than shipping a bundle with no playbook at all.
+ */
+export function embeddedTriagePlaybook(): TriagePlaybook {
+  return { text: EMBEDDED_TRIAGE_PLAYBOOK, source: "local", origin: "built into this ADE CLI" };
+}
+
+export function readLocalTriagePlaybook(
+  options: TriagePlaybookLookupOptions = {},
+): TriagePlaybook {
+  for (const candidate of triagePlaybookLocalCandidates(options)) {
+    const text = readPlaybookFile(candidate);
+    if (text) return { text, source: "local", origin: candidate };
+  }
+  return embeddedTriagePlaybook();
+}
+
+/**
+ * The maintained copy on `main`, falling back to whatever this machine has.
+ *
+ * The fetch is short, best effort, and skippable: the machine that needs triage
+ * is often the machine with no working network, and a command that hangs for 30
+ * seconds before printing a path is a command nobody runs twice.
+ */
+export async function resolveTriagePlaybook(
+  options: TriagePlaybookLookupOptions & {
+    fetchImpl?: typeof fetch | null;
+    timeoutMs?: number;
+    url?: string;
+  } = {},
+): Promise<TriagePlaybook> {
+  const env = options.env ?? process.env;
+  const local = () => readLocalTriagePlaybook(options);
+  if (env[TRIAGE_NO_FETCH_ENV]?.trim()) return local();
+  const fetchImpl = options.fetchImpl === undefined
+    ? (typeof fetch === "function" ? fetch : null)
+    : options.fetchImpl;
+  if (!fetchImpl) return local();
+
+  const url = options.url ?? TRIAGE_PLAYBOOK_REMOTE_URL;
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    options.timeoutMs ?? TRIAGE_PLAYBOOK_FETCH_TIMEOUT_MS,
+  );
+  try {
+    const response = await fetchImpl(url, {
+      signal: controller.signal,
+      // The pinned raw.githubusercontent.com URL answers directly. A redirect
+      // means something rewrote the request — a captive portal, a proxy, a
+      // hijacked DNS answer — and following it would fetch instructions for a
+      // coding agent from an origin nobody pinned. Fail to the local copy.
+      redirect: "error",
+      headers: { accept: "text/plain" },
+    });
+    if (!response.ok) return local();
+    // Checked before the body is read, so a mis-served giant file is refused
+    // rather than buffered.
+    const declaredLength = Number(response.headers?.get?.("content-length") ?? "");
+    if (Number.isFinite(declaredLength) && declaredLength > TRIAGE_PLAYBOOK_MAX_BYTES) return local();
+    const text = await response.text();
+    if (!text.trim() || text.length > TRIAGE_PLAYBOOK_MAX_BYTES) return local();
+    return { text, source: "remote", origin: url };
+  } catch {
+    // Offline, DNS down, TLS interception, aborted by the timeout — all the
+    // same answer: use what is on this machine.
+    return local();
+  } finally {
+    clearTimeout(timer);
+  }
+}
diff --git a/apps/ade-cli/src/services/imageAttachment.ts b/apps/ade-cli/src/services/imageAttachment.ts
index cf3e988f45..12d38587e5 100644
--- a/apps/ade-cli/src/services/imageAttachment.ts
+++ b/apps/ade-cli/src/services/imageAttachment.ts
@@ -1,8 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
-import { randomUUID } from "node:crypto";
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  legacyAttachmentCapMessage,
+} from "../../../desktop/src/shared/chatAttachmentLimits";
+import {
+  resolveStagedAttachmentExtension,
+  stagedAttachmentDestPath,
+} from "../../../desktop/src/shared/chatAttachmentStagingFs";
 
-const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+// The base64/in-memory ceiling, single-sourced so the constant and every
+// rejection message that renders it stay in step.
+const MAX_IMAGE_BYTES = LEGACY_MAX_CHAT_ATTACHMENT_BYTES;
 const IMAGE_MIME_BY_EXTENSION: Record<string, string> = {
   ".bmp": "image/bmp",
   ".gif": "image/gif",
@@ -39,7 +48,7 @@ function sniffImageMimeType(buffer: Buffer): string | null {
 export async function readImageFileAndSniffMime(filePath: string): Promise<{ data: Buffer; mimeType: string }> {
   const stat = await fs.promises.stat(filePath);
   if (!stat.isFile()) throw new Error("Path is not a file.");
-  if (stat.size > MAX_IMAGE_BYTES) throw new Error("Image must be 10 MB or smaller.");
+  if (stat.size > MAX_IMAGE_BYTES) throw new Error(legacyAttachmentCapMessage("Image"));
   const data = await fs.promises.readFile(filePath);
   const mimeType = sniffImageMimeType(data);
   if (!mimeType) throw new Error("Path is not an image.");
@@ -62,9 +71,9 @@ function decodeBase64ImagePayload(value: string): Buffer {
     throw new Error("Temporary attachment base64 is invalid.");
   }
   const maxEncodedLength = Math.ceil(MAX_IMAGE_BYTES / 3) * 4;
-  if (compact.length > maxEncodedLength) throw new Error("Temporary attachments must be 10 MB or smaller.");
+  if (compact.length > maxEncodedLength) throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
   const content = Buffer.from(compact, "base64");
-  if (content.byteLength > MAX_IMAGE_BYTES) throw new Error("Temporary attachments must be 10 MB or smaller.");
+  if (content.byteLength > MAX_IMAGE_BYTES) throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
   return content;
 }
 
@@ -80,7 +89,7 @@ function parseTempAttachmentPayload(payload: Record<string, unknown>) {
     const content = match[2] === ";base64"
       ? decodeBase64ImagePayload(match[3] ?? "")
       : Buffer.from(decodeURIComponent(match[3] ?? ""), "utf8");
-    if (content.byteLength > MAX_IMAGE_BYTES) throw new Error("Temporary attachments must be 10 MB or smaller.");
+    if (content.byteLength > MAX_IMAGE_BYTES) throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
     if (sniffImageMimeType(content) !== mimeType) throw new Error("Temporary attachment MIME type does not match payload.");
     return { content, filename, mimeType };
   }
@@ -98,10 +107,21 @@ export async function saveImageTempAttachment(
   payload: Record<string, unknown>,
 ): Promise<{ path: string; mimeType: string; previewDataUrl: string | null }> {
   const { content, filename, mimeType } = parseTempAttachmentPayload(payload);
-  await fs.promises.mkdir(baseDir, { recursive: true });
-  const ext = path.extname(filename) || Object.entries(IMAGE_MIME_BY_EXTENSION)
-    .find(([, entryMime]) => entryMime === mimeType)?.[0] || ".png";
-  const destPath = path.join(baseDir, `${randomUUID()}${ext}`);
+  const attachmentsDir = path.resolve(baseDir);
+  await fs.promises.mkdir(attachmentsDir, { recursive: true });
+  // The display name is remote-controlled on this path (`chat.saveTempAttachment`
+  // over sync), and unlike the generic byte-staging helper this route has
+  // already sniffed the bytes and verified them against a declared image MIME.
+  // So the bytes name the file, not the caller: a real PNG called `run.cmd`
+  // stages as `.png`. The caller's extension is honoured only where the table
+  // agrees it names this exact MIME, which is what keeps a `.jpg` from being
+  // rewritten to the table's first `image/jpeg` entry.
+  const namedExtension = resolveStagedAttachmentExtension(filename, null);
+  const ext = namedExtension && IMAGE_MIME_BY_EXTENSION[namedExtension] === mimeType
+    ? namedExtension
+    : Object.entries(IMAGE_MIME_BY_EXTENSION)
+      .find(([, entryMime]) => entryMime === mimeType)?.[0] || ".png";
+  const destPath = stagedAttachmentDestPath(attachmentsDir, ext);
   await fs.promises.writeFile(destPath, content);
   return { path: destPath, mimeType, previewDataUrl: null };
 }
diff --git a/apps/ade-cli/src/services/personalChats/personalChatScope.ts b/apps/ade-cli/src/services/personalChats/personalChatScope.ts
index 53ca1bcece..3c345e4120 100644
--- a/apps/ade-cli/src/services/personalChats/personalChatScope.ts
+++ b/apps/ade-cli/src/services/personalChats/personalChatScope.ts
@@ -14,6 +14,7 @@ import { resolveReadableHistoryPath } from "../../../../desktop/src/main/service
 import type { AdeRuntime } from "../../bootstrap";
 import { resolveMachineAdeLayout } from "../projects/machineLayout";
 import { readImageFileAndSniffMime, saveImageTempAttachment } from "../imageAttachment";
+import { projectAttachmentsDir } from "../../../../desktop/src/shared/chatAttachmentStagingFs";
 
 type PersonalChatScopeOptions = {
   createRuntime?: typeof import("../../bootstrap").createAdeRuntime;
@@ -374,13 +375,13 @@ export class PersonalChatScope {
       }
       case "saveTempAttachment":
         result = await saveImageTempAttachment(
-          path.join(runtime.projectRoot, ".ade", "attachments"),
+          projectAttachmentsDir(runtime.projectRoot),
           args,
         );
         break;
       case "getImageDataUrl": {
         const attachmentsRoot = await fs.promises.realpath(
-          path.join(runtime.projectRoot, ".ade", "attachments"),
+          projectAttachmentsDir(runtime.projectRoot),
         );
         const requestedPath = await fs.promises.realpath(requiredString(args.path, "path"));
         if (requestedPath !== attachmentsRoot && !requestedPath.startsWith(`${attachmentsRoot}${path.sep}`)) {
diff --git a/apps/ade-cli/src/services/sync/attachmentUploadService.test.ts b/apps/ade-cli/src/services/sync/attachmentUploadService.test.ts
new file mode 100644
index 0000000000..ab897a2f72
--- /dev/null
+++ b/apps/ade-cli/src/services/sync/attachmentUploadService.test.ts
@@ -0,0 +1,221 @@
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  ATTACHMENT_UPLOAD_PATH,
+  createAttachmentUploadRegistry,
+  type AttachmentUploadRegistry,
+} from "./attachmentUploadService";
+
+const FALLTHROUGH_BODY = "fell-through";
+
+describe("attachmentUploadService", () => {
+  let tempRoot: string;
+  let server: http.Server;
+  let baseUrl: string;
+  let registry: AttachmentUploadRegistry;
+  let nowMs: number;
+
+  const attachmentsDir = () => path.join(tempRoot, ".ade", "attachments");
+
+  const listedAttachments = (): string[] => {
+    try {
+      return fs.readdirSync(attachmentsDir()).sort();
+    } catch {
+      return [];
+    }
+  };
+
+  const startServer = async (target: AttachmentUploadRegistry): Promise<void> => {
+    server = http.createServer((request, response) => {
+      if (target.handleRequest(request, response)) return;
+      // Stands in for the real 426 loopback-probe fall-through.
+      response.writeHead(426, { "content-type": "text/plain" });
+      response.end(FALLTHROUGH_BODY);
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const address = server.address();
+    if (typeof address !== "object" || !address) throw new Error("server did not bind");
+    baseUrl = `http://127.0.0.1:${address.port}`;
+  };
+
+  beforeEach(async () => {
+    tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ade-upload-"));
+    nowMs = 1_700_000_000_000;
+    registry = createAttachmentUploadRegistry({ now: () => nowMs, maxBytes: 1024 });
+    await startServer(registry);
+  });
+
+  afterEach(async () => {
+    registry.dispose();
+    await new Promise<void>((resolve) => {
+      server.closeAllConnections?.();
+      server.close(() => resolve());
+    });
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  });
+
+  const upload = async (
+    ticket: string | null,
+    body: BodyInit,
+    init: RequestInit = {},
+  ): Promise<Response> =>
+    await fetch(`${baseUrl}${ATTACHMENT_UPLOAD_PATH}`, {
+      method: "POST",
+      ...init,
+      headers: {
+        ...(ticket ? { authorization: `Bearer ${ticket}` } : {}),
+        ...(init.headers ?? {}),
+      },
+      body,
+    });
+
+  it("stores a posted body under the project attachments dir and returns its path", async () => {
+    const issued = registry.issue({ projectRoot: tempRoot, filename: "diagram.PNG" });
+    expect(issued.path).toBe(ATTACHMENT_UPLOAD_PATH);
+    expect(issued.maxBytes).toBe(1024);
+    expect(issued.expiresAtMs).toBeGreaterThan(nowMs);
+
+    const content = Buffer.from("attachment-bytes-\u0000\u00ff", "binary");
+    const response = await upload(issued.ticket, content);
+    expect(response.status).toBe(200);
+    const result = (await response.json()) as { path: string };
+
+    expect(path.dirname(result.path)).toBe(path.resolve(attachmentsDir()));
+    expect(path.extname(result.path)).toBe(".png");
+    expect(fs.readFileSync(result.path)).toEqual(content);
+    expect(listedAttachments()).toHaveLength(1);
+    expect(registry.pendingCount()).toBe(0);
+  });
+
+  it("falls through for any other pathname", async () => {
+    const response = await fetch(`${baseUrl}/`, { method: "GET" });
+    expect(response.status).toBe(426);
+    expect(await response.text()).toBe(FALLTHROUGH_BODY);
+  });
+
+  it("handles the upload path even with a query string appended", async () => {
+    const response = await fetch(`${baseUrl}${ATTACHMENT_UPLOAD_PATH}?ticket=nope`, { method: "GET" });
+    // Handled by the registry (405), not the 426 fall-through.
+    expect(response.status).toBe(405);
+  });
+
+  it("rejects a request with no Authorization header", async () => {
+    registry.issue({ projectRoot: tempRoot, filename: "a.png" });
+    const response = await upload(null, "hello");
+    expect(response.status).toBe(401);
+    expect(listedAttachments()).toEqual([]);
+  });
+
+  it("rejects an unknown ticket", async () => {
+    registry.issue({ projectRoot: tempRoot, filename: "a.png" });
+    const response = await upload("not-a-real-ticket", "hello");
+    expect(response.status).toBe(401);
+    expect(listedAttachments()).toEqual([]);
+  });
+
+  it("rejects an expired ticket", async () => {
+    const issued = registry.issue({ projectRoot: tempRoot, filename: "a.png" });
+    nowMs = issued.expiresAtMs + 1;
+    const response = await upload(issued.ticket, "hello");
+    expect(response.status).toBe(401);
+    expect(listedAttachments()).toEqual([]);
+  });
+
+  it("consumes a ticket on first use so a replay is rejected", async () => {
+    const issued = registry.issue({ projectRoot: tempRoot, filename: "a.txt" });
+    const first = await upload(issued.ticket, "hello");
+    expect(first.status).toBe(200);
+    const replay = await upload(issued.ticket, "hello again");
+    expect(replay.status).toBe(401);
+    expect(listedAttachments()).toHaveLength(1);
+  });
+
+  it("rejects a non-POST method", async () => {
+    const issued = registry.issue({ projectRoot: tempRoot, filename: "a.png" });
+    const response = await fetch(`${baseUrl}${ATTACHMENT_UPLOAD_PATH}`, {
+      method: "GET",
+      headers: { authorization: `Bearer ${issued.ticket}` },
+    });
+    expect(response.status).toBe(405);
+    expect(listedAttachments()).toEqual([]);
+  });
+
+  it("rejects a declared Content-Length over the cap before reading the body", async () => {
+    const issued = registry.issue({ projectRoot: tempRoot, filename: "a.bin" });
+    const response = await upload(issued.ticket, Buffer.alloc(2048, 7));
+    expect(response.status).toBe(413);
+    expect(listedAttachments()).toEqual([]);
+  });
+
+  it("caps a chunked body that declares no Content-Length and leaves no .part file", async () => {
+    const issued = registry.issue({ projectRoot: tempRoot, filename: "a.bin" });
+    const status = await new Promise<number | null>((resolve) => {
+      let observed: number | null = null;
+      const request = http.request(
+        `${baseUrl}${ATTACHMENT_UPLOAD_PATH}`,
+        {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${issued.ticket}`,
+            "transfer-encoding": "chunked",
+          },
+        },
+        (response) => {
+          observed = response.statusCode ?? null;
+          response.resume();
+          response.on("end", () => resolve(observed));
+          response.on("close", () => resolve(observed));
+        },
+      );
+      // The server answers and drops the socket while we are still writing, so
+      // a write-side EPIPE/ECONNRESET is expected — it must not mask a missing
+      // response, hence `observed` is the only thing we resolve with.
+      request.on("error", () => resolve(observed));
+      const chunk = Buffer.alloc(512, 3);
+      for (let index = 0; index < 8; index += 1) request.write(chunk);
+      request.end();
+    });
+    // Not `.catch(() => 413)`: a transport failure must fail the test, not pass it.
+    expect(status).toBe(413);
+    // The response is only written after the `.part` cleanup, so by the time
+    // the client sees 413 the attachments dir must hold nothing at all — no
+    // final file and no leftover partial.
+    expect(listedAttachments()).toEqual([]);
+  });
+
+  it("never lets a traversal-shaped filename escape the attachments dir", async () => {
+    for (const filename of ["../../../../etc/passwd", "x.png/../../evil.sh", "..\\..\\evil.bat"]) {
+      const issued = registry.issue({ projectRoot: tempRoot, filename });
+      const response = await upload(issued.ticket, "payload");
+      expect(response.status).toBe(200);
+      const result = (await response.json()) as { path: string };
+      expect(path.dirname(result.path)).toBe(path.resolve(attachmentsDir()));
+      // Basename is a fresh UUID plus at most a sanitized extension.
+      expect(path.basename(result.path, path.extname(result.path))).toMatch(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+      );
+      expect(fs.existsSync(result.path)).toBe(true);
+    }
+    expect(fs.existsSync(path.join(tempRoot, ".ade", "evil.sh"))).toBe(false);
+  });
+
+  it("refuses to issue a ticket without a project root", () => {
+    expect(() => registry.issue({ projectRoot: "   ", filename: "a.png" })).toThrow(
+      /project root/i,
+    );
+  });
+
+  it("prunes expired tickets instead of leaking them", () => {
+    const first = registry.issue({ projectRoot: tempRoot, filename: "a.png" });
+    expect(registry.pendingCount()).toBe(1);
+    nowMs = first.expiresAtMs + 1;
+    registry.issue({ projectRoot: tempRoot, filename: "b.png" });
+    expect(registry.pendingCount()).toBe(1);
+  });
+});
diff --git a/apps/ade-cli/src/services/sync/attachmentUploadService.ts b/apps/ade-cli/src/services/sync/attachmentUploadService.ts
new file mode 100644
index 0000000000..4190027267
--- /dev/null
+++ b/apps/ade-cli/src/services/sync/attachmentUploadService.ts
@@ -0,0 +1,369 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { MAX_CHAT_ATTACHMENT_BYTES } from "../../../../desktop/src/shared/chatAttachmentLimits";
+import {
+  projectAttachmentsDir,
+  safeAttachmentExtension,
+  stagedAttachmentDestPath,
+} from "../../../../desktop/src/shared/chatAttachmentStagingFs";
+
+/**
+ * Streamed HTTP attachment upload for paired sync clients.
+ *
+ * The sync stack has no HTTP authentication of its own — the only request the
+ * listener answered before this route existed was an unconditional 426. So
+ * authorization here is DELEGATED to the already-authenticated WebSocket
+ * session: a peer that finished `hello` mints a short-lived, single-use ticket
+ * over the command channel (`chat.createAttachmentUpload`) and presents it as
+ * an HTTP bearer. The HTTP leg carries no standing authority — a ticket names
+ * one project root, one extension, expires in two minutes, and is consumed on
+ * first use, so a replay cannot resume a partially uploaded body.
+ *
+ * The destination basename is always a fresh UUID. The client-supplied filename
+ * only ever contributes a validated extension, resolved once at issue time, so
+ * a ticket cannot smuggle a path fragment through to the write.
+ */
+
+export const ATTACHMENT_UPLOAD_PATH = "/ade-attachments/upload";
+export const ATTACHMENT_UPLOAD_TICKET_TTL_MS = 120_000;
+
+export type AttachmentUploadTicket = {
+  ticket: string;
+  expiresAtMs: number;
+  maxBytes: number;
+  /** The upload path, so clients never hardcode it. */
+  path: string;
+};
+
+export type AttachmentUploadRegistry = {
+  issue(args: { projectRoot: string; filename: string; deviceId?: string | null }): AttachmentUploadTicket;
+  /** True when this request was an upload request (handled, success or failure). */
+  handleRequest(request: http.IncomingMessage, response: http.ServerResponse): boolean;
+  /** Test/diagnostic seam. */
+  pendingCount(): number;
+  dispose(): void;
+};
+
+type PendingTicket = {
+  ticket: string;
+  projectRoot: string;
+  ext: string;
+  expiresAtMs: number;
+  deviceId: string | null;
+};
+
+/**
+ * Same `(event, fields)` shape the rest of the sync stack logs with, so a
+ * `SharedSyncListenerLogger` or a host `Logger` can be passed straight through.
+ * A looser `(...args: unknown[]) => void` also satisfies it.
+ */
+type AttachmentUploadLogger = {
+  debug?: (message: string, fields?: Record<string, unknown>) => void;
+  warn?: (message: string, fields?: Record<string, unknown>) => void;
+};
+
+function bearerTokenFrom(request: http.IncomingMessage): string | null {
+  const header = request.headers.authorization;
+  const value = Array.isArray(header) ? header[0] : header;
+  if (typeof value !== "string") return null;
+  const match = /^Bearer[ ]+(\S+)$/i.exec(value.trim());
+  return match?.[1] ?? null;
+}
+
+/**
+ * Belt and braces over the `Map.get` above it, NOT a constant-time lookup.
+ *
+ * The hash lookup that finds the ticket is not constant time, so this
+ * comparison does not make the whole check constant time and is not claimed to.
+ * What protects the ticket is its shape: 32 bytes from `randomBytes`, so there
+ * is no low-entropy prefix for a timing oracle to walk toward. This runs anyway
+ * because it is free, and because it fails closed if the lookup key and the
+ * stored ticket ever stop being the same string.
+ */
+function equalsStoredTicket(a: string, b: string): boolean {
+  const left = Buffer.from(a, "utf8");
+  const right = Buffer.from(b, "utf8");
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(left, right);
+}
+
+function writeJson(response: http.ServerResponse, status: number, body: Record<string, unknown>): void {
+  if (response.headersSent || response.writableEnded) return;
+  const payload = JSON.stringify(body);
+  response.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(payload),
+    "cache-control": "no-store",
+  });
+  response.end(payload);
+}
+
+function parseContentLength(request: http.IncomingMessage): number | null {
+  const header = request.headers["content-length"];
+  const value = Array.isArray(header) ? header[0] : header;
+  if (typeof value !== "string" || !value.trim()) return null;
+  const parsed = Number(value.trim());
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+
+async function unlinkQuietly(filePath: string): Promise<void> {
+  try {
+    await fs.promises.unlink(filePath);
+  } catch {
+    // A torn upload may never have created the file; nothing to clean up.
+  }
+}
+
+type BodyResult = { ok: true } | { ok: false; reason: "too_large" | "io"; message: string };
+
+/**
+ * Stream the request body into `partPath`, aborting the moment the running
+ * total passes `maxBytes`. A chunked upload with no Content-Length is capped
+ * here and nowhere else, so this counter is the real ceiling.
+ */
+function streamBodyToFile(
+  request: http.IncomingMessage,
+  partPath: string,
+  maxBytes: number,
+): Promise<BodyResult> {
+  return new Promise<BodyResult>((resolve) => {
+    const out = fs.createWriteStream(partPath);
+    let total = 0;
+    let settled = false;
+    let outcome: BodyResult | null = null;
+    // Settle only on the write stream's `close`. `createWriteStream` opens its
+    // fd asynchronously, so resolving on the abort itself would let the caller
+    // unlink the `.part` file BEFORE the open completed — and the open would
+    // then recreate it. Waiting for `close` also guarantees the fd is released
+    // before the rename, which Windows requires.
+    const settle = (result: BodyResult) => {
+      if (outcome) return;
+      outcome = result;
+      out.destroy();
+    };
+    const onData = (chunk: Buffer) => {
+      total += chunk.length;
+      if (total > maxBytes) {
+        request.pause();
+        settle({
+          ok: false,
+          reason: "too_large",
+          message: "Attachment exceeds the maximum upload size.",
+        });
+        return;
+      }
+      if (!out.write(chunk)) {
+        request.pause();
+        out.once("drain", () => {
+          if (!settled && !outcome) request.resume();
+        });
+      }
+    };
+    const onEnd = () => {
+      out.end();
+    };
+    const onRequestError = (error: Error) => {
+      settle({ ok: false, reason: "io", message: error.message });
+    };
+    const onAborted = () => {
+      settle({ ok: false, reason: "io", message: "Upload aborted." });
+    };
+    out.on("error", (error: Error) => {
+      settle({ ok: false, reason: "io", message: error.message });
+    });
+    out.on("close", () => {
+      if (settled) return;
+      settled = true;
+      request.off("data", onData);
+      request.off("end", onEnd);
+      request.off("error", onRequestError);
+      request.off("aborted", onAborted);
+      resolve(outcome ?? { ok: true });
+    });
+    request.on("data", onData);
+    request.on("end", onEnd);
+    request.on("error", onRequestError);
+    request.on("aborted", onAborted);
+  });
+}
+
+export function createAttachmentUploadRegistry(options?: {
+  now?: () => number;
+  ttlMs?: number;
+  maxBytes?: number;
+  logger?: AttachmentUploadLogger;
+}): AttachmentUploadRegistry {
+  const now = options?.now ?? Date.now;
+  const ttlMs = Math.max(1_000, options?.ttlMs ?? ATTACHMENT_UPLOAD_TICKET_TTL_MS);
+  const maxBytes = Math.max(1, options?.maxBytes ?? MAX_CHAT_ATTACHMENT_BYTES);
+  const logger = options?.logger;
+  const pending = new Map<string, PendingTicket>();
+  let disposed = false;
+
+  // No timers: the map is swept on every issue and every request, which is the
+  // only moment a stale ticket could matter. A timer here would also have to be
+  // unref'd to keep short-lived CLI processes from hanging on exit.
+  const prune = () => {
+    const cutoff = now();
+    for (const [key, entry] of pending) {
+      if (entry.expiresAtMs <= cutoff) pending.delete(key);
+    }
+  };
+
+  const respondAndDrop = (
+    request: http.IncomingMessage,
+    response: http.ServerResponse,
+    status: number,
+    message: string,
+  ) => {
+    writeJson(response, status, { error: message });
+    // The client may still be pushing a body we refuse to read. Let the
+    // response flush first, then drop the socket instead of draining megabytes.
+    if (response.writableEnded) {
+      request.destroy();
+      return;
+    }
+    response.once("finish", () => {
+      request.destroy();
+    });
+    response.once("close", () => {
+      request.destroy();
+    });
+  };
+
+  const run = async (request: http.IncomingMessage, response: http.ServerResponse): Promise<void> => {
+    if (disposed) {
+      respondAndDrop(request, response, 503, "Attachment upload is not available.");
+      return;
+    }
+    if ((request.method ?? "").toUpperCase() !== "POST") {
+      respondAndDrop(request, response, 405, "Method not allowed.");
+      return;
+    }
+    prune();
+    const presented = bearerTokenFrom(request);
+    if (!presented) {
+      respondAndDrop(request, response, 401, "Missing upload ticket.");
+      return;
+    }
+    // The map lookup — not the comparison below it — is what decides whether a
+    // ticket is known, and a hash lookup is not constant time. That is fine
+    // here: the key is 32 random bytes, so there is no prefix to walk.
+    const entry = pending.get(presented);
+    // Single use: consume before a single body byte is read, so a replay can
+    // never resume a partial upload.
+    if (entry) pending.delete(presented);
+    if (!entry || !equalsStoredTicket(presented, entry.ticket) || entry.expiresAtMs <= now()) {
+      respondAndDrop(request, response, 401, "Invalid or expired upload ticket.");
+      return;
+    }
+
+    const declaredLength = parseContentLength(request);
+    if (declaredLength != null && declaredLength > maxBytes) {
+      respondAndDrop(request, response, 413, "Attachment exceeds the maximum upload size.");
+      return;
+    }
+
+    const attachmentsDir = path.resolve(projectAttachmentsDir(entry.projectRoot));
+    // Same UUID-basename + containment-recheck rule the local copy path uses,
+    // from the one shared helper, so the two cannot name destinations
+    // differently. It throws rather than returns on a containment failure,
+    // which the basename being a UUID makes unreachable today.
+    let destPath: string;
+    try {
+      destPath = stagedAttachmentDestPath(attachmentsDir, entry.ext);
+    } catch {
+      respondAndDrop(request, response, 400, "Invalid upload destination.");
+      return;
+    }
+
+    const partPath = `${destPath}.part`;
+    try {
+      await fs.promises.mkdir(attachmentsDir, { recursive: true });
+    } catch (error) {
+      logger?.warn?.("attachment_upload.mkdir_failed", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      respondAndDrop(request, response, 500, "Unable to prepare the attachment directory.");
+      return;
+    }
+
+    const result = await streamBodyToFile(request, partPath, maxBytes);
+    if (!result.ok) {
+      await unlinkQuietly(partPath);
+      if (result.reason === "too_large") {
+        respondAndDrop(request, response, 413, "Attachment exceeds the maximum upload size.");
+        return;
+      }
+      logger?.debug?.("attachment_upload.body_failed", { error: result.message });
+      // The socket is usually already gone on an aborted upload; writeJson
+      // no-ops if it is.
+      writeJson(response, 400, { error: "Upload failed." });
+      return;
+    }
+
+    try {
+      // Rename only after the full body landed, so a torn upload never leaves a
+      // half file at the final path for the chat to pick up.
+      await fs.promises.rename(partPath, destPath);
+    } catch (error) {
+      await unlinkQuietly(partPath);
+      logger?.warn?.("attachment_upload.rename_failed", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      writeJson(response, 500, { error: "Unable to store the attachment." });
+      return;
+    }
+    logger?.debug?.("attachment_upload.stored", { deviceId: entry.deviceId, ext: entry.ext });
+    writeJson(response, 200, { path: destPath });
+  };
+
+  return {
+    issue({ projectRoot, filename, deviceId }): AttachmentUploadTicket {
+      if (disposed) throw new Error("Attachment upload is not available on this host.");
+      const root = typeof projectRoot === "string" ? projectRoot.trim() : "";
+      if (!root) throw new Error("Attachment upload requires a project root.");
+      prune();
+      const ticket = randomBytes(32).toString("base64url");
+      const expiresAtMs = now() + ttlMs;
+      pending.set(ticket, {
+        ticket,
+        projectRoot: root,
+        ext: safeAttachmentExtension(typeof filename === "string" ? filename : ""),
+        expiresAtMs,
+        deviceId: typeof deviceId === "string" && deviceId.trim() ? deviceId.trim() : null,
+      });
+      return { ticket, expiresAtMs, maxBytes, path: ATTACHMENT_UPLOAD_PATH };
+    },
+
+    handleRequest(request: http.IncomingMessage, response: http.ServerResponse): boolean {
+      let pathname: string;
+      try {
+        // Parsed, never string-compared: a query string or a `//` prefix must
+        // not slip past into the 426 fall-through (or vice versa).
+        pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+      } catch {
+        return false;
+      }
+      if (pathname !== ATTACHMENT_UPLOAD_PATH) return false;
+      void run(request, response).catch((error: unknown) => {
+        logger?.warn?.("attachment_upload.unhandled_error", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        writeJson(response, 500, { error: "Upload failed." });
+      });
+      return true;
+    },
+
+    pendingCount(): number {
+      return pending.size;
+    },
+
+    dispose(): void {
+      disposed = true;
+      pending.clear();
+    },
+  };
+}
diff --git a/apps/ade-cli/src/services/sync/sharedSyncListener.ts b/apps/ade-cli/src/services/sync/sharedSyncListener.ts
index 627ceee230..b35a472844 100644
--- a/apps/ade-cli/src/services/sync/sharedSyncListener.ts
+++ b/apps/ade-cli/src/services/sync/sharedSyncListener.ts
@@ -29,6 +29,10 @@ import {
   inspectSyncListenerPort,
   type SyncListenerPortDiagnosis,
 } from "./syncListenerPortInspect";
+import {
+  createAttachmentUploadRegistry,
+  type AttachmentUploadRegistry,
+} from "./attachmentUploadService";
 
 // Re-exported so existing importers (and `ade doctor`) keep their entry point.
 export {
@@ -187,6 +191,13 @@ export type SharedSyncListener = {
   getExpectedLoopbackNonce(): string;
   /** Private in-process credential attached only by the trusted relay tunnel client. */
   getRelayBridgeProof(): string;
+  /**
+   * Ticket registry backing the streamed attachment-upload route mounted on
+   * this listener's http server. The sync host mints tickets against this exact
+   * instance, so the WS session that authorized an upload and the HTTP request
+   * that performs it share one registry.
+   */
+  getAttachmentUploadRegistry(): AttachmentUploadRegistry;
   getLoopbackValidationStatus(): SyncLoopbackValidationStatus;
   /** Force-check that loopback still reaches this exact listener instance. */
   revalidateLoopback(): Promise<void>;
@@ -334,6 +345,9 @@ export function createSharedSyncListener(options: {
   // only to the in-process tunnel client and rotates with the listener process.
   const relayBridgeProofBytes = randomBytes(32);
   const relayBridgeProof = relayBridgeProofBytes.toString("base64url");
+  // One registry per listener instance, shared by every candidate bind: a
+  // ticket minted before a port migration is still honoured after it.
+  const attachmentUploads = createAttachmentUploadRegistry({ logger });
 
   let server: WebSocketServer | null = null;
   // The http.Server fronting `server`. `ws` does not own/close an
@@ -549,6 +563,9 @@ export function createSharedSyncListener(options: {
       }
       previousAttemptedPort = attemptedPort;
       const candidateHttpServer = http.createServer((request, response) => {
+        // WS upgrades never reach here (they are handled on `upgrade`), so the
+        // only non-upload request shape left is the loopback 426 probe.
+        if (attachmentUploads.handleRequest(request, response)) return;
         writeAdeLoopbackUpgradeResponse(request, response, expectedLoopbackNonce);
       });
       const candidateServer = new WebSocketServer({
@@ -795,6 +812,10 @@ export function createSharedSyncListener(options: {
       return relayBridgeProof;
     },
 
+    getAttachmentUploadRegistry(): AttachmentUploadRegistry {
+      return attachmentUploads;
+    },
+
     getLoopbackValidationStatus(): SyncLoopbackValidationStatus {
       return { ...loopbackValidationStatus };
     },
@@ -865,6 +886,7 @@ export function createSharedSyncListener(options: {
       closed = true;
       handler = null;
       fallbackHandler = null;
+      attachmentUploads.dispose();
       loopbackValidatedHandlers.clear();
       if (listeningPromise) {
         await listeningPromise.catch(() => {});
diff --git a/apps/ade-cli/src/services/sync/syncHostService.ts b/apps/ade-cli/src/services/sync/syncHostService.ts
index 4230d5937b..1ee4a08c6c 100644
--- a/apps/ade-cli/src/services/sync/syncHostService.ts
+++ b/apps/ade-cli/src/services/sync/syncHostService.ts
@@ -268,6 +268,13 @@ import {
   type SyncLoopbackProbeResult,
   type SyncLoopbackValidationStatus,
 } from "./syncLoopbackProbe";
+import {
+  ATTACHMENT_UPLOAD_PATH,
+  createAttachmentUploadRegistry,
+  type AttachmentUploadRegistry,
+  type AttachmentUploadTicket,
+} from "./attachmentUploadService";
+import { MAX_CHAT_ATTACHMENT_BYTES } from "../../../../desktop/src/shared/chatAttachmentLimits";
 export { selectChangesetBatchChunk } from "./changesetPump";
 export { SYNC_HOST_MOBILE_REPLICA_RESEED_GAP } from "./mobileReplicaReseed";
 const execFileAsync = promisify(execFile);
@@ -1496,6 +1503,11 @@ export function buildSyncHostHelloOkPayload(args: {
   connectionTransport?: "direct" | "relay";
   /** Advertise only when this concrete handler accepts terminal_input. */
   terminalInputAckEnabled?: boolean;
+  /**
+   * Advertise the streamed HTTP attachment-upload route. Purely additive:
+   * older clients and iOS ignore it and stay on `chat.saveTempAttachment`.
+   */
+  attachmentUploadEnabled?: boolean;
   /**
    * Whether this peer is authorized to use the paired runtime RPC channel and
    * loopback port-forwarding (paired AND a desktop runtime-host). Defaults to
@@ -1550,6 +1562,15 @@ export function buildSyncHostHelloOkPayload(args: {
       chatHistoryPaging: {
         enabled: true,
       },
+      ...(args.attachmentUploadEnabled
+        ? {
+            attachmentUploadV1: {
+              enabled: true as const,
+              path: ATTACHMENT_UPLOAD_PATH,
+              maxBytes: MAX_CHAT_ATTACHMENT_BYTES,
+            },
+          }
+        : {}),
       ...(isInvalidationOnlyBrowserPeer(args.peer)
         ? {
             invalidationOnlyV1: {
@@ -2070,7 +2091,17 @@ export function createSyncHostService(args: SyncHostServiceArgs) {
     ?? createMachineIdentitySigningStore({ logger: args.logger });
   const adoptNow = args.adoptNow ?? Date.now;
   const dpopNonceCache = createSyncDpopNonceCache();
+  // The upload route is served by whichever http server this host is behind.
+  // With a shared listener that server outlives project switches, so the
+  // registry must be the listener's own — a host-local one would mint tickets
+  // no request handler knows about. Only the self-owned-listener path creates
+  // (and therefore disposes) its own.
+  const ownsAttachmentUploadRegistry = !args.sharedListener;
+  const attachmentUploads: AttachmentUploadRegistry =
+    args.sharedListener?.getAttachmentUploadRegistry()
+    ?? createAttachmentUploadRegistry({ logger: args.logger });
   const remoteCommandService = args.remoteCommandService ?? createSyncRemoteCommandService({
+    attachmentUploads,
     db: args.db,
     productAnalyticsService: args.productAnalyticsService,
     projectRoot: args.projectRoot,
@@ -2130,6 +2161,12 @@ export function createSyncHostService(args: SyncHostServiceArgs) {
     isCloudRelayEnabled: () => Boolean(args.getCloudRelayWssUrl?.()),
     logger: args.logger,
   });
+  // Advertise the upload route only when a client can actually mint a ticket
+  // for it. An injected `remoteCommandService` (tests, custom embeddings) may
+  // not register the command, and the route is useless without it.
+  const attachmentUploadEnabled = remoteCommandService
+    .getSupportedActions()
+    .includes("chat.createAttachmentUpload");
   const heartbeatIntervalMs = Math.max(5_000, Math.floor(args.heartbeatIntervalMs ?? DEFAULT_SYNC_HEARTBEAT_INTERVAL_MS));
   const backpressureTimeoutMs = Math.max(heartbeatIntervalMs * 3, 10_000);
   const pollIntervalMs = Math.max(100, Math.floor(args.pollIntervalMs ?? DEFAULT_SYNC_POLL_INTERVAL_MS));
@@ -2782,6 +2819,7 @@ export function createSyncHostService(args: SyncHostServiceArgs) {
   const httpServer = sharedListener
     ? null
     : http.createServer((request, response) => {
+        if (attachmentUploads.handleRequest(request, response)) return;
         writeAdeLoopbackUpgradeResponse(request, response, expectedLoopbackNonce);
       });
   const server = sharedListener
@@ -7469,6 +7507,7 @@ export function createSyncHostService(args: SyncHostServiceArgs) {
         relayAuthorization: peer.relayAuthorization?.metadata() ?? null,
         connectionTransport: syncConnectionTransportForOrigin(peer.transportOrigin),
         terminalInputAckEnabled: true,
+        attachmentUploadEnabled,
         // Runtime RPC channel + port-forward are desktop-runtime-host only,
         // even after successful pairing (phones/browsers stay on the mobile
         // command allowlist).
@@ -8474,6 +8513,28 @@ export function createSyncHostService(args: SyncHostServiceArgs) {
       return bootstrapToken;
     },
 
+    /**
+     * Mint an upload ticket for a caller that reached this host over the
+     * runtime RPC channel rather than the sync command channel — a paired
+     * desktop going through `chat.createAttachmentUpload` on the ADE action
+     * registry. Same registry instance either way, because only the request
+     * handler holding that map can redeem what it issues.
+     *
+     * Deliberately NOT gated on `attachmentUploadEnabled`. That flag answers a
+     * narrower question — whether this host's `remoteCommandService` registered
+     * the sync COMMAND, which an injected or embedded service may not — while
+     * the HTTP route itself is served unconditionally by whichever listener
+     * this host is behind. Gating here would refuse tickets the route would
+     * happily redeem, with a reason that is not the real one.
+     */
+    issueAttachmentUploadTicket(args: {
+      projectRoot: string;
+      filename: string;
+      deviceId?: string | null;
+    }): AttachmentUploadTicket {
+      return attachmentUploads.issue(args);
+    },
+
     setLocalActiveLanePresence(laneIds: string[]): void {
       setLocalActiveLanePresence(laneIds);
     },
@@ -8685,6 +8746,9 @@ export function createSyncHostService(args: SyncHostServiceArgs) {
     async dispose(): Promise<void> {
       if (disposed) return;
       disposed = true;
+      // Never dispose a shared listener's registry: it outlives this host and
+      // still serves the next project's uploads.
+      if (ownsAttachmentUploadRegistry) attachmentUploads.dispose();
       localActiveLaneIds = new Set<string>();
       lanePresenceByLaneId.clear();
       dropInFlightCommandRecordsForProject();
diff --git a/apps/ade-cli/src/services/sync/syncRemoteCommandService.test.ts b/apps/ade-cli/src/services/sync/syncRemoteCommandService.test.ts
index 149798b7d9..ffc9f389dc 100644
--- a/apps/ade-cli/src/services/sync/syncRemoteCommandService.test.ts
+++ b/apps/ade-cli/src/services/sync/syncRemoteCommandService.test.ts
@@ -6,7 +6,16 @@ import type { SyncCommandPayload, SyncPairingConnectInfo, SyncWebPairingInfo } f
 import { parsePairingQrText } from "../../../../desktop/src/shared/pairingQr";
 import { deriveDeterministicLaneNameFromPrompt } from "../../../../desktop/src/shared/laneNameFallback";
 import { MOBILE_SYNC_OPTIONAL_REMOTE_COMMAND_ACTIONS } from "../../../../desktop/src/shared/syncMobileCompatibility";
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  legacyAttachmentCapMessage,
+} from "../../../../desktop/src/shared/chatAttachmentLimits";
 import { createSyncRemoteCommandService } from "./syncRemoteCommandService";
+import {
+  ATTACHMENT_UPLOAD_PATH,
+  createAttachmentUploadRegistry,
+  type AttachmentUploadRegistry,
+} from "./attachmentUploadService";
 
 function makePayload(
   action: string,
@@ -46,6 +55,7 @@ function createService(options?: {
   usageTrackingService?: Record<string, unknown>;
   productAnalyticsService?: Record<string, unknown>;
   pushPublisherService?: Record<string, unknown>;
+  attachmentUploads?: AttachmentUploadRegistry | null;
   personalChatScope?: {
     call: ReturnType<typeof vi.fn>;
     streamEvents?: ReturnType<typeof vi.fn>;
@@ -107,6 +117,7 @@ function createService(options?: {
     ...(options?.productAnalyticsService ? { productAnalyticsService: options.productAnalyticsService } : {}),
     ...(options?.pushPublisherService ? { pushPublisherService: options.pushPublisherService } : {}),
     ...(options?.personalChatScope ? { personalChatScope: options.personalChatScope } : {}),
+    ...(options?.attachmentUploads ? { attachmentUploads: options.attachmentUploads } : {}),
     logger,
   } as any);
   return { service, ptyService, sessionService, externalSessionsService: options?.externalSessionsService, logger };
@@ -2015,10 +2026,51 @@ describe("createSyncRemoteCommandService", () => {
     }
   });
 
+  it("never lets a remote display name choose the staged temp attachment's extension", async () => {
+    // `filename` is fully remote-controlled on this route. The bytes are a real
+    // PNG (the MIME sniff is what gates the write), but the name claims `.cmd`
+    // — and before this went through the shared staging helpers, `path.extname`
+    // put that straight into the on-disk name.
+    const projectRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-sync-remote-"));
+    const png = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+    const { service } = createService({ projectRoot });
+
+    try {
+      const executable = await service.execute(makePayload("chat.saveTempAttachment", {
+        base64: png.toString("base64"),
+        mime: "image/png",
+        filename: "run.cmd",
+      })) as { path: string };
+      // `.cmd` is a syntactically valid extension, so the guard that matters is
+      // the MIME table: the sniffed type owns the name, not the caller's.
+      expect(path.extname(executable.path)).toBe(".png");
+
+      // A traversal-shaped name cannot escape the attachments directory or
+      // smuggle a separator into the basename either.
+      const traversal = await service.execute(makePayload("chat.saveTempAttachment", {
+        base64: png.toString("base64"),
+        mime: "image/png",
+        filename: "../../escape.png",
+      })) as { path: string };
+      expect(path.dirname(traversal.path)).toBe(path.join(projectRoot, ".ade", "attachments"));
+
+      // An extension the validator rejects outright falls back to the sniffed
+      // MIME rather than reaching the destination raw.
+      const overlong = await service.execute(makePayload("chat.saveTempAttachment", {
+        base64: png.toString("base64"),
+        mime: "image/png",
+        filename: `weird.${"a".repeat(40)}`,
+      })) as { path: string };
+      expect(path.extname(overlong.path)).toBe(".png");
+    } finally {
+      await fs.promises.rm(projectRoot, { recursive: true, force: true });
+    }
+  });
+
   it("rejects temporary attachments with mismatched MIME or oversized payloads", async () => {
     const projectRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-sync-remote-"));
     const png = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
-    const maxEncodedLength = Math.ceil((10 * 1024 * 1024) / 3) * 4;
+    const maxEncodedLength = Math.ceil(LEGACY_MAX_CHAT_ATTACHMENT_BYTES / 3) * 4;
     const { service } = createService({ projectRoot });
 
     try {
@@ -2030,13 +2082,61 @@ describe("createSyncRemoteCommandService", () => {
         base64: "A".repeat(maxEncodedLength + 4),
         mime: "image/png",
         filename: "too-large.png",
-      }))).rejects.toThrow("10 MB or smaller");
+      }))).rejects.toThrow(legacyAttachmentCapMessage("Temporary attachments"));
       await expect(fs.promises.readdir(path.join(projectRoot, ".ade", "attachments"))).rejects.toThrow();
     } finally {
       await fs.promises.rm(projectRoot, { recursive: true, force: true });
     }
   });
 
+  it("mints a single-use upload ticket for the streamed attachment route", async () => {
+    const projectRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-sync-remote-"));
+    const attachmentUploads = createAttachmentUploadRegistry();
+    const { service } = createService({ projectRoot, attachmentUploads });
+
+    try {
+      const ticket = await service.execute(makePayload("chat.createAttachmentUpload", {
+        filename: "recording.mov",
+      })) as { ticket: string; path: string; maxBytes: number; expiresAtMs: number };
+
+      expect(ticket.path).toBe(ATTACHMENT_UPLOAD_PATH);
+      expect(ticket.ticket).toMatch(/^[A-Za-z0-9_-]{43}$/);
+      expect(ticket.maxBytes).toBe(50 * 1024 * 1024);
+      expect(ticket.expiresAtMs).toBeGreaterThan(Date.now());
+      expect(attachmentUploads.pendingCount()).toBe(1);
+    } finally {
+      attachmentUploads.dispose();
+      await fs.promises.rm(projectRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("fails the upload-ticket command clearly when the host has no upload route", async () => {
+    const projectRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-sync-remote-"));
+    const { service } = createService({ projectRoot });
+
+    try {
+      await expect(service.execute(makePayload("chat.createAttachmentUpload", {
+        filename: "a.png",
+      }))).rejects.toThrow("Attachment upload is not available on this host.");
+    } finally {
+      await fs.promises.rm(projectRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("does not expose the same-machine attachment copy as a remote command", async () => {
+    // `chat.copyTempAttachment` takes an UNCONSTRAINED absolute source path and
+    // copies it into `.ade/attachments`, which `chat.getImageDataUrl` will then
+    // read back. Reachable over sync that is an arbitrary-file-read primitive
+    // for any paired peer, so it lives only on the local ADE action registry.
+    // Remote peers stage files via `chat.createAttachmentUpload` or base64.
+    const { service } = createService();
+
+    expect(service.getSupportedActions()).not.toContain("chat.copyTempAttachment");
+    await expect(
+      service.execute(makePayload("chat.copyTempAttachment" as never, { sourcePath: "/etc/passwd" })),
+    ).rejects.toThrow(/Unsupported remote command/);
+  });
+
   it("advertises the requested web-parity remote actions", () => {
     const { service } = createService();
 
diff --git a/apps/ade-cli/src/services/sync/syncRemoteCommandService.ts b/apps/ade-cli/src/services/sync/syncRemoteCommandService.ts
index 1021f540a0..20b3b1cab3 100644
--- a/apps/ade-cli/src/services/sync/syncRemoteCommandService.ts
+++ b/apps/ade-cli/src/services/sync/syncRemoteCommandService.ts
@@ -7,6 +7,8 @@ import {
   normalizeAgentChatSessionMetadataFields,
 } from "../../../../desktop/src/shared/types/chat";
 import { runWithAbortSignal } from "./abortSignal";
+import { projectAttachmentsDir } from "../../../../desktop/src/shared/chatAttachmentStagingFs";
+import type { AttachmentUploadRegistry, AttachmentUploadTicket } from "./attachmentUploadService";
 import type {
   AgentChatCreateArgs,
   AgentChatCreateScheduledWorkArgs,
@@ -417,6 +419,13 @@ type SyncRemoteCommandServiceArgs = {
   issueRuntimeHostPairingGrant?: () => string;
   /** Whether the account-gated machine relay is currently available. */
   isCloudRelayEnabled?: () => boolean;
+  /**
+   * Ticket registry for the streamed HTTP attachment-upload route on this
+   * host's sync listener. Absent when the host fronts no http server, in which
+   * case `chat.createAttachmentUpload` fails with a clear message and the
+   * client falls back to base64 `chat.saveTempAttachment`.
+   */
+  attachmentUploads?: AttachmentUploadRegistry | null;
   logger: Logger;
 };
 
@@ -1914,9 +1923,44 @@ async function saveAgentChatTempAttachment(
   payload: Record<string, unknown>,
 ): Promise<{ path: string; mimeType: string; previewDataUrl: string | null }> {
   const projectRoot = requireProjectRoot(args, "chat.saveTempAttachment");
-  return await saveImageTempAttachment(path.join(projectRoot, ".ade", "attachments"), payload);
+  return await saveImageTempAttachment(projectAttachmentsDir(projectRoot), payload);
+}
+
+/**
+ * Mint a single-use ticket for the streamed HTTP upload route. The WS session
+ * this command arrives on is already authenticated, so the ticket is the only
+ * authority the (unauthenticated) HTTP leg ever gets.
+ *
+ * This is how a mobile or browser sync client stages a file-shaped attachment;
+ * a paired DESKTOP arrives instead through the runtime RPC channel, on the ADE
+ * action registry's `chat.createAttachmentUpload`. Both mint from the host's
+ * one `AttachmentUploadRegistry` — the registry half reaches it through
+ * `syncHostService.issueAttachmentUploadTicket`, which is this same
+ * `args.attachmentUploads` instance — because only the HTTP request handler
+ * holding that map can redeem what it issues.
+ *
+ * There is deliberately no remote "copy this path" command on THIS channel:
+ * `chat.copyTempAttachment` takes an unconstrained absolute source path, and
+ * the mobile command allowlist is the one place ADE draws that line. The action
+ * registry does not draw it (see the note on `copyTempAttachment` there), so
+ * this exclusion narrows what a phone can do, not what a paired desktop can.
+ */
+function createAgentChatAttachmentUpload(
+  args: SyncRemoteCommandServiceArgs,
+  payload: Record<string, unknown>,
+): AttachmentUploadTicket {
+  const projectRoot = requireProjectRoot(args, "chat.createAttachmentUpload");
+  const registry = args.attachmentUploads;
+  if (!registry) throw new Error("Attachment upload is not available on this host.");
+  const rawFilename = typeof payload.filename === "string" ? payload.filename.trim() : "";
+  return registry.issue({
+    projectRoot,
+    filename: rawFilename || "attachment",
+    deviceId: typeof payload.deviceId === "string" ? payload.deviceId : null,
+  });
 }
 
+
 function inferPrAiProvider(modelId: string): "codex" | "claude" {
   const descriptor = getModelById(modelId);
   return descriptor?.family === "anthropic" ? "claude" : "codex";
@@ -4440,6 +4484,8 @@ function registerChatRemoteCommands({ args, register }: RemoteCommandRegistratio
   register("chat.getTurnFileDiff", { viewerAllowed: true }, async (payload) => getRemoteTurnFileDiff(args, payload));
   register("chat.saveTempAttachment", { viewerAllowed: true }, async (payload) =>
     saveAgentChatTempAttachment(args, payload));
+  register("chat.createAttachmentUpload", { viewerAllowed: true }, async (payload) =>
+    createAgentChatAttachmentUpload(args, payload));
   register("chat.listPromptStashes", { viewerAllowed: true }, async () =>
     listPromptStashes(requireService(args.db, "Database not available.")));
   register("chat.createPromptStash", { viewerAllowed: true }, async (payload) =>
diff --git a/apps/ade-cli/src/tuiClient/__tests__/adeApi.test.ts b/apps/ade-cli/src/tuiClient/__tests__/adeApi.test.ts
index c4b47be180..11fb3e1d10 100644
--- a/apps/ade-cli/src/tuiClient/__tests__/adeApi.test.ts
+++ b/apps/ade-cli/src/tuiClient/__tests__/adeApi.test.ts
@@ -482,6 +482,35 @@ describe("latestTokenStats", () => {
     });
   });
 
+  it("keeps the parsed rate-limit window when a prose rate_limit notice follows it", () => {
+    // The plan-usage warning is emitted at most once per session, and the
+    // auto-resume lines reuse `noticeKind: "rate_limit"` with prose detail.
+    // If those overwrote the snapshot, the statusline's rate-limit window
+    // would blank out exactly when a limit trips and never come back.
+    const events = [
+      envelope(1, {
+        type: "system_notice",
+        noticeKind: "rate_limit",
+        severity: "info",
+        message: "Approaching Claude plan limit",
+        detail: "87% utilized | resets 2026-08-29T18:00:00.000Z",
+      } as AgentChatEventEnvelope["event"]),
+      envelope(2, {
+        type: "system_notice",
+        noticeKind: "rate_limit",
+        severity: "info",
+        message: "Auto-resume scheduled for Aug 29, 7:31 PM",
+        detail:
+          "ADE will ask this chat to continue the interrupted task once the usage limit resets. Sending a message or retrying the turn cancels it.",
+      } as AgentChatEventEnvelope["event"]),
+    ];
+
+    expect(latestTokenStats(events).rateLimit).toEqual({
+      usedPercentage: 87,
+      resetsAt: Math.round(Date.parse("2026-08-29T18:00:00.000Z") / 1000),
+    });
+  });
+
   it("falls back to the active model contextWindow when the event omits one", () => {
     const events = [
       envelope(1, { type: "status", turnStatus: "started" }),
diff --git a/apps/ade-cli/src/tuiClient/adeApi.ts b/apps/ade-cli/src/tuiClient/adeApi.ts
index 7237023668..fc2d09f804 100644
--- a/apps/ade-cli/src/tuiClient/adeApi.ts
+++ b/apps/ade-cli/src/tuiClient/adeApi.ts
@@ -1344,14 +1344,24 @@ export function latestTokenStats(
       cacheCreationTokens = null;
     }
     if (event.type === "system_notice" && event.noticeKind === "rate_limit") {
+      // `rate_limit` is a shared noticeKind, not a dedicated usage-snapshot
+      // event: the plan-usage warning carries "<n>% utilized | resets <iso>",
+      // but the auto-resume lines ("Auto-resume scheduled for …", "Auto-resume
+      // paused after two attempts") wear the same kind with prose detail.
+      // Overwriting unconditionally therefore wiped the statusline's rate-limit
+      // window the moment a limit actually tripped — the warning is emitted at
+      // most once per session (`claudeRateLimitWarningEmitted`), so nothing ever
+      // put the numbers back. Only a notice that actually parses replaces the
+      // snapshot; the rest leave the last known window standing.
       const detail = typeof event.detail === "string" ? event.detail : "";
       const pct = detail.match(/(\d+(?:\.\d+)?)%\s+utilized/i);
       const reset = detail.match(/resets\s+([0-9TZ:.-]+)/i);
       const resetMs = reset?.[1] ? Date.parse(reset[1]) : Number.NaN;
-      rateLimit = {
-        usedPercentage: pct?.[1] ? Number(pct[1]) : null,
-        resetsAt: Number.isFinite(resetMs) ? Math.round(resetMs / 1000) : null,
-      };
+      const usedPercentage = pct?.[1] ? Number(pct[1]) : null;
+      const resetsAt = Number.isFinite(resetMs) ? Math.round(resetMs / 1000) : null;
+      if (usedPercentage != null || resetsAt != null) {
+        rateLimit = { usedPercentage, resetsAt };
+      }
     }
   }
   if (contextState !== "measured") {
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 221420b77a..03643daab8 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -309,6 +309,10 @@
           "!ggml-base.en.bin"
         ]
       },
+      {
+        "from": "../../docs/triage",
+        "to": "docs/triage"
+      },
       {
         "from": "../../NOTICE",
         "to": "NOTICE"
diff --git a/apps/desktop/resources/ade-cli-help.txt b/apps/desktop/resources/ade-cli-help.txt
index ec9a343039..7320564de3 100644
--- a/apps/desktop/resources/ade-cli-help.txt
+++ b/apps/desktop/resources/ade-cli-help.txt
@@ -40,6 +40,7 @@ _    ____  _____
     $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor [--online]                         Inspect installed app and machine-brain health
     $ ade report-issue [--open] [--send]            Print a redacted diagnostic report; --send hands it to ADE
+    $ ade triage [--agent] [--provider <name>]      Build a triage context + playbook and hand the repair to your coding agent
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
     $ ade operations status | wait                  Poll operation/test/chat/run status
@@ -181,6 +182,7 @@ _    ____  _____
     $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor [--online]                         Inspect installed app and machine-brain health
     $ ade report-issue [--open] [--send]            Print a redacted diagnostic report; --send hands it to ADE
+    $ ade triage [--agent] [--provider <name>]      Build a triage context + playbook and hand the repair to your coding agent
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
     $ ade operations status | wait                  Poll operation/test/chat/run status
@@ -260,6 +262,48 @@ _    ____  _____
 
   Start with: ade doctor --text
 
+## ade triage --help
+_    ____  _____
+    / \  |  _ \| ____|
+   / _ \ | | | |  _|
+  / ___ \| |_| | |___
+ /_/   \_\____/|_____|
+
+  ADE Triage
+
+  Hand a broken ADE install to your own coding agent. Runs the same checks as
+  "ade doctor" and collects the same redacted diagnostics as "ade report-issue",
+  writes them plus a maintained repair playbook into a fresh temp directory, and
+  then starts whichever agent CLI is installed so you can work the fix with it.
+
+  The playbook is fetched from GitHub when the network allows (3s timeout) and
+  falls back to the copy shipped with this build; the output says which won.
+
+    $ ade triage                          Launch the first installed agent CLI
+    $ ade triage --provider codex         Launch a specific one
+    $ ade triage --agent --json           Print the handoff for an agent already running
+    $ ade triage --agent --text           The same, human-readable
+
+  Flags:
+    --agent                Launch nothing; print contextPath, playbookPath,
+                           playbookSource, suggestedPrompt and the detected
+                           agent CLIs. Use this from inside an agent session.
+    --provider <name>      claude | codex | cursor-agent | opencode | droid.
+    --text                 Human-readable output.
+    --json                 Structured JSON output (default).
+
+  Notes:
+    Detection order is claude, codex, cursor-agent, opencode, droid. With no
+    agent CLI installed, triage prints the --agent output and exits 0 — the
+    files are the deliverable, the launch is a convenience.
+    When an agent is launched the terminal belongs to it: the file paths are
+    printed on stderr before it starts, stdout stays empty, and triage exits
+    with the agent's own exit code.
+    The context file is redacted with the same rules as "ade report-issue"; it
+    never contains credentials, and it is written to a temp directory, not into
+    your project.
+    Set ADE_TRIAGE_NO_FETCH=1 to skip the playbook fetch entirely.
+
 ## ade code --help
 _    ____  _____
     / \  |  _ \| ____|
@@ -368,11 +412,16 @@ _    ____  _____
     $ ade lanes import --branch <branch>            Create a lane for an existing branch, checked out in a new managed
                                                     worktree (fails if the branch is already checked out somewhere —
                                                     that worktree is already a lane)
-    $ ade lanes archive <lane>                      Archive a lane in ADE
+    $ ade lanes archive <lane>                      Archive a lane in ADE; also brings down the Docker services
+                                                    its env init started (best-effort — a failed teardown still archives)
     $ ade lanes reclaim-preview <lane>              Show reclaimable space and safety warnings
     $ ade lanes archive-and-reclaim <lane> --confirm RECLAIM
                                                     Archive the lane, then remove its ADE-managed local files
-    $ ade lanes unarchive <lane>                    Restore an archived lane and recreate its worktree if needed
+    $ ade lanes unarchive <lane>                    Restore an archived lane and recreate its worktree if needed.
+                                                    Docker comes back up too: a recreated worktree re-runs the whole
+                                                    env init before returning, a plain unarchive returns immediately
+                                                    and restarts Docker in the background (watch lane env init events).
+                                                    Run "ade lanes action initEnv --arg laneId=<lane>" for the full sequence
     $ ade lanes delete <lane> --force               Delete a lane and clean up its worktree
     $ ade lanes reparent <lane> --parent <parent>   Move lane onto a new parent (runs git rebase)
     $ ade lanes reparent <lane> --parent <parent> --stack-base-branch <branch>
@@ -524,6 +573,10 @@ _    ____  _____
     $ ade prs link --lane <lane> --url <pr-url>     Map an existing GitHub PR to a lane
     $ ade prs checks <pr> --text                    Show the CI rollup + per-check rows ("not run" = nothing verified the commit)
     $ ade prs comments <pr> --text                  Show unresolved review work
+    $ ade prs comment-edit <pr> --comment <id> --body "..."
+                                                    Edit an issue or review comment
+    $ ade prs comment-react <pr> --comment <id> --content +1
+                                                    React to a PR comment (GraphQL node id or REST database id)
     $ ade prs github-snapshot --include-external-closed --history-page-limit 4
                                                     Include bounded closed PR history in the GitHub snapshot
     $ ade prs github-snapshot --include-state-counts --no-revalidate
@@ -630,6 +683,13 @@ _    ____  _____
     $ ade chat message <session> --kind auto --text "status"
                                                     Deliver via auto | queue | wake | interrupt-replace
     $ ade chat steer <session> --text "context"     Steer/queue context into an active turn
+    $ ade chat steer <session> --text "context" --dispatch interrupt
+                                                    Deliver into the running turn: inline | interrupt.
+                                                    Omit --dispatch to stage for the next turn.
+                                                    Claude takes inline and interrupt; Cursor takes
+                                                    interrupt (cancel + resend on the same thread).
+                                                    Other providers reject the flag outright and nothing
+                                                    is sent; omit --dispatch to stage the message.
     $ ade chat wait <session> --for idle --timeout-ms 600000
                                                     Wait for idle, active, awaiting-input, or terminal
     $ ade chat recover <session> --turn <turn-id> --action nudge
@@ -715,8 +775,9 @@ _    ____  _____
     fork stays on the source provider and in the source lane; brief summarizes
     the chat, can switch provider, and accepts --target-lane.
     Claude, Codex, OpenCode, and Droid fork through the provider's own fork.
-    Cursor has no fork surface, so ADE forks it by seeding a fresh Cursor agent
-    with this conversation's context instead of copying a provider thread.
+    Cursor has no fork surface, so ADE forks it by replaying this conversation
+    into a fresh Cursor agent instead of copying a provider thread; the oldest
+    turns drop if the transcript exceeds the target model's context window.
 
   Personal chats attach to the machine-owned ADE brain and never register a
   project. They work with a desktopless brain and through the same
@@ -794,6 +855,7 @@ _    ____  _____
     $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor [--online]                         Inspect installed app and machine-brain health
     $ ade report-issue [--open] [--send]            Print a redacted diagnostic report; --send hands it to ADE
+    $ ade triage [--agent] [--provider <name>]      Build a triage context + playbook and hand the repair to your coding agent
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
     $ ade operations status | wait                  Poll operation/test/chat/run status
@@ -998,6 +1060,7 @@ _    ____  _____
     $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor [--online]                         Inspect installed app and machine-brain health
     $ ade report-issue [--open] [--send]            Print a redacted diagnostic report; --send hands it to ADE
+    $ ade triage [--agent] [--provider <name>]      Build a triage context + playbook and hand the repair to your coding agent
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
     $ ade operations status | wait                  Poll operation/test/chat/run status
@@ -1432,6 +1495,7 @@ _    ____  _____
     $ ade sync status | pin generate                Manage machine sync and phone pairing
     $ ade doctor [--online]                         Inspect installed app and machine-brain health
     $ ade report-issue [--open] [--send]            Print a redacted diagnostic report; --send hands it to ADE
+    $ ade triage [--agent] [--provider <name>]      Build a triage context + playbook and hand the repair to your coding agent
     $ ade lanes list | show | create | child        Work with lanes and lane stacks
     $ ade git status | commit | push | stash        Run ADE-aware git operations
     $ ade operations status | wait                  Poll operation/test/chat/run status
diff --git a/apps/desktop/scripts/regen-ade-cli-help.cjs b/apps/desktop/scripts/regen-ade-cli-help.cjs
index 3e58bb0535..074e112d27 100644
--- a/apps/desktop/scripts/regen-ade-cli-help.cjs
+++ b/apps/desktop/scripts/regen-ade-cli-help.cjs
@@ -8,6 +8,7 @@ const { spawnSync } = require("child_process");
 const SUBCOMMANDS = [
   "auth",
   "doctor",
+  "triage",
   "code",
   "skill",
   "lanes",
diff --git a/apps/desktop/scripts/validate-mac-artifacts.mjs b/apps/desktop/scripts/validate-mac-artifacts.mjs
index 8c0e9dc3f2..f27088e450 100644
--- a/apps/desktop/scripts/validate-mac-artifacts.mjs
+++ b/apps/desktop/scripts/validate-mac-artifacts.mjs
@@ -438,6 +438,11 @@ async function validatePackagedRuntime(appPath, description, expectedArch, optio
   const adeCliBinPath = path.join(resourcesPath, "ade-cli", "bin", "ade");
   const adeCliInstallerPath = path.join(resourcesPath, "ade-cli", "install-path.sh");
   const bundledAgentSkillsRoot = path.join(resourcesPath, "agent-skills");
+  // `ade triage` hands this file to a coding agent as its instructions, and
+  // electron-builder only warns when an extraResources source goes missing, so
+  // a dropped entry would ship silently and degrade triage to its built-in
+  // minimum on every installed machine.
+  const triagePlaybookPath = path.join(resourcesPath, "docs", "triage", "PLAYBOOK.md");
   const nodeModulesPath = path.join(unpackedPath, "node_modules");
   const nodePtyModulePath = path.join(nodeModulesPath, "node-pty");
   const smokeScriptPath = path.join(unpackedPath, "dist", "main", "packagedRuntimeSmoke.cjs");
@@ -451,6 +456,7 @@ async function validatePackagedRuntime(appPath, description, expectedArch, optio
     await assertPathExists(path.join(resourcesPath, "ade-cli", relativePath), label);
   }
   await assertBundledAgentSkills(bundledAgentSkillsRoot);
+  await assertPathExists(triagePlaybookPath, "packaged ade triage playbook");
   await assertExecutable(adeCliBinPath, "bundled ADE CLI wrapper");
   await assertExecutable(adeCliInstallerPath, "bundled ADE CLI PATH installer");
   await assertPathExists(nodePtyModulePath, "unpacked node-pty module");
diff --git a/apps/desktop/scripts/validate-win-artifacts.mjs b/apps/desktop/scripts/validate-win-artifacts.mjs
index b3df38e2fb..62e316be96 100644
--- a/apps/desktop/scripts/validate-win-artifacts.mjs
+++ b/apps/desktop/scripts/validate-win-artifacts.mjs
@@ -604,6 +604,11 @@ async function validatePackagedRuntime(appDir) {
   const uninstallCleanupPath = path.join(resourcesPath, "ade-cli", "windows-uninstall-cleanup.ps1");
   const adeCliTuiPath = path.join(resourcesPath, "ade-cli", "tuiClient", "cli.mjs");
   const bundledAgentSkillsRoot = path.join(resourcesPath, "agent-skills");
+  // `ade triage` hands this file to a coding agent as its instructions, and
+  // electron-builder only warns when an extraResources source goes missing, so
+  // a dropped entry would ship silently and degrade triage to its built-in
+  // minimum on every installed machine.
+  const triagePlaybookPath = path.join(resourcesPath, "docs", "triage", "PLAYBOOK.md");
   const nodeModulesPath = path.join(unpackedPath, "node_modules");
   const nodePtyModulePath = path.join(nodeModulesPath, "node-pty");
   const smokeScriptPath = path.join(unpackedPath, "dist", "main", "packagedRuntimeSmoke.cjs");
@@ -622,6 +627,7 @@ async function validatePackagedRuntime(appDir) {
     );
   }
   await assertBundledAgentSkills(bundledAgentSkillsRoot);
+  await assertPathExists(triagePlaybookPath, "packaged ade triage playbook");
   await assertPathExists(nodePtyModulePath, "unpacked node-pty module");
   await assertPathExists(smokeScriptPath, "unpacked packaged runtime smoke script");
   await assertPathExists(crsqliteDllPath, "unpacked Windows cr-sqlite extension");
diff --git a/apps/desktop/src/main/main.ts b/apps/desktop/src/main/main.ts
index 8531f75fb0..a02d351aa8 100644
--- a/apps/desktop/src/main/main.ts
+++ b/apps/desktop/src/main/main.ts
@@ -77,6 +77,7 @@ import {
 import { detectInstallSource } from "./services/analytics/installSource";
 import {
   captureAgentTurnSettledAnalytics,
+  captureChatAutoResumeAnalytics,
   captureChatMentionsExpandedAnalytics,
   captureSessionMetadataRegeneratedAnalytics,
 } from "./services/analytics/agentTurnProductAnalytics";
@@ -3883,6 +3884,10 @@ app.whenReady().then(async () => {
         projectId,
         event,
       }),
+      onAutoResumeOutcome: (properties) => captureChatAutoResumeAnalytics({
+        analytics: productAnalyticsService,
+        properties,
+      }),
       onSessionEnded: onTrackedSessionEnded,
       getDirtyFileTextForPath: async (absPath: string) => {
         const trimmed = absPath.trim();
diff --git a/apps/desktop/src/main/services/adeActions/registry.test.ts b/apps/desktop/src/main/services/adeActions/registry.test.ts
index dc56a226c3..c6a765b863 100644
--- a/apps/desktop/src/main/services/adeActions/registry.test.ts
+++ b/apps/desktop/src/main/services/adeActions/registry.test.ts
@@ -174,6 +174,107 @@ describe("isAllowedAdeAction", () => {
     expect(isAllowedAdeAction("git", "COMMIT")).toBe(false);
   });
 
+  it("allowlists every chat action a caller invokes by string", () => {
+    // The inverse direction of the allowlist: not "is each entry valid" but
+    // "does each name someone actually calls have an entry". A name called by
+    // string with no entry fails at `run_ade_action` with "is not exposed
+    // through ADE actions", which no compiler or type sees.
+    //
+    // Two callers reach the chat domain by string, and BOTH have to be in this
+    // list — `chat.createAttachmentUpload` shipped unallowlisted precisely
+    // because it is called only from the second one, so a preload-only sweep
+    // would have passed:
+    //
+    //   perl -0777 -ne 'while(/"chat",\s*\n?\s*"([A-Za-z][A-Za-z0-9]*)"/g)
+    //     {print "$1\n"}' src/preload/preload.ts | sort -u
+    //   perl -0777 -ne 'while(/domain:\s*"chat",\s*\n?\s*action:\s*"([A-Za-z]
+    //     [A-Za-z0-9]*)"/g){print "$1\n"}' \
+    //     src/main/services/remoteRuntime/remoteConnectionService.ts | sort -u
+    //
+    // Re-run both when adding a chat action to either caller.
+    const CALLED_BY_STRING = [
+      // src/preload/preload.ts
+      "approveToolUse", "archiveSession", "cancelDispatchedSteer", "cancelScheduledWork",
+      "cancelSteer", "clearCodexGoal", "copyTempAttachment", "createPromptStash",
+      "createScheduledWork", "createSession", "deletePromptStash", "deleteSession",
+      "dispatchSteer", "editSteer", "ensureCtoSession", "fileSearch",
+      "generateAutoLaneIdentity", "getAvailableModels", "getChatEventHistory",
+      "getChatEventHistoryPage", "getClaudeSessionInfo", "getClaudeSessionMessages",
+      "getCodexGoal", "getContextUsage", "getImageDataUrl", "getMainTranscript",
+      "getParallelLaunchState", "getSessionCapabilities", "getSessionSummary",
+      "getSlashCommands", "getSubagentTranscript", "getTurnFileDiff", "handoffSession",
+      "interrupt", "killDroidWorker", "launchCli", "launchHeadless",
+      "listClaudeOutputStyles", "listClaudePlugins", "listClaudeSessions",
+      "listMentionSuggestions", "listPromptStashes", "listScheduledWork", "listSessions",
+      "listSubagents", "markCrossMachineHandoff", "modelCatalog",
+      "prepareCrossMachineHandoff", "recoverCodexTurn", "recoverContinuity", "recoverTurn",
+      "regenerateSessionMetadata", "reloadClaudePlugins", "resetCodexMemory",
+      "resolveSmartLinkPreview", "resolveUnprocessedMessage", "respondToInput",
+      "restoreCancelledQueue", "rewindFiles", "saveTempAttachment", "sendMessage",
+      "setClaudeOutputStyle", "setCodexGoal", "setCodexGoalStatus", "setParallelLaunchState",
+      "setScheduledWorkPaused", "steer", "suggestLaneNameFromPrompt",
+      "terminateCodexBackgroundTerminal", "unarchiveSession", "updateSession",
+      "validateCrossMachineSource", "warmupModel",
+      // src/main/services/remoteRuntime/remoteConnectionService.ts
+      "createAttachmentUpload",
+    ];
+
+    // A silently emptied list would make every assertion below vacuous.
+    expect(CALLED_BY_STRING.length).toBeGreaterThan(50);
+    for (const action of CALLED_BY_STRING) {
+      expect(ADE_ACTION_ALLOWLIST.chat, `chat.${action} is called by string but not allowlisted`)
+        .toContain(action);
+    }
+  });
+
+  it("implements the chat actions the registry owns rather than forwarding", () => {
+    // Allowlisting a name nothing implements is invisible in desktop-only
+    // builds (the renderer's own IPC handler answers) and fatal in
+    // runtime-backed ones: `callAction` rejects with "is not callable" and the
+    // feature is dead on every remote/brain-backed machine.
+    // `chat.createAttachmentUpload` was exactly that on this branch before the
+    // fix: `remoteConnectionService.uploadChatAttachment` called it by string,
+    // and it existed only on the sync command channel — never on this domain
+    // service — so remote-paired attach failed on every machine.
+    //
+    // These are the actions the chat domain service builds ITSELF from the
+    // runtime's project root rather than forwarding to `agentChatService`, so a
+    // bare stub is enough to catch one going missing.
+    const service = getAdeActionDomainServices({
+      projectRoot: "/tmp/ade-registry-test",
+      agentChatService: {},
+    } as never).chat as Record<string, unknown> | null;
+
+    expect(service).toBeTruthy();
+    for (const action of [
+      "saveTempAttachment",
+      "copyTempAttachment",
+      "createAttachmentUpload",
+      "getImageDataUrl",
+      "getTurnFileDiff",
+      "listMentionSuggestions",
+    ]) {
+      expect(ADE_ACTION_ALLOWLIST.chat).toContain(action);
+      expect(typeof service?.[action], `chat.${action} is not callable`).toBe("function");
+    }
+  });
+
+  it("keeps copyTempAttachment's remote reach tied to authority a paired peer already holds", () => {
+    // `chat.copyTempAttachment` takes an unconstrained absolute source path and
+    // is NOT local-only: `run_ade_action` is reachable over the sync runtime RPC
+    // channel, whose JSON-RPC handler is the same origin-blind factory the local
+    // unix socket gets, so a paired peer can read any file on this disk with it.
+    //
+    // That is acceptable only while the same peer already holds strictly greater
+    // authority through the same door. `chat.launchCli` runs arbitrary processes
+    // and is allowlisted and un-gated, which is the comparison the registry's
+    // comment makes. If that ever stops being true, the comparison is void and
+    // copyTempAttachment needs a real gate rather than a reassuring comment.
+    expect(ADE_ACTION_ALLOWLIST.chat).toContain("copyTempAttachment");
+    expect(isAllowedAdeAction("chat", "launchCli")).toBe(true);
+    expect(isCtoOnlyAdeAction("chat", "launchCli")).toBe(false);
+  });
+
   it("each allowlist entry is marked allowed by the predicate", () => {
     // Round-trip: whatever is in the data drives the predicate, so this
     // guards against accidental mutations (e.g. a trailing space in a name).
diff --git a/apps/desktop/src/main/services/adeActions/registry.ts b/apps/desktop/src/main/services/adeActions/registry.ts
index 680b59a78f..2e66f3bbdc 100644
--- a/apps/desktop/src/main/services/adeActions/registry.ts
+++ b/apps/desktop/src/main/services/adeActions/registry.ts
@@ -112,6 +112,15 @@ import type {
   LinearConnectionStatus,
 } from "../../../shared/types";
 import { getModelById } from "../../../shared/modelRegistry";
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  legacyAttachmentCapMessage,
+} from "../../../shared/chatAttachmentLimits";
+import {
+  projectAttachmentsDir,
+  stageAttachmentBytes,
+  stageAttachmentCopy,
+} from "../../../shared/chatAttachmentStagingFs";
 import {
   buildLaneEnvTeardown,
   ensureActiveLanePortLease,
@@ -633,6 +642,12 @@ export const ADE_ACTION_ALLOWLIST: Partial<Record<AdeActionDomain, readonly stri
     "reloadClaudePlugins",
     "rewindFiles",
     "saveTempAttachment",
+    "copyTempAttachment",
+    // The paired desktop's ticket mint for the streamed HTTP upload route.
+    // `remoteConnectionService.uploadChatAttachment` calls it by string over
+    // `run_ade_action`, so leaving it off this list left remote-paired attach
+    // failing on every machine.
+    "createAttachmentUpload",
     "sendMessage",
     "readTranscript",
     "readTranscriptPage",
@@ -1353,7 +1368,9 @@ function buildOrchestrationDomainService(runtime: AdeRuntime): OpaqueService | n
   }) as unknown as OpaqueService;
 }
 
-const MAX_TEMP_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+// The base64/in-memory ceiling, single-sourced so the constant and the
+// rejection message can never drift apart.
+const MAX_TEMP_ATTACHMENT_BYTES = LEGACY_MAX_CHAT_ATTACHMENT_BYTES;
 const FILE_SEARCH_SESSION_LANE_CACHE_MAX = 200;
 // Only non-identity sessions are cached: a regular chat session's lane binding
 // is immutable (updateSession exposes no laneId; handoffs create new sessions),
@@ -1488,19 +1505,17 @@ async function saveAgentChatTempAttachment(projectRoot: string, arg: { data?: st
     throw new Error("Temporary attachment data is required.");
   }
   if (arg.data.length > maxEncodedLength) {
-    throw new Error("Temporary attachments must be 10 MB or smaller.");
+    throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
   }
   const content = Buffer.from(arg.data, "base64");
   if (content.byteLength > MAX_TEMP_ATTACHMENT_BYTES) {
-    throw new Error("Temporary attachments must be 10 MB or smaller.");
+    throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
   }
-  const baseDir = path.join(projectRoot, ".ade", "attachments");
-  await fs.promises.mkdir(baseDir, { recursive: true });
-  const filename = typeof arg.filename === "string" ? arg.filename : "";
-  const ext = path.extname(filename) || ".png";
-  const destPath = path.join(baseDir, `${randomUUID()}${ext}`);
-  await fs.promises.writeFile(destPath, content);
-  return { path: destPath };
+  return await stageAttachmentBytes({
+    content,
+    filename: typeof arg.filename === "string" ? arg.filename : null,
+    attachmentsDir: projectAttachmentsDir(projectRoot),
+  });
 }
 
 function resolveAgentChatImagePath(projectRoot: string, rawPath: unknown): string {
@@ -1561,7 +1576,7 @@ async function getAgentChatImageDataUrl(projectRoot: string, arg: { path?: strin
     throw new Error("Path is not a file.");
   }
   if (stat.size > MAX_TEMP_ATTACHMENT_BYTES) {
-    throw new Error("Image must be 10 MB or smaller.");
+    throw new Error(legacyAttachmentCapMessage("Image"));
   }
   const data = await fs.promises.readFile(imagePath);
   const mimeType = sniffImageMimeType(data);
@@ -1819,6 +1834,51 @@ function buildChatDomainService(runtime: AdeRuntime): OpaqueService | null {
     },
     saveTempAttachment: (args?: { data?: string; filename?: string }) =>
       saveAgentChatTempAttachment(runtime.projectRoot, args ?? {}),
+    // The composer's same-machine attachment staging. The renderer only reaches
+    // it after `getAttachmentStagingMode` answered `copy`, which it only does
+    // when the chat's machine binding IS this machine — so in the product the
+    // unconstrained source path is always one this user just dragged in.
+    //
+    // That is a statement about the UI, not a boundary, and there is no gate
+    // here: this IS reachable over sync RPC from a paired peer. The handler
+    // serving that channel is the same zero-argument factory the local unix
+    // socket gets (`setSyncRuntimeRpcHandlerFactory` in cli.ts), and
+    // `SessionState` carries no transport origin, so nothing downstream can
+    // tell the two callers apart. A paired peer can therefore read any file on
+    // this disk through here.
+    //
+    // Not an escalation, for two reasons. Opening that channel at all requires
+    // a runtime-host pairing grant (syncPairedChannelService refuses `rpc_open`
+    // without one), and a peer holding it already reaches `chat.launchCli` —
+    // arbitrary processes on this machine — through the same door. Pairing,
+    // not this allowlist, is where that trust is decided.
+    copyTempAttachment: (args?: { sourcePath?: string; filename?: string }) =>
+      stageAttachmentCopy({
+        sourcePath: typeof args?.sourcePath === "string" ? args.sourcePath : "",
+        filename: typeof args?.filename === "string" ? args.filename : null,
+        attachmentsDir: projectAttachmentsDir(runtime.projectRoot),
+      }),
+    /**
+     * Mint a ticket for the streamed HTTP upload route so a paired desktop can
+     * stage a file it holds WITHOUT base64-inflating it through two heaps.
+     *
+     * This is the registry half of the same feature `chat.createAttachmentUpload`
+     * serves on the sync command channel (mobile and other sync clients). Both
+     * mint from the host's one `AttachmentUploadRegistry` instance — a ticket is
+     * only redeemable by the request handler that shares that map, so a
+     * second registry here would issue tickets no route recognises.
+     */
+    createAttachmentUpload: (args?: { filename?: string }) => {
+      const syncHost = runtime.syncHostService;
+      if (!syncHost) {
+        throw new Error("This machine is not sharing this project, so it cannot accept attachment uploads.");
+      }
+      const filename = typeof args?.filename === "string" ? args.filename.trim() : "";
+      return syncHost.issueAttachmentUploadTicket({
+        projectRoot: runtime.projectRoot,
+        filename: filename || "attachment",
+      });
+    },
     getImageDataUrl: (args?: { path?: string }) =>
       getAgentChatImageDataUrl(runtime.projectRoot, args ?? {}),
   };
diff --git a/apps/desktop/src/main/services/analytics/agentTurnProductAnalytics.ts b/apps/desktop/src/main/services/analytics/agentTurnProductAnalytics.ts
index bfd09ce7ce..d8d3d3888c 100644
--- a/apps/desktop/src/main/services/analytics/agentTurnProductAnalytics.ts
+++ b/apps/desktop/src/main/services/analytics/agentTurnProductAnalytics.ts
@@ -1,4 +1,5 @@
 import type { AgentChatTurnSettledEvent } from "../chat/agentChatService";
+import type { ChatAutoResumeAnalyticsProperties } from "../chat/chatAutoResumeCoordinator";
 import type { ProductAnalyticsService } from "./productAnalyticsService";
 
 type AgentTurnAnalytics = Pick<ProductAnalyticsService, "captureInternal">;
@@ -50,6 +51,28 @@ export function captureChatMentionsExpandedAnalytics(args: {
   });
 }
 
+/**
+ * One coarse fact per auto-resume transition, so the product question — does
+ * auto-resume actually rescue a chat a usage limit stopped? — can be answered
+ * from `armed` versus `resumed` versus `paused`.
+ *
+ * No project or session id, deliberately: unlike the turn-settled events this
+ * file's other producers emit, nothing here is scoped to a chat or a repo, and
+ * the arm cap already bounds the volume without a per-session dedupe key. The
+ * coordinator hands over the whole closed property set, so this function cannot
+ * widen it.
+ */
+export function captureChatAutoResumeAnalytics(args: {
+  analytics: AgentTurnAnalytics;
+  properties: ChatAutoResumeAnalyticsProperties;
+}): void {
+  args.analytics.captureInternal({
+    event: "ade_feature_used",
+    surface: "api",
+    properties: { feature: "work", ...args.properties },
+  });
+}
+
 export function captureAgentTurnSettledAnalytics(args: {
   analytics: AgentTurnAnalytics;
   projectId: string;
diff --git a/apps/desktop/src/main/services/analytics/productAnalyticsPolicy.ts b/apps/desktop/src/main/services/analytics/productAnalyticsPolicy.ts
index 3411832c43..47d35db22e 100644
--- a/apps/desktop/src/main/services/analytics/productAnalyticsPolicy.ts
+++ b/apps/desktop/src/main/services/analytics/productAnalyticsPolicy.ts
@@ -137,6 +137,11 @@ const ANALYTICS_ONLY_ACTIONS = new Set([
   // settle-tuple write that had to be reconciled through the chokepoint.
   "settle_teardown_residue",
   "settle_remote_write_reconciled",
+  // The chat auto-resume loop after a provider usage limit: whether a resume
+  // was scheduled, whether one actually ran, and whether the re-arm cap stopped
+  // the chat from spending another turn. Three coarse transitions and nothing
+  // about the chat itself.
+  "auto_resume",
   // One coarse fact per "Report issue" press: whether the GitHub issue page
   // opened. Never the surface it was pressed on, and never the report itself.
   "issue_report",
@@ -284,6 +289,11 @@ const SAFE_STRING_VALUES: Partial<Record<string, ReadonlySet<string>>> = {
     // `failed` on purpose: "we chose not to send" and "we tried and could not"
     // answer different questions, and the first is the guardrail working.
     "skipped_budget",
+    // The three auto-resume transitions. `cancelled` above is deliberately NOT
+    // reused for the fourth one: cancellation fires on ordinary user activity,
+    // so it would be a typing signal rather than a workflow outcome, and it is
+    // derivable from armed minus resumed anyway.
+    "armed", "resumed", "paused",
   ]),
   provider: new Set(["codex", "openai", "claude", "cursor", "droid", "opencode", "pi", "gemini", "lmstudio", "local", "other"]),
   model_family: new Set([
diff --git a/apps/desktop/src/main/services/analytics/productAnalyticsService.test.ts b/apps/desktop/src/main/services/analytics/productAnalyticsService.test.ts
index d3e88bc0ed..d78c4f571f 100644
--- a/apps/desktop/src/main/services/analytics/productAnalyticsService.test.ts
+++ b/apps/desktop/src/main/services/analytics/productAnalyticsService.test.ts
@@ -1501,6 +1501,29 @@ describe("product analytics producers", () => {
     })).not.toHaveProperty("count_bucket");
   });
 
+  it("keeps the three auto-resume outcomes through the sanitizer and drops a fourth", () => {
+    // `action` is allowlisted separately from the event's key list and every
+    // outcome value has its own allowlist, so an unregistered pair ships
+    // anonymous rather than not at all — the failure mode the settle-teardown
+    // event hit first.
+    for (const outcome of ["armed", "resumed", "paused"]) {
+      expect(sanitizeProductAnalyticsProperties("ade_feature_used", {
+        feature: "work",
+        action: "auto_resume",
+        outcome,
+        provider: "claude",
+      })).toEqual({ feature: "work", action: "auto_resume", outcome, provider: "claude" });
+    }
+
+    // The set is closed at three. A fourth transition cannot be added by
+    // spelling it at a call site.
+    expect(sanitizeProductAnalyticsProperties("ade_feature_used", {
+      feature: "work",
+      action: "auto_resume",
+      outcome: "rescheduled",
+    })).not.toHaveProperty("outcome");
+  });
+
   it("keeps the Report-issue outcome through the sanitizer and nothing else", () => {
     // "Report issue" is the one control on ADE's error screens, so the only
     // product question is whether pressing it reaches GitHub. `action` is
diff --git a/apps/desktop/src/main/services/chat/agentChatService.test.ts b/apps/desktop/src/main/services/chat/agentChatService.test.ts
index 5a5aedcbc2..83c27b17e8 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.test.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.test.ts
@@ -18331,6 +18331,616 @@ describe("createAgentChatService", () => {
       expect(service.hasActiveWorkloads()).toBe(false);
     });
 
+    describe("auto-resume after a provider usage limit resets", () => {
+      /**
+       * Drives one Codex turn to a usage-limit failure. `resetAt` is the reset
+       * instant the provider publishes through `account/rateLimits/updated`;
+       * `null` models a provider that reports no reset time at all.
+       */
+      const codexTurnStarts = (): number => mockState.codexRequestPayloads
+        .filter((payload) => payload.method === "turn/start").length;
+
+      const waitForNextCodexTurnStart = async (startsBefore: number): Promise<void> => {
+        await vi.waitFor(() => {
+          expect(codexTurnStarts()).toBeGreaterThan(startsBefore);
+        }, { timeout: 5_000, interval: 10 });
+      };
+
+      const failCodexTurnAtUsageLimit = (turnId: string, resetAt: string | null): void => {
+        mockState.emitCodexPayload({
+          jsonrpc: "2.0",
+          method: "turn/started",
+          params: { turn: { id: turnId, status: "inProgress" } },
+        });
+        mockState.emitCodexPayload({
+          jsonrpc: "2.0",
+          method: "account/rateLimits/updated",
+          params: { rateLimits: { remaining: 0, limit: 100, resetAt } },
+        });
+        const error = {
+          message: "You've hit your usage limit.",
+          codexErrorInfo: "usageLimitReached",
+        };
+        mockState.emitCodexPayload({
+          jsonrpc: "2.0",
+          method: "error",
+          params: { turnId, error, willRetry: false },
+        });
+        mockState.emitCodexPayload({
+          jsonrpc: "2.0",
+          method: "turn/completed",
+          params: { turn: { id: turnId, status: "failed", error } },
+        });
+      };
+
+      const completeCodexTurn = (turnId: string): void => {
+        mockState.emitCodexPayload({
+          jsonrpc: "2.0",
+          method: "turn/started",
+          params: { turn: { id: turnId, status: "inProgress" } },
+        });
+        mockState.emitCodexPayload({
+          jsonrpc: "2.0",
+          method: "turn/completed",
+          params: { turn: { id: turnId, status: "completed" } },
+        });
+      };
+
+      const failTurnAtUsageLimit = async (
+        service: any,
+        sessionId: string,
+        turnId: string,
+        resetAt: string | null,
+      ): Promise<void> => {
+        const turnStartsBefore = codexTurnStarts();
+        const turn = service.runSessionTurn({ sessionId, text: "Ship the fix." });
+        await waitForNextCodexTurnStart(turnStartsBefore);
+        failCodexTurnAtUsageLimit(turnId, resetAt);
+        await turn;
+      };
+
+      /**
+       * A reset instant whose armed fire time lands `inMs` from now, once the
+       * 90s anti-race buffer is added. Tests that need the resume to actually
+       * fire have to arm against a window that is nearly over — the buffer is
+       * the whole reason a fresh reset instant is minutes away, not seconds.
+       */
+      const resetFiringIn = (inMs: number): string =>
+        new Date(Date.now() - 90_000 + inMs).toISOString();
+
+      /**
+       * A scheduled-work store whose load blocks until the test releases it.
+       *
+       * Both halves of the arm/cancel race only exist while the scheduler has
+       * no rows: an arm parked on `scheduledWorkReady` has not written its row
+       * yet, and a booting brain has not read the durable one back yet. Holding
+       * `loadState` open is the only way to stand in that window on purpose
+       * instead of hoping a sleep lands inside it.
+       */
+      const createBootGatedScheduledWorkDb = () => {
+        const backing = createScheduledWorkDb();
+        let releaseBoot!: () => void;
+        const booted = new Promise<void>((resolve) => { releaseBoot = resolve; });
+        return {
+          db: {
+            ...backing.db,
+            getJson: (key: string) => (key === SCHEDULED_WORK_STATE_KEY
+              // Read on release, not on call, so the test can seed the durable
+              // row after it knows the session id.
+              ? booted.then(() => backing.db.getJson(key))
+              : backing.db.getJson(key)),
+          },
+          seed: (state: ChatScheduledWorkState) => {
+            backing.db.setJson(SCHEDULED_WORK_STATE_KEY, state);
+          },
+          readState: backing.readState,
+          releaseBoot: () => releaseBoot(),
+        };
+      };
+
+      it("cancels an auto-resume that was arming when the user sent a message", async () => {
+        const scheduledWork = createBootGatedScheduledWorkDb();
+        const events: AgentChatEventEnvelope[] = [];
+        const { service } = createService({
+          db: scheduledWork.db,
+          onEvent: (event: AgentChatEventEnvelope) => events.push(event),
+        });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+
+        await failTurnAtUsageLimit(
+          service,
+          session.id,
+          "turn-limit-arming",
+          new Date(Date.now() + 30 * 60_000).toISOString(),
+        );
+        // The failure event is what starts the arm, so this is the point after
+        // which the arm is parked on the scheduler with no row written yet.
+        await waitForEvent(
+          events,
+          (event): event is AgentChatEventEnvelope => event.event.type === "error",
+        );
+        // The user gets there first. A sweep now finds nothing to cancel — the
+        // row it is looking for is still in flight behind the scheduler.
+        await service.sendMessage({
+          sessionId: session.id,
+          text: "Never mind, I'll drive this myself.",
+        });
+
+        scheduledWork.releaseBoot();
+
+        // The row really was created and then undone — asserting only that
+        // nothing is pending would pass before the arm had even written it.
+        await vi.waitFor(() => {
+          expect(scheduledWork.readState()?.schedules).toEqual([
+            expect.objectContaining({
+              id: `auto-resume:${session.id}`,
+              source: "auto_resume_limit",
+              status: "cancelled",
+            }),
+          ]);
+        });
+        expect(await service.listScheduledWork({ sessionId: session.id })).toEqual([]);
+      });
+
+      it("cancels a durable auto-resume during scheduler boot", async () => {
+        const scheduledWork = createBootGatedScheduledWorkDb();
+        const { service } = createService({ db: scheduledWork.db });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+        // A row armed before the last restart, still on disk, not yet loaded.
+        scheduledWork.seed({
+          version: 1,
+          schedules: [{
+            id: `auto-resume:${session.id}`,
+            sessionId: session.id,
+            kind: "wakeup",
+            prompt: "Continue the interrupted task from where it stopped.",
+            reason: "Auto-resume after usage limit reset",
+            fireAt: Date.now() + 30 * 60_000,
+            createdAt: Date.now() - 60_000,
+            status: "scheduled",
+            pausedFlag: false,
+            lateFlag: false,
+            durable: true,
+            source: "auto_resume_limit",
+          }],
+          pausedSessionIds: [],
+        });
+
+        await service.sendMessage({
+          sessionId: session.id,
+          text: "I'm back, taking this over.",
+        });
+
+        scheduledWork.releaseBoot();
+
+        await vi.waitFor(async () => {
+          expect(await service.listScheduledWork({ sessionId: session.id })).toEqual([]);
+        });
+        expect(scheduledWork.readState()?.schedules).toEqual([
+          expect.objectContaining({
+            id: `auto-resume:${session.id}`,
+            status: "cancelled",
+          }),
+        ]);
+      });
+
+      it("stops re-arming after two consecutive auto-resume failures", async () => {
+        const scheduledWork = createScheduledWorkDb();
+        const events: AgentChatEventEnvelope[] = [];
+        const { service } = createService({
+          db: scheduledWork.db,
+          onEvent: (event: AgentChatEventEnvelope) => events.push(event),
+        });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+
+        // The cap only counts resumes that actually ran and died at the limit
+        // again, so this drives the real trip path: every failure after the
+        // first one belongs to a turn the scheduler itself dispatched. Claude's
+        // snapshot is session-scoped and `mergeSnapshot` carries a stale reset
+        // forward, so a limit the resume cannot clear still publishes a fresh
+        // reset instant on every cycle; Codex's rolling window models that here.
+        await failTurnAtUsageLimit(service, session.id, "turn-cap-1", resetFiringIn(400));
+
+        const firstResumeStarts = codexTurnStarts();
+        await waitForNextCodexTurnStart(firstResumeStarts);
+        failCodexTurnAtUsageLimit("turn-cap-2", resetFiringIn(400));
+
+        const secondResumeStarts = codexTurnStarts();
+        await waitForNextCodexTurnStart(secondResumeStarts);
+        failCodexTurnAtUsageLimit("turn-cap-3", resetFiringIn(400));
+
+        const paused = await waitForEvent(
+          events,
+          (event): event is AgentChatEventEnvelope =>
+            event.event.type === "system_notice"
+            && typeof event.event.message === "string"
+            && event.event.message.startsWith("Auto-resume paused"),
+        );
+        expect(paused.event).toMatchObject({ noticeKind: "rate_limit", severity: "info" });
+        // The notice explains the failure, so it has to be committed after it.
+        // The cap check runs from inside the error's own commit, before that
+        // event has minted its sequence, so an inline emit would number the
+        // notice below the error and render it above.
+        const lastLimitError = [...events].reverse().find((event) =>
+          event.event.type === "error"
+          && typeof event.event.message === "string"
+          && event.event.message.includes("usage limit"));
+        expect(lastLimitError?.sequence).toEqual(expect.any(Number));
+        expect(paused.sequence ?? -1).toBeGreaterThan(lastLimitError?.sequence ?? 0);
+
+        // Three failures, two arms: the third window is never armed, so no
+        // further turn is spent on a limit that is not lifting.
+        expect(events.filter((event) =>
+          event.event.type === "system_notice"
+          && typeof event.event.message === "string"
+          && event.event.message.startsWith("Auto-resume scheduled for")))
+          .toHaveLength(2);
+        const [afterCap] = await service.listScheduledWork({ sessionId: session.id });
+        expect(afterCap?.status).toBe("fired");
+
+        // A user message is the intervening event that clears the streak, so
+        // the next limit arms again rather than staying paused forever.
+        await vi.waitFor(() => {
+          expect(service.hasActiveWorkloads()).toBe(false);
+        }, { timeout: 5_000, interval: 10 });
+        const userTurnStarts = codexTurnStarts();
+        await service.sendMessage({ sessionId: session.id, text: "Try again now." });
+        await waitForNextCodexTurnStart(userTurnStarts);
+        completeCodexTurn("turn-cap-user");
+
+        const nextResetMs = Date.now() + 150 * 60_000;
+        await failTurnAtUsageLimit(
+          service, session.id, "turn-cap-4", new Date(nextResetMs).toISOString(),
+        );
+        await vi.waitFor(async () => {
+          const [next] = await service.listScheduledWork({ sessionId: session.id });
+          expect(Date.parse(next?.nextRunAt ?? "")).toBe(nextResetMs + 90_000);
+        }, { timeout: 5_000, interval: 10 });
+      });
+
+      it("a successful auto-resume resets the streak", async () => {
+        const scheduledWork = createScheduledWorkDb();
+        const events: AgentChatEventEnvelope[] = [];
+        const { service } = createService({
+          db: scheduledWork.db,
+          onEvent: (event: AgentChatEventEnvelope) => events.push(event),
+        });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+
+        // Walk the chat right up to the cap, then let a resume actually work.
+        await failTurnAtUsageLimit(service, session.id, "streak-1", resetFiringIn(400));
+        const firstResumeStarts = codexTurnStarts();
+        await waitForNextCodexTurnStart(firstResumeStarts);
+        failCodexTurnAtUsageLimit("streak-2", resetFiringIn(400));
+
+        const secondResumeStarts = codexTurnStarts();
+        await waitForNextCodexTurnStart(secondResumeStarts);
+        completeCodexTurn("streak-resume-ok");
+
+        // The next limit arrives on another scheduled turn, so nothing in
+        // between clears the streak by hand — only the successful resume can.
+        // A fired resume always carries `scheduledWake`, which is exactly what
+        // the dispatch sweep skips, so without the completion hook this chat
+        // would still be holding two failed arms and would pause itself here
+        // instead of scheduling a third resume.
+        await vi.waitFor(() => {
+          expect(service.hasActiveWorkloads()).toBe(false);
+        }, { timeout: 5_000, interval: 10 });
+        const wakeupStarts = codexTurnStarts();
+        await service.createScheduledWork({
+          sessionId: session.id,
+          runAt: new Date(Date.now() + 300).toISOString(),
+          prompt: "Pick the task back up.",
+          reason: "Follow-up",
+        });
+        await waitForNextCodexTurnStart(wakeupStarts);
+        const laterResetMs = Date.now() + 60 * 60_000;
+        failCodexTurnAtUsageLimit("streak-3", new Date(laterResetMs).toISOString());
+
+        await vi.waitFor(async () => {
+          const rows = await service.listScheduledWork({ sessionId: session.id });
+          const resume = rows.find((row: { id: string }) => row.id === `auto-resume:${session.id}`);
+          expect(Date.parse(resume?.nextRunAt ?? "")).toBe(laterResetMs + 90_000);
+        }, { timeout: 5_000, interval: 10 });
+        expect(events.some((event) =>
+          event.event.type === "system_notice"
+          && typeof event.event.message === "string"
+          && event.event.message.startsWith("Auto-resume paused"))).toBe(false);
+      });
+
+      it("explicit cancel wins over an in-flight arm", async () => {
+        const scheduledWork = createBootGatedScheduledWorkDb();
+        const events: AgentChatEventEnvelope[] = [];
+        const { service } = createService({
+          db: scheduledWork.db,
+          onEvent: (event: AgentChatEventEnvelope) => events.push(event),
+        });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+        // A durable row from before the last restart, so Chat info has
+        // something to offer Cancel for while this process is still booting the
+        // scheduler — and while the fresh arm below is parked behind it.
+        scheduledWork.seed({
+          version: 1,
+          schedules: [{
+            id: `auto-resume:${session.id}`,
+            sessionId: session.id,
+            kind: "wakeup",
+            prompt: "Continue the interrupted task from where it stopped.",
+            reason: "Auto-resume after usage limit reset",
+            fireAt: Date.now() + 30 * 60_000,
+            createdAt: Date.now() - 60_000,
+            status: "scheduled",
+            pausedFlag: false,
+            lateFlag: false,
+            durable: true,
+            source: "auto_resume_limit",
+          }],
+          pausedSessionIds: [],
+        });
+
+        // Both the dismissal and the arm below park behind the booting
+        // scheduler, and the dismissal parked first, so it is the one that runs
+        // first on release — the arm's upsert lands on an already-cancelled row
+        // and its `scheduled` status would otherwise win, resurrecting exactly
+        // the row the user just dismissed.
+        const dismissal = service.cancelScheduledWork({
+          sessionId: session.id,
+          scheduleId: `auto-resume:${session.id}`,
+        });
+        await failTurnAtUsageLimit(
+          service,
+          session.id,
+          "turn-limit-dismissed",
+          new Date(Date.now() + 45 * 60_000).toISOString(),
+        );
+        await waitForEvent(
+          events,
+          (event): event is AgentChatEventEnvelope => event.event.type === "error",
+        );
+
+        scheduledWork.releaseBoot();
+        await dismissal;
+
+        await vi.waitFor(async () => {
+          expect(await service.listScheduledWork({ sessionId: session.id })).toEqual([]);
+        }, { timeout: 5_000, interval: 10 });
+        expect(scheduledWork.readState()?.schedules).toEqual([
+          expect.objectContaining({
+            id: `auto-resume:${session.id}`,
+            status: "cancelled",
+          }),
+        ]);
+      });
+
+      it("an empty send leaves a pending auto-resume armed", async () => {
+        const scheduledWork = createScheduledWorkDb();
+        const { service } = createService({ db: scheduledWork.db });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+
+        await failTurnAtUsageLimit(
+          service,
+          session.id,
+          "turn-limit-empty-send",
+          new Date(Date.now() + 30 * 60_000).toISOString(),
+        );
+        await vi.waitFor(async () => {
+          expect(await service.listScheduledWork({ sessionId: session.id })).toHaveLength(1);
+        }, { timeout: 5_000, interval: 10 });
+
+        // A send that never becomes a turn is not the user taking over.
+        await service.sendMessage({ sessionId: session.id, text: "   " });
+
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        expect(await service.listScheduledWork({ sessionId: session.id })).toHaveLength(1);
+      });
+
+      it("schedules a tagged auto-resume when the usage limit reports a reset time", async () => {
+        const scheduledWork = createScheduledWorkDb();
+        const events: AgentChatEventEnvelope[] = [];
+        const { service } = createService({
+          db: scheduledWork.db,
+          onEvent: (event: AgentChatEventEnvelope) => events.push(event),
+        });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+        const resetAtMs = Date.now() + 30 * 60_000;
+
+        await failTurnAtUsageLimit(
+          service,
+          session.id,
+          "turn-limit-1",
+          new Date(resetAtMs).toISOString(),
+        );
+
+        await vi.waitFor(async () => {
+          expect(await service.listScheduledWork({ sessionId: session.id })).toHaveLength(1);
+        });
+        const [schedule] = await service.listScheduledWork({ sessionId: session.id });
+        expect(schedule).toMatchObject({
+          id: `auto-resume:${session.id}`,
+          sessionId: session.id,
+          kind: "wakeup",
+          status: "scheduled",
+          source: "auto_resume_limit",
+          durable: true,
+        });
+        expect(schedule.prompt).toContain("Continue the interrupted task from where it stopped");
+        // Reset instant plus the 90s buffer, so the resume never races the reset.
+        expect(Date.parse(schedule.nextRunAt ?? "")).toBe(resetAtMs + 90_000);
+        // The tag survives a brain restart alongside the rest of the row.
+        expect(scheduledWork.readState()?.schedules).toEqual([
+          expect.objectContaining({
+            id: `auto-resume:${session.id}`,
+            source: "auto_resume_limit",
+            fireAt: resetAtMs + 90_000,
+          }),
+        ]);
+
+        const notice = await waitForEvent(
+          events,
+          (event): event is AgentChatEventEnvelope =>
+            event.event.type === "system_notice"
+            && typeof event.event.message === "string"
+            && event.event.message.startsWith("Auto-resume scheduled for"),
+        );
+        expect(notice.event).toMatchObject({ noticeKind: "rate_limit", severity: "info" });
+      });
+
+      it("schedules no auto-resume when the usage limit reports no reset time", async () => {
+        const scheduledWork = createScheduledWorkDb();
+        const events: AgentChatEventEnvelope[] = [];
+        const { service } = createService({
+          db: scheduledWork.db,
+          onEvent: (event: AgentChatEventEnvelope) => events.push(event),
+        });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+
+        await failTurnAtUsageLimit(service, session.id, "turn-limit-noreset", null);
+
+        await waitForEvent(
+          events,
+          (event): event is AgentChatEventEnvelope => event.event.type === "error",
+        );
+        expect(await service.listScheduledWork({ sessionId: session.id })).toEqual([]);
+        expect(events.some((event) =>
+          event.event.type === "system_notice"
+          && typeof event.event.message === "string"
+          && event.event.message.startsWith("Auto-resume scheduled for"))).toBe(false);
+      });
+
+      it("replaces the pending auto-resume instead of stacking on a repeat usage limit", async () => {
+        const scheduledWork = createScheduledWorkDb();
+        const { service } = createService({ db: scheduledWork.db });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+        const firstResetMs = Date.now() + 30 * 60_000;
+        const secondResetMs = Date.now() + 90 * 60_000;
+
+        await failTurnAtUsageLimit(
+          service,
+          session.id,
+          "turn-limit-a",
+          new Date(firstResetMs).toISOString(),
+        );
+        await vi.waitFor(async () => {
+          expect(await service.listScheduledWork({ sessionId: session.id })).toHaveLength(1);
+        });
+
+        await failTurnAtUsageLimit(
+          service,
+          session.id,
+          "turn-limit-b",
+          new Date(secondResetMs).toISOString(),
+        );
+        await vi.waitFor(async () => {
+          const [schedule] = await service.listScheduledWork({ sessionId: session.id });
+          expect(Date.parse(schedule?.nextRunAt ?? "")).toBe(secondResetMs + 90_000);
+        });
+        expect(await service.listScheduledWork({ sessionId: session.id })).toHaveLength(1);
+      });
+
+      it("cancels the pending auto-resume when the user sends a message", async () => {
+        const scheduledWork = createScheduledWorkDb();
+        const { service } = createService({ db: scheduledWork.db });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+
+        await failTurnAtUsageLimit(
+          service,
+          session.id,
+          "turn-limit-user",
+          new Date(Date.now() + 30 * 60_000).toISOString(),
+        );
+        await vi.waitFor(async () => {
+          expect(await service.listScheduledWork({ sessionId: session.id })).toHaveLength(1);
+        });
+
+        await service.sendMessage({
+          sessionId: session.id,
+          text: "Never mind, I'll drive this myself.",
+        });
+
+        await vi.waitFor(async () => {
+          expect(await service.listScheduledWork({ sessionId: session.id })).toEqual([]);
+        });
+      });
+
+      it("leaves user-created scheduled work untouched when it cancels an auto-resume", async () => {
+        const scheduledWork = createScheduledWorkDb();
+        const { service } = createService({ db: scheduledWork.db });
+        const session = await service.createSession({
+          laneId: "lane-1",
+          provider: "codex",
+          model: "gpt-5.4",
+        });
+        const userSchedule = await service.createScheduledWork({
+          sessionId: session.id,
+          delaySeconds: 3_600,
+          prompt: "Check CI in an hour.",
+          reason: "CI watcher",
+        });
+
+        await failTurnAtUsageLimit(
+          service,
+          session.id,
+          "turn-limit-scoped",
+          new Date(Date.now() + 30 * 60_000).toISOString(),
+        );
+        await vi.waitFor(async () => {
+          expect(await service.listScheduledWork({ sessionId: session.id })).toHaveLength(2);
+        });
+
+        await service.sendMessage({
+          sessionId: session.id,
+          text: "Taking over manually.",
+        });
+
+        await vi.waitFor(async () => {
+          const remaining = await service.listScheduledWork({ sessionId: session.id });
+          expect(remaining.map((item: { id: string }) => item.id)).toEqual([userSchedule.item.id]);
+        });
+        const [survivor] = await service.listScheduledWork({ sessionId: session.id });
+        expect(survivor.source).toBeUndefined();
+      });
+    });
+
     it("creates durable recurring and one-shot scheduled work and validates inputs and session state", async () => {
       const scheduledWork = createScheduledWorkDb();
       const events: AgentChatEventEnvelope[] = [];
diff --git a/apps/desktop/src/main/services/chat/agentChatService.ts b/apps/desktop/src/main/services/chat/agentChatService.ts
index 3882c56396..7185893a73 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.ts
@@ -207,6 +207,11 @@ import {
   resolvePathWithinRoot,
   stableStringify,
 } from "../shared/utils";
+import {
+  exceedsProviderInlineLimit,
+  inlineAttachmentHintPart,
+} from "./attachmentInlineGuard";
+import { projectAttachmentsDir } from "../../../shared/chatAttachmentStagingFs";
 import {
   resolveCliSpawnInvocation,
   terminateProcessTree,
@@ -524,6 +529,9 @@ import {
   snapshotFromClaudeSessionQuotaText,
   type ClaudeSessionQuotaSnapshot,
 } from "../../../shared/claudeSessionQuota";
+import { isAutoResumeScheduledWork } from "../../../shared/chatAutoResume";
+import { createChatAutoResumeCoordinator } from "./chatAutoResumeCoordinator";
+import type { ChatAutoResumeAnalyticsProperties } from "./chatAutoResumeCoordinator";
 import { buildAdeCliAgentGuidance } from "../../../shared/adeCliGuidance";
 import { getAdeAgentSkillRootsForPrompt } from "../../../shared/agentSkillRoots";
 import {
@@ -5948,6 +5956,14 @@ async function buildStreamingUserContent(
       const data = await args.readAttachmentBytes(attachment);
       const mediaType = inferAttachmentMediaType(attachment);
 
+      // Every branch below this point inlines `data` into the request body.
+      // The attachment cap is larger than what a provider accepts inline, so
+      // an oversized file degrades to a path hint rather than a rejected turn.
+      if (exceedsProviderInlineLimit(data.byteLength)) {
+        parts.push(inlineAttachmentHintPart(attachment.path, data.byteLength));
+        continue;
+      }
+
       if (attachment.type === "image") {
         if (args.runtimeKind === "claude" || args.modelDescriptor?.capabilities.vision) {
           parts.push({
@@ -7863,6 +7879,12 @@ export function createAgentChatService(args: {
     sessionId: string;
     outcome: "completed" | "partial" | "failed";
   }) => void;
+  /**
+   * Content-free hook fired once per auto-resume transition (armed, resumed,
+   * paused). Carries no session id by construction — see
+   * `ChatAutoResumeAnalyticsProperties`.
+   */
+  onAutoResumeOutcome?: (properties: ChatAutoResumeAnalyticsProperties) => void;
   onSessionEnded?: (args: { laneId: string; sessionId: string; exitCode: number | null }) => void;
   onLinearIssueChatLinked?: (args: {
     laneId: string;
@@ -7920,6 +7942,7 @@ export function createAgentChatService(args: {
     onTurnSettled,
     onChatMentionsExpanded,
     onSessionMetadataRegenerated,
+    onAutoResumeOutcome,
     onSessionEnded,
     onLinearIssueChatLinked,
     getDirtyFileTextForPath,
@@ -8365,11 +8388,34 @@ export function createAgentChatService(args: {
   };
 
   const managedSessions = new Map<string, ManagedChatSession>();
+  // Declared here rather than next to its only caller further down the file:
+  // `notifyChatSessionEnded` (immediately below) calls `autoResume.forgetSession`,
+  // and a `const` declared thousands of lines later is in its temporal dead zone
+  // for any call that lands before that line executes. Every dependency below is
+  // read through a closure at call time, so nothing else has to move with it.
+  const autoResume = createChatAutoResumeCoordinator({
+    getScheduler: () => scheduledWorkScheduler,
+    whenSchedulerReady: () => scheduledWorkReady,
+    isSessionSchedulable: (sessionId) => {
+      const row = sessionService.get(sessionId);
+      return Boolean(row && !row.archivedAt && isSchedulableAgentSession(row));
+    },
+    emitNotice: (sessionId, notice) => {
+      const managed = managedSessions.get(sessionId);
+      if (!managed) return;
+      emitChatEvent(managed, notice);
+    },
+    ...(onAutoResumeOutcome ? { captureAnalytics: onAutoResumeOutcome } : {}),
+    logger,
+  });
   // Listeners for "this chat is over" (deleted or archived). Services that hold
   // a per-chat lock — the iOS simulator session, for one — release it here
   // instead of staying bound to a chat that no longer exists.
   const chatSessionEndedListeners = new Set<(sessionId: string) => void>();
   const notifyChatSessionEnded = (sessionId: string): void => {
+    // Covers archive and delete both. Auto-resume state outlives nothing here:
+    // the chat is over, so a streak counter for it is pure retention.
+    autoResume.forgetSession(sessionId);
     for (const listener of chatSessionEndedListeners) {
       try {
         listener(sessionId);
@@ -14486,6 +14532,26 @@ export function createAgentChatService(args: {
     };
   };
 
+  // ── Auto-resume after a provider usage limit resets ──
+
+  /**
+   * Reset instant the provider published for the current usage limit, in ms.
+   * Only providers that actually report one are consulted — Claude's plan
+   * quota snapshot and Codex's `account/rateLimits` view. Every other provider
+   * returns null, which keeps today's manual-recovery-only behaviour.
+   */
+  const usageLimitResetAtMs = (managed: ManagedChatSession): number | null => {
+    const claudeReset = managed.claudeSessionQuotaSnapshot?.resetsAtMs;
+    if (typeof claudeReset === "number" && Number.isFinite(claudeReset)) return claudeReset;
+    const runtime = managed.runtime;
+    if (runtime?.kind === "codex") {
+      const resetAt = runtime.rateLimits?.resetAt;
+      const parsed = typeof resetAt === "string" ? Date.parse(resetAt) : Number.NaN;
+      if (Number.isFinite(parsed)) return parsed;
+    }
+    return null;
+  };
+
   type CommitChatEventOptions = {
     liveEvent?: AgentChatEvent;
   };
@@ -14496,6 +14562,14 @@ export function createAgentChatService(args: {
     options: CommitChatEventOptions = {},
   ): void => {
     const decoratedEvent = event.type === "error" ? decorateAgentCliError(managed, event) : event;
+    if (decoratedEvent.type === "error") {
+      autoResume.maybeArmAfterUsageLimit({
+        sessionId: managed.session.id,
+        provider: managed.session.provider,
+        resetAtMs: usageLimitResetAtMs(managed),
+        error: decoratedEvent,
+      });
+    }
     const liveEvent = options.liveEvent ?? decoratedEvent;
     const storedEvent = compactChatEventForStorage(decoratedEvent);
     managed.session.lastActivityAt = nowIso();
@@ -14864,27 +14938,31 @@ export function createAgentChatService(args: {
     if (
       normalizedEvent.type === "user_message"
       && normalizedEvent.deliveryState !== "queued"
-      && normalizedEvent.turnId
       && normalizedEvent.metadata?.scheduledWake?.scheduleId
-      && scheduledWorkScheduler
     ) {
-      runScheduledWorkMutation(
-        "record_turn_started",
-        scheduledWorkScheduler.recordTurnStarted(
-          normalizedEvent.metadata.scheduledWake.scheduleId,
-          normalizedEvent.turnId,
-        ),
-      );
+      const scheduleId = normalizedEvent.metadata.scheduledWake.scheduleId;
+      if (normalizedEvent.turnId && scheduledWorkScheduler) {
+        runScheduledWorkMutation(
+          "record_turn_started",
+          scheduledWorkScheduler.recordTurnStarted(scheduleId, normalizedEvent.turnId),
+        );
+      }
+      if (isAutoResumeScheduledWork({ id: scheduleId })) {
+        autoResume.noteResumeTurnStarted(managed.session.id);
+      }
     }
 
-    if (normalizedEvent.type === "done" && normalizedEvent.turnId && scheduledWorkScheduler) {
-      runScheduledWorkMutation(
-        "record_turn_finished",
-        scheduledWorkScheduler.recordTurnFinished(
-          normalizedEvent.turnId,
-          managed.preview?.trim() || undefined,
-        ),
-      );
+    if (normalizedEvent.type === "done") {
+      autoResume.noteTurnFinished(managed.session.id);
+      if (normalizedEvent.turnId && scheduledWorkScheduler) {
+        runScheduledWorkMutation(
+          "record_turn_finished",
+          scheduledWorkScheduler.recordTurnFinished(
+            normalizedEvent.turnId,
+            managed.preview?.trim() || undefined,
+          ),
+        );
+      }
     }
 
     const compactionEvent = mapLegacyCompactionEvent(
@@ -31192,6 +31270,12 @@ export function createAgentChatService(args: {
       });
       return false;
     }
+    // Past the drop, so a steer the queue refused is not mistaken for activity
+    // and leaves any pending auto-resume armed. The queued message itself is
+    // real user input, and it will run.
+    if (!metadata?.scheduledWake) {
+      autoResume.cancelForSession(sessionId, "user_message");
+    }
     const displayText = extra?.displayText?.trim().length ? extra.displayText.trim() : text;
     const uuid = randomUUID();
     runtime.pendingSteers.push({
@@ -36636,6 +36720,13 @@ export function createAgentChatService(args: {
       try {
         let buf: Buffer;
         if (attachment.type === "image") {
+          // An image has no path-shaped fallback here — it is inlined or it is
+          // a text hint — so the size check happens before the read, not after.
+          const imageSize = resolvedAttachmentDiskSize(attachment);
+          if (imageSize != null && exceedsProviderInlineLimit(imageSize)) {
+            blocks.push(inlineAttachmentHintPart(attachment.path, imageSize));
+            continue;
+          }
           buf = await readResolvedAttachmentBytes(attachment);
         } else {
           const dirtyBuf = await readDirtyResolvedAttachmentBytes(attachment);
@@ -39746,6 +39837,16 @@ export function createAgentChatService(args: {
       optimisticCodexTurnStart,
     } = prepared;
 
+    // Both dispatch commit points cancel the pending auto-resume: this one and
+    // the accepted branch of `enqueueSteerOrDrop`. Together they cover every
+    // route a message can take — send, steer, wake queue, continuity capsule
+    // and the headless `runSessionTurn`, which reaches the provider through
+    // here and so can no longer walk past the sweep. A message that was refused
+    // upstream never gets here, so it leaves the resume armed. Scheduled wakes
+    // are excluded: a fired resume must not cancel itself.
+    if (!metadata?.scheduledWake) {
+      autoResume.cancelForSession(sessionId, "user_message");
+    }
     recordLinearIssueContextForLane(managed, contextAttachments);
     recordGitHubIssueContextForLane(managed, contextAttachments);
 
@@ -43417,6 +43518,7 @@ export function createAgentChatService(args: {
     cancellable: true,
     ...(schedule.lateFlag ? { late: true } : {}),
     ...(schedule.outcomeSummary ? { outcomeSummary: schedule.outcomeSummary } : {}),
+    ...(schedule.source ? { source: schedule.source } : {}),
   });
 
   const createScheduledWork = async (
@@ -43682,6 +43784,9 @@ export function createAgentChatService(args: {
     if (!existing) {
       throw new Error(`Scheduled work '${normalizedScheduleId}' was not found in chat '${normalizedSessionId}'.`);
     }
+    if (isAutoResumeScheduledWork(existing)) {
+      autoResume.noteScheduleDismissed(normalizedSessionId);
+    }
     if (existing.provider === "claude") {
       const cancellation = await requestClaudeScheduledWorkCancellation(
         [existing],
@@ -45590,6 +45695,7 @@ export function createAgentChatService(args: {
     cursorCloudHydrateInFlight.clear();
     cursorCloudHydratedRunIds.clear();
     scheduledWorkScheduler?.dispose();
+    autoResume.forgetAll();
     for (const recovery of cancelledQueueRecoveries.values()) clearTimeout(recovery.timer);
     cancelledQueueRecoveries.clear();
     for (const sessionId of [...managedSessions.keys()]) {
@@ -45615,6 +45721,7 @@ export function createAgentChatService(args: {
     cursorCloudHydrateInFlight.clear();
     cursorCloudHydratedRunIds.clear();
     scheduledWorkScheduler?.dispose();
+    autoResume.forgetAll();
     for (const recovery of cancelledQueueRecoveries.values()) clearTimeout(recovery.timer);
     cancelledQueueRecoveries.clear();
     for (const sessionId of [...sessionTurnCollectors.keys()]) {
@@ -49020,7 +49127,7 @@ export function createAgentChatService(args: {
           }
         };
 
-        cleanupDir(path.join(projectRoot, ".ade", "attachments"));
+        cleanupDir(projectAttachmentsDir(projectRoot));
         cleanupDir(path.join(resolveAdeLayout(projectRoot).tmpDir, "agent-chat-attachments"));
       } catch { /* ignore */ }
     },
diff --git a/apps/desktop/src/main/services/chat/attachmentInlineGuard.ts b/apps/desktop/src/main/services/chat/attachmentInlineGuard.ts
new file mode 100644
index 0000000000..d12315ea11
--- /dev/null
+++ b/apps/desktop/src/main/services/chat/attachmentInlineGuard.ts
@@ -0,0 +1,45 @@
+import {
+  MAX_PROVIDER_INLINE_IMAGE_BYTES,
+  formatAttachmentSize,
+} from "../../../shared/chatAttachmentLimits";
+
+/**
+ * The attachment cap and the provider inline cap are different numbers on
+ * purpose. A staged attachment may be up to `MAX_CHAT_ATTACHMENT_BYTES`,
+ * because most providers receive a *path*: Codex gets a staged copy, Cursor,
+ * Pi and Droid get path-shaped worker IPC, Claude gets `[File attached: ...]`
+ * for non-images. Those paths do not care how big the file is.
+ *
+ * Three call sites do care, because they base64 the bytes into the model
+ * request itself: Claude images (`buildClaudeV2Message`), OpenCode/AI-SDK
+ * streaming content (`buildStreamingUserContent`), and the Droid/Pi prompt
+ * blocks (`buildAgentPromptBlocks`). Base64 inflates by a third and the
+ * provider rejects the request, so raising the attachment cap must not raise
+ * what those three inline. They check this instead and fall back to a text
+ * hint naming the path, which every provider can still act on.
+ */
+export function exceedsProviderInlineLimit(byteLength: number): boolean {
+  return byteLength > MAX_PROVIDER_INLINE_IMAGE_BYTES;
+}
+
+/**
+ * The stand-in a provider sees instead of inlined bytes. Names the path so the
+ * agent can read the file itself with its own tools, and says why — an
+ * unexplained omission reads as a bug to the model and to the user.
+ */
+function attachmentTooLargeToInlineText(displayPath: string, byteLength: number): string {
+  return `[Attachment not inlined: ${displayPath} is ${formatAttachmentSize(byteLength)}, over the ${formatAttachmentSize(MAX_PROVIDER_INLINE_IMAGE_BYTES)} inline limit. Read it from that path if you need its contents.]`;
+}
+
+/**
+ * The hint as a content part, ready to push. All three inlining call sites
+ * build the same `text` part with the same leading newline, so they take the
+ * whole part from here rather than each re-deriving the wording and spacing —
+ * three copies of a provider-facing sentence is three chances to drift.
+ */
+export function inlineAttachmentHintPart(
+  displayPath: string,
+  byteLength: number,
+): { type: "text"; text: string } {
+  return { type: "text", text: `\n${attachmentTooLargeToInlineText(displayPath, byteLength)}` };
+}
diff --git a/apps/desktop/src/main/services/chat/buildClaudeV2Message.test.ts b/apps/desktop/src/main/services/chat/buildClaudeV2Message.test.ts
index 51fd8bd377..94816bb94a 100644
--- a/apps/desktop/src/main/services/chat/buildClaudeV2Message.test.ts
+++ b/apps/desktop/src/main/services/chat/buildClaudeV2Message.test.ts
@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { AgentChatFileRef } from "../../../shared/types/chat";
+import { MAX_PROVIDER_INLINE_IMAGE_BYTES } from "../../../shared/chatAttachmentLimits";
 import {
   buildClaudeV2Message,
   buildClaudeV2MessageAsync,
@@ -147,6 +148,43 @@ describe("buildClaudeV2Message", () => {
     expect(Buffer.from(source.data as string, "base64").toString()).toBe("unsaved-image-bytes");
   });
 
+  // Raising the composer attachment cap to 50 MB must not raise what Claude is
+  // asked to swallow inline: base64 inflates by a third and the API rejects the
+  // request outright, which would kill the turn instead of degrading it.
+  it("does not inline an image past the provider inline limit", async () => {
+    const oversized = Buffer.alloc(MAX_PROVIDER_INLINE_IMAGE_BYTES + 1, 0x41);
+    fs.writeFileSync(path.join(tmpDir, "huge.png"), oversized);
+    const attachments: AgentChatFileRef[] = [{ path: "huge.png", type: "image" }];
+
+    const result = await buildClaudeV2MessageAsync("Describe this", attachments, {
+      baseDir: tmpDir,
+      forceUserMessage: true,
+    });
+    const msg = result as SDKUserMessagePartial;
+    const blocks = msg.message.content as Array<Record<string, unknown>>;
+
+    expect(blocks.some((block) => block.type === "image")).toBe(false);
+    const hint = blocks.find((block) => block.type === "text" && String(block.text).includes("huge.png"));
+    expect(hint).toBeDefined();
+    expect(String(hint!.text)).toContain("not inlined");
+  });
+
+  it("still inlines an image exactly at the provider inline limit", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "exact.png"),
+      Buffer.alloc(MAX_PROVIDER_INLINE_IMAGE_BYTES, 0x42),
+    );
+    const attachments: AgentChatFileRef[] = [{ path: "exact.png", type: "image" }];
+
+    const result = await buildClaudeV2MessageAsync("Describe this", attachments, {
+      baseDir: tmpDir,
+      forceUserMessage: true,
+    });
+    const msg = result as SDKUserMessagePartial;
+    const blocks = msg.message.content as Array<Record<string, unknown>>;
+    expect(blocks.some((block) => block.type === "image")).toBe(true);
+  });
+
   // ─────────────────────────────────────────────────────────────────────────
   // 4. Missing image file -> text fallback
   // ─────────────────────────────────────────────────────────────────────────
diff --git a/apps/desktop/src/main/services/chat/buildClaudeV2Message.ts b/apps/desktop/src/main/services/chat/buildClaudeV2Message.ts
index 750b70fe07..50b2fb7ec1 100644
--- a/apps/desktop/src/main/services/chat/buildClaudeV2Message.ts
+++ b/apps/desktop/src/main/services/chat/buildClaudeV2Message.ts
@@ -9,6 +9,10 @@ import {
   readFileWithinRootSecure,
   type DirtyFileTextLookup,
 } from "../shared/utils";
+import {
+  exceedsProviderInlineLimit,
+  inlineAttachmentHintPart,
+} from "./attachmentInlineGuard";
 
 type ResolvedAgentChatFileRef = AgentChatFileRef & {
   _resolvedPath?: string;
@@ -129,6 +133,13 @@ export async function buildClaudeV2MessageAsync(
         resolvedPath,
         getDirtyFileTextForPath: options.getDirtyFileTextForPath,
       });
+      // Base64 inflates by a third and Anthropic rejects an oversized image
+      // request outright, so an attachment past the inline ceiling becomes the
+      // same path hint a non-image attachment gets. The turn still runs.
+      if (exceedsProviderInlineLimit(data.byteLength)) {
+        content.push(inlineAttachmentHintPart(attachment.path, data.byteLength));
+        continue;
+      }
       content.push({
         type: "image",
         source: { type: "base64", media_type: mediaType, data: data.toString("base64") },
diff --git a/apps/desktop/src/main/services/chat/chatAutoResumeCoordinator.test.ts b/apps/desktop/src/main/services/chat/chatAutoResumeCoordinator.test.ts
new file mode 100644
index 0000000000..1e0ebf5577
--- /dev/null
+++ b/apps/desktop/src/main/services/chat/chatAutoResumeCoordinator.test.ts
@@ -0,0 +1,179 @@
+import { describe, expect, it, vi } from "vitest";
+import { createChatAutoResumeCoordinator } from "./chatAutoResumeCoordinator";
+import type { ChatAutoResumeAnalyticsProperties } from "./chatAutoResumeCoordinator";
+import type { ChatScheduledWorkRecord } from "./chatScheduledWorkScheduler";
+
+/**
+ * The per-chat streak the coordinator keeps is invisible from the chat service:
+ * every user-driven dispatch clears it on its way to the provider, so only a
+ * scheduler-fired resume can advance it and only these direct calls can show
+ * that a record was dropped rather than merely reset.
+ */
+function createHarness() {
+  const rows = new Map<string, ChatScheduledWorkRecord>();
+  const notices: Array<{ sessionId: string; message: string }> = [];
+  const captures: ChatAutoResumeAnalyticsProperties[] = [];
+  const scheduler = {
+    list: (sessionId: string) =>
+      [...rows.values()].filter((row) => row.sessionId === sessionId),
+    upsert: async (input: Partial<ChatScheduledWorkRecord> & { id: string; sessionId: string }) => {
+      const row = {
+        ...(rows.get(input.id) ?? {}),
+        ...input,
+        createdAt: rows.get(input.id)?.createdAt ?? Date.now(),
+      } as ChatScheduledWorkRecord;
+      rows.set(row.id, row);
+      return row;
+    },
+    cancel: async (id: string) => {
+      const row = rows.get(id);
+      if (row) row.status = "cancelled";
+      return row ?? null;
+    },
+  };
+  const coordinator = createChatAutoResumeCoordinator({
+    getScheduler: () => scheduler as never,
+    whenSchedulerReady: () => Promise.resolve(),
+    isSessionSchedulable: () => true,
+    emitNotice: (sessionId, notice) => {
+      notices.push({ sessionId, message: notice.message });
+    },
+    captureAnalytics: (properties) => {
+      captures.push(properties);
+    },
+    logger: { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() } as never,
+  });
+
+  /** One usage-limit failure against an exact reset instant. */
+  const failAtResetInstant = async (sessionId: string, resetAtMs: number): Promise<void> => {
+    coordinator.maybeArmAfterUsageLimit({
+      sessionId,
+      provider: "codex",
+      resetAtMs,
+      error: { message: "You've hit your usage limit.", errorInfo: "usageLimitReached" },
+    });
+    // Arming is detached behind the scheduler wait; drain the microtasks it
+    // parks on rather than reaching into the coordinator's internals.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  };
+
+  /** One usage-limit failure whose reset instant is `minutes` out. */
+  const failAtUsageLimit = (sessionId: string, minutes: number): Promise<void> =>
+    failAtResetInstant(sessionId, Date.now() + minutes * 60_000);
+
+  return { coordinator, rows, notices, captures, failAtUsageLimit, failAtResetInstant };
+}
+
+describe("createChatAutoResumeCoordinator", () => {
+  it("auto-resume state is dropped when the session ends", async () => {
+    const { coordinator, notices, failAtUsageLimit } = createHarness();
+
+    // Two failed arms without an intervening dispatch caps the chat.
+    await failAtUsageLimit("chat-1", 30);
+    await failAtUsageLimit("chat-1", 90);
+    await failAtUsageLimit("chat-1", 150);
+    expect(notices.filter((notice) => notice.message.startsWith("Auto-resume paused")))
+      .toHaveLength(1);
+
+    // The chat is archived or deleted. Nothing about the old streak may survive
+    // it — including the record itself, which would otherwise be retained for
+    // the life of the process for a chat that no longer exists.
+    coordinator.forgetSession("chat-1");
+
+    notices.length = 0;
+    await failAtUsageLimit("chat-1", 210);
+    expect(notices.map((notice) => notice.message))
+      .toEqual([expect.stringContaining("Auto-resume scheduled for")]);
+  });
+});
+
+/**
+ * The workflow-outcome analytics. The product question is whether auto-resume
+ * rescues a limited chat, which is only answerable if `armed`, `resumed` and
+ * `paused` each count transitions rather than attempts — an event per retried
+ * arm or per repeated failure would inflate exactly the ratio being read.
+ */
+describe("auto-resume analytics", () => {
+  it("records one armed event per distinct arm and one paused event per capped streak", async () => {
+    const { captures, failAtUsageLimit, failAtResetInstant } = createHarness();
+    const reset = Date.now() + 30 * 60_000;
+
+    // One failure can commit two error events (the provider notification and
+    // the failed turn's completion) against the same reset instant. That is one
+    // arm, so it must be one event.
+    await failAtResetInstant("chat-1", reset);
+    await failAtResetInstant("chat-1", reset);
+    expect(captures).toEqual([{ action: "auto_resume", outcome: "armed", provider: "codex" }]);
+
+    // A second, genuinely different window re-arms; the third failure is the
+    // one the cap refuses, and it reports `paused` rather than a third `armed`.
+    await failAtUsageLimit("chat-1", 90);
+    await failAtUsageLimit("chat-1", 150);
+    await failAtUsageLimit("chat-1", 210);
+    expect(captures.map((capture) => capture.outcome)).toEqual([
+      "armed",
+      "armed",
+      "paused",
+    ]);
+  });
+
+  it("records one resumed event per fired resume, including after a restart", async () => {
+    const { coordinator, captures, failAtUsageLimit } = createHarness();
+
+    await failAtUsageLimit("chat-1", 30);
+    captures.length = 0;
+
+    coordinator.noteResumeTurnStarted("chat-1");
+    // The scheduler will not deliver a second wake into a live turn, but a
+    // repeated note about the same one must not double-count it either.
+    coordinator.noteResumeTurnStarted("chat-1");
+    expect(captures).toEqual([{ action: "auto_resume", outcome: "resumed", provider: "codex" }]);
+
+    // The armed row is durable and outlives the process that wrote it. A resume
+    // that fires with no in-memory record is still a rescue; dropping it would
+    // make `resumed` look rarer than `armed` purely because ADE restarted.
+    captures.length = 0;
+    coordinator.noteResumeTurnStarted("chat-never-seen");
+    expect(captures).toEqual([{ action: "auto_resume", outcome: "resumed" }]);
+  });
+
+  it("records nothing when ordinary user activity cancels the pending resume", async () => {
+    const { coordinator, captures, failAtUsageLimit } = createHarness();
+
+    await failAtUsageLimit("chat-1", 30);
+    captures.length = 0;
+
+    // `cancelForSession` runs on every user dispatch for every chat. Counting
+    // it would measure typing rather than the workflow, and armed-minus-resumed
+    // already answers the question it would.
+    coordinator.cancelForSession("chat-1", "user_message");
+    coordinator.noteScheduleDismissed("chat-1");
+    coordinator.noteTurnFinished("chat-1");
+    coordinator.forgetSession("chat-1");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(captures).toEqual([]);
+  });
+
+  it("keeps session ids, reset instants, and provider error text out of the payload", async () => {
+    const { coordinator, captures, failAtUsageLimit } = createHarness();
+
+    await failAtUsageLimit("chat-secret-id", 30);
+    coordinator.noteResumeTurnStarted("chat-secret-id");
+    await failAtUsageLimit("chat-secret-id", 90);
+    await failAtUsageLimit("chat-secret-id", 150);
+    await failAtUsageLimit("chat-secret-id", 210);
+    expect(captures.length).toBeGreaterThan(0);
+
+    for (const capture of captures) {
+      // A closed key set, not a bag: nothing that identifies the chat, the
+      // limit, or what the user was doing may ride along.
+      expect(Object.keys(capture).sort()).toEqual(
+        capture.provider ? ["action", "outcome", "provider"] : ["action", "outcome"],
+      );
+      const serialized = JSON.stringify(capture);
+      expect(serialized).not.toContain("chat-secret-id");
+      expect(serialized).not.toContain("usage limit");
+      expect(serialized).not.toMatch(/\d{5,}/);
+    }
+  });
+});
diff --git a/apps/desktop/src/main/services/chat/chatAutoResumeCoordinator.ts b/apps/desktop/src/main/services/chat/chatAutoResumeCoordinator.ts
new file mode 100644
index 0000000000..0c246f0473
--- /dev/null
+++ b/apps/desktop/src/main/services/chat/chatAutoResumeCoordinator.ts
@@ -0,0 +1,489 @@
+import {
+  AUTO_RESUME_PROMPT,
+  AUTO_RESUME_REASON,
+  AUTO_RESUME_SCHEDULED_WORK_SOURCE,
+  autoResumeFireAtMs,
+  autoResumeScheduleId,
+  autoResumeScheduledMessage,
+  isPendingAutoResumeScheduledWork,
+  isUsageLimitChatError,
+} from "../../../shared/chatAutoResume";
+import type { AgentChatEvent } from "../../../shared/types/chat";
+import type { Logger } from "../logging/logger";
+import type {
+  ChatScheduledWorkRecord,
+  ChatScheduledWorkScheduler,
+} from "./chatScheduledWorkScheduler";
+
+type AutoResumeNotice = Extract<AgentChatEvent, { type: "system_notice" }>;
+
+/**
+ * The subset of an `error` chat event this coordinator reads. Structural on
+ * purpose: the chat service owns `AgentChatEvent`, and taking the whole union
+ * here would drag its session types along for two fields.
+ */
+export type AutoResumeErrorInput = {
+  message?: string | null;
+  errorInfo?: string | { category?: string | null } | null;
+  turnId?: string | undefined;
+};
+
+/**
+ * The whole analytics payload this coordinator may produce, spelled out as a
+ * closed type rather than a property bag. The product question is only whether
+ * auto-resume rescues a limited chat, so `armed` (a resume was scheduled),
+ * `resumed` (an auto-resume-originated turn started) and `paused` (the re-arm
+ * cap stopped the loop) are the whole vocabulary — and nothing about the chat,
+ * the limit, or the reset instant can be added here without changing the type.
+ *
+ * `cancelled` is deliberately absent: a cancel fires on ordinary user activity,
+ * so counting it would measure typing rather than the workflow, and the number
+ * that matters (armed minus resumed) is already derivable.
+ */
+export type ChatAutoResumeAnalyticsProperties = {
+  action: "auto_resume";
+  outcome: "armed" | "resumed" | "paused";
+  /** Coarse provider slug only; the analytics sanitizer drops anything unlisted. */
+  provider?: string;
+};
+
+export type ChatAutoResumeCoordinatorDeps = {
+  /** Assigned late by the chat service, so it is read per call, not captured. */
+  getScheduler: () => ChatScheduledWorkScheduler | null;
+  /** Resolves once the scheduler has loaded its durable state. */
+  whenSchedulerReady: () => Promise<void>;
+  /** False for archived, ended, or non-schedulable chats. */
+  isSessionSchedulable: (sessionId: string) => boolean;
+  emitNotice: (sessionId: string, notice: AutoResumeNotice) => void;
+  /**
+   * Coarse workflow-outcome analytics. Injected for the same reason `logger` and
+   * `emitNotice` are: this file owns the transitions, not the transport, and it
+   * must not be able to reach the analytics service (or a session id) directly.
+   * Optional, so a wiring without analytics keeps auto-resume working.
+   */
+  captureAnalytics?: (properties: ChatAutoResumeAnalyticsProperties) => void;
+  logger: Logger;
+};
+
+export type ChatAutoResumeCoordinator = {
+  maybeArmAfterUsageLimit: (args: {
+    sessionId: string;
+    provider: string;
+    /** Reset instant the provider published, or null when it publishes none. */
+    resetAtMs: number | null;
+    error: AutoResumeErrorInput;
+  }) => void;
+  cancelForSession: (sessionId: string, reason: string) => void;
+  noteScheduleDismissed: (sessionId: string) => void;
+  noteResumeTurnStarted: (sessionId: string) => void;
+  noteTurnFinished: (sessionId: string) => void;
+  forgetSession: (sessionId: string) => void;
+  forgetAll: () => void;
+};
+
+/**
+ * Per-session auto-resume bookkeeping.
+ *
+ * `cancelEpoch` closes the arm/cancel race. Arming is asynchronous — it waits
+ * on the scheduler and then upserts — so a user message can land while the
+ * upsert is still in flight and find nothing to cancel, and a cancel issued
+ * while the brain is still loading its durable state finds nothing either
+ * even though a row exists on disk. Every cancel bumps the epoch; the arm
+ * captures it before scheduling and undoes its own row if it moved.
+ *
+ * `consecutiveArms` bounds re-arming. The reset instant we can see is not
+ * always the limit that rejected the turn: Claude's snapshot is session (5h)
+ * scoped and `mergeSnapshot` carries a stale `resetsAtMs` forward, so a
+ * weekly-limit rejection can arm against a session reset, fail at the same
+ * limit when it fires, and re-arm every cycle — burning a real turn each
+ * time. Two attempts, then the chat waits for a human.
+ *
+ * A record exists only for a chat that actually hit a usage limit. Cancel and
+ * dismissal read the map and never create: they run on every dispatch for every
+ * chat, so minting there would grow the map for the life of the process with
+ * nothing in it to cancel. Nothing is lost by it either — an arm creates its
+ * record synchronously before its first await, so "no record" means "no arm in
+ * flight", which is exactly the case a cancel has nothing to outrank.
+ */
+type AutoResumeSessionState = {
+  cancelEpoch: number;
+  consecutiveArms: number;
+  /** An arm is between the scheduler wait and its upsert. */
+  arming: boolean;
+  /** Notice de-dupe: one "auto-resume scheduled" line per armed fire time. */
+  noticeFireAt: number | null;
+  /**
+   * Reset instant the streak last counted. Separate from `noticeFireAt`
+   * because dismissing the schedule has to let a later limit re-announce
+   * without also re-opening the counting window against the same instant.
+   */
+  lastArmedFireAt: number | null;
+  /** One "auto-resume paused" line per capped streak, not one per failure. */
+  pauseNoticed: boolean;
+  /** A fired resume dispatched a turn that has not reported `done` yet. */
+  resumeTurnPending: boolean;
+  /** That turn died at the limit again, so its completion proves nothing. */
+  resumeTurnHitLimit: boolean;
+  /**
+   * Coarse provider slug of the limit that armed this streak, kept only so the
+   * fired resume's analytics carries the same one the arm did — the resume
+   * dispatch reaches this file with no provider in hand.
+   */
+  provider: string | null;
+};
+
+/** Consecutive arms allowed with no intervening user message. */
+const AUTO_RESUME_MAX_CONSECUTIVE_ARMS = 2;
+
+const PAUSED_NOTICE_DETAIL =
+  "The usage limit stopped this chat again after two automatic resumes, so ADE will not schedule another one. Send a message when you want to continue.";
+const SCHEDULED_NOTICE_DETAIL =
+  "ADE will ask this chat to continue the interrupted task once the usage limit resets. Sending a message or retrying the turn cancels it.";
+
+/**
+ * Auto-resume after a provider usage limit resets.
+ *
+ * Owns the whole subsystem: the per-chat streak state, the durable row, the two
+ * system notices, and the races between arming, cancelling and firing. The chat
+ * service keeps only thin call sites — it reports what happened (a limit error,
+ * a dispatch, a dismissal, a turn finishing) and this decides what that means.
+ */
+export function createChatAutoResumeCoordinator(
+  deps: ChatAutoResumeCoordinatorDeps,
+): ChatAutoResumeCoordinator {
+  const { getScheduler, whenSchedulerReady, isSessionSchedulable, emitNotice, logger } = deps;
+  const stateBySession = new Map<string, AutoResumeSessionState>();
+
+  const ensureState = (sessionId: string): AutoResumeSessionState => {
+    const existing = stateBySession.get(sessionId);
+    if (existing) return existing;
+    const created: AutoResumeSessionState = {
+      cancelEpoch: 0,
+      consecutiveArms: 0,
+      arming: false,
+      noticeFireAt: null,
+      lastArmedFireAt: null,
+      pauseNoticed: false,
+      resumeTurnPending: false,
+      resumeTurnHitLimit: false,
+      provider: null,
+    };
+    stateBySession.set(sessionId, created);
+    return created;
+  };
+
+  /**
+   * One coarse fact per auto-resume transition. Every call site is a state
+   * change that already happened, never an attempt, so a retried arm or a
+   * repeated report cannot turn one workflow into a burst.
+   */
+  const captureOutcome = (
+    outcome: ChatAutoResumeAnalyticsProperties["outcome"],
+    provider: string | null,
+  ): void => {
+    deps.captureAnalytics?.({
+      action: "auto_resume",
+      outcome,
+      ...(provider ? { provider } : {}),
+    });
+  };
+
+  const findPendingRow = (sessionId: string): ChatScheduledWorkRecord | null =>
+    getScheduler()?.list(sessionId).find(isPendingAutoResumeScheduledWork) ?? null;
+
+  const cancelPendingRow = async (sessionId: string, reason: string): Promise<void> => {
+    const scheduler = getScheduler();
+    if (!scheduler) return;
+    const pending = findPendingRow(sessionId);
+    if (!pending) return;
+    try {
+      await scheduler.cancel(pending.id);
+      logger.info("agent_chat.auto_resume_cancelled", {
+        sessionId,
+        scheduleId: pending.id,
+        reason,
+      });
+    } catch (error) {
+      logger.warn("agent_chat.auto_resume_cancel_failed", {
+        sessionId,
+        scheduleId: pending.id,
+        reason,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  };
+
+  /**
+   * The one auto-resume notice envelope. Both lines — armed and paused — are
+   * rate-limit notices attributed to the turn that failed, so the card renders
+   * them in the same place with the same weight.
+   */
+  const emitAutoResumeNotice = (
+    sessionId: string,
+    notice: { message: string; detail: string; turnId?: string | undefined },
+  ): void => {
+    emitNotice(sessionId, {
+      type: "system_notice",
+      noticeKind: "rate_limit",
+      severity: "info",
+      message: notice.message,
+      detail: notice.detail,
+      ...(notice.turnId ? { turnId: notice.turnId } : {}),
+    });
+  };
+
+  /**
+   * Cancels ADE's own auto-resume row and nothing else. Engaging with a chat is
+   * not a reason to drop a cron or wakeup the user (or the agent) asked for, so
+   * the sweep is scoped by the `auto_resume_limit` tag.
+   *
+   * Synchronous at the call site by design — it runs inside the dispatch choke
+   * points — but the sweep itself has to wait for the scheduler, and the row may
+   * not exist yet at all. Bumping the epoch first is what makes both cases safe:
+   * an arm that lands afterwards cancels the row it just created.
+   */
+  const cancelForSession = (sessionId: string, reason: string): void => {
+    const state = stateBySession.get(sessionId);
+    if (state) {
+      state.cancelEpoch += 1;
+      state.noticeFireAt = null;
+      state.lastArmedFireAt = null;
+      // A user message is exactly the intervening event the re-arm cap waits for.
+      state.consecutiveArms = 0;
+      state.pauseNoticed = false;
+      state.resumeTurnPending = false;
+      state.resumeTurnHitLimit = false;
+    }
+    // The sweep runs whether or not this process has state for the chat: a row
+    // armed before the last restart is on disk with nothing in the map yet.
+    void (async () => {
+      try {
+        await whenSchedulerReady();
+        await cancelPendingRow(sessionId, reason);
+      } catch (error) {
+        logger.warn("agent_chat.auto_resume_cancel_failed", {
+          sessionId,
+          reason,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    })();
+  };
+
+  /**
+   * The user dismissed the schedule from Chat info. The scheduler cancels the
+   * row itself; this is the in-memory half.
+   */
+  const noteScheduleDismissed = (sessionId: string): void => {
+    const state = stateBySession.get(sessionId);
+    // No record is not a gap, so do not "fix" this by minting one: an arm
+    // creates its record synchronously before its first await, so a dismissal
+    // that finds nothing has no in-flight arm to outrank, and any arm after it
+    // is answering a new limit and should be allowed to schedule.
+    if (!state) return;
+    // An explicit dismissal outranks an arm that is still in flight: the epoch
+    // bump is what makes that arm undo the row it is about to write, because the
+    // upsert's own `scheduled` status would otherwise win over the dismissal and
+    // resurrect the row the user just cancelled.
+    state.cancelEpoch += 1;
+    // Let a later limit announce a fresh resume. The counting window
+    // (`lastArmedFireAt`) deliberately survives — dismissing a schedule is not
+    // evidence that the reset instant it armed against was right.
+    state.noticeFireAt = null;
+  };
+
+  /**
+   * A fired resume's turn, watched to completion.
+   *
+   * The cap counts arms that were never proven right. A resume that runs
+   * without dying at the limit again proves the window we armed against was
+   * the one gating the chat, so the streak starts over. Nothing else can do
+   * this: a fired resume always carries `scheduledWake`, which is exactly what
+   * the dispatch sweep skips, so without this the cap is a lifetime budget and
+   * a healthy headless chat pauses itself after two limits days apart.
+   *
+   * Tracked as one flag per session rather than by turn id: the dispatched
+   * `user_message` does not carry a turn id on every provider (Codex assigns it
+   * only once the provider answers), and the scheduler will not deliver a wake
+   * into a live turn, so the next `done` on this chat is the resume's own.
+   */
+  const noteResumeTurnStarted = (sessionId: string): void => {
+    const state = stateBySession.get(sessionId);
+    // Reported BEFORE the state guard, not after. The armed row is durable and
+    // outlives this process, so a resume armed yesterday fires today with
+    // nothing in the map — and dropping those would make `resumed` look rarer
+    // than `armed` purely because ADE restarted, which is the one bias this
+    // measurement cannot carry. Only the not-pending -> pending edge reports,
+    // so a repeated note about the same live resume cannot double-count it.
+    if (!state?.resumeTurnPending) captureOutcome("resumed", state?.provider ?? null);
+    if (!state) return;
+    state.resumeTurnPending = true;
+    state.resumeTurnHitLimit = false;
+  };
+
+  const noteTurnFinished = (sessionId: string): void => {
+    const state = stateBySession.get(sessionId);
+    if (!state || !state.resumeTurnPending) return;
+    state.resumeTurnPending = false;
+    if (state.resumeTurnHitLimit) {
+      state.resumeTurnHitLimit = false;
+      return;
+    }
+    state.consecutiveArms = 0;
+    state.pauseNoticed = false;
+    state.lastArmedFireAt = null;
+    state.noticeFireAt = null;
+  };
+
+  /**
+   * Arms one durable resume per chat when a turn dies at a usage limit AND the
+   * provider told us when the limit lifts. The row uses a deterministic id, so
+   * a repeat failure replaces the pending resume instead of stacking a second
+   * one. Delivery itself is ordinary scheduled work: if a turn is active when
+   * it comes due, the scheduler defers to the next turn boundary rather than
+   * pushing a second prompt into a live turn.
+   */
+  const maybeArmAfterUsageLimit = (args: {
+    sessionId: string;
+    provider: string;
+    resetAtMs: number | null;
+    error: AutoResumeErrorInput;
+  }): void => {
+    if (!isUsageLimitChatError(args.error)) return;
+    const { sessionId } = args;
+    const turnId = args.error.turnId;
+    const tracked = stateBySession.get(sessionId);
+    // Recorded before the reset instant is even consulted: a repeat limit with
+    // no publishable reset still means the resume we spent was wasted.
+    if (tracked?.resumeTurnPending) {
+      tracked.resumeTurnHitLimit = true;
+    }
+    const fireAt = autoResumeFireAtMs(args.resetAtMs, Date.now());
+    // No reset instant (or one already in the past): keep the manual recovery
+    // card as the only path, exactly as before.
+    if (fireAt == null) return;
+    if (!isSessionSchedulable(sessionId)) return;
+    if (tracked?.arming) return;
+    const state = tracked ?? ensureState(sessionId);
+    // Remembered only for the fired resume's analytics; see the field's note.
+    state.provider = args.provider;
+    if (state.consecutiveArms >= AUTO_RESUME_MAX_CONSECUTIVE_ARMS) {
+      // Two resumes have already fired straight back into the same limit, so
+      // the reset instant this provider publishes is not the one gating this
+      // chat. Stop spending a turn per cycle and hand it back to the user.
+      if (!state.pauseNoticed) {
+        state.pauseNoticed = true;
+        // Guarded by the same flag as the notice, so a chat that keeps failing
+        // at the limit reports the pause once per streak rather than once per
+        // failure.
+        captureOutcome("paused", args.provider);
+        // Detached on purpose, like the scheduled notice below. This runs from
+        // inside the chat service's event commit, before the error event that
+        // triggered it has minted its sequence number, so emitting inline
+        // numbers the notice BELOW the error and renders it above the failure
+        // it explains. Deferring by one microtask is sufficient and no more:
+        // the commit mints the sequence synchronously in that same frame.
+        // Anything awaited between here and that mint would break the ordering
+        // again, which is what the transcript-order assertion in the cap
+        // regression test pins.
+        void (async () => {
+          try {
+            await Promise.resolve();
+            emitAutoResumeNotice(sessionId, {
+              message: "Auto-resume paused after two attempts",
+              detail: PAUSED_NOTICE_DETAIL,
+              turnId,
+            });
+          } catch (error) {
+            logger.warn("agent_chat.auto_resume_notice_failed", {
+              sessionId,
+              error: error instanceof Error ? error.message : String(error),
+            });
+          }
+        })();
+      }
+      return;
+    }
+    state.arming = true;
+    const armedAtEpoch = state.cancelEpoch;
+
+    void (async () => {
+      try {
+        await whenSchedulerReady();
+        const scheduler = getScheduler();
+        if (!scheduler) return;
+        const schedule = await scheduler.upsert({
+          id: autoResumeScheduleId(sessionId),
+          sessionId,
+          kind: "wakeup",
+          prompt: AUTO_RESUME_PROMPT,
+          reason: AUTO_RESUME_REASON,
+          fireAt,
+          status: "scheduled",
+          pausedFlag: false,
+          lateFlag: false,
+          durable: true,
+          source: AUTO_RESUME_SCHEDULED_WORK_SOURCE,
+        });
+        if (schedule.status === "cancelled" || schedule.status === "done") return;
+        // A cancel landed while the upsert was in flight (a user message, or a
+        // sweep that ran while the scheduler was still loading its durable
+        // state). The row it was looking for only exists now, so undo it here.
+        if (stateBySession.get(sessionId) !== state || state.cancelEpoch !== armedAtEpoch) {
+          await cancelPendingRow(sessionId, "cancelled_while_arming");
+          return;
+        }
+        // One failure can commit more than one error event — a provider `error`
+        // notification and the failed turn's completion carry the same limit —
+        // so the cap counts distinct reset instants, not raw arms. A genuinely
+        // wrong-window re-arm always brings a fresh reset instant with it,
+        // because a repeat of the same one is already in the past by then and
+        // never gets this far.
+        if (state.lastArmedFireAt !== fireAt) {
+          state.consecutiveArms += 1;
+          state.lastArmedFireAt = fireAt;
+          // Bound by construction: this is the same gate the cap counts, so a
+          // streak reports at most `AUTO_RESUME_MAX_CONSECUTIVE_ARMS` arms, and
+          // the duplicate error events one failure can commit collapse into one.
+          captureOutcome("armed", args.provider);
+        }
+        logger.info("agent_chat.auto_resume_scheduled", {
+          sessionId,
+          scheduleId: schedule.id,
+          provider: args.provider,
+          fireAt: new Date(fireAt).toISOString(),
+          status: schedule.status,
+          consecutiveArms: state.consecutiveArms,
+        });
+        if (state.noticeFireAt === fireAt) return;
+        state.noticeFireAt = fireAt;
+        emitAutoResumeNotice(sessionId, {
+          message: autoResumeScheduledMessage(fireAt),
+          detail: SCHEDULED_NOTICE_DETAIL,
+          turnId,
+        });
+      } catch (error) {
+        logger.warn("agent_chat.auto_resume_schedule_failed", {
+          sessionId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      } finally {
+        state.arming = false;
+      }
+    })();
+  };
+
+  return {
+    maybeArmAfterUsageLimit,
+    cancelForSession,
+    noteScheduleDismissed,
+    noteResumeTurnStarted,
+    noteTurnFinished,
+    forgetSession: (sessionId: string): void => {
+      stateBySession.delete(sessionId);
+    },
+    forgetAll: (): void => {
+      stateBySession.clear();
+    },
+  };
+}
diff --git a/apps/desktop/src/main/services/chat/chatScheduledWorkScheduler.ts b/apps/desktop/src/main/services/chat/chatScheduledWorkScheduler.ts
index d4f494afae..a8033eb53c 100644
--- a/apps/desktop/src/main/services/chat/chatScheduledWorkScheduler.ts
+++ b/apps/desktop/src/main/services/chat/chatScheduledWorkScheduler.ts
@@ -1,4 +1,5 @@
 import { nextCronFireAt as nextChatScheduledCronFireAt } from "../../../shared/chatScheduledWork";
+import { AUTO_RESUME_SCHEDULED_WORK_SOURCE } from "../../../shared/chatAutoResume";
 
 export { nextChatScheduledCronFireAt };
 
@@ -12,6 +13,12 @@ export { nextChatScheduledCronFireAt };
 
 export type ChatScheduledWorkKind = "wakeup" | "cron" | "loop";
 
+/**
+ * Provenance tag for rows ADE created on the user's behalf. Untagged rows are
+ * user- or agent-created and must never be swept by ADE's own housekeeping.
+ */
+export type ChatScheduledWorkSource = typeof AUTO_RESUME_SCHEDULED_WORK_SOURCE;
+
 export type ChatScheduledWorkStatus =
   | "scheduled"
   | "paused"
@@ -40,6 +47,8 @@ export type ChatScheduledWorkRecord = {
   provider?: "claude";
   providerSessionId?: string;
   providerScheduleId?: string;
+  /** Set only on rows ADE created itself (see `ChatScheduledWorkSource`). */
+  source?: ChatScheduledWorkSource;
 };
 
 export type ChatScheduledWorkState = {
@@ -177,6 +186,9 @@ function normalizeSchedule(value: unknown): ChatScheduledWorkRecord | null {
     ...(typeof record.providerScheduleId === "string"
       ? { providerScheduleId: record.providerScheduleId }
       : {}),
+    ...(record.source === AUTO_RESUME_SCHEDULED_WORK_SOURCE
+      ? { source: AUTO_RESUME_SCHEDULED_WORK_SOURCE }
+      : {}),
   };
 }
 
diff --git a/apps/desktop/src/main/services/chat/heicAttachmentConverter.ts b/apps/desktop/src/main/services/chat/heicAttachmentConverter.ts
index 29b783205e..c97756926e 100644
--- a/apps/desktop/src/main/services/chat/heicAttachmentConverter.ts
+++ b/apps/desktop/src/main/services/chat/heicAttachmentConverter.ts
@@ -7,9 +7,15 @@ import {
   isHeicAttachment,
   type HeicConversionErrorCode,
 } from "../../../shared/types/chat";
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  legacyAttachmentCapMessage,
+} from "../../../shared/chatAttachmentLimits";
 
 const execFileAsync = promisify(execFile);
-const MAX_HEIC_BYTES = 10 * 1024 * 1024;
+// A HEIC arrives as base64 in a command payload and is decoded in memory, so it
+// carries the legacy ceiling rather than the 50 MB file one.
+const MAX_HEIC_BYTES = LEGACY_MAX_CHAT_ATTACHMENT_BYTES;
 const SIPS_TIMEOUT_MS = 30_000;
 
 type RunSips = (inputPath: string, outputPath: string) => Promise<void>;
@@ -94,7 +100,7 @@ export async function convertHeicBufferToJpeg(
     throw new HeicAttachmentConversionError("unavailable");
   }
   if (content.byteLength > MAX_HEIC_BYTES) {
-    throw new Error("Temporary attachments must be 10 MB or smaller.");
+    throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
   }
 
   const tempDir = await fs.promises.mkdtemp(
diff --git a/apps/desktop/src/main/services/chat/workerAttachmentImages.ts b/apps/desktop/src/main/services/chat/workerAttachmentImages.ts
index 3dfa5af8f8..74cd0c7792 100644
--- a/apps/desktop/src/main/services/chat/workerAttachmentImages.ts
+++ b/apps/desktop/src/main/services/chat/workerAttachmentImages.ts
@@ -1,9 +1,17 @@
 import path from "node:path";
 import { getImageAttachmentMediaType } from "../../../shared/types/chat";
+import { MAX_PROVIDER_INLINE_IMAGE_BYTES } from "../../../shared/chatAttachmentLimits";
 import { readFileWithinRootSecure } from "../shared/utils";
 
-/** Match the composer temp-attachment cap so IPC and disk agree. */
-export const WORKER_MAX_IMAGE_FILE_BYTES = 10 * 1024 * 1024;
+/**
+ * Ceiling for an image the worker materializes into base64 for its provider.
+ *
+ * Deliberately the provider inline limit and NOT the composer attachment cap —
+ * those diverged when attachments were raised to 50 MB. A worker image is
+ * inlined into the model request, so it keeps the smaller number; the composer
+ * cap governs what may sit on disk, which is a different question.
+ */
+const WORKER_MAX_IMAGE_FILE_BYTES = MAX_PROVIDER_INLINE_IMAGE_BYTES;
 
 export type WorkerPathImageSource = {
   path: string;
diff --git a/apps/desktop/src/main/services/ipc/ipcTimeouts.ts b/apps/desktop/src/main/services/ipc/ipcTimeouts.ts
index 45d3c8bf43..ed98d9e711 100644
--- a/apps/desktop/src/main/services/ipc/ipcTimeouts.ts
+++ b/apps/desktop/src/main/services/ipc/ipcTimeouts.ts
@@ -183,6 +183,13 @@ export function ipcInvokeTimeoutMs(channel: string, args: readonly unknown[] = [
       return IOS_SIMULATOR_LAUNCH_TIMEOUT_MS;
     case IPC.transcriptionTranscribe:
       return 6 * 60_000;
+    // Streams up to 50 MB to a paired host over HTTP. The upload client's own
+    // budget is 5 minutes, so on the 30s default the renderer reported a
+    // failure — and dropped the pending attachment chip — for an upload that
+    // was still in flight. This has to sit above the client's budget so the
+    // legible reason wins.
+    case IPC.remoteRuntimeUploadChatAttachment:
+      return 6 * 60_000;
     // Preview Lab compiles the target before it can render a frame, so these
     // three carry the same 10 minute budget the local runtime map gives them.
     // The remote-runtime path reads its IPC budget from these same cases via
diff --git a/apps/desktop/src/main/services/ipc/registerIpc.ts b/apps/desktop/src/main/services/ipc/registerIpc.ts
index 8a455b8b3c..9e0909e046 100644
--- a/apps/desktop/src/main/services/ipc/registerIpc.ts
+++ b/apps/desktop/src/main/services/ipc/registerIpc.ts
@@ -5,6 +5,15 @@ import {
   type createAutoUpdateService,
 } from "../updates/autoUpdateService";
 import { DEFAULT_AUTO_UPDATE_PREFERENCES, EMPTY_AGENT_TOOLS_CACHE_SNAPSHOT } from "../../../shared/types";
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  legacyAttachmentCapMessage,
+} from "../../../shared/chatAttachmentLimits";
+import {
+  projectAttachmentsDir,
+  stageAttachmentBytes,
+  stageAttachmentCopy,
+} from "../../../shared/chatAttachmentStagingFs";
 import { INERT_KEEP_AWAKE_SNAPSHOT } from "../../../shared/types/keepAwake";
 import type {
   KeepAwakeFixResult,
@@ -481,6 +490,7 @@ import type {
   AgentChatContextUsageArgs,
   AgentChatRewindFilesArgs,
   AgentChatRewindFilesResult,
+  AgentChatCopyTempAttachmentArgs,
   AgentChatFileSearchArgs,
   AgentChatFileSearchResult,
   AgentChatGetTurnFileDiffArgs,
@@ -3685,8 +3695,10 @@ export function registerIpc({
     return null;
   };
 
-  const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
-  const MAX_TEMP_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+  // Both of these are the base64/in-memory ceiling, single-sourced from
+  // `chatAttachmentLimits` so the constant and the message can never drift.
+  const MAX_IMAGE_BYTES = LEGACY_MAX_CHAT_ATTACHMENT_BYTES;
+  const MAX_TEMP_ATTACHMENT_BYTES = LEGACY_MAX_CHAT_ATTACHMENT_BYTES;
 
   /**
    * Read an allow-listed image file from disk after a stat-based size check,
@@ -3700,7 +3712,7 @@ export function registerIpc({
       throw new Error("Path is not a file.");
     }
     if (stat.size > MAX_IMAGE_BYTES) {
-      throw new Error("Image must be 10 MB or smaller.");
+      throw new Error(legacyAttachmentCapMessage("Image"));
     }
     const data = await fs.promises.readFile(filePath);
     const mimeType = sniffImageMimeType(data);
@@ -3710,26 +3722,52 @@ export function registerIpc({
     return { data, mimeType };
   };
 
+  /**
+   * The directory a staged chat attachment lands in. Inside the project's
+   * `.ade` so CLI subprocesses (and the Files viewer) can reach it; system temp
+   * when no project is open.
+   */
+  const agentChatTempAttachmentDir = (): string => {
+    const ctx = getCtx();
+    return ctx.project?.rootPath
+      ? projectAttachmentsDir(ctx.project.rootPath)
+      : path.join(app.getPath("temp"), "ade-attachments");
+  };
+
   const saveAgentChatTempAttachmentBuffer = async (
     content: Buffer,
     filename: string,
   ): Promise<{ path: string }> => {
     if (content.byteLength > MAX_TEMP_ATTACHMENT_BYTES) {
-      throw new Error("Temporary attachments must be 10 MB or smaller.");
+      throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
     }
-    const ctx = getCtx();
-    // Save within the project's .ade directory so CLI subprocesses have
-    // filesystem access. Fall back to system temp if no project is open.
-    const baseDir = ctx.project?.rootPath
-      ? path.join(ctx.project.rootPath, ".ade", "attachments")
-      : path.join(app.getPath("temp"), "ade-attachments");
-    await fs.promises.mkdir(baseDir, { recursive: true });
-    const ext = path.extname(filename) || ".png";
-    const destPath = path.join(baseDir, `${randomUUID()}${ext}`);
-    await fs.promises.writeFile(destPath, content);
-    return { path: destPath };
+    return await stageAttachmentBytes({
+      content,
+      filename,
+      attachmentsDir: agentChatTempAttachmentDir(),
+    });
   };
 
+  /**
+   * Stage a file that already exists on this machine's disk by copying it,
+   * never by round-tripping its bytes through base64 and IPC. Drag-drop and the
+   * file picker both hand the renderer a real path via `webUtils`, so the only
+   * thing that has to cross the boundary is the path itself — which is why this
+   * path carries the 50 MB product cap while the base64 handler keeps 10 MB.
+   *
+   * The rule itself lives in `shared/chatAttachmentStagingFs` so this handler,
+   * the ADE action registry's `chat.copyTempAttachment`, and the sync host's
+   * upload route all name the destination the same way.
+   */
+  const copyAgentChatTempAttachmentFile = async (
+    sourcePath: string,
+    filename: string,
+  ): Promise<{ path: string }> => await stageAttachmentCopy({
+    sourcePath,
+    filename,
+    attachmentsDir: agentChatTempAttachmentDir(),
+  });
+
   ipcMain.handle(IPC.appRevealPath, async (_event, arg: { path: string }): Promise<void> => {
     const raw = typeof arg?.path === "string" ? arg.path.trim() : "";
     if (!raw) return;
@@ -3802,7 +3840,7 @@ export function registerIpc({
     const png = image.toPNG();
     if (!png.byteLength) return null;
     if (png.byteLength > MAX_TEMP_ATTACHMENT_BYTES) {
-      throw new Error("Clipboard image must be 10 MB or smaller.");
+      throw new Error(legacyAttachmentCapMessage("Clipboard image"));
     }
     return {
       data: png.toString("base64"),
@@ -3826,11 +3864,11 @@ export function registerIpc({
         : "photo.heic";
       const maxEncodedLength = Math.ceil(MAX_TEMP_ATTACHMENT_BYTES / 3) * 4;
       if (arg.data.length > maxEncodedLength) {
-        throw new Error("Temporary attachments must be 10 MB or smaller.");
+        throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
       }
       const content = Buffer.from(arg.data, "base64");
       if (content.byteLength > MAX_TEMP_ATTACHMENT_BYTES) {
-        throw new Error("Temporary attachments must be 10 MB or smaller.");
+        throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
       }
       try {
         const converted = await convertHeicBufferToJpeg(
@@ -3860,7 +3898,7 @@ export function registerIpc({
     const png = image.toPNG();
     if (!png.byteLength) return null;
     if (png.byteLength > MAX_TEMP_ATTACHMENT_BYTES) {
-      throw new Error("Clipboard image must be 10 MB or smaller.");
+      throw new Error(legacyAttachmentCapMessage("Clipboard image"));
     }
     const saved = await saveAgentChatTempAttachmentBuffer(png, "clipboard.png");
     const previewImage = image.resize({ width: 96, height: 96, quality: "best" });
@@ -8232,12 +8270,18 @@ export function registerIpc({
   ipcMain.handle(IPC.agentChatSaveTempAttachment, async (_event, arg: { data: string; filename: string }): Promise<{ path: string }> => {
     const maxEncodedLength = Math.ceil(MAX_TEMP_ATTACHMENT_BYTES / 3) * 4;
     if (typeof arg.data === "string" && arg.data.length > maxEncodedLength) {
-      throw new Error("Temporary attachments must be 10 MB or smaller.");
+      throw new Error(legacyAttachmentCapMessage("Temporary attachments"));
     }
     const content = Buffer.from(arg.data, "base64");
     return saveAgentChatTempAttachmentBuffer(content, arg.filename);
   });
 
+  ipcMain.handle(
+    IPC.agentChatCopyTempAttachment,
+    async (_event, arg: AgentChatCopyTempAttachmentArgs): Promise<{ path: string }> =>
+      copyAgentChatTempAttachmentFile(arg?.sourcePath ?? "", arg?.filename ?? ""),
+  );
+
   ipcMain.handle(IPC.agentChatGetTurnFileDiff, async (_event, arg: AgentChatGetTurnFileDiffArgs) => {
     const ctx = getCtx();
     const cwd = ctx.project?.rootPath;
diff --git a/apps/desktop/src/main/services/ipc/runtimeBridge.ts b/apps/desktop/src/main/services/ipc/runtimeBridge.ts
index 33428335ee..edf7273832 100644
--- a/apps/desktop/src/main/services/ipc/runtimeBridge.ts
+++ b/apps/desktop/src/main/services/ipc/runtimeBridge.ts
@@ -48,6 +48,8 @@ import type {
   RuntimeEventsReleaseResult,
   SyncWebPairingInfo,
 } from "../../../shared/types";
+import type { ChatAttachmentStagingMode } from "../../../shared/types/chat";
+import { LEGACY_MAX_CHAT_ATTACHMENT_BYTES } from "../../../shared/chatAttachmentLimits";
 import type { LocalRuntimeConnectionPool } from "../localRuntime/localRuntimeConnectionPool";
 import { matchRemoteProjectByRootPath } from "../attention/remoteProjectIdentity";
 import { RemoteConnectionPool } from "../remoteRuntime/remoteConnectionPool";
@@ -1112,6 +1114,47 @@ export function registerRuntimeBridge({
     },
   );
 
+  ipcMain.handle(
+    IPC.remoteRuntimeAttachmentUploadCapability,
+    async (
+      _event,
+      arg: { id: string },
+    ): Promise<ChatAttachmentStagingMode> => {
+      const id = typeof arg?.id === "string" ? arg.id.trim() : "";
+      // No target named: nothing can be probed, so answer with the mode every
+      // host supports rather than inventing a second "unknown" vocabulary.
+      if (!id) return { mode: "base64", maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES };
+      return await remoteConnectionService.getAttachmentUploadCapability(id);
+    },
+  );
+
+  ipcMain.handle(
+    IPC.remoteRuntimeUploadChatAttachment,
+    async (
+      _event,
+      arg: {
+        id: string;
+        projectId: string;
+        sourcePath: string;
+        filename: string;
+      },
+    ): Promise<{ path: string }> => {
+      const id = typeof arg?.id === "string" ? arg.id.trim() : "";
+      const projectId = typeof arg?.projectId === "string" ? arg.projectId.trim() : "";
+      const sourcePath = typeof arg?.sourcePath === "string" ? arg.sourcePath.trim() : "";
+      const filename = typeof arg?.filename === "string" ? arg.filename.trim() : "";
+      if (!id) throw new Error("Remote target id is required.");
+      if (!projectId) throw new Error("Remote project is required.");
+      if (!sourcePath) throw new Error("Attachment source path is required.");
+      return await remoteConnectionService.uploadChatAttachment({
+        targetId: id,
+        projectId,
+        sourcePath,
+        filename,
+      });
+    },
+  );
+
   ipcMain.handle(
     IPC.remoteRuntimeEnsurePortForward,
     async (
diff --git a/apps/desktop/src/main/services/remoteRuntime/attachmentUploadClient.test.ts b/apps/desktop/src/main/services/remoteRuntime/attachmentUploadClient.test.ts
new file mode 100644
index 0000000000..9eb3586f49
--- /dev/null
+++ b/apps/desktop/src/main/services/remoteRuntime/attachmentUploadClient.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+
+import { parseRemoteAttachmentUploadTicket } from "./attachmentUploadClient";
+
+/**
+ * The ticket arrives over the sync socket as untyped JSON from another machine,
+ * and it is the only thing that names the route this process is about to POST a
+ * file to. Everything it accepts has to be checked here, because nothing
+ * downstream re-checks it.
+ */
+describe("parseRemoteAttachmentUploadTicket", () => {
+  const valid = {
+    ticket: "tkt-abc",
+    path: "/remote-attachment-upload/tkt-abc",
+    maxBytes: 50 * 1024 * 1024,
+    expiresAtMs: 1_787_000_000_000,
+  };
+
+  it("accepts a well-formed ticket and normalises it", () => {
+    expect(parseRemoteAttachmentUploadTicket(valid)).toEqual(valid);
+  });
+
+  it("trims surrounding whitespace on the ticket and the route path", () => {
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, ticket: "  tkt-abc  ", path: " /up " }))
+      .toEqual({ ...valid, ticket: "tkt-abc", path: "/up" });
+  });
+
+  it("floors a fractional byte cap rather than carrying it into a size check", () => {
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, maxBytes: 1024.9 })?.maxBytes)
+      .toBe(1024);
+  });
+
+  it("accepts a numeric string cap, which is how JSON transports large ints", () => {
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, maxBytes: "2048" })?.maxBytes)
+      .toBe(2048);
+  });
+
+  it("defaults an unusable expiry to 0 rather than NaN", () => {
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, expiresAtMs: "soon" })?.expiresAtMs)
+      .toBe(0);
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, expiresAtMs: undefined })?.expiresAtMs)
+      .toBe(0);
+  });
+
+  it("rejects a missing or blank ticket", () => {
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, ticket: "" })).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, ticket: "   " })).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, ticket: 42 })).toBeNull();
+  });
+
+  it("rejects a route path that is not rooted", () => {
+    // A relative path would be resolved against the capability URL's own path,
+    // and an absolute URL would move the request to another origin entirely.
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, path: "upload" })).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, path: "" })).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, path: "https://evil.example/up" }))
+      .toBeNull();
+  });
+
+  it("rejects a non-positive or unreadable byte cap", () => {
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, maxBytes: 0 })).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, maxBytes: -1 })).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, maxBytes: "lots" })).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, maxBytes: undefined })).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket({ ...valid, maxBytes: Number.POSITIVE_INFINITY }))
+      .toBeNull();
+  });
+
+  it("rejects anything that is not an object", () => {
+    expect(parseRemoteAttachmentUploadTicket(null)).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket(undefined)).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket("tkt-abc")).toBeNull();
+    expect(parseRemoteAttachmentUploadTicket(7)).toBeNull();
+  });
+});
diff --git a/apps/desktop/src/main/services/remoteRuntime/attachmentUploadClient.ts b/apps/desktop/src/main/services/remoteRuntime/attachmentUploadClient.ts
new file mode 100644
index 0000000000..732944c8af
--- /dev/null
+++ b/apps/desktop/src/main/services/remoteRuntime/attachmentUploadClient.ts
@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import path from "node:path";
+import type { RemoteAttachmentUploadRoute } from "./attachmentUploadRoute";
+
+/** Ticket a host mints over the authenticated sync socket for one upload. */
+export type RemoteAttachmentUploadTicket = {
+  ticket: string;
+  expiresAtMs: number;
+  maxBytes: number;
+  path: string;
+};
+
+export function parseRemoteAttachmentUploadTicket(value: unknown): RemoteAttachmentUploadTicket | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  const ticket = typeof record.ticket === "string" ? record.ticket.trim() : "";
+  const routePath = typeof record.path === "string" ? record.path.trim() : "";
+  const maxBytes = Number(record.maxBytes);
+  const expiresAtMs = Number(record.expiresAtMs);
+  if (!ticket || !routePath.startsWith("/")) return null;
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) return null;
+  return {
+    ticket,
+    path: routePath,
+    maxBytes: Math.floor(maxBytes),
+    expiresAtMs: Number.isFinite(expiresAtMs) ? expiresAtMs : 0,
+  };
+}
+
+const UPLOAD_TIMEOUT_MS = 5 * 60_000;
+
+/**
+ * Stream one file to a paired host's attachment-upload route.
+ *
+ * The body is piped from disk, never buffered: the whole point of this leg is
+ * that a 50 MB attachment does not become a 67 MB base64 string in two
+ * processes' heaps. Authorization is the single-use ticket the host minted over
+ * the already-authenticated sync socket; this request carries no other
+ * credential and grants nothing on its own.
+ */
+export async function uploadRemoteAttachment(args: {
+  route: RemoteAttachmentUploadRoute;
+  ticket: RemoteAttachmentUploadTicket;
+  sourcePath: string;
+  timeoutMs?: number;
+}): Promise<{ path: string }> {
+  const absolute = path.resolve(args.sourcePath);
+  const stat = await fs.promises.stat(absolute);
+  if (!stat.isFile()) throw new Error("Attachment path is not a file.");
+  const limit = Math.min(args.route.maxBytes, args.ticket.maxBytes);
+  if (stat.size > limit) {
+    throw new Error(`Attachment is larger than the machine accepts (${limit} bytes).`);
+  }
+
+  // The ticket names the route path; the capability names the origin. Compose
+  // them rather than trusting either alone, so a host that moves the route in a
+  // later version is followed without a client change.
+  const url = new URL(args.route.url);
+  url.pathname = args.ticket.path;
+  const transport = url.protocol === "https:" ? https : http;
+
+  return await new Promise<{ path: string }>((resolve, reject) => {
+    const body = fs.createReadStream(absolute);
+    let settled = false;
+    const fail = (error: unknown) => {
+      if (settled) return;
+      settled = true;
+      body.destroy();
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+
+    const request = transport.request(
+      url,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${args.ticket.ticket}`,
+          "Content-Type": "application/octet-stream",
+          "Content-Length": String(stat.size),
+        },
+      },
+      (response) => {
+        const chunks: Buffer[] = [];
+        response.on("data", (chunk: Buffer) => {
+          // Bound the response read: a well-behaved host answers with a small
+          // JSON object, and a misbehaving one must not be able to stream into
+          // this process's memory.
+          if (chunks.length < 64) chunks.push(chunk);
+        });
+        response.on("end", () => {
+          if (settled) return;
+          const text = Buffer.concat(chunks).toString("utf8");
+          const status = response.statusCode ?? 0;
+          if (status < 200 || status >= 300) {
+            let message = `Attachment upload failed (HTTP ${status}).`;
+            try {
+              const parsed = JSON.parse(text) as { error?: unknown };
+              if (typeof parsed.error === "string" && parsed.error.trim()) {
+                message = parsed.error.trim();
+              }
+            } catch {
+              // Non-JSON body: keep the status-only message.
+            }
+            fail(new Error(message));
+            return;
+          }
+          let uploadedPath = "";
+          try {
+            const parsed = JSON.parse(text) as { path?: unknown };
+            uploadedPath = typeof parsed.path === "string" ? parsed.path.trim() : "";
+          } catch {
+            fail(new Error("The machine returned an unreadable upload response."));
+            return;
+          }
+          if (!uploadedPath) {
+            fail(new Error("The machine did not return an attachment path."));
+            return;
+          }
+          settled = true;
+          resolve({ path: uploadedPath });
+        });
+        response.on("error", fail);
+      },
+    );
+
+    request.setTimeout(args.timeoutMs ?? UPLOAD_TIMEOUT_MS, () => {
+      request.destroy(new Error("Attachment upload timed out."));
+    });
+    request.on("error", fail);
+    body.on("error", fail);
+    body.pipe(request);
+  });
+}
diff --git a/apps/desktop/src/main/services/remoteRuntime/attachmentUploadRoute.test.ts b/apps/desktop/src/main/services/remoteRuntime/attachmentUploadRoute.test.ts
new file mode 100644
index 0000000000..28f4ebd2be
--- /dev/null
+++ b/apps/desktop/src/main/services/remoteRuntime/attachmentUploadRoute.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { resolveRemoteAttachmentUploadRoute } from "./attachmentUploadRoute";
+
+const CAPABLE = {
+  features: {
+    attachmentUploadV1: { enabled: true as const, path: "/ade-attachments/upload", maxBytes: 52_428_800 },
+  },
+} as never;
+
+describe("resolveRemoteAttachmentUploadRoute", () => {
+  it("maps a direct ws endpoint to the http upload URL", () => {
+    expect(resolveRemoteAttachmentUploadRoute({
+      endpoint: "ws://192.168.1.20:8787/",
+      hello: CAPABLE,
+    })).toEqual({ url: "http://192.168.1.20:8787/ade-attachments/upload", maxBytes: 52_428_800 });
+  });
+
+  it("maps a direct wss endpoint to https", () => {
+    expect(resolveRemoteAttachmentUploadRoute({
+      endpoint: "wss://mac.tail1234.ts.net:8787/",
+      hello: CAPABLE,
+    })?.url).toBe("https://mac.tail1234.ts.net:8787/ade-attachments/upload");
+  });
+
+  it("drops any query or fragment on the sync endpoint", () => {
+    expect(resolveRemoteAttachmentUploadRoute({
+      endpoint: "ws://host:8787/?token=abc#frag",
+      hello: CAPABLE,
+    })?.url).toBe("http://host:8787/ade-attachments/upload");
+  });
+
+  it("returns null for a host that does not advertise the route", () => {
+    expect(resolveRemoteAttachmentUploadRoute({
+      endpoint: "ws://host:8787/",
+      hello: { features: {} } as never,
+    })).toBeNull();
+    expect(resolveRemoteAttachmentUploadRoute({
+      endpoint: "ws://host:8787/",
+      hello: null,
+    })).toBeNull();
+  });
+
+  it("returns null on a relay-routed socket", () => {
+    // The relay brokers WebSocket frames only; an HTTP POST to that URL would
+    // never reach the host's own listener.
+    expect(resolveRemoteAttachmentUploadRoute({
+      endpoint: "wss://relay.ade.dev/bridge/abc",
+      hello: { ...(CAPABLE as object), connectionTransport: "relay" } as never,
+    })).toBeNull();
+  });
+
+  it("returns null for an endpoint that is not a websocket URL", () => {
+    for (const endpoint of ["ssh://host:22", "not a url", ""]) {
+      expect(resolveRemoteAttachmentUploadRoute({ endpoint, hello: CAPABLE })).toBeNull();
+    }
+  });
+
+  it("returns null for a malformed capability", () => {
+    const cases = [
+      { enabled: true, path: "ade-attachments/upload", maxBytes: 10 },
+      { enabled: true, path: "/ok", maxBytes: 0 },
+      { enabled: true, path: "/ok", maxBytes: Number.NaN },
+    ];
+    for (const attachmentUploadV1 of cases) {
+      expect(resolveRemoteAttachmentUploadRoute({
+        endpoint: "ws://host:8787/",
+        hello: { features: { attachmentUploadV1 } } as never,
+      })).toBeNull();
+    }
+  });
+
+  it("follows a route path the host moved in a later version", () => {
+    expect(resolveRemoteAttachmentUploadRoute({
+      endpoint: "ws://host:8787/",
+      hello: {
+        features: { attachmentUploadV1: { enabled: true, path: "/ade-attachments/v2", maxBytes: 100 } },
+      } as never,
+    })).toEqual({ url: "http://host:8787/ade-attachments/v2", maxBytes: 100 });
+  });
+});
diff --git a/apps/desktop/src/main/services/remoteRuntime/attachmentUploadRoute.ts b/apps/desktop/src/main/services/remoteRuntime/attachmentUploadRoute.ts
new file mode 100644
index 0000000000..0cf3e3a0f6
--- /dev/null
+++ b/apps/desktop/src/main/services/remoteRuntime/attachmentUploadRoute.ts
@@ -0,0 +1,54 @@
+import type { PairedRuntimeHelloOkPayload } from "../../../shared/types/pairedRuntime";
+
+export type RemoteAttachmentUploadRoute = {
+  /** Absolute URL to POST the attachment body to. */
+  url: string;
+  /** Host-declared ceiling; the client rejects larger files before uploading. */
+  maxBytes: number;
+};
+
+/**
+ * Where — if anywhere — this paired connection can accept a streamed HTTP
+ * attachment upload.
+ *
+ * Three independent things all have to hold, and each one failing is a normal
+ * outcome that falls back to base64 rather than an error:
+ *
+ * 1. The host advertised `features.attachmentUploadV1`. Hosts older than the
+ *    feature omit it, per the additive-capability rule.
+ * 2. The socket is a DIRECT one. A relay-routed connection terminates at the
+ *    relay, which brokers WebSocket frames and nothing else — an HTTP POST to
+ *    that URL would never reach the host's own listener. `connectionTransport`
+ *    is the host's own statement about which it is.
+ * 3. The endpoint is a `ws:`/`wss:` URL we can map to `http:`/`https:`. The
+ *    sync HTTP server and the WebSocket share one port, so the origin is the
+ *    endpoint's with the scheme swapped and the path replaced.
+ */
+export function resolveRemoteAttachmentUploadRoute(args: {
+  endpoint: string;
+  hello: Pick<PairedRuntimeHelloOkPayload, "features" | "connectionTransport"> | null | undefined;
+}): RemoteAttachmentUploadRoute | null {
+  const capability = args.hello?.features?.attachmentUploadV1;
+  if (capability?.enabled !== true) return null;
+  if (args.hello?.connectionTransport === "relay") return null;
+
+  const routePath = typeof capability.path === "string" ? capability.path.trim() : "";
+  if (!routePath.startsWith("/")) return null;
+  const maxBytes = Number(capability.maxBytes);
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) return null;
+
+  let url: URL;
+  try {
+    url = new URL(args.endpoint);
+  } catch {
+    return null;
+  }
+  if (url.protocol === "ws:") url.protocol = "http:";
+  else if (url.protocol === "wss:") url.protocol = "https:";
+  else return null;
+
+  url.pathname = routePath;
+  url.search = "";
+  url.hash = "";
+  return { url: url.toString(), maxBytes: Math.floor(maxBytes) };
+}
diff --git a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.ts b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.ts
index 2b968261d6..3b8b469095 100644
--- a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.ts
+++ b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionPool.ts
@@ -38,6 +38,11 @@ import {
   DesktopPairedMachineStore,
 } from "./syncPairedMachineStore";
 import type { SyncPortForwardClient } from "./syncPortForwardClient";
+import type { SyncRuntimeTransport } from "./syncRuntimeTransport";
+import {
+  resolveRemoteAttachmentUploadRoute,
+  type RemoteAttachmentUploadRoute,
+} from "./attachmentUploadRoute";
 import { classifyPairedRuntimeEndpoint } from "./pairedRuntimeRoutes";
 import { getSshHostKeyTrustForTarget } from "./sshTransport";
 
@@ -55,6 +60,14 @@ type PoolEntry =
   | (PoolEntryBase & {
       transport: "paired";
       pairedPortForwardClient: SyncPortForwardClient;
+      /**
+       * The live authenticated sync socket. Retained (not just its derived
+       * port-forward client) because `connection.hello.features` is the host's
+       * capability advertisement and `connection.endpoint` is the only place
+       * the host's address and port exist on this side. Both are needed to
+       * decide whether an attachment can be uploaded over HTTP and where to.
+       */
+      pairedTransport: SyncRuntimeTransport;
       relayAccountOwnerUserId: string | null;
     });
 
@@ -469,6 +482,7 @@ export class RemoteConnectionPool {
           client: paired.client,
           transport: "paired",
           pairedPortForwardClient: paired.portForwardClient,
+          pairedTransport: paired.transport,
           relayAccountOwnerUserId: paired.relayAccountOwnerUserId,
           result: paired.result,
         };
@@ -564,6 +578,21 @@ export class RemoteConnectionPool {
     return await this.callActionWithEntry(entry, projectId, request);
   }
 
+  /**
+   * The HTTP attachment-upload route this target advertises, or null when it
+   * has none. Null is an ordinary answer — an SSH target, a relay-routed
+   * paired target, and a host older than the feature all return it, and every
+   * caller falls back to the base64 command path.
+   */
+  async getAttachmentUploadRoute(targetId: string): Promise<RemoteAttachmentUploadRoute | null> {
+    const entry = await this.requireEntry(targetId);
+    if (entry.transport !== "paired") return null;
+    return resolveRemoteAttachmentUploadRoute({
+      endpoint: entry.pairedTransport.connection.endpoint,
+      hello: entry.pairedTransport.connection.hello,
+    });
+  }
+
   async callActionForTarget(
     target: RemoteRuntimeTarget,
     projectId: string,
diff --git a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionService.test.ts b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionService.test.ts
index f2c682e429..145141f945 100644
--- a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionService.test.ts
+++ b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionService.test.ts
@@ -1,4 +1,15 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createAttachmentUploadRegistry } from "../../../../../ade-cli/src/services/sync/attachmentUploadService";
+import { MAX_CHAT_ATTACHMENT_BYTES } from "../../../shared/chatAttachmentLimits";
+import { projectAttachmentsDir } from "../../../shared/chatAttachmentStagingFs";
+import {
+  getAdeActionDomainServices,
+  isAllowedAdeAction,
+} from "../adeActions/registry";
 import type {
   RemoteRuntimeConnectResult,
   RemoteRuntimeTarget,
@@ -1423,3 +1434,166 @@ describe("RemoteConnectionService", () => {
     );
   });
 });
+
+describe("uploadChatAttachment", () => {
+  const servers: http.Server[] = [];
+  const tempDirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(servers.splice(0).map((server) =>
+      new Promise<void>((resolve) => server.close(() => resolve())),
+    ));
+    await Promise.all(tempDirs.splice(0).map((dir) =>
+      fs.promises.rm(dir, { recursive: true, force: true }),
+    ));
+  });
+
+  /**
+   * The two gates `run_ade_action` applies to a chat action, in its order and
+   * with its wording (adeRpcServer.ts). Deliberately NOT a stub of
+   * `callAction`: the defect this covers was that the real registry had no
+   * `createAttachmentUpload` and the real allowlist had no entry for it, so a
+   * mocked action call would have proved nothing.
+   */
+  function dispatchRunAdeAction(
+    runtime: unknown,
+    request: { domain: string; action: string; args?: Record<string, unknown> },
+  ): Promise<{ domain: string; action: string; result: unknown; statusHints: Record<string, unknown> }> {
+    const services = getAdeActionDomainServices(runtime as never) as Record<
+      string,
+      Record<string, unknown> | null
+    >;
+    const service = services[request.domain];
+    const callable = service?.[request.action];
+    if (typeof callable !== "function") {
+      throw new Error(`Action '${request.domain}.${request.action}' is not callable.`);
+    }
+    if (!isAllowedAdeAction(request.domain as never, request.action)) {
+      throw new Error(
+        `Action '${request.domain}.${request.action}' is not exposed through ADE actions.`,
+      );
+    }
+    return Promise.resolve(callable(request.args ?? {})).then((result) => ({
+      domain: request.domain,
+      action: request.action,
+      result,
+      statusHints: {},
+    }));
+  }
+
+  it("mints a ticket through the real action registry and streams the file to the host's route", async () => {
+    // End to end across the whole two-leg design: the paired desktop asks the
+    // host's ADE action registry for a ticket over `run_ade_action`, then POSTs
+    // the body to the host's real upload route with that ticket as its only
+    // authority. Before `chat.createAttachmentUpload` existed on the registry
+    // and in the allowlist, the first leg failed and remote-paired attach was
+    // dead on every machine.
+    const projectRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-upload-project-"));
+    const sourceDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-upload-src-"));
+    tempDirs.push(projectRoot, sourceDir);
+
+    const uploads = createAttachmentUploadRegistry();
+    const server = http.createServer((request, response) => {
+      if (uploads.handleRequest(request, response)) return;
+      response.writeHead(426);
+      response.end();
+    });
+    servers.push(server);
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : 0;
+
+    // The host-side runtime the registry builds its chat domain from. Only the
+    // three fields this action reads are populated.
+    const runtime = {
+      projectRoot,
+      agentChatService: {},
+      syncHostService: {
+        issueAttachmentUploadTicket: (args: {
+          projectRoot: string;
+          filename: string;
+          deviceId?: string | null;
+        }) => uploads.issue(args),
+      },
+    };
+
+    const remote = target("paired-host", Date.now());
+    const targetRegistry = {
+      list: vi.fn(() => [remote]),
+      get: vi.fn((id: string) => (id === remote.id ? remote : null)),
+      update: vi.fn(),
+    } as unknown as RemoteTargetRegistry;
+    const pool = {
+      onEntryEvicted: vi.fn(() => () => {}),
+      getAttachmentUploadRoute: vi.fn(async () => ({
+        url: `http://127.0.0.1:${port}/ade-attachments/upload`,
+        maxBytes: MAX_CHAT_ATTACHMENT_BYTES,
+      })),
+      callActionForTarget: vi.fn(
+        async (
+          _target: RemoteRuntimeTarget,
+          _projectId: string,
+          request: { domain: string; action: string; args?: Record<string, unknown> },
+        ) => dispatchRunAdeAction(runtime, request),
+      ),
+    } as unknown as RemoteConnectionPool;
+
+    const sourcePath = path.join(sourceDir, "design notes.pdf");
+    const content = Buffer.from("%PDF-1.7 real bytes that must survive the wire");
+    await fs.promises.writeFile(sourcePath, content);
+
+    const service = new RemoteConnectionService(targetRegistry, pool);
+    const staged = await service.uploadChatAttachment({
+      targetId: remote.id,
+      projectId: "project-1",
+      sourcePath,
+      filename: "design notes.pdf",
+    });
+
+    // Landed in the host project's attachments dir under a UUID basename that
+    // carries only the validated extension.
+    expect(path.dirname(staged.path)).toBe(projectAttachmentsDir(projectRoot));
+    expect(path.basename(staged.path, ".pdf")).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+    await expect(fs.promises.readFile(staged.path)).resolves.toEqual(content);
+    // Single use: the ticket was consumed, and no `.part` file was left behind.
+    expect(uploads.pendingCount()).toBe(0);
+    await expect(fs.promises.readdir(projectAttachmentsDir(projectRoot)))
+      .resolves.toHaveLength(1);
+  });
+
+  it("reports the machine cannot accept uploads when it is not hosting sync", async () => {
+    const projectRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-upload-nohost-"));
+    tempDirs.push(projectRoot);
+
+    const remote = target("paired-host", Date.now());
+    const targetRegistry = {
+      list: vi.fn(() => [remote]),
+      get: vi.fn((id: string) => (id === remote.id ? remote : null)),
+      update: vi.fn(),
+    } as unknown as RemoteTargetRegistry;
+    const pool = {
+      onEntryEvicted: vi.fn(() => () => {}),
+      getAttachmentUploadRoute: vi.fn(async () => ({
+        url: "http://127.0.0.1:1/ade-attachments/upload",
+        maxBytes: MAX_CHAT_ATTACHMENT_BYTES,
+      })),
+      callActionForTarget: vi.fn(
+        async (
+          _target: RemoteRuntimeTarget,
+          _projectId: string,
+          request: { domain: string; action: string; args?: Record<string, unknown> },
+        ) => dispatchRunAdeAction({ projectRoot, agentChatService: {} }, request),
+      ),
+    } as unknown as RemoteConnectionPool;
+
+    const service = new RemoteConnectionService(targetRegistry, pool);
+    await expect(service.uploadChatAttachment({
+      targetId: remote.id,
+      projectId: "project-1",
+      sourcePath: path.join(projectRoot, "missing.png"),
+      filename: "missing.png",
+    })).rejects.toThrow(/not sharing this project/i);
+  });
+});
diff --git a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionService.ts b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionService.ts
index 73bf2b88be..d6365355d4 100644
--- a/apps/desktop/src/main/services/remoteRuntime/remoteConnectionService.ts
+++ b/apps/desktop/src/main/services/remoteRuntime/remoteConnectionService.ts
@@ -33,11 +33,20 @@ import type {
   RemoteRuntimeTrustSshHostKeyResult,
 } from "../../../shared/types";
 import type { DesktopPairedMachineCredentials } from "../../../shared/types/pairedRuntime";
+import type { ChatAttachmentStagingMode } from "../../../shared/types/chat";
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  MAX_CHAT_ATTACHMENT_BYTES,
+} from "../../../shared/chatAttachmentLimits";
 import {
   capRemoteRuntimeErrorDetail,
   RemoteRuntimeConnectError,
 } from "../../../shared/types";
 import { coerceProjects } from "./remoteBootstrap";
+import {
+  parseRemoteAttachmentUploadTicket,
+  uploadRemoteAttachment,
+} from "./attachmentUploadClient";
 import {
   isRemoteRuntimeConnectionError,
   type RemoteConnectionPool,
@@ -958,6 +967,75 @@ export class RemoteConnectionService {
     )) as ListMyGitHubReposResult;
   }
 
+  /**
+   * How this target accepts a staged chat attachment, and how large one may be.
+   *
+   * `"upload"` means the host advertised the streamed HTTP route and the socket
+   * is direct enough to use it. `"base64"` is every other case — SSH targets,
+   * relay-routed sockets, and hosts predating the feature — and keeps the
+   * legacy base64 command with its smaller, image-only ceiling.
+   *
+   * The answer is already a {@link ChatAttachmentStagingMode}, so the renderer
+   * routes on it directly. It used to be a separate `"command"` vocabulary that
+   * preload renamed on the way out, which meant two names for one fact.
+   * `"copy"` is the one mode this can never return: it is a property of the
+   * caller (same machine), not of the target.
+   */
+  async getAttachmentUploadCapability(
+    targetId: string,
+  ): Promise<ChatAttachmentStagingMode> {
+    const legacy: ChatAttachmentStagingMode = {
+      mode: "base64",
+      maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+    };
+    try {
+      const route = await this.pool.getAttachmentUploadRoute(targetId);
+      if (!route) return legacy;
+      return {
+        mode: "upload",
+        maxBytes: Math.min(route.maxBytes, MAX_CHAT_ATTACHMENT_BYTES),
+      };
+    } catch {
+      // A target that is not connected cannot be probed; the caller degrades to
+      // the base64 path, which reconnects on its own.
+      return legacy;
+    }
+  }
+
+  /**
+   * Stage an attachment on a paired machine by streaming its bytes over HTTP.
+   *
+   * Two legs, in this order and only this order: mint a single-use ticket over
+   * the authenticated sync socket, then POST the body with that ticket. The
+   * HTTP leg never carries the pairing secret, and a ticket that is not spent
+   * expires on its own.
+   */
+  async uploadChatAttachment(args: {
+    targetId: string;
+    projectId: string;
+    sourcePath: string;
+    filename: string;
+  }): Promise<{ path: string }> {
+    const route = await this.pool.getAttachmentUploadRoute(args.targetId);
+    if (!route) {
+      throw new Error("This machine does not accept attachment uploads.");
+    }
+    const minted = await this.callAction(args.targetId, args.projectId, {
+      domain: "chat",
+      action: "createAttachmentUpload",
+      args: { filename: args.filename },
+    });
+    const ticket = parseRemoteAttachmentUploadTicket(minted.result);
+    if (!ticket) {
+      throw new Error("This machine returned an unusable attachment upload ticket.");
+    }
+    return await uploadRemoteAttachment({
+      route,
+      ticket,
+      sourcePath: args.sourcePath,
+    });
+  }
+
   async callAction(
     targetId: string,
     projectId: string,
diff --git a/apps/desktop/src/main/services/storage/storageInsightsService.ts b/apps/desktop/src/main/services/storage/storageInsightsService.ts
index 67ddba582b..4ea2ecc0d7 100644
--- a/apps/desktop/src/main/services/storage/storageInsightsService.ts
+++ b/apps/desktop/src/main/services/storage/storageInsightsService.ts
@@ -2,6 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { resolveAdeLayout } from "../../../shared/adeLayout";
+import { projectAttachmentsDir } from "../../../shared/chatAttachmentStagingFs";
 import type {
   DbBreakdownEntry,
   MaintenanceAction,
@@ -1025,7 +1026,7 @@ export function createStorageInsightsService(options: StorageInsightsServiceOpti
       if (await hasSymlinkAncestor(projectRoot, targetPath)) {
         return { valid: null, reason: "Links cannot be used in a cleanup path." };
       }
-      const attachmentsRoot = path.join(layout.adeDir, "attachments");
+      const attachmentsRoot = projectAttachmentsDir(projectRoot);
       if (isSameOrWithin(attachmentsRoot, targetPath)) {
         // This store backs prompt stashes and renderer-owned composer drafts.
         // Main cannot enumerate every active draft, so recursive or per-file
diff --git a/apps/desktop/src/preload/global.d.ts b/apps/desktop/src/preload/global.d.ts
index a22398de9b..83102a0c47 100644
--- a/apps/desktop/src/preload/global.d.ts
+++ b/apps/desktop/src/preload/global.d.ts
@@ -728,7 +728,11 @@ import type {
   SearchRebuildResult,
 } from "../shared/types";
 import type { GitHubIssueLike } from "../shared/laneGitHubIssue";
-import type { ConvertImageToJpegResult } from "../shared/types/chat";
+import type {
+  AgentChatCopyTempAttachmentArgs,
+  ChatAttachmentStagingMode,
+  ConvertImageToJpegResult,
+} from "../shared/types/chat";
 import type { DiskPressureSnapshot } from "../main/services/storage/diskPressure";
 import type {
   MaintenanceRunReport,
@@ -2019,6 +2023,13 @@ declare global {
           },
           pin?: OpenProjectBinding | null,
         ) => Promise<{ path: string }>;
+        getAttachmentStagingMode: (
+          pin?: OpenProjectBinding | null,
+        ) => Promise<ChatAttachmentStagingMode>;
+        stageFileAttachment: (
+          args: AgentChatCopyTempAttachmentArgs,
+          pin?: OpenProjectBinding | null,
+        ) => Promise<{ path: string }>;
         getImageDataUrl: (
           path: string,
           pin?: OpenProjectBinding | null,
diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.ts
index 1f0e81ee0a..7b08f9c9a6 100644
--- a/apps/desktop/src/preload/preload.ts
+++ b/apps/desktop/src/preload/preload.ts
@@ -5,7 +5,15 @@ import { projectBindingKey } from "../shared/projectIdentity";
 import { isSyncServiceUnavailableError } from "../shared/runtimeErrors";
 import { resolvePackageChannelFromProcess } from "../shared/packageChannel";
 import { EXTERNAL_FILES_WORKSPACE_ID_PREFIX } from "../shared/types/files";
-import type { ConvertImageToJpegResult } from "../shared/types/chat";
+import type {
+  AgentChatCopyTempAttachmentArgs,
+  ChatAttachmentStagingMode,
+  ConvertImageToJpegResult,
+} from "../shared/types/chat";
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  MAX_CHAT_ATTACHMENT_BYTES,
+} from "../shared/chatAttachmentLimits";
 import {
   type AttentionAcknowledgmentOutcome,
   type AttentionItem,
@@ -1451,6 +1459,7 @@ const MUTATING_CHAT_ACTIONS = new Set<string>([
   "warmupModel",
   "rewindFiles",
   "saveTempAttachment",
+  "copyTempAttachment",
   "setCodexGoal",
   "setCodexGoalStatus",
   "clearCodexGoal",
@@ -7157,6 +7166,58 @@ const adeBridge = {
       callPinnedOrBoundRuntimeActionOr(pin, "chat", "saveTempAttachment", { args }, () =>
         ipcRenderer.invoke(IPC.agentChatSaveTempAttachment, args),
       ),
+    /**
+     * How a staged attachment reaches the machine that owns this chat, and how
+     * large it may be. The composer asks once per batch and routes on the
+     * answer instead of hardcoding a cap, so the ceiling always matches the
+     * path the bytes will actually take.
+     */
+    getAttachmentStagingMode: async (
+      pin?: OpenProjectBinding | null,
+    ): Promise<ChatAttachmentStagingMode> => {
+      if (pin?.kind !== "remote") {
+        // Same machine as the main process: the bytes never move, only the
+        // path. `copy` is the one mode the main process cannot answer with,
+        // because it is a property of the caller, not of the target — so it is
+        // decided here and every other mode comes back ready to use.
+        return { mode: "copy", maxBytes: MAX_CHAT_ATTACHMENT_BYTES };
+      }
+      const capability = (await ipcRenderer.invoke(
+        IPC.remoteRuntimeAttachmentUploadCapability,
+        { id: pin.targetId },
+      )) as ChatAttachmentStagingMode | null;
+      if (capability?.mode === "upload" || capability?.mode === "base64") {
+        return capability;
+      }
+      return { mode: "base64", maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES };
+    },
+    /**
+     * Stage a file that exists on this machine's disk without reading it into
+     * the renderer. `copy` hands the path to the local brain, which copies it;
+     * `upload` streams it to the paired host over HTTP. Callers reach this only
+     * after `getAttachmentStagingMode` said so — `base64` has no path here and
+     * keeps using `saveTempAttachment`.
+     */
+    stageFileAttachment: async (
+      args: AgentChatCopyTempAttachmentArgs,
+      pin?: OpenProjectBinding | null,
+    ): Promise<{ path: string }> => {
+      if (pin?.kind === "remote") {
+        return (await ipcRenderer.invoke(IPC.remoteRuntimeUploadChatAttachment, {
+          id: pin.targetId,
+          projectId: pin.projectId,
+          sourcePath: args.sourcePath,
+          filename: args.filename,
+        })) as { path: string };
+      }
+      return await callPinnedOrBoundRuntimeActionOr(
+        pin,
+        "chat",
+        "copyTempAttachment",
+        { args },
+        () => ipcRenderer.invoke(IPC.agentChatCopyTempAttachment, args),
+      );
+    },
     getImageDataUrl: async (
       path: string,
       pin?: OpenProjectBinding | null,
diff --git a/apps/desktop/src/renderer/browserMock.ts b/apps/desktop/src/renderer/browserMock.ts
index a07d839746..783b04367e 100644
--- a/apps/desktop/src/renderer/browserMock.ts
+++ b/apps/desktop/src/renderer/browserMock.ts
@@ -31,6 +31,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
 import { getDefaultModelDescriptor } from "../shared/modelRegistry";
+import { LEGACY_MAX_CHAT_ATTACHMENT_BYTES } from "../shared/chatAttachmentLimits";
 import { normalizeAppPackageChannel, type AppPackageChannel } from "../shared/packageChannel";
 import { deriveSmartLinkPreview } from "../shared/smartLinks";
 import { remoteProjectBindingKey } from "../shared/projectIdentity";
@@ -5119,6 +5120,14 @@ if (typeof window !== "undefined" && shouldInstallBrowserMock(window)) {
         },
       }),
       saveTempAttachment: resolvedArg({ path: "/tmp/browser-mock-attachment" }),
+      // Vite-only preview runs in a browser: no webUtils, so no real path.
+      getAttachmentStagingMode: resolvedArg({
+        mode: "base64" as const,
+        maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+      }),
+      stageFileAttachment: async () => {
+        throw new Error("Attachment upload is not available in the browser preview.");
+      },
       getImageDataUrl: resolvedArg({ dataUrl: BROWSER_MOCK_IMAGE_DATA_URL }),
       resolveSmartLinkPreview: async ({ url }: { url: string }) => deriveSmartLinkPreview(url),
       getEventHistory: async (arg: {
diff --git a/apps/desktop/src/renderer/components/chat/AgentChatComposer.test.tsx b/apps/desktop/src/renderer/components/chat/AgentChatComposer.test.tsx
index 3122839967..70f8fca0e7 100644
--- a/apps/desktop/src/renderer/components/chat/AgentChatComposer.test.tsx
+++ b/apps/desktop/src/renderer/components/chat/AgentChatComposer.test.tsx
@@ -9,6 +9,10 @@ import type {
   OpenProjectBinding,
 } from "../../../shared/types";
 import { THIS_MACHINE_NAME } from "../../../shared/machineIdentity";
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  formatAttachmentSize,
+} from "../../../shared/chatAttachmentLimits";
 import {
   AgentChatComposer,
   HEIC_CONVERSION_UNAVAILABLE_MESSAGE,
@@ -1225,14 +1229,19 @@ describe("AgentChatComposer", () => {
     expect(uploadInput).toBeTruthy();
 
     const oversized = new File(["too large"], "oversized.txt", { type: "text/plain" });
-    Object.defineProperty(oversized, "size", { value: 11 * 1024 * 1024 });
+    Object.defineProperty(oversized, "size", {
+      value: LEGACY_MAX_CHAT_ATTACHMENT_BYTES + 1024 * 1024,
+    });
     fireEvent.change(uploadInput!, { target: { files: [oversized] } });
 
-    expect(await screen.findByText(/Maximum allowed size is 10 MB/)).toBeTruthy();
+    const capMessage = new RegExp(
+      `Maximum allowed size is ${formatAttachmentSize(LEGACY_MAX_CHAT_ATTACHMENT_BYTES)}`,
+    );
+    expect(await screen.findByText(capMessage)).toBeTruthy();
     fireEvent.click(screen.getByLabelText("Dismiss error"));
 
     await waitFor(() => {
-      expect(screen.queryByText(/Maximum allowed size is 10 MB/)).toBeNull();
+      expect(screen.queryByText(capMessage)).toBeNull();
     });
   });
 
diff --git a/apps/desktop/src/renderer/components/chat/AgentChatComposer.tsx b/apps/desktop/src/renderer/components/chat/AgentChatComposer.tsx
index 6f25e460d9..aa3e16c533 100644
--- a/apps/desktop/src/renderer/components/chat/AgentChatComposer.tsx
+++ b/apps/desktop/src/renderer/components/chat/AgentChatComposer.tsx
@@ -133,12 +133,21 @@ import { settingsRouteFor } from "../settings/settingsManifest";
 import type { AgentChatPromptHistoryEntry } from "./chatPromptHistory";
 import { ChatAttachmentDropOverlay } from "./ChatAttachmentDropOverlay";
 import type { AgentChatAttachmentDropTarget } from "./chatAttachmentDropTarget";
-
-const MAX_TEMP_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+import {
+  AttachmentConversionError,
+  attachmentPlanRejection,
+  planAttachmentStaging,
+  readAttachmentStagingMode,
+  stageAttachmentBytesFromFile,
+  type StagedAttachment,
+} from "./chatAttachmentStaging";
+
+// Attachment ceilings are not a renderer constant any more: they depend on the
+// leg the bytes take, which depends on the machine that owns the chat. See
+// `chatAttachmentStaging.ts` and `shared/chatAttachmentLimits.ts`.
 const CLIPBOARD_IMAGE_PASTE_FALLBACK_DELAY_MS = 80;
 const PROMPT_HISTORY_SEQUENCE_TIMEOUT_MS = 3_000;
 type PromptHistoryArrowKey = "ArrowUp" | "ArrowDown";
-const BASE64_ENCODE_CHUNK_SIZE = 0x8000;
 const ISSUE_CONTEXT_MENU_WIDTH = 180;
 const ISSUE_CONTEXT_MENU_GAP = 8;
 const ISSUE_CONTEXT_MENU_VIEWPORT_GUTTER = 8;
@@ -151,13 +160,6 @@ const HEIC_CONVERSION_MESSAGES: Record<HeicConversionErrorCode, string> = {
   failed: HEIC_CONVERSION_FAILED_MESSAGE,
 };
 
-class AttachmentConversionError extends Error {
-  constructor(readonly code: HeicConversionErrorCode) {
-    super(code);
-    this.name = "AttachmentConversionError";
-  }
-}
-
 function attachmentErrorMessage(error: unknown, filename: string): string {
   if (error instanceof AttachmentConversionError) {
     return HEIC_CONVERSION_MESSAGES[error.code];
@@ -333,16 +335,6 @@ function normalizeImageAttachmentUrl(value: string | null | undefined): string |
   }
 }
 
-function arrayBufferToBase64(buffer: ArrayBuffer): string {
-  const bytes = new Uint8Array(buffer);
-  const parts: string[] = [];
-  for (let i = 0; i < bytes.length; i += BASE64_ENCODE_CHUNK_SIZE) {
-    const chunk = bytes.subarray(i, i + BASE64_ENCODE_CHUNK_SIZE);
-    parts.push(String.fromCharCode(...chunk));
-  }
-  return btoa(parts.join(""));
-}
-
 type ExecutionModeOption = {
   value: AgentChatExecutionMode;
   label: string;
@@ -1912,9 +1904,16 @@ export function AgentChatComposer({
   const [attachmentResults, setAttachmentResults] = useState<AgentChatFileRef[]>([]);
   const [attachmentCursor, setAttachmentCursor] = useState(0);
   const [attachError, setAttachError] = useState<string | null>(null);
+  // Files whose staging failed for a reason a second attempt could fix — a
+  // dropped connection, a host that was mid-restart. Holding the `File` handles
+  // is what makes the retry real rather than a message telling the user to
+  // drag it in again. Size rejections deliberately do NOT land here: retrying
+  // a too-large file cannot succeed, so offering it would be a lie.
+  const [attachRetryFiles, setAttachRetryFiles] = useState<File[] | null>(null);
   const [attachNotice, setAttachNotice] = useState<{ message: string; undoPath: string } | null>(null);
   const [pendingImageAttachments, setPendingImageAttachments] = useState<ChatAttachmentPendingImage[]>([]);
   const [imagePreviewUrls, setImagePreviewUrls] = useState<Record<string, string>>({});
+  const [attachmentSizes, setAttachmentSizes] = useState<Record<string, number>>({});
 
   useEffect(() => {
     if (!attachNotice) return;
@@ -2422,6 +2421,27 @@ export function AgentChatComposer({
     });
   }, []);
 
+  /**
+   * Byte size of a file this composer staged, keyed by its staged path. Only
+   * the composer can know this without a round trip — it held the `File`.
+   * Kept alongside the preview URLs and dropped with them.
+   */
+  const rememberAttachmentSize = useCallback((path: string, size: number) => {
+    if (!Number.isFinite(size) || size < 0) return;
+    setAttachmentSizes((current) => (
+      current[path] === size ? current : { ...current, [path]: size }
+    ));
+  }, []);
+
+  /**
+   * Forget everything this composer remembers about a staged path.
+   *
+   * Preview URL and byte size are two halves of one record — both are keyed by
+   * the staged path and both are only knowable here — so they are dropped
+   * together. Clearing only the preview left the size map growing for the
+   * lifetime of the composer, one entry per file the user ever attached and
+   * then removed.
+   */
   const clearPreviewForPath = useCallback((path: string) => {
     setImagePreviewUrls((current) => {
       if (!current[path]) return current;
@@ -2429,6 +2449,12 @@ export function AgentChatComposer({
       delete next[path];
       return next;
     });
+    setAttachmentSizes((current) => {
+      if (!(path in current)) return current;
+      const next = { ...current };
+      delete next[path];
+      return next;
+    });
   }, []);
 
   const createObjectPreviewUrl = useCallback((file: File): string | null => {
@@ -2508,18 +2534,25 @@ export function AgentChatComposer({
     previousPendingImageAttachmentsRef.current = pendingImageAttachments;
   }, [imagePreviewUrls, pendingImageAttachments, revokePreviewUrl]);
 
+  // Attachments the parent dropped (a send, a reset, a removal that did not
+  // come through `handleRemoveAttachment`) take their per-path composer state
+  // with them. Previews and sizes are pruned by the same rule so the two maps
+  // cannot disagree about which paths this composer still knows.
   useEffect(() => {
     const currentPaths = new Set(attachments.map((attachment) => attachment.path));
     const previousPaths = previousAttachmentPathsRef.current;
-    setImagePreviewUrls((current) => {
+    const isStale = (path: string): boolean => previousPaths.has(path) && !currentPaths.has(path);
+    const pruneStale = <T,>(current: Record<string, T>): Record<string, T> => {
       let next = current;
       for (const path of Object.keys(current)) {
-        if (!previousPaths.has(path) || currentPaths.has(path)) continue;
+        if (!isStale(path)) continue;
         if (next === current) next = { ...current };
         delete next[path];
       }
       return next;
-    });
+    };
+    setImagePreviewUrls(pruneStale);
+    setAttachmentSizes(pruneStale);
     previousAttachmentPathsRef.current = currentPaths;
   }, [attachments]);
 
@@ -2588,9 +2621,15 @@ export function AgentChatComposer({
     if (fileAddInProgressRef.current) return;
     fileAddInProgressRef.current = true;
     setAttachError(null);
+    setAttachRetryFiles(null);
+    const retryable: File[] = [];
     try {
       let addedInBatch = 0;
       const initialSlotCount = attachmentSlotsUsed;
+      // One probe per batch, not per file: the answer is a property of the
+      // machine, and asking again mid-batch would only widen the window in
+      // which half the files were staged under a different contract.
+      const stagingMode = await readAttachmentStagingMode(composerMachineBinding);
       for (const file of Array.from(files)) {
         if (parallelChatMode && initialSlotCount + addedInBatch >= PARALLEL_CHAT_MAX_ATTACHMENTS) {
           setAttachError(`You can attach up to ${PARALLEL_CHAT_MAX_ATTACHMENTS} files for parallel launch.`);
@@ -2599,11 +2638,19 @@ export function AgentChatComposer({
         const sourceAttachmentName = file.name || "clipboard.png";
         const isHeicUpload = isHeicAttachment(sourceAttachmentName, file.type);
         const isImageAttachment = inferAttachmentType(sourceAttachmentName, file.type) === "image";
+        const plan = planAttachmentStaging({
+          mode: stagingMode,
+          sourcePath: window.ade?.project?.getDroppedPath?.(file) ?? null,
+          requiresByteConversion: isHeicUpload,
+        });
 
-        if (file.size > MAX_TEMP_ATTACHMENT_BYTES) {
-          setAttachError(
-            `File "${file.name || "clipboard"}" is too large (${(file.size / 1024 / 1024).toFixed(1)} MB). Maximum allowed size is 10 MB.`,
-          );
+        const rejection = attachmentPlanRejection(
+          plan,
+          file.name || "clipboard",
+          file.size,
+        );
+        if (rejection) {
+          setAttachError(rejection);
           continue;
         }
 
@@ -2612,35 +2659,27 @@ export function AgentChatComposer({
           : null;
         const attachmentOwnerBinding = composerMachineBinding;
         try {
-          const buf = await file.arrayBuffer();
-          let attachmentName = sourceAttachmentName;
-          let attachmentData = arrayBufferToBase64(buf);
-          let attachmentMimeType: string | null = file.type || null;
-          let convertedPreviewDataUrl: string | null = null;
-          if (isHeicUpload) {
-            const convertImageToJpeg = window.ade?.app?.convertImageToJpeg;
-            if (typeof convertImageToJpeg !== "function") {
-              throw new AttachmentConversionError("unavailable");
-            }
-            const converted = await convertImageToJpeg({
-              data: attachmentData,
+          // The two transports differ only in HOW the bytes reach the host.
+          // Each yields the same three facts, and everything after — the
+          // binding-changed guard, the cancelled-pending guard, the preview and
+          // size bookkeeping, the hand-off to the parent — is identical, so it
+          // is written once below. Duplicating it is how the two branches drift.
+          let staged: StagedAttachment;
+          if (plan.transport === "path") {
+            const { path: stagedPath } = await window.ade.agentChat.stageFileAttachment(
+              { sourcePath: plan.sourcePath, filename: sourceAttachmentName },
+              attachmentOwnerBinding,
+            );
+            staged = { path: stagedPath, mimeType: file.type || null, previewDataUrl: null };
+          } else {
+            staged = await stageAttachmentBytesFromFile({
+              file,
               filename: sourceAttachmentName,
-              mimeType: file.type || null,
+              requiresHeicConversion: isHeicUpload,
+              pin: attachmentOwnerBinding,
             });
-            if (converted.ok !== true) {
-              throw new AttachmentConversionError(
-                converted.errorCode === "unavailable" ? "unavailable" : "failed",
-              );
-            }
-            attachmentName = converted.filename;
-            attachmentData = converted.data;
-            attachmentMimeType = converted.mimeType;
-            convertedPreviewDataUrl = `data:${converted.mimeType};base64,${converted.data}`;
           }
-          const { path: tempPath } = await window.ade.agentChat.saveTempAttachment({
-            data: attachmentData,
-            filename: attachmentName,
-          }, attachmentOwnerBinding);
+
           if (latestComposerMachineBindingRef.current?.key !== attachmentOwnerBinding?.key) {
             if (pendingImage) dropPendingImageAttachment(pendingImage.id);
             setAttachError(`"${sourceAttachmentName}" was not attached because the selected machine changed. Attach it again.`);
@@ -2650,27 +2689,28 @@ export function AgentChatComposer({
             cancelledPendingImageAttachmentsRef.current.delete(pendingImage.id);
             continue;
           }
-          const attachmentType = inferAttachmentType(tempPath, attachmentMimeType);
-          const pendingPreviewUrl = pendingImage?.previewUrl ?? null;
+          const attachmentType = inferAttachmentType(staged.path, staged.mimeType);
           if (attachmentType === "image") {
-            if (convertedPreviewDataUrl) {
-              rememberPreviewUrl(tempPath, convertedPreviewDataUrl);
-            } else if (pendingPreviewUrl) {
-              rememberPreviewUrl(tempPath, pendingPreviewUrl);
-            }
-          }
-          onAddAttachment({ path: tempPath, type: attachmentType });
-          if (pendingImage) {
-            dropPendingImageAttachment(pendingImage.id);
+            // A converted JPEG's data URL wins over the object URL for the
+            // original: the HEIC the browser could not decode has no preview.
+            rememberPreviewUrl(staged.path, staged.previewDataUrl ?? pendingImage?.previewUrl);
           }
+          rememberAttachmentSize(staged.path, file.size);
+          onAddAttachment({ path: staged.path, type: attachmentType });
+          if (pendingImage) dropPendingImageAttachment(pendingImage.id);
           addedInBatch += 1;
         } catch (error) {
+          // The pending placeholder always comes down, whatever went wrong.
+          // A staging failure that left a spinner up would read as "still
+          // working" forever.
           if (pendingImage) dropPendingImageAttachment(pendingImage.id);
           setAttachError(attachmentErrorMessage(error, sourceAttachmentName));
+          if (!(error instanceof AttachmentConversionError)) retryable.push(file);
         }
       }
     } finally {
       fileAddInProgressRef.current = false;
+      setAttachRetryFiles(retryable.length ? retryable : null);
     }
   };
   addFileAttachmentsRef.current = addFileAttachments;
@@ -5366,11 +5406,28 @@ export function AgentChatComposer({
             {attachError ? (
               <div className="flex items-center gap-1.5 px-3">
                 <span className="text-[length:calc(var(--chat-font-size)*10/14)] text-red-300/75">{attachError}</span>
+                {attachRetryFiles?.length ? (
+                  <button
+                    type="button"
+                    className="shrink-0 rounded px-1 text-[length:calc(var(--chat-font-size)*10/14)] text-red-200/80 underline underline-offset-2 transition-colors hover:text-red-100"
+                    onClick={() => {
+                      const files = attachRetryFiles;
+                      setAttachRetryFiles(null);
+                      setAttachError(null);
+                      void addFileAttachments(files);
+                    }}
+                  >
+                    Try again
+                  </button>
+                ) : null}
                 <button
                   type="button"
                   aria-label="Dismiss error"
                   className="shrink-0 rounded p-0.5 text-red-300/60 hover:text-red-200/80 transition-colors"
-                  onClick={() => setAttachError(null)}
+                  onClick={() => {
+                    setAttachError(null);
+                    setAttachRetryFiles(null);
+                  }}
                 >
                   <X size={10} weight="bold" />
                 </button>
@@ -5407,6 +5464,8 @@ export function AgentChatComposer({
               contextAttachments={contextAttachments}
               pendingImageAttachments={pendingImageAttachments}
               imagePreviewUrls={imagePreviewUrls}
+              attachmentSizes={attachmentSizes}
+              machinePin={composerMachineBinding}
               mode={surfaceMode}
               onRemove={handleRemoveAttachment}
               onRemoveContext={onRemoveContextAttachment}
diff --git a/apps/desktop/src/renderer/components/chat/AgentChatMessageList.tsx b/apps/desktop/src/renderer/components/chat/AgentChatMessageList.tsx
index 3b71f5df76..dccb2d5352 100644
--- a/apps/desktop/src/renderer/components/chat/AgentChatMessageList.tsx
+++ b/apps/desktop/src/renderer/components/chat/AgentChatMessageList.tsx
@@ -137,7 +137,7 @@ import { ChatUserMinimap } from "./ChatUserMinimap";
 import { promptHistoryEventKey } from "./chatPromptHistory";
 import { AgentCliAuthCard, type AgentCliAuthCardInfo } from "./AgentCliAuthCard";
 import { ChatContinuityRecoveryCard } from "./ChatContinuityRecoveryCard";
-import { classifyProviderFailure, ProviderFailureRecoveryCard } from "./ProviderFailureRecoveryCard";
+import { classifyProviderFailure, providerFailureEventId, ProviderFailureRecoveryCard } from "./ProviderFailureRecoveryCard";
 import { HighlightedCode } from "./CodeHighlighter";
 import { MosaicCard } from "./MosaicCard";
 import { MOSAIC_FENCE_LANGUAGE } from "../../../shared/chatMosaic";
@@ -3882,6 +3882,7 @@ function renderEvent(
           {recovery ? (
             <ProviderFailureRecoveryCard
               recovery={recovery}
+              eventId={providerFailureEventId(envelope.timestamp, event)}
               disabled={Boolean(options?.sessionTurnActive)}
               onRetry={options?.onRetryProviderFailure
                 ? () => options.onRetryProviderFailure!(event.turnId ?? null)
@@ -5368,8 +5369,11 @@ function AgentChatMessageListMain({
   laneId?: string | null;
   /**
    * Machine that owns this chat. Null = the machine this project tab is bound
-   * to. Threaded through so a filename clicked in a foreign chat is looked up
-   * on the machine that actually has the file.
+   * to. Used by the workspace-path opener, so a filename clicked in a foreign
+   * chat is looked up on the machine that actually has the file.
+   *
+   * Row-level consumers (attachment previews) do NOT take it from here: they
+   * read `useChatRuntimeScope()`, which the pane provides with this same value.
    */
   runtimePin?: OpenProjectBinding | null;
   sessionId?: string | null;
diff --git a/apps/desktop/src/renderer/components/chat/AgentChatPane.test.tsx b/apps/desktop/src/renderer/components/chat/AgentChatPane.test.tsx
index 7458536afa..19ac5d2338 100644
--- a/apps/desktop/src/renderer/components/chat/AgentChatPane.test.tsx
+++ b/apps/desktop/src/renderer/components/chat/AgentChatPane.test.tsx
@@ -79,6 +79,7 @@ import {
   writeChatCompanionUiState,
 } from "./chatCompanionUiState";
 import { CHAT_AUTH_RECOVERED_EVENT, CHAT_AUTH_RETRY_REJECTED_EVENT, CHAT_RETRY_AUTH_TURN_EVENT } from "./AgentCliAuthCard";
+import { formatAutoResumeTime } from "../../../shared/chatAutoResume";
 import {
   isChatSessionRetained,
   releaseAllRetainedChatSessions,
@@ -3981,6 +3982,298 @@ describe("AgentChatPane submit recovery", () => {
     });
   });
 
+  it("shows the pending auto-resume on the usage-limit card and cancels it on request", async () => {
+    const nextRunAt = "2026-07-10T20:30:00.000Z";
+    const session = buildSession("session-1", {
+      status: "idle",
+      awaitingInput: false,
+      scheduledWork: [{
+        id: "auto-resume:session-1",
+        sessionId: "session-1",
+        kind: "wakeup",
+        status: "scheduled",
+        title: "Auto-resume after usage limit reset",
+        prompt: "The provider usage limit has reset. Continue the interrupted task from where it stopped.",
+        nextRunAt,
+        createdAt: "2026-07-10T18:19:00.000Z",
+        durable: true,
+        cancellable: true,
+        source: "auto_resume_limit",
+      }],
+    });
+    const { cancelScheduledWork } = installAdeMocks({
+      sessions: [session],
+      eventHistory: {
+        sessionId: session.sessionId,
+        events: [
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T18:18:52.000Z",
+            sequence: 1,
+            event: { type: "user_message", text: "Keep shipping the fix." },
+          },
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T18:18:53.000Z",
+            sequence: 2,
+            event: {
+              type: "error" as const,
+              message: "Rate limited by Codex.",
+              turnId: "turn-limit",
+              errorInfo: { category: "rate_limit" as const, provider: "Codex" },
+            },
+          },
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T18:18:53.066Z",
+            sequence: 3,
+            event: { type: "done" as const, status: "failed" as const, turnId: "turn-limit", model: "gpt-5.4" },
+          },
+        ],
+        truncated: false,
+        sessionFound: true,
+      },
+    });
+
+    renderPane(session);
+
+    const banner = await screen.findByTestId("auto-resume-scheduled");
+    expect(banner.textContent).toContain("Auto-resume scheduled for");
+    expect(banner.textContent).toContain(formatAutoResumeTime(Date.parse(nextRunAt)));
+
+    fireEvent.click(screen.getByRole("button", { name: "Cancel auto-resume" }));
+    await waitFor(() => {
+      expect(cancelScheduledWork).toHaveBeenCalledWith({
+        sessionId: session.sessionId,
+        scheduleId: "auto-resume:session-1",
+      }, null);
+    });
+    await waitFor(() => expect(screen.queryByTestId("auto-resume-scheduled")).toBeNull());
+  });
+
+  function autoResumeSession(sessionId: string) {
+    return buildSession(sessionId, {
+      status: "idle",
+      awaitingInput: false,
+      scheduledWork: [{
+        id: `auto-resume:${sessionId}`,
+        sessionId,
+        kind: "wakeup",
+        status: "scheduled",
+        title: "Auto-resume after usage limit reset",
+        prompt: "The provider usage limit has reset. Continue the interrupted task from where it stopped.",
+        nextRunAt: "2026-07-10T20:30:00.000Z",
+        createdAt: "2026-07-10T18:19:00.000Z",
+        durable: true,
+        cancellable: true,
+        source: "auto_resume_limit",
+      }],
+    });
+  }
+
+  it("renders the usage-limit card for Codex's raw `usageLimitReached` errorInfo", async () => {
+    // The exact shape Codex forwards: no structured `errorInfo.category`, just
+    // the opaque provider string, and it spells the limit "usageLimitReached"
+    // — not "usageLimitExceeded". The host arms auto-resume off
+    // `isUsageLimitChatError`, which matches it; a renderer classifier that
+    // only knew "usagelimitexceeded"/"ratelimit" left this chat with a live
+    // schedule and no card, no anchor, and no way to cancel.
+    const session = autoResumeSession("session-1");
+    installAdeMocks({
+      sessions: [session],
+      eventHistory: {
+        sessionId: session.sessionId,
+        truncated: false,
+        sessionFound: true,
+        events: [
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T18:18:53.000Z",
+            sequence: 1,
+            event: {
+              type: "error" as const,
+              message: "You've hit your usage limit.",
+              turnId: "turn-limit",
+              errorInfo: "usageLimitReached",
+            },
+          },
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T18:18:53.066Z",
+            sequence: 2,
+            event: { type: "done" as const, status: "failed" as const, turnId: "turn-limit", model: "gpt-5.4" },
+          },
+        ],
+      },
+    });
+
+    renderPane(session);
+
+    expect(await screen.findByText("Usage limit")).toBeTruthy();
+    const banner = await screen.findByTestId("auto-resume-scheduled");
+    expect(banner.textContent).toContain("Auto-resume scheduled for");
+    expect(screen.getByRole("button", { name: "Cancel auto-resume" })).toBeTruthy();
+  });
+
+  it("offers the pending auto-resume only on the newest usage-limit card", async () => {
+    const session = autoResumeSession("session-1");
+    installAdeMocks({
+      sessions: [session],
+      eventHistory: {
+        sessionId: session.sessionId,
+        truncated: false,
+        sessionFound: true,
+        events: [
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-08T09:00:00.000Z",
+            sequence: 1,
+            event: {
+              type: "error" as const,
+              message: "Usage limit reached on Monday.",
+              turnId: "turn-monday",
+              errorInfo: { category: "rate_limit" as const, provider: "Codex" },
+            },
+          },
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-08T09:00:00.100Z",
+            sequence: 2,
+            event: { type: "done" as const, status: "failed" as const, turnId: "turn-monday", model: "gpt-5.4" },
+          },
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T18:18:53.000Z",
+            sequence: 3,
+            event: {
+              type: "error" as const,
+              message: "Usage limit reached on Friday.",
+              turnId: "turn-friday",
+              errorInfo: { category: "rate_limit" as const, provider: "Codex" },
+            },
+          },
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T18:18:53.066Z",
+            sequence: 4,
+            event: { type: "done" as const, status: "failed" as const, turnId: "turn-friday", model: "gpt-5.4" },
+          },
+        ],
+      },
+    });
+
+    renderPane(session);
+
+    // getByTestId throws on a second match, so this alone rules out the older
+    // card also advertising the one armed schedule.
+    const banner = await screen.findByTestId("auto-resume-scheduled");
+    const newestFailure = screen.getByText("Usage limit reached on Friday.");
+    expect(
+      newestFailure.compareDocumentPosition(banner) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("keeps the auto-resume off older cards that repeat the newest failure verbatim", async () => {
+    // The provider writes the same sentence every time the limit is hit, and
+    // `turnId` is optional on this path — the degenerate case where a weaker
+    // card identity would let a stale card alias the newest one.
+    const session = autoResumeSession("session-1");
+    const repeated = "Usage limit exceeded.";
+    installAdeMocks({
+      sessions: [session],
+      eventHistory: {
+        sessionId: session.sessionId,
+        truncated: false,
+        sessionFound: true,
+        events: [
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-08T09:00:00.000Z",
+            sequence: 1,
+            event: { type: "error" as const, message: repeated },
+          },
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T18:18:53.000Z",
+            sequence: 2,
+            event: { type: "error" as const, message: repeated },
+          },
+        ],
+      },
+    });
+
+    renderPane(session);
+
+    const banner = await screen.findByTestId("auto-resume-scheduled");
+    const failures = screen.getAllByText(repeated);
+    expect(failures).toHaveLength(2);
+    expect(
+      failures[1]!.compareDocumentPosition(banner) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("drops the scheduled-wake marker when the user retries an auto-resumed turn", async () => {
+    // Otherwise the replayed marker makes the host treat a user-initiated retry
+    // as the schedule's own turn and skip the cancel it promises.
+    const session = buildSession("session-1", { status: "idle", awaitingInput: false });
+    const { send } = installAdeMocks({
+      sessions: [session],
+      eventHistory: {
+        sessionId: session.sessionId,
+        truncated: false,
+        sessionFound: true,
+        events: [
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T20:30:00.000Z",
+            sequence: 1,
+            event: {
+              type: "user_message" as const,
+              text: "The provider usage limit has reset. Continue the interrupted task.",
+              turnId: "turn-resumed",
+              metadata: {
+                scheduledWake: {
+                  scheduleId: "auto-resume:session-1",
+                  kind: "wakeup" as const,
+                  firedAt: "2026-07-10T20:30:00.000Z",
+                },
+                hostContinuation: { reason: "provider_schedule_cleanup" as const },
+              },
+            },
+          },
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T20:30:04.000Z",
+            sequence: 2,
+            event: {
+              type: "error" as const,
+              message: "Usage limit exceeded again.",
+              turnId: "turn-resumed",
+              errorInfo: { category: "rate_limit" as const, provider: "Codex" },
+            },
+          },
+          {
+            sessionId: session.sessionId,
+            timestamp: "2026-07-10T20:30:04.066Z",
+            sequence: 3,
+            event: { type: "done" as const, status: "failed" as const, turnId: "turn-resumed", model: "gpt-5.4" },
+          },
+        ],
+      },
+    });
+
+    renderPane(session);
+
+    fireEvent.click(await screen.findByRole("button", { name: "Retry turn" }));
+    await waitFor(() => {
+      expect(send).toHaveBeenCalledWith(expect.objectContaining({
+        sessionId: session.sessionId,
+        text: "The provider usage limit has reset. Continue the interrupted task.",
+        metadata: { hostContinuation: { reason: "provider_schedule_cleanup" } },
+      }), null);
+    });
+  });
+
   it("skips steer messages during provider-failure retry and surfaces a rejected resend", async () => {
     const session = buildSession("session-1", { status: "idle", awaitingInput: false });
     const { send } = installAdeMocks({
diff --git a/apps/desktop/src/renderer/components/chat/AgentChatPane.tsx b/apps/desktop/src/renderer/components/chat/AgentChatPane.tsx
index bcc29d0771..71de1951f9 100644
--- a/apps/desktop/src/renderer/components/chat/AgentChatPane.tsx
+++ b/apps/desktop/src/renderer/components/chat/AgentChatPane.tsx
@@ -19,6 +19,7 @@ import {
   type AgentChatEvent,
   type AgentChatEventEnvelope,
   type AgentChatEventHistorySnapshot,
+  type AgentChatEventMetadata,
   type AgentChatContextAttachment,
   type AgentChatFileRef,
   type ChatMentionSuggestion,
@@ -134,6 +135,13 @@ import {
   ChatInfoHostContext,
   type MosaicRenderContext,
 } from "./AgentChatMessageList";
+import {
+  ChatAutoResumeContext,
+  classifyProviderFailure,
+  providerFailureEventId,
+  type ChatAutoResumeState,
+} from "./ProviderFailureRecoveryCard";
+import { isPendingAutoResumeScheduledWork } from "../../../shared/chatAutoResume";
 import { ChatWorkspacePathProvider, useWorkspacePathOpener } from "./chatWorkspacePaths";
 import { ChatRuntimeScopeProvider, useChatScopeDerivation } from "./ChatRuntimeScope";
 import { useSessionLifecycleSnapshot } from "../work/SessionLifecycleChips";
@@ -492,6 +500,19 @@ function hasChatActionsAutoOpenFired(storage: ChatActionsAutoOpenStorage, sessio
   return true;
 }
 
+/**
+ * Metadata minus the scheduled-wake marker, or `undefined` when nothing else
+ * was riding along — so a replay that had only the marker sends no metadata at
+ * all rather than an empty object the host has never seen.
+ */
+function withoutScheduledWake(metadata: AgentChatEventMetadata): AgentChatEventMetadata | undefined {
+  const rest: AgentChatEventMetadata = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (key !== "scheduledWake") rest[key] = value;
+  }
+  return Object.keys(rest).length ? rest : undefined;
+}
+
 function transcriptRecordText(record: Record<string, unknown> | null): string | null {
   if (!record) return null;
   for (const key of ["text", "summary", "description", "output", "command", "path", "query"] as const) {
@@ -7569,6 +7590,68 @@ export function AgentChatPane({
     });
   }, []);
 
+  // ADE's own auto-resume row for this chat, if the provider usage limit left
+  // one armed. Published as context so the failure card can offer a Cancel next
+  // to the retry affordances without drilling props through every event row.
+  // User- and agent-created schedules are excluded by the `auto_resume_limit`
+  // tag, so cancelling here can never drop a schedule the user asked for.
+  const pendingAutoResumeSchedule = useMemo(
+    () => (selectedSession?.scheduledWork ?? []).find(isPendingAutoResumeScheduledWork) ?? null,
+    [selectedSession?.scheduledWork],
+  );
+  // The schedule belongs to the failure that armed it, which is always the most
+  // recent usage-limit error in the transcript. Anchoring to it keeps every
+  // older usage-limit card in the same chat from advertising a live schedule.
+  // Gated on the schedule: without one there is nothing to anchor, and the walk
+  // below is a full-transcript scan that would otherwise re-run on every event
+  // append for the overwhelmingly common case of a chat with no armed resume.
+  const latestRateLimitFailureEventId = useMemo(() => {
+    if (!pendingAutoResumeSchedule) return null;
+    for (let index = selectedEventsForDisplay.length - 1; index >= 0; index -= 1) {
+      const envelope = selectedEventsForDisplay[index];
+      const event = envelope?.event;
+      if (!envelope || event?.type !== "error") continue;
+      if (classifyProviderFailure(event)?.kind !== "rate_limit") continue;
+      return providerFailureEventId(envelope.timestamp, event);
+    }
+    return null;
+  }, [pendingAutoResumeSchedule, selectedEventsForDisplay]);
+  const autoResumeContextValue = useMemo<ChatAutoResumeState>(() => {
+    if (!selectedSessionId || !pendingAutoResumeSchedule) return null;
+    const scheduleId = pendingAutoResumeSchedule.id;
+    const sessionId = selectedSessionId;
+    return {
+      scheduleId,
+      nextRunAt: pendingAutoResumeSchedule.nextRunAt ?? null,
+      anchorEventId: latestRateLimitFailureEventId,
+      cancel: async () => {
+        try {
+          const result = await window.ade.agentChat.cancelScheduledWork(
+            { sessionId, scheduleId },
+            chatRuntimePinRef.current,
+          );
+          patchSessionSummary(sessionId, {
+            scheduledWork: (selectedSession?.scheduledWork ?? []).filter((item) =>
+              item.id !== scheduleId || !(
+                result.providerCancellationConfirmed || result.schedule.status === "cancelled"
+              )),
+          });
+          scheduleSessionsRefresh();
+          return null;
+        } catch (cancelError) {
+          return cancelError instanceof Error ? cancelError.message : String(cancelError);
+        }
+      },
+    };
+  }, [
+    latestRateLimitFailureEventId,
+    patchSessionSummary,
+    pendingAutoResumeSchedule,
+    scheduleSessionsRefresh,
+    selectedSession?.scheduledWork,
+    selectedSessionId,
+  ]);
+
   useLayoutEffect(() => {
     if (!isTileVisible) return undefined;
     const unsubscribe = window.ade.agentChat.onEvent((envelope) => {
@@ -8226,10 +8309,16 @@ export function AgentChatPane({
     const attachments = Array.isArray(userEvent.attachments) ? userEvent.attachments : [];
     const contextAttachments = Array.isArray(userEvent.contextAttachments) ? userEvent.contextAttachments : [];
     const metadata = userEvent.metadata;
+    // The host skips its auto-resume cancel for any send carrying
+    // `scheduledWake` — that is how the auto-resume's own turn avoids
+    // cancelling the schedule it was fired by. Replaying that marker would make
+    // a user-initiated retry inherit the exemption and leave the schedule
+    // armed, contradicting the notice that says retrying cancels it.
+    const replayMetadata = metadata?.scheduledWake ? withoutScheduledWake(metadata) : metadata;
     const replayContext = {
       ...(attachments.length ? { attachments } : {}),
       ...(contextAttachments.length ? { contextAttachments } : {}),
-      ...(metadata !== undefined ? { metadata } : {}),
+      ...(replayMetadata !== undefined ? { metadata: replayMetadata } : {}),
     };
     try {
       submitInFlightRef.current = true;
@@ -13965,6 +14054,7 @@ export function AgentChatPane({
                         may render here. PersonalChatsPage provides no such context. */}
                     {!cloudConversationPending && !(cloudHydrateFailed && !chatHasMessages) ? (
                     <ChatInfoHostContext.Provider value={true}>
+                    <ChatAutoResumeContext.Provider value={autoResumeContextValue}>
                       <AgentChatMessageList
                         key={renderedSessionId ?? "chat-draft"}
                         events={subagentView ? subagentEventsForDisplay : selectedEventsForDisplay}
@@ -14040,6 +14130,7 @@ export function AgentChatPane({
                         allowLocalProofArtifactProtocol={!isRemoteChat}
                         onOpenProofDrawer={subagentView ? undefined : openProofDrawer}
                       />
+                    </ChatAutoResumeContext.Provider>
                     </ChatInfoHostContext.Provider>
                     ) : null}
                     {!appPanelOpen ? composerNoticeOverlay : null}
diff --git a/apps/desktop/src/renderer/components/chat/ChatAttachmentPreviewModal.tsx b/apps/desktop/src/renderer/components/chat/ChatAttachmentPreviewModal.tsx
new file mode 100644
index 0000000000..86623ad898
--- /dev/null
+++ b/apps/desktop/src/renderer/components/chat/ChatAttachmentPreviewModal.tsx
@@ -0,0 +1,234 @@
+import { useEffect, useMemo, useRef, useState, type KeyboardEvent } from "react";
+import { createPortal } from "react-dom";
+import { X } from "@phosphor-icons/react";
+import type { OpenProjectBinding } from "../../../shared/types/core";
+import { createMonacoModelRegistry } from "../files/monacoModelRegistry";
+import { resolveLanguageId } from "../files/filePresentation";
+import { createPinnedFilesApi } from "../files/v2/pinnedFilesApi";
+import { editorTabId, type EditorTab } from "../files/v2/editorGroupsStore";
+import { resolveViewerKind } from "../files/v2/viewerRegistry";
+import { ViewerHost } from "../files/v2/ViewerHost";
+import {
+  resolveAttachmentWorkspaceTarget,
+  type AttachmentViewerTarget,
+} from "./attachmentViewerTarget";
+
+type ResolveState =
+  | { status: "loading" }
+  | { status: "ready"; target: AttachmentViewerTarget }
+  | { status: "error"; message: string };
+
+/**
+ * A staged or sent chat attachment, opened full-size with the Files tab's own
+ * viewer platform.
+ *
+ * Reuse, not a fork: the viewer is chosen by `resolveViewerKind` and rendered
+ * by `ViewerHost`, so a PDF, a CSV, a video, an office document and a source
+ * file all render here exactly as they do in Files, and a viewer added there
+ * shows up here with no change. The only thing this component owns is the
+ * dialog chrome and locating the attachment inside a workspace.
+ *
+ * Editing is deliberately out of scope. `ViewerHost` derives `readOnly` from
+ * whether the payload round-trips as text, so a code or markdown attachment
+ * would technically be writable; the popup never surfaces a save affordance and
+ * an attachment is a snapshot the user handed to an agent, not a project file.
+ */
+export function ChatAttachmentPreviewModal({
+  attachmentPath,
+  title,
+  pin,
+  fallbackImageDataUrl,
+  onClose,
+}: {
+  attachmentPath: string;
+  title: string;
+  pin: OpenProjectBinding | null;
+  /**
+   * Preview bytes the chip already holds for an image attachment. Used only
+   * when workspace resolution fails — an attachment staged with no project
+   * open lands in system temp, outside every workspace, and would otherwise
+   * lose a preview that used to work.
+   */
+  fallbackImageDataUrl?: string | null;
+  onClose: () => void;
+}) {
+  const files = useMemo(() => createPinnedFilesApi(pin), [pin]);
+  const registryRef = useRef(createMonacoModelRegistry());
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const closeButtonRef = useRef<HTMLButtonElement | null>(null);
+  const [state, setState] = useState<ResolveState>({ status: "loading" });
+
+  useEffect(() => {
+    let cancelled = false;
+    setState({ status: "loading" });
+    // `Promise.resolve().then` so a bridge that throws synchronously (no
+    // `window.ade.files` at all) becomes the same error state as a rejected
+    // read, instead of escaping the effect and taking the transcript down.
+    Promise.resolve()
+      .then(() => files.listWorkspaces({}))
+      .then((workspaces) => {
+        if (cancelled) return;
+        const target = resolveAttachmentWorkspaceTarget(attachmentPath, workspaces);
+        if (!target) {
+          setState({
+            status: "error",
+            message: "This attachment is outside every open workspace, so it can't be previewed here.",
+          });
+          return;
+        }
+        setState({ status: "ready", target });
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        setState({
+          status: "error",
+          message: error instanceof Error ? error.message : String(error),
+        });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [files, attachmentPath]);
+
+  // Return focus where it came from, pull it into the dialog, and lock body
+  // scroll — same contract as the image lightbox this replaces.
+  useEffect(() => {
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    closeButtonRef.current?.focus();
+    const previousBodyOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = previousBodyOverflow;
+      if (previouslyFocused && typeof previouslyFocused.focus === "function") {
+        previouslyFocused.focus();
+      }
+    };
+  }, []);
+
+  const registry = registryRef.current;
+  // The popup owns its Monaco models; nothing else shares this registry, so
+  // closing it must free them or every preview leaks one model per file.
+  useEffect(() => () => registry.disposeAll(), [registry]);
+
+  const tab: EditorTab | null = useMemo(() => {
+    if (state.status !== "ready") return null;
+    const { workspaceId, relativePath } = state.target;
+    return {
+      id: editorTabId(workspaceId, relativePath),
+      workspaceId,
+      laneId: null,
+      path: relativePath,
+      title,
+      viewerKind: resolveViewerKind({ path: relativePath }),
+      languageId: resolveLanguageId(relativePath),
+      preview: true,
+      pinned: false,
+    };
+  }, [state, title]);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === "Escape") {
+      event.stopPropagation();
+      onClose();
+      return;
+    }
+    if (event.key !== "Tab") return;
+    const root = containerRef.current;
+    if (!root) return;
+    const focusables = Array.from(
+      root.querySelectorAll<HTMLElement>(
+        'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])',
+      ),
+    ).filter((element) => element.tabIndex >= 0);
+    if (focusables.length === 0) {
+      event.preventDefault();
+      closeButtonRef.current?.focus();
+      return;
+    }
+    const first = focusables[0]!;
+    const last = focusables[focusables.length - 1]!;
+    const active = document.activeElement as HTMLElement | null;
+    if (event.shiftKey) {
+      if (active === first || !active || !root.contains(active)) {
+        event.preventDefault();
+        last.focus();
+      }
+    } else if (active === last || !active || !root.contains(active)) {
+      event.preventDefault();
+      first.focus();
+    }
+  };
+
+  return createPortal(
+    <div
+      ref={containerRef}
+      className="fixed inset-0 z-[120] flex items-center justify-center bg-black/75 p-8"
+      role="dialog"
+      aria-modal="true"
+      aria-label={title}
+      data-testid="chat-attachment-preview"
+      onClick={onClose}
+      onKeyDown={handleKeyDown}
+    >
+      <div
+        className="relative flex h-[min(85vh,900px)] w-[min(92vw,1200px)] flex-col overflow-hidden rounded-md border border-white/10 bg-[color:var(--surface-1,#111)]"
+        onClick={(event) => event.stopPropagation()}
+      >
+        <div className="flex shrink-0 items-center gap-2 border-b border-white/8 px-3 py-2">
+          <span className="min-w-0 flex-1 truncate text-[11px] text-fg/80" title={attachmentPath}>
+            {title}
+          </span>
+          <button
+            ref={closeButtonRef}
+            type="button"
+            className="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded border border-white/10 bg-black/40 text-white/75 transition-colors hover:bg-black hover:text-white"
+            title="Close"
+            aria-label="Close"
+            onClick={onClose}
+          >
+            <X size={13} weight="bold" />
+          </button>
+        </div>
+        <div className="min-h-0 flex-1">
+          {state.status === "loading" ? (
+            <Centered>Opening {title}…</Centered>
+          ) : state.status === "error" ? (
+            fallbackImageDataUrl ? (
+              <div className="flex h-full items-center justify-center p-4">
+                <img
+                  src={fallbackImageDataUrl}
+                  alt={title}
+                  className="max-h-full max-w-full rounded object-contain"
+                />
+              </div>
+            ) : (
+              <Centered tone="danger">{state.message}</Centered>
+            )
+          ) : tab ? (
+            <ViewerHost
+              workspaceId={state.target.workspaceId}
+              files={files}
+              rootPath={state.target.rootPath}
+              tab={tab}
+              theme="dark"
+              registry={registry}
+            />
+          ) : null}
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+function Centered({ children, tone }: { children: React.ReactNode; tone?: "danger" }) {
+  return (
+    <div
+      className={`flex h-full items-center justify-center p-6 text-center text-sm ${
+        tone === "danger" ? "text-red-300/80" : "text-fg/55"
+      }`}
+    >
+      {children}
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/components/chat/ChatAttachmentTray.test.tsx b/apps/desktop/src/renderer/components/chat/ChatAttachmentTray.test.tsx
index b5fde6fc93..b40c6d6154 100644
--- a/apps/desktop/src/renderer/components/chat/ChatAttachmentTray.test.tsx
+++ b/apps/desktop/src/renderer/components/chat/ChatAttachmentTray.test.tsx
@@ -43,8 +43,12 @@ describe("ChatAttachmentTray", () => {
   const getImageDataUrl = vi.fn();
   const getRuntimeImageDataUrl = vi.fn();
   const writeClipboardImage = vi.fn();
+  const listWorkspaces = vi.fn();
 
   beforeEach(() => {
+    listWorkspaces.mockResolvedValue([
+      { id: "primary", kind: "primary", laneId: null, name: "ADE", branchRef: null, rootPath: "/tmp", isReadOnlyByDefault: false, mobileReadOnly: true },
+    ]);
     getImageDataUrl.mockResolvedValue({ dataUrl: "data:image/png;base64,abc123" });
     getRuntimeImageDataUrl.mockResolvedValue({ dataUrl: "data:image/png;base64,runtime123" });
     writeClipboardImage.mockResolvedValue(undefined);
@@ -58,6 +62,12 @@ describe("ChatAttachmentTray", () => {
         agentChat: {
           getImageDataUrl: getRuntimeImageDataUrl,
         },
+        files: {
+          listWorkspaces,
+          readFile: vi.fn(async () => {
+            throw new Error("not needed for image previews");
+          }),
+        },
       },
     });
   });
@@ -82,7 +92,8 @@ describe("ChatAttachmentTray", () => {
 
     fireEvent.click(openButton);
 
-    expect(screen.getByRole("dialog", { name: "screenshot.png" })).toBeTruthy();
+    // The preview popup is code-split, so it resolves a tick after the click.
+    expect(await screen.findByRole("dialog", { name: "screenshot.png" })).toBeTruthy();
   });
 
   it("renders seeded image previews without reading the file back", () => {
@@ -201,7 +212,9 @@ describe("ChatAttachmentTray", () => {
     expect(onFocusPrompt).toHaveBeenCalledTimes(2);
   });
 
-  it("keeps non-image attachments as filename chips", () => {
+  it("renders non-image attachments as openable filename chips", () => {
+    // Non-image attachments used to be inert filename pills. Every attachment
+    // now opens in the universal preview, so the chip is the affordance.
     render(
       <ChatAttachmentTray
         attachments={[{ path: "/tmp/context.txt", type: "file" }]}
@@ -210,7 +223,7 @@ describe("ChatAttachmentTray", () => {
     );
 
     expect(screen.getByText("context.txt")).toBeTruthy();
-    expect(screen.queryByRole("button", { name: "Open context.txt" })).toBeNull();
+    expect(screen.getByRole("button", { name: "Open context.txt" })).toBeTruthy();
   });
 
   it("renders image URL attachments as URL chips without loading a local preview", () => {
@@ -291,3 +304,125 @@ describe("ChatAttachmentTray", () => {
     expect(onRemoveContext).toHaveBeenCalledWith("github:ade/app#42");
   });
 });
+
+describe("ChatAttachmentTray file chips", () => {
+  const listWorkspaces = vi.fn();
+  const readFile = vi.fn();
+
+  beforeEach(() => {
+    readFile.mockResolvedValue({
+      path: ".ade/attachments/9f3a.csv",
+      content: "a,b\n1,2\n",
+      encoding: "utf-8",
+      size: 8,
+      totalSize: 8,
+      isBinary: false,
+      isPartial: false,
+    });
+    listWorkspaces.mockResolvedValue([
+      {
+        id: "primary",
+        kind: "primary",
+        laneId: null,
+        name: "ADE",
+        branchRef: null,
+        rootPath: "/Users/a/Projects/ADE",
+        isReadOnlyByDefault: false,
+        mobileReadOnly: true,
+      },
+    ]);
+    Object.defineProperty(window, "ade", {
+      configurable: true,
+      value: { app: {}, agentChat: {}, files: { listWorkspaces, readFile } },
+    });
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.clearAllMocks();
+  });
+
+  it("renders a non-image attachment as a chip with its name and size", () => {
+    render(
+      <ChatAttachmentTray
+        attachments={[{ path: "/Users/a/Projects/ADE/.ade/attachments/9f3a.pdf", type: "file" }]}
+        attachmentSizes={{ "/Users/a/Projects/ADE/.ade/attachments/9f3a.pdf": 2_411_724 }}
+        mode="standard"
+        onRemove={() => undefined}
+      />,
+    );
+
+    const chip = screen.getByTestId("chat-file-attachment-chip");
+    expect(chip.textContent).toContain("9f3a.pdf");
+    expect(chip.textContent).toContain("2.3 MB");
+    expect(screen.getByRole("button", { name: "Remove 9f3a.pdf" })).toBeTruthy();
+  });
+
+  it("omits the size when the caller does not know it", () => {
+    render(
+      <ChatAttachmentTray
+        attachments={[{ path: "/Users/a/Projects/ADE/.ade/attachments/notes.txt", type: "file" }]}
+        mode="standard"
+      />,
+    );
+    const chip = screen.getByTestId("chat-file-attachment-chip");
+    expect(chip.textContent).toContain("notes.txt");
+    expect(chip.textContent).not.toMatch(/\d+(\.\d+)? (B|KB|MB|GB)/);
+  });
+
+  it("middle-truncates a long filename so the extension survives", () => {
+    render(
+      <ChatAttachmentTray
+        attachments={[{
+          path: "/Users/a/Projects/ADE/.ade/attachments/quarterly-engineering-report-final-v7.xlsx",
+          type: "file",
+        }]}
+        mode="standard"
+      />,
+    );
+    const chip = screen.getByTestId("chat-file-attachment-chip");
+    expect(chip.textContent).toContain("…");
+    expect(chip.textContent).toContain(".xlsx");
+  });
+
+  it("removes a chip with Delete and Backspace", () => {
+    const onRemove = vi.fn();
+    const path = "/Users/a/Projects/ADE/.ade/attachments/a.zip";
+    render(
+      <ChatAttachmentTray attachments={[{ path, type: "file" }]} mode="standard" onRemove={onRemove} />,
+    );
+    fireEvent.keyDown(screen.getByTestId("chat-file-attachment-chip"), { key: "Delete" });
+    fireEvent.keyDown(screen.getByTestId("chat-file-attachment-chip"), { key: "Backspace" });
+    expect(onRemove).toHaveBeenCalledTimes(2);
+    expect(onRemove).toHaveBeenCalledWith(path);
+  });
+
+  it("opens the preview popup on Enter and closes it on Escape", async () => {
+    render(
+      <ChatAttachmentTray
+        attachments={[{ path: "/Users/a/Projects/ADE/.ade/attachments/9f3a.csv", type: "file" }]}
+        mode="standard"
+      />,
+    );
+    fireEvent.keyDown(screen.getByTestId("chat-file-attachment-chip"), { key: "Enter" });
+
+    const dialog = await screen.findByRole("dialog", { name: "9f3a.csv" });
+    await waitFor(() => expect(listWorkspaces).toHaveBeenCalled());
+
+    fireEvent.keyDown(dialog, { key: "Escape" });
+    await waitFor(() => expect(screen.queryByRole("dialog", { name: "9f3a.csv" })).toBeNull());
+  });
+
+  it("closes the preview popup on a click outside", async () => {
+    render(
+      <ChatAttachmentTray
+        attachments={[{ path: "/Users/a/Projects/ADE/.ade/attachments/9f3a.csv", type: "file" }]}
+        mode="standard"
+      />,
+    );
+    fireEvent.click(screen.getByTestId("chat-file-attachment-chip"));
+    const dialog = await screen.findByRole("dialog", { name: "9f3a.csv" });
+    fireEvent.click(dialog);
+    await waitFor(() => expect(screen.queryByRole("dialog", { name: "9f3a.csv" })).toBeNull());
+  });
+});
diff --git a/apps/desktop/src/renderer/components/chat/ChatAttachmentTray.tsx b/apps/desktop/src/renderer/components/chat/ChatAttachmentTray.tsx
index 6877f27730..e58cca4c27 100644
--- a/apps/desktop/src/renderer/components/chat/ChatAttachmentTray.tsx
+++ b/apps/desktop/src/renderer/components/chat/ChatAttachmentTray.tsx
@@ -1,12 +1,54 @@
-import { forwardRef, useEffect, useRef, useState, type KeyboardEvent, type MouseEvent } from "react";
-import { createPortal } from "react-dom";
-import { Copy, File, GithubLogo, Globe, Image, X } from "@phosphor-icons/react";
+import { Suspense, forwardRef, lazy, useEffect, useState, type KeyboardEvent, type MouseEvent, type ReactNode } from "react";
+import { Copy, GithubLogo, Globe, Image, X } from "@phosphor-icons/react";
 import type { AgentChatContextAttachment, AgentChatFileRef, ChatSurfaceMode } from "../../../shared/types";
+import type { OpenProjectBinding } from "../../../shared/types/core";
 import { chatContextAttachmentKey } from "../../../shared/chatContextAttachments";
+import { formatAttachmentSize } from "../../../shared/chatAttachmentLimits";
 import { githubIssueIdentifier } from "../../../shared/laneGitHubIssue";
 import { cn } from "../ui/cn";
+import { getFileIcon } from "../files/filePresentation";
 import { GITHUB_BRAND } from "../lanes/githubBrand";
 import { LinearMark, LINEAR_BRAND } from "../lanes/linearBrand";
+/**
+ * The preview popup pulls in the whole Files viewer platform — Monaco, the PDF
+ * and document renderers, the CSV grid. That is a large amount of code for a
+ * surface most chats never open, and the composer is on the app's hottest
+ * render path, so it loads on first open rather than with the tray.
+ */
+const ChatAttachmentPreviewModal = lazy(() => import("./ChatAttachmentPreviewModal")
+  .then((module) => ({ default: module.ChatAttachmentPreviewModal })));
+
+/**
+ * The open-on-demand preview popup every attachment chip shares, so one popup
+ * renders the whole set rather than each chip growing its own.
+ *
+ * `fallbackImageDataUrl` is the only thing the two callers differ on: an image
+ * thumbnail has already loaded bytes, and those are the only way to render an
+ * attachment that lives outside every workspace, where the Files viewers
+ * cannot reach it. A file chip has no such bytes and passes nothing.
+ */
+function useAttachmentPreview(args: {
+  path: string;
+  title: string;
+  pin: OpenProjectBinding | null;
+  fallbackImageDataUrl?: string | null;
+}): { open: () => void; element: ReactNode } {
+  const [expanded, setExpanded] = useState(false);
+  return {
+    open: () => setExpanded(true),
+    element: expanded ? (
+      <Suspense fallback={null}>
+        <ChatAttachmentPreviewModal
+          attachmentPath={args.path}
+          title={args.title}
+          pin={args.pin}
+          fallbackImageDataUrl={args.fallbackImageDataUrl}
+          onClose={() => setExpanded(false)}
+        />
+      </Suspense>
+    ) : null,
+  };
+}
 
 function attachmentName(path: string): string {
   // Split on both POSIX and Windows separators so a Windows path
@@ -16,6 +58,19 @@ function attachmentName(path: string): string {
   return segments.pop() || path;
 }
 
+/**
+ * Keep the head and the extension, elide the middle. A file chip's two useful
+ * ends are what the user named it and what type it is; truncating from the
+ * right throws the second one away, which is exactly the part that tells them
+ * whether they attached the PDF or the spreadsheet.
+ */
+function middleTruncateFilename(name: string, maxLength = 32): string {
+  if (name.length <= maxLength) return name;
+  const head = Math.ceil((maxLength - 1) / 2);
+  const tail = Math.floor((maxLength - 1) / 2);
+  return `${name.slice(0, head)}…${name.slice(name.length - tail)}`;
+}
+
 export type ChatAttachmentPendingImage = {
   id: string;
   name: string;
@@ -272,20 +327,27 @@ function ImageAttachmentPreview({
   attachment,
   toneClassName,
   initialPreviewUrl,
+  machinePin,
   onRemove,
   onFocusPrompt,
 }: {
   attachment: AgentChatFileRef;
   toneClassName: string;
   initialPreviewUrl?: string | null;
+  machinePin: OpenProjectBinding | null;
   onRemove?: (path: string) => void;
   onFocusPrompt?: () => void;
 }) {
   const [dataUrl, setDataUrl] = useState<string | null>(initialPreviewUrl ?? null);
   const [previewFailed, setPreviewFailed] = useState(false);
-  const [expanded, setExpanded] = useState(false);
   const [copyState, setCopyState] = useState<"idle" | "copied" | "failed">("idle");
   const name = attachmentName(attachment.path);
+  const preview = useAttachmentPreview({
+    path: attachment.path,
+    title: name,
+    pin: machinePin,
+    fallbackImageDataUrl: dataUrl,
+  });
 
   useEffect(() => {
     let cancelled = false;
@@ -372,9 +434,7 @@ function ImageAttachmentPreview({
             onRemove: onRemove ? () => onRemove(attachment.path) : undefined,
             onFocusPrompt,
           })}
-          onClick={() => {
-            if (dataUrl) setExpanded(true);
-          }}
+          onClick={preview.open}
         >
           {dataUrl ? (
             <img src={dataUrl} alt={name} className="h-full w-full object-cover" draggable={false} />
@@ -415,13 +475,7 @@ function ImageAttachmentPreview({
           ) : null}
         </span>
       </div>
-      {expanded && dataUrl ? (
-        <ImageLightbox
-          name={name}
-          dataUrl={dataUrl}
-          onClose={() => setExpanded(false)}
-        />
-      ) : null}
+      {preview.element}
     </>
   );
 }
@@ -483,6 +537,93 @@ function PendingImageAttachmentPreview({
   );
 }
 
+/**
+ * Every non-image attachment, as one chip: type icon, middle-truncated name,
+ * human size when known, remove ×.
+ *
+ * Size is shown only when the caller knows it. The composer does — it staged
+ * the file and has the `File.size` — but a chip re-rendered from transcript
+ * history has only a path, and statting every attachment of every past message
+ * would be a per-chip round trip (two, on a remote machine) to render one
+ * label. The chip degrades to name-only rather than paying that, or worse,
+ * flashing a number in late.
+ */
+function FileAttachmentChip({
+  attachment,
+  toneClassName,
+  sizeBytes,
+  machinePin,
+  onRemove,
+  onFocusPrompt,
+}: {
+  attachment: AgentChatFileRef;
+  toneClassName: string;
+  sizeBytes?: number;
+  machinePin: OpenProjectBinding | null;
+  onRemove?: (path: string) => void;
+  onFocusPrompt?: () => void;
+}) {
+  const name = attachmentName(attachment.path);
+  const preview = useAttachmentPreview({ path: attachment.path, title: name, pin: machinePin });
+  const onOpen = preview.open;
+  const { icon: Icon, color } = getFileIcon(name);
+  const sizeLabel = typeof sizeBytes === "number" && Number.isFinite(sizeBytes)
+    ? formatAttachmentSize(sizeBytes)
+    : null;
+  return (
+    <>
+    <span
+      className={cn(
+        "ade-liquid-glass-pill group inline-flex max-w-full cursor-pointer items-center gap-2 rounded-[var(--chat-radius-pill)] border px-2.5 py-1.5 transition-colors focus:outline-none focus:ring-1 focus:ring-white/25",
+        toneClassName,
+      )}
+      title={sizeLabel ? `${name} — ${sizeLabel}` : name}
+      role="button"
+      aria-label={`Open ${name}`}
+      tabIndex={0}
+      data-testid="chat-file-attachment-chip"
+      data-chat-image-attachment-focus-target="true"
+      onClick={onOpen}
+      onKeyDown={(event) => {
+        if (event.key === "Enter" || event.key === " ") {
+          event.preventDefault();
+          event.stopPropagation();
+          onOpen();
+          return;
+        }
+        handleImageAttachmentKeyDown(event, {
+          onRemove: onRemove ? () => onRemove(attachment.path) : undefined,
+          onFocusPrompt,
+        });
+      }}
+    >
+      <Icon size={13} weight="bold" style={{ color }} className="shrink-0" />
+      <span className="min-w-0 max-w-[240px] truncate text-[11px] font-medium text-fg/85">
+        {middleTruncateFilename(name)}
+      </span>
+      {sizeLabel ? (
+        <span className="shrink-0 text-[10px] tabular-nums text-current/45">{sizeLabel}</span>
+      ) : null}
+      {onRemove ? (
+        <button
+          type="button"
+          className="shrink-0 rounded-full text-current/45 transition-colors hover:bg-white/[0.06] hover:text-current"
+          title={`Remove ${name}`}
+          aria-label={`Remove ${name}`}
+          onClick={(event) => {
+            event.stopPropagation();
+            onRemove(attachment.path);
+          }}
+        >
+          <X size={10} weight="bold" />
+        </button>
+      ) : null}
+    </span>
+    {preview.element}
+    </>
+  );
+}
+
 function ImageUrlAttachmentChip({
   path,
   url,
@@ -543,110 +684,23 @@ function ImageUrlAttachmentChip({
   );
 }
 
-function ImageLightbox({
-  name,
-  dataUrl,
-  onClose,
-}: {
-  name: string;
-  dataUrl: string;
-  onClose: () => void;
-}) {
-  const closeButtonRef = useRef<HTMLButtonElement | null>(null);
-  const containerRef = useRef<HTMLDivElement | null>(null);
-
-  // Save the element that opened us so focus can return there on close,
-  // pull focus into the dialog on mount, and lock body scroll while open so
-  // the wheel doesn't move the page behind the overlay.
-  useEffect(() => {
-    const previouslyFocused = document.activeElement as HTMLElement | null;
-    closeButtonRef.current?.focus();
-    const previousBodyOverflow = document.body.style.overflow;
-    document.body.style.overflow = "hidden";
-    return () => {
-      document.body.style.overflow = previousBodyOverflow;
-      if (previouslyFocused && typeof previouslyFocused.focus === "function") {
-        previouslyFocused.focus();
-      }
-    };
-  }, []);
-
-  // Close on Escape and trap Tab / Shift-Tab inside the dialog. The dialog
-  // contains exactly the close button as a focusable element, so the trap
-  // pins focus there in either direction.
-  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
-    if (event.key === "Escape") {
-      event.stopPropagation();
-      onClose();
-      return;
-    }
-    if (event.key !== "Tab") return;
-    const root = containerRef.current;
-    if (!root) return;
-    const focusables = Array.from(
-      root.querySelectorAll<HTMLElement>(
-        'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])',
-      ),
-    ).filter((element) => element.tabIndex >= 0);
-    if (focusables.length === 0) {
-      event.preventDefault();
-      closeButtonRef.current?.focus();
-      return;
-    }
-    const first = focusables[0]!;
-    const last = focusables[focusables.length - 1]!;
-    const active = document.activeElement as HTMLElement | null;
-    if (event.shiftKey) {
-      if (active === first || !active || !root.contains(active)) {
-        event.preventDefault();
-        last.focus();
-      }
-    } else {
-      if (active === last || !active || !root.contains(active)) {
-        event.preventDefault();
-        first.focus();
-      }
-    }
-  };
-
-  return createPortal(
-    <div
-      ref={containerRef}
-      className="fixed inset-0 z-[120] flex items-center justify-center bg-black/75 p-8"
-      role="dialog"
-      aria-modal="true"
-      aria-label={name}
-      onClick={onClose}
-      onKeyDown={handleKeyDown}
-    >
-      <div className="relative max-h-full max-w-full">
-        <button
-          ref={closeButtonRef}
-          type="button"
-          className="absolute right-2 top-2 inline-flex h-7 w-7 items-center justify-center rounded border border-white/10 bg-black/70 text-white/80 transition-colors hover:bg-black hover:text-white"
-          title="Close"
-          aria-label="Close"
-          onClick={onClose}
-        >
-          <X size={14} weight="bold" />
-        </button>
-        <img
-          src={dataUrl}
-          alt={name}
-          className="max-h-[calc(100vh-4rem)] max-w-[calc(100vw-4rem)] rounded-md object-contain"
-          onClick={(event) => event.stopPropagation()}
-        />
-      </div>
-    </div>,
-    document.body,
-  );
-}
-
 type ChatAttachmentTrayProps = {
   attachments: AgentChatFileRef[];
   contextAttachments?: AgentChatContextAttachment[];
   pendingImageAttachments?: ChatAttachmentPendingImage[];
   imagePreviewUrls?: Record<string, string | undefined>;
+  /**
+   * Staged sizes by path. The composer knows them from the `File` it staged;
+   * a tray rendered from transcript history does not, and chips render
+   * name-only there rather than statting every past attachment.
+   */
+  attachmentSizes?: Record<string, number | undefined>;
+  /**
+   * Machine that owns these attachments. The preview popup reads the file
+   * through the Files API with this pin, so an attachment staged on a paired
+   * host opens from that host instead of resolving a same-named path here.
+   */
+  machinePin?: OpenProjectBinding | null;
   mode: ChatSurfaceMode;
   onRemove?: (path: string) => void;
   onRemoveContext?: (key: string) => void;
@@ -661,6 +715,8 @@ export const ChatAttachmentTray = forwardRef<HTMLDivElement, ChatAttachmentTrayP
   contextAttachments = [],
   pendingImageAttachments = [],
   imagePreviewUrls = {},
+  attachmentSizes = {},
+  machinePin = null,
   mode,
   onRemove,
   onRemoveContext,
@@ -733,33 +789,22 @@ export const ChatAttachmentTray = forwardRef<HTMLDivElement, ChatAttachmentTrayP
               attachment={attachment}
               toneClassName={chipTone}
               initialPreviewUrl={imagePreviewUrls[attachment.path]}
+              machinePin={machinePin}
               onRemove={onRemove}
               onFocusPrompt={onFocusPrompt}
             />
           );
         }
         return (
-          <span
+          <FileAttachmentChip
             key={attachment.path}
-            className={cn(
-              "ade-liquid-glass-pill group inline-flex max-w-full items-center gap-2 rounded-[var(--chat-radius-pill)] px-2.5 py-1.5 font-mono text-[10px] transition-colors",
-              chipTone,
-            )}
-          >
-            <File size={12} weight="bold" />
-            <span className="max-w-[260px] truncate">{attachmentName(attachment.path)}</span>
-            {onRemove ? (
-              <button
-                type="button"
-                className="rounded-full text-current/45 transition-colors hover:bg-white/[0.06] hover:text-current"
-                title={`Remove ${attachmentName(attachment.path)}`}
-                aria-label={`Remove ${attachmentName(attachment.path)}`}
-                onClick={() => onRemove(attachment.path)}
-              >
-                <X size={10} weight="bold" />
-              </button>
-            ) : null}
-          </span>
+            attachment={attachment}
+            toneClassName={chipTone}
+            sizeBytes={attachmentSizes[attachment.path]}
+            machinePin={machinePin}
+            onRemove={onRemove}
+            onFocusPrompt={onFocusPrompt}
+          />
         );
       })}
     </div>
diff --git a/apps/desktop/src/renderer/components/chat/ProviderFailureRecoveryCard.tsx b/apps/desktop/src/renderer/components/chat/ProviderFailureRecoveryCard.tsx
index bad56ac7c0..1a8db28a17 100644
--- a/apps/desktop/src/renderer/components/chat/ProviderFailureRecoveryCard.tsx
+++ b/apps/desktop/src/renderer/components/chat/ProviderFailureRecoveryCard.tsx
@@ -1,5 +1,6 @@
-import { useState } from "react";
+import React, { useState } from "react";
 import type { AgentChatEvent } from "../../../shared/types";
+import { formatAutoResumeTime, isUsageLimitChatError } from "../../../shared/chatAutoResume";
 
 export type ProviderFailureRecovery = {
   kind: "capacity" | "rate_limit";
@@ -7,6 +8,44 @@ export type ProviderFailureRecovery = {
   guidance: string;
 };
 
+/**
+ * Pending auto-resume for the chat that owns this transcript, published by the
+ * chat host. Consumed here rather than drilled through the event-row props so
+ * only this card re-renders when the schedule appears or is cancelled.
+ */
+export type ChatAutoResumeState = {
+  scheduleId: string;
+  /** ISO fire time of the durable scheduled-work row. */
+  nextRunAt: string | null;
+  /**
+   * {@link providerFailureEventId} of the newest usage-limit failure in this
+   * chat. The context is per-chat, so without an anchor every usage-limit card
+   * ever written to the transcript would advertise the one armed schedule —
+   * including failures from days ago that have nothing to do with it.
+   */
+  anchorEventId: string | null;
+  cancel: () => Promise<string | null> | void;
+} | null;
+
+export const ChatAutoResumeContext = React.createContext<ChatAutoResumeState>(null);
+
+/**
+ * Identity of one error row, built from the row's own envelope so the chat pane
+ * and the transcript row agree without either one knowing the other's indexing.
+ *
+ * Error events carry no id. The transcript collapse dedupes them by turn plus
+ * message, but `turnId` is optional on this path, and a usage limit produces
+ * the same message every time it is hit — so turn plus message alone would let
+ * a failure from days ago alias the newest one. The envelope timestamp is what
+ * separates them.
+ */
+export function providerFailureEventId(
+  timestamp: string,
+  event: Extract<AgentChatEvent, { type: "error" }>,
+): string {
+  return `${timestamp}::${event.turnId ?? ""}::${event.message}`;
+}
+
 export function classifyProviderFailure(
   event: Extract<AgentChatEvent, { type: "error" }>,
 ): ProviderFailureRecovery | null {
@@ -20,7 +59,11 @@ export function classifyProviderFailure(
       guidance: "The provider ended this turn because the selected model is at capacity. This thread is still safe to continue.",
     };
   }
-  if (identity.includes("usagelimitexceeded") || identity.includes("ratelimit")) {
+  // Delegated rather than spelled out again: the host arms the auto-resume off
+  // `isUsageLimitChatError`, and a card that recognised a narrower set of
+  // shapes than the schedule did left Codex usage limits ("usageLimitReached")
+  // armed on the host with no card, no anchor, and no way to cancel.
+  if (isUsageLimitChatError(event)) {
     return {
       kind: "rate_limit",
       label: "Usage limit",
@@ -32,17 +75,27 @@ export function classifyProviderFailure(
 
 export function ProviderFailureRecoveryCard({
   recovery,
+  eventId,
   disabled,
   onRetry,
   onChooseModel,
 }: {
   recovery: ProviderFailureRecovery;
+  /** {@link providerFailureEventId} of the error this card belongs to. */
+  eventId: string;
   disabled: boolean;
   onRetry?: () => Promise<string | null>;
   onChooseModel?: () => void;
 }) {
   const [retryPending, setRetryPending] = useState(false);
   const [retryError, setRetryError] = useState<string | null>(null);
+  const [cancelPending, setCancelPending] = useState(false);
+  const autoResume = React.useContext(ChatAutoResumeContext);
+  const autoResumeAt = autoResume?.nextRunAt ? Date.parse(autoResume.nextRunAt) : Number.NaN;
+  const showAutoResume = recovery.kind === "rate_limit"
+    && autoResume != null
+    && autoResume.anchorEventId === eventId
+    && Number.isFinite(autoResumeAt);
 
   const retry = async () => {
     if (!onRetry || retryPending) return;
@@ -57,11 +110,40 @@ export function ProviderFailureRecoveryCard({
     }
   };
 
+  const cancelAutoResume = async () => {
+    if (!autoResume || cancelPending) return;
+    setCancelPending(true);
+    setRetryError(null);
+    try {
+      setRetryError((await autoResume.cancel()) ?? null);
+    } catch (error) {
+      setRetryError(error instanceof Error ? error.message : String(error));
+    } finally {
+      setCancelPending(false);
+    }
+  };
+
   return (
     <div className="mt-3 rounded-[calc(var(--chat-radius-card)-8px)] border border-amber-300/12 bg-amber-400/[0.045] px-3 py-2.5">
       <div className="text-[length:calc(var(--chat-font-size)*10.5/14)] leading-relaxed text-amber-50/72">
         {recovery.guidance}
       </div>
+      {showAutoResume ? (
+        <div
+          data-testid="auto-resume-scheduled"
+          className="mt-2 flex flex-wrap items-center gap-2 text-[length:calc(var(--chat-font-size)*10.5/14)] leading-relaxed text-amber-50/72"
+        >
+          <span>{`Auto-resume scheduled for ${formatAutoResumeTime(autoResumeAt)}`}</span>
+          <button
+            type="button"
+            disabled={cancelPending}
+            className="rounded-md border border-amber-200/16 bg-amber-300/[0.07] px-2 py-0.5 font-mono text-[length:calc(var(--chat-font-size)*9/14)] font-semibold text-amber-50/80 transition-colors hover:border-amber-200/30 hover:bg-amber-300/[0.13] disabled:pointer-events-none disabled:opacity-40"
+            onClick={() => { void cancelAutoResume(); }}
+          >
+            Cancel auto-resume
+          </button>
+        </div>
+      ) : null}
       <div className="mt-2 flex flex-wrap gap-1.5">
         <button
           type="button"
diff --git a/apps/desktop/src/renderer/components/chat/UserMessageIssueContext.tsx b/apps/desktop/src/renderer/components/chat/UserMessageIssueContext.tsx
index 8a37477c73..495cd3c5b8 100644
--- a/apps/desktop/src/renderer/components/chat/UserMessageIssueContext.tsx
+++ b/apps/desktop/src/renderer/components/chat/UserMessageIssueContext.tsx
@@ -5,6 +5,7 @@ import { chatContextAttachmentKey } from "../../../shared/chatContextAttachments
 import { GitHubIssueSelectModal } from "../app/GitHubIssueSelectModal";
 import { LinearIssueSelectModal } from "../app/LinearIssueSelectModal";
 import { ChatAttachmentTray } from "./ChatAttachmentTray";
+import { useChatRuntimeScope } from "./ChatRuntimeScope";
 
 export function UserMessageIssueContext({
   attachments,
@@ -17,6 +18,12 @@ export function UserMessageIssueContext({
   mode: ChatSurfaceMode;
   sessionId?: string | null;
 }) {
+  // The machine that owns this chat, so attachment previews read from it.
+  // Taken from the chat's runtime scope rather than a prop: this renders inside
+  // `AgentChatMessageList`, which sits under `ChatRuntimeScopeProvider` with the
+  // identical pin, and the prop form drilled that same value through four
+  // layers of transcript row plumbing to arrive here unchanged.
+  const machinePin = useChatRuntimeScope().pin;
   const [linearDetailsIssueId, setLinearDetailsIssueId] = useState<string | null>(null);
   const [githubDetailsIssueId, setGitHubDetailsIssueId] = useState<string | null>(null);
   const [hiddenContextKeys, setHiddenContextKeys] = useState<string[]>([]);
@@ -41,6 +48,7 @@ export function UserMessageIssueContext({
       <ChatAttachmentTray
         attachments={attachments}
         contextAttachments={visibleContextAttachments}
+        machinePin={machinePin}
         mode={mode}
         className="mt-1 px-0 py-0"
         onOpenContext={(attachment) => {
diff --git a/apps/desktop/src/renderer/components/chat/attachmentViewerTarget.test.ts b/apps/desktop/src/renderer/components/chat/attachmentViewerTarget.test.ts
new file mode 100644
index 0000000000..032dd3f999
--- /dev/null
+++ b/apps/desktop/src/renderer/components/chat/attachmentViewerTarget.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import type { FilesWorkspace } from "../../../shared/types";
+import { resolveViewerKind } from "../files/v2/viewerRegistry";
+import { resolveAttachmentWorkspaceTarget } from "./attachmentViewerTarget";
+
+function workspace(overrides: Partial<FilesWorkspace> & { id: string; rootPath: string }): FilesWorkspace {
+  return {
+    kind: "primary",
+    laneId: null,
+    name: overrides.id,
+    branchRef: null,
+    isReadOnlyByDefault: false,
+    mobileReadOnly: true,
+    ...overrides,
+  } as FilesWorkspace;
+}
+
+describe("resolveAttachmentWorkspaceTarget", () => {
+  const primary = workspace({ id: "primary", rootPath: "/Users/a/Projects/ADE" });
+  const lane = workspace({
+    id: "lane-1",
+    kind: "worktree",
+    laneId: "lane-1",
+    rootPath: "/Users/a/Projects/ADE/.ade/worktrees/lane-1",
+  });
+
+  it("maps a staged attachment to the project workspace", () => {
+    expect(resolveAttachmentWorkspaceTarget(
+      "/Users/a/Projects/ADE/.ade/attachments/9f3a.png",
+      [primary],
+    )).toEqual({
+      workspaceId: "primary",
+      rootPath: "/Users/a/Projects/ADE",
+      relativePath: ".ade/attachments/9f3a.png",
+    });
+  });
+
+  it("prefers the deepest containing workspace", () => {
+    // Both roots contain the path; the lane worktree is the honest owner.
+    expect(resolveAttachmentWorkspaceTarget(
+      "/Users/a/Projects/ADE/.ade/worktrees/lane-1/.ade/attachments/9f3a.pdf",
+      [primary, lane],
+    )).toMatchObject({
+      workspaceId: "lane-1",
+      relativePath: ".ade/attachments/9f3a.pdf",
+    });
+  });
+
+  it("resolves a Windows attachment path against a Windows root", () => {
+    const win = workspace({ id: "win", rootPath: "C:\\Users\\a\\Projects\\ADE" });
+    expect(resolveAttachmentWorkspaceTarget(
+      "C:\\Users\\a\\Projects\\ADE\\.ade\\attachments\\9f3a.csv",
+      [win],
+    )).toMatchObject({ workspaceId: "win", relativePath: ".ade/attachments/9f3a.csv" });
+  });
+
+  it("returns null for an attachment outside every workspace", () => {
+    // Staged into system temp because no project was open.
+    expect(resolveAttachmentWorkspaceTarget(
+      "/var/folders/tmp/ade-attachments/9f3a.png",
+      [primary, lane],
+    )).toBeNull();
+  });
+
+  it("returns null when the path IS the workspace root", () => {
+    expect(resolveAttachmentWorkspaceTarget("/Users/a/Projects/ADE", [primary])).toBeNull();
+  });
+
+  it("does not match a sibling directory that merely shares a prefix", () => {
+    expect(resolveAttachmentWorkspaceTarget(
+      "/Users/a/Projects/ADE-backup/.ade/attachments/9f3a.png",
+      [primary],
+    )).toBeNull();
+  });
+});
+
+describe("viewer kind resolution for staged attachments", () => {
+  it("picks the right Files viewer for each attachment type", () => {
+    const cases: Array<[string, string]> = [
+      [".ade/attachments/a.pdf", "pdf"],
+      [".ade/attachments/a.png", "image"],
+      [".ade/attachments/a.svg", "image"],
+      [".ade/attachments/a.mp3", "audio"],
+      [".ade/attachments/a.mp4", "video"],
+      [".ade/attachments/a.csv", "csv"],
+      [".ade/attachments/a.xlsx", "document"],
+      [".ade/attachments/a.html", "html"],
+      [".ade/attachments/a.md", "markdown"],
+      [".ade/attachments/a.ts", "code"],
+    ];
+    for (const [path, expected] of cases) {
+      expect(resolveViewerKind({ path })).toBe(expected);
+    }
+  });
+
+  it("falls back to the binary viewer for an unreadable payload", () => {
+    expect(resolveViewerKind({ path: ".ade/attachments/a.bin", isBinary: true })).toBe("binary");
+  });
+});
diff --git a/apps/desktop/src/renderer/components/chat/attachmentViewerTarget.ts b/apps/desktop/src/renderer/components/chat/attachmentViewerTarget.ts
new file mode 100644
index 0000000000..ebbd80cf6c
--- /dev/null
+++ b/apps/desktop/src/renderer/components/chat/attachmentViewerTarget.ts
@@ -0,0 +1,71 @@
+import type { FilesWorkspace } from "../../../shared/types";
+import { normalizePathForComparison } from "../../lib/pathUtils";
+
+export type AttachmentViewerTarget = {
+  workspaceId: string;
+  /** Absolute workspace root, for "open externally" actions in the viewers. */
+  rootPath: string;
+  /** Workspace-relative, forward-slash path the Files APIs expect. */
+  relativePath: string;
+};
+
+/** Split on both separators so a Windows attachment path resolves too. */
+function segments(value: string): string[] {
+  return value.split(/[\\/]+/).filter((part) => part.length > 0);
+}
+
+/**
+ * Does the attachment path start with this root, segment for segment?
+ *
+ * The comparison itself is delegated to `normalizePathForComparison`, the same
+ * helper every other Files-side path equality check in the renderer uses, so a
+ * Windows root is folded and a POSIX one is not — matching how the two
+ * filesystems actually behave. The segment split stays because the caller needs
+ * the relative tail, and because comparing joined segments is what makes
+ * `/a/ADE-backup` fail against `/a/ADE` instead of passing a string prefix.
+ */
+function isPathPrefix(rootSegments: string[], pathSegments: string[]): boolean {
+  if (rootSegments.length > pathSegments.length) return false;
+  return normalizePathForComparison(rootSegments.join("/"))
+    === normalizePathForComparison(pathSegments.slice(0, rootSegments.length).join("/"));
+}
+
+/**
+ * Locate a chat attachment inside a Files workspace so the Files-tab viewers
+ * can open it.
+ *
+ * Attachments live at `<projectRoot>/.ade/attachments/<uuid><ext>`, which is
+ * inside the primary workspace — so this is a containment question, not a new
+ * capability. Resolving it on the client (rather than through
+ * `files.openExternalPath`) keeps the whole lookup pin-aware: every Files call
+ * that follows takes the same machine binding, so an attachment staged on a
+ * paired host is read from THAT host rather than silently resolving against a
+ * same-named path on this one.
+ *
+ * The longest matching root wins, so an attachment inside a lane worktree
+ * resolves to the lane's workspace instead of the project that contains it.
+ */
+export function resolveAttachmentWorkspaceTarget(
+  attachmentPath: string,
+  workspaces: readonly FilesWorkspace[],
+): AttachmentViewerTarget | null {
+  const pathSegments = segments(attachmentPath);
+  if (!pathSegments.length) return null;
+
+  let best: AttachmentViewerTarget | null = null;
+  let bestDepth = -1;
+  for (const workspace of workspaces) {
+    const rootSegments = segments(workspace.rootPath ?? "");
+    if (!rootSegments.length) continue;
+    if (rootSegments.length >= pathSegments.length) continue;
+    if (!isPathPrefix(rootSegments, pathSegments)) continue;
+    if (rootSegments.length <= bestDepth) continue;
+    bestDepth = rootSegments.length;
+    best = {
+      workspaceId: workspace.id,
+      rootPath: workspace.rootPath,
+      relativePath: pathSegments.slice(rootSegments.length).join("/"),
+    };
+  }
+  return best;
+}
diff --git a/apps/desktop/src/renderer/components/chat/chatAttachmentStaging.test.ts b/apps/desktop/src/renderer/components/chat/chatAttachmentStaging.test.ts
new file mode 100644
index 0000000000..d4378bcd4a
--- /dev/null
+++ b/apps/desktop/src/renderer/components/chat/chatAttachmentStaging.test.ts
@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  MAX_CHAT_ATTACHMENT_BYTES,
+  formatAttachmentSize,
+} from "../../../shared/chatAttachmentLimits";
+import {
+  CONSERVATIVE_ATTACHMENT_STAGING_MODE,
+  attachmentPlanRejection,
+  planAttachmentStaging,
+  readAttachmentStagingMode,
+} from "./chatAttachmentStaging";
+
+const COPY_MODE = { mode: "copy" as const, maxBytes: MAX_CHAT_ATTACHMENT_BYTES };
+const UPLOAD_MODE = { mode: "upload" as const, maxBytes: MAX_CHAT_ATTACHMENT_BYTES };
+const BASE64_MODE = { mode: "base64" as const, maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES };
+
+describe("planAttachmentStaging", () => {
+  it("sends only the path when the machine copies and the file has one", () => {
+    expect(planAttachmentStaging({
+      mode: COPY_MODE,
+      sourcePath: "/Users/a/Downloads/report.pdf",
+      requiresByteConversion: false,
+    })).toEqual({
+      transport: "path",
+      sourcePath: "/Users/a/Downloads/report.pdf",
+      maxBytes: MAX_CHAT_ATTACHMENT_BYTES,
+    });
+  });
+
+  it("streams the path to a host that advertises the upload route", () => {
+    expect(planAttachmentStaging({
+      mode: UPLOAD_MODE,
+      sourcePath: "C:\\Users\\a\\Desktop\\clip.mp4",
+      requiresByteConversion: false,
+    })).toEqual({
+      transport: "path",
+      sourcePath: "C:\\Users\\a\\Desktop\\clip.mp4",
+      maxBytes: MAX_CHAT_ATTACHMENT_BYTES,
+    });
+  });
+
+  it("falls back to bytes at the legacy cap when the host has no upload route", () => {
+    expect(planAttachmentStaging({
+      mode: BASE64_MODE,
+      sourcePath: "/Users/a/Downloads/report.pdf",
+      requiresByteConversion: false,
+    })).toEqual({ transport: "bytes", maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES });
+  });
+
+  it("falls back to bytes when the file has no path, even on a capable machine", () => {
+    // A clipboard paste, and every file in the hosted web client, where
+    // `getDroppedPath` returns "".
+    for (const sourcePath of [null, undefined, "", "   "]) {
+      expect(planAttachmentStaging({
+        mode: COPY_MODE,
+        sourcePath,
+        requiresByteConversion: false,
+      })).toEqual({ transport: "bytes", maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES });
+    }
+  });
+
+  it("falls back to bytes for a file the renderer has to convert first", () => {
+    expect(planAttachmentStaging({
+      mode: UPLOAD_MODE,
+      sourcePath: "/Users/a/Photos/IMG_0001.HEIC",
+      requiresByteConversion: true,
+    })).toEqual({ transport: "bytes", maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES });
+  });
+
+  it("never returns a cap above the legacy ceiling on the bytes path", () => {
+    // A host that over-declares must not widen what the base64 command accepts.
+    const plan = planAttachmentStaging({
+      mode: { mode: "base64", maxBytes: MAX_CHAT_ATTACHMENT_BYTES },
+      sourcePath: null,
+      requiresByteConversion: false,
+    });
+    expect(plan.maxBytes).toBe(LEGACY_MAX_CHAT_ATTACHMENT_BYTES);
+  });
+});
+
+describe("attachmentPlanRejection", () => {
+  it("accepts a 40 MB file on the path leg and rejects it on the bytes leg", () => {
+    const fortyMb = 40 * 1024 * 1024;
+    expect(attachmentPlanRejection(
+      { transport: "path", sourcePath: "/x/big.zip", maxBytes: MAX_CHAT_ATTACHMENT_BYTES },
+      "big.zip",
+      fortyMb,
+    )).toBeNull();
+
+    const rejection = attachmentPlanRejection(
+      { transport: "bytes", maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES },
+      "big.zip",
+      fortyMb,
+    );
+    expect(rejection).toContain("big.zip");
+    expect(rejection).toContain(formatAttachmentSize(fortyMb));
+    expect(rejection).toContain(formatAttachmentSize(LEGACY_MAX_CHAT_ATTACHMENT_BYTES));
+  });
+
+  it("accepts a file exactly at the cap", () => {
+    expect(attachmentPlanRejection(
+      { transport: "path", sourcePath: "/x/exact", maxBytes: MAX_CHAT_ATTACHMENT_BYTES },
+      "exact",
+      MAX_CHAT_ATTACHMENT_BYTES,
+    )).toBeNull();
+  });
+});
+
+describe("readAttachmentStagingMode", () => {
+  afterEach(() => {
+    delete (globalThis as { window?: unknown }).window;
+  });
+
+  function stubWindow(getAttachmentStagingMode: unknown): void {
+    (globalThis as { window?: unknown }).window = {
+      ade: { agentChat: { getAttachmentStagingMode } },
+    };
+  }
+
+  it("returns the machine's answer", async () => {
+    stubWindow(vi.fn(async () => UPLOAD_MODE));
+    await expect(readAttachmentStagingMode(null)).resolves.toEqual(UPLOAD_MODE);
+  });
+
+  it("degrades to the legacy contract when the bridge lacks the method", async () => {
+    stubWindow(undefined);
+    await expect(readAttachmentStagingMode(null))
+      .resolves.toEqual(CONSERVATIVE_ATTACHMENT_STAGING_MODE);
+  });
+
+  it("degrades to the legacy contract when the probe throws", async () => {
+    stubWindow(vi.fn(async () => {
+      throw new Error("machine is not connected");
+    }));
+    await expect(readAttachmentStagingMode(null))
+      .resolves.toEqual(CONSERVATIVE_ATTACHMENT_STAGING_MODE);
+  });
+
+  it("degrades to the legacy contract on a malformed answer", async () => {
+    stubWindow(vi.fn(async () => ({ mode: "upload" })));
+    await expect(readAttachmentStagingMode(null))
+      .resolves.toEqual(CONSERVATIVE_ATTACHMENT_STAGING_MODE);
+  });
+});
diff --git a/apps/desktop/src/renderer/components/chat/chatAttachmentStaging.ts b/apps/desktop/src/renderer/components/chat/chatAttachmentStaging.ts
new file mode 100644
index 0000000000..c3e2b92a85
--- /dev/null
+++ b/apps/desktop/src/renderer/components/chat/chatAttachmentStaging.ts
@@ -0,0 +1,169 @@
+import {
+  LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+  attachmentTooLargeMessage,
+} from "../../../shared/chatAttachmentLimits";
+import type {
+  ChatAttachmentStagingMode,
+  HeicConversionErrorCode,
+} from "../../../shared/types/chat";
+import type { OpenProjectBinding } from "../../../shared/types/core";
+
+export type AttachmentStagingPlan =
+  /** Send only the path; the bytes never enter the renderer. */
+  | { transport: "path"; sourcePath: string; maxBytes: number }
+  /** Read the file and send base64 — the legacy image-only command. */
+  | { transport: "bytes"; maxBytes: number };
+
+/**
+ * How ONE file is staged, given what the destination machine supports.
+ *
+ * The machine-level answer (`mode`) is necessary but not sufficient: a host may
+ * accept a 50 MB streamed upload while this particular file has no path to
+ * stream. Three things force the bytes path even on a capable machine:
+ *
+ * - **No source path.** A clipboard paste is bytes in memory and nothing else.
+ *   So is every file in the hosted web client, where `webUtils` does not exist
+ *   and `getDroppedPath` returns "". There is no file on disk to point at.
+ * - **Conversion.** A HEIC photo is decoded to JPEG in the renderer first, so
+ *   what gets staged is a buffer this process produced, not the file the user
+ *   picked.
+ * - **The host said so.** `mode: "base64"` — a host predating the upload route,
+ *   or a relay-routed socket an HTTP POST cannot follow.
+ *
+ * Whenever the bytes path is taken the cap drops to the legacy ceiling, because
+ * that is the contract `chat.saveTempAttachment` actually enforces on the other
+ * end. Returning the larger number here would only move the rejection later.
+ */
+export function planAttachmentStaging(args: {
+  mode: ChatAttachmentStagingMode;
+  sourcePath: string | null | undefined;
+  requiresByteConversion: boolean;
+}): AttachmentStagingPlan {
+  const sourcePath = args.sourcePath?.trim() ?? "";
+  if (
+    args.mode.mode === "base64"
+    || args.requiresByteConversion
+    || !sourcePath
+  ) {
+    return {
+      transport: "bytes",
+      maxBytes: Math.min(args.mode.maxBytes, LEGACY_MAX_CHAT_ATTACHMENT_BYTES),
+    };
+  }
+  return { transport: "path", sourcePath, maxBytes: args.mode.maxBytes };
+}
+
+/** The rejection a file gets when it exceeds the plan's ceiling. */
+export function attachmentPlanRejection(
+  plan: AttachmentStagingPlan,
+  name: string,
+  byteLength: number,
+): string | null {
+  if (byteLength <= plan.maxBytes) return null;
+  return attachmentTooLargeMessage(name, byteLength, plan.maxBytes);
+}
+
+/** Fallback used before the machine answers, and if the probe itself fails. */
+export const CONSERVATIVE_ATTACHMENT_STAGING_MODE: ChatAttachmentStagingMode = {
+  mode: "base64",
+  maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+};
+
+/**
+ * Ask the machine that owns this chat how it stages attachments. Never throws —
+ * a machine that cannot answer gets the conservative legacy contract, which
+ * every host has supported since attachments existed.
+ */
+export async function readAttachmentStagingMode(
+  pin: OpenProjectBinding | null | undefined,
+): Promise<ChatAttachmentStagingMode> {
+  const read = window.ade?.agentChat?.getAttachmentStagingMode;
+  if (typeof read !== "function") return CONSERVATIVE_ATTACHMENT_STAGING_MODE;
+  try {
+    const mode = await read(pin);
+    if (!mode || typeof mode.maxBytes !== "number" || !Number.isFinite(mode.maxBytes)) {
+      return CONSERVATIVE_ATTACHMENT_STAGING_MODE;
+    }
+    return mode;
+  } catch {
+    return CONSERVATIVE_ATTACHMENT_STAGING_MODE;
+  }
+}
+
+/** What either transport hands back, so the composer's tail is written once. */
+export type StagedAttachment = {
+  path: string;
+  mimeType: string | null;
+  /** Set only when the renderer produced the bytes, i.e. a converted HEIC. */
+  previewDataUrl: string | null;
+};
+
+/**
+ * A HEIC the renderer could not hand to the host as JPEG. Distinguished from
+ * every other staging failure because the file will fail the same way on every
+ * attempt, so the composer offers no retry for it.
+ */
+export class AttachmentConversionError extends Error {
+  constructor(readonly code: HeicConversionErrorCode) {
+    super(code);
+    this.name = "AttachmentConversionError";
+  }
+}
+
+// btoa takes a string, and spreading a multi-megabyte Uint8Array into
+// String.fromCharCode blows the argument limit, so encode in chunks.
+const BASE64_ENCODE_CHUNK_SIZE = 0x8000;
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  const parts: string[] = [];
+  for (let i = 0; i < bytes.length; i += BASE64_ENCODE_CHUNK_SIZE) {
+    const chunk = bytes.subarray(i, i + BASE64_ENCODE_CHUNK_SIZE);
+    parts.push(String.fromCharCode(...chunk));
+  }
+  return btoa(parts.join(""));
+}
+
+/**
+ * The bytes leg of {@link planAttachmentStaging}: read the file in the
+ * renderer, convert it first when the host cannot read the format, and hand the
+ * base64 to the legacy `saveTempAttachment` command.
+ *
+ * HEIC is converted here rather than on the host because the file may never
+ * reach a host that can decode it — a clipboard paste and the hosted web client
+ * both arrive as bytes with no path at all.
+ */
+export async function stageAttachmentBytesFromFile(args: {
+  file: File;
+  filename: string;
+  requiresHeicConversion: boolean;
+  pin: OpenProjectBinding | null | undefined;
+}): Promise<StagedAttachment> {
+  const buffer = await args.file.arrayBuffer();
+  let filename = args.filename;
+  let data = arrayBufferToBase64(buffer);
+  let mimeType: string | null = args.file.type || null;
+  let previewDataUrl: string | null = null;
+  if (args.requiresHeicConversion) {
+    const convertImageToJpeg = window.ade?.app?.convertImageToJpeg;
+    if (typeof convertImageToJpeg !== "function") {
+      throw new AttachmentConversionError("unavailable");
+    }
+    const converted = await convertImageToJpeg({
+      data,
+      filename: args.filename,
+      mimeType: args.file.type || null,
+    });
+    if (converted.ok !== true) {
+      throw new AttachmentConversionError(
+        converted.errorCode === "unavailable" ? "unavailable" : "failed",
+      );
+    }
+    filename = converted.filename;
+    data = converted.data;
+    mimeType = converted.mimeType;
+    previewDataUrl = `data:${converted.mimeType};base64,${converted.data}`;
+  }
+  const { path } = await window.ade.agentChat.saveTempAttachment({ data, filename }, args.pin);
+  return { path, mimeType, previewDataUrl };
+}
diff --git a/apps/desktop/src/renderer/webclient/adapter/agentChat.ts b/apps/desktop/src/renderer/webclient/adapter/agentChat.ts
index 9a45ce0828..553bff8b6f 100644
--- a/apps/desktop/src/renderer/webclient/adapter/agentChat.ts
+++ b/apps/desktop/src/renderer/webclient/adapter/agentChat.ts
@@ -1,4 +1,5 @@
 import type { SyncChatEventPayload } from "../../../shared/types/sync";
+import { LEGACY_MAX_CHAT_ATTACHMENT_BYTES } from "../../../shared/chatAttachmentLimits";
 import type {
   AgentChatCancelDispatchedSteerResult,
   AgentChatCancelScheduledWorkResult,
@@ -475,6 +476,18 @@ export function createAgentChatNamespace(infra: AdapterInfra): AdeNamespace<"age
       guardPin("saveTempAttachment", pin);
       return await call("chat.saveTempAttachment", args, { path: "" }, false);
     },
+    // The hosted web client has no `webUtils`, so a dropped or picked file
+    // never carries a real disk path — there is nothing to copy or stream and
+    // the browser only ever holds bytes. It stays on the base64 command with
+    // the legacy ceiling, and `stageFileAttachment` is unreachable by
+    // construction rather than by a runtime check that could drift.
+    getAttachmentStagingMode: async () => ({
+      mode: "base64" as const,
+      maxBytes: LEGACY_MAX_CHAT_ATTACHMENT_BYTES,
+    }),
+    stageFileAttachment: async () => {
+      throw new Error("Attachment upload is not available in the web client.");
+    },
     getImageDataUrl: async (path: string, pin?: RuntimePinArg) => {
       guardPin("getImageDataUrl", pin);
       return { dataUrl: (await requestDataUrl(client, infra.state, "readArtifact", { path })) ?? "" };
diff --git a/apps/desktop/src/shared/chatAttachmentLimits.ts b/apps/desktop/src/shared/chatAttachmentLimits.ts
new file mode 100644
index 0000000000..9bc97a573e
--- /dev/null
+++ b/apps/desktop/src/shared/chatAttachmentLimits.ts
@@ -0,0 +1,71 @@
+/**
+ * Size ceilings for chat attachments, shared by the desktop renderer, the
+ * desktop main process, and the ADE CLI sync host.
+ *
+ * There are two caps because there are two fundamentally different ways an
+ * attachment reaches the host:
+ *
+ * - **As a file.** A local disk-to-disk copy, or a streamed HTTP upload to a
+ *   paired host. Bytes never sit in a JS string and never ride a message-shaped
+ *   transport, so the ceiling is the product one: {@link MAX_CHAT_ATTACHMENT_BYTES}.
+ * - **As base64 in a command payload.** The legacy `chat.saveTempAttachment`
+ *   path. Base64 inflates by a third, the whole payload is buffered in memory on
+ *   both ends, and over sync it is chunked into 720 KiB frames under a 25 MB
+ *   payload cap. That path keeps its historical ceiling,
+ *   {@link LEGACY_MAX_CHAT_ATTACHMENT_BYTES}.
+ *
+ * A client talking to a host that does not advertise the upload route only ever
+ * sees the legacy cap, so an older host is never handed a payload it would
+ * reject halfway through.
+ */
+
+/** Ceiling for attachments that move as files (local copy or HTTP upload). */
+export const MAX_CHAT_ATTACHMENT_BYTES = 50 * 1024 * 1024;
+
+/** Ceiling for attachments that move as base64 inside a command payload. */
+export const LEGACY_MAX_CHAT_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Ceiling for image bytes a provider adapter inlines into a model request.
+ *
+ * Independent of the attachment cap on purpose. Staging a 50 MB screenshot for
+ * Codex or handing its path to Droid is fine; base64-inlining it into an
+ * Anthropic or OpenCode request is not — it triples the request body and the
+ * provider rejects it. Raising the attachment cap must not raise this one, so
+ * every inline path checks it and degrades to a path hint instead.
+ */
+export const MAX_PROVIDER_INLINE_IMAGE_BYTES = 10 * 1024 * 1024;
+
+/** Human size for composer copy: "9 KB", "1.4 MB". */
+export function formatAttachmentSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "";
+  if (bytes < 1024) return `${Math.max(0, Math.round(bytes))} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb < 10 ? kb.toFixed(1) : Math.round(kb)} KB`;
+  const mb = kb / 1024;
+  if (mb < 1024) return `${mb < 10 ? mb.toFixed(1) : Math.round(mb)} MB`;
+  return `${(mb / 1024).toFixed(1)} GB`;
+}
+
+/**
+ * The one message every legacy-cap rejection uses.
+ *
+ * `subject` names what was rejected ("Temporary attachments", "Image",
+ * "Clipboard image") because the caller knows which of the base64 paths the
+ * user actually took. The ceiling is rendered from the constant, so raising
+ * {@link LEGACY_MAX_CHAT_ATTACHMENT_BYTES} can never leave a stale "10 MB"
+ * behind in a message the constant no longer matches.
+ */
+export function legacyAttachmentCapMessage(subject: string): string {
+  return `${subject} must be ${formatAttachmentSize(LEGACY_MAX_CHAT_ATTACHMENT_BYTES)} or smaller.`;
+}
+
+/** The one message every "too large" rejection uses, so all surfaces agree. */
+export function attachmentTooLargeMessage(
+  name: string,
+  bytes: number,
+  limitBytes: number,
+): string {
+  const label = name.trim() || "attachment";
+  return `File "${label}" is too large (${formatAttachmentSize(bytes)}). Maximum allowed size is ${formatAttachmentSize(limitBytes)}.`;
+}
diff --git a/apps/desktop/src/shared/chatAttachmentStagingFs.test.ts b/apps/desktop/src/shared/chatAttachmentStagingFs.test.ts
new file mode 100644
index 0000000000..f116e7f884
--- /dev/null
+++ b/apps/desktop/src/shared/chatAttachmentStagingFs.test.ts
@@ -0,0 +1,221 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MAX_CHAT_ATTACHMENT_BYTES } from "./chatAttachmentLimits";
+import {
+  projectAttachmentsDir,
+  resolveStagedAttachmentExtension,
+  safeAttachmentExtension,
+  stageAttachmentBytes,
+  stageAttachmentCopy,
+  stagedAttachmentDestPath,
+} from "./chatAttachmentStagingFs";
+
+describe("projectAttachmentsDir", () => {
+  it("names the one location every process stages into", () => {
+    // Six call sites across the desktop main process, the ADE action registry
+    // and the CLI sync host used to spell this out by hand.
+    expect(projectAttachmentsDir(path.join("/tmp", "proj")))
+      .toBe(path.join("/tmp", "proj", ".ade", "attachments"));
+  });
+});
+
+describe("safeAttachmentExtension", () => {
+  it("keeps a plain extension and folds its case", () => {
+    expect(safeAttachmentExtension("Screenshot.PNG")).toBe(".png");
+    expect(safeAttachmentExtension("  notes.pdf  ")).toBe(".pdf");
+  });
+
+  it("drops anything a destination basename must not carry", () => {
+    // A separator, a second dot, an over-long tail, or nothing at all: the
+    // destination falls back to no extension rather than trusting the input.
+    expect(safeAttachmentExtension("../../evil")).toBe("");
+    expect(safeAttachmentExtension("archive.tar.gz")).toBe(".gz");
+    expect(safeAttachmentExtension("payload.thisextensionistoolong")).toBe("");
+    expect(safeAttachmentExtension("README")).toBe("");
+    expect(safeAttachmentExtension(null)).toBe("");
+  });
+});
+
+describe("resolveStagedAttachmentExtension", () => {
+  it("prefers the display name, falling back to the source path", () => {
+    expect(resolveStagedAttachmentExtension("report.csv", "/tmp/a.bin")).toBe(".csv");
+    expect(resolveStagedAttachmentExtension("report", "/tmp/a.bin")).toBe(".bin");
+    // Separator-agnostic, so a Windows source path resolves the same way.
+    expect(resolveStagedAttachmentExtension("", "C:\\Users\\a\\shot.PNG")).toBe(".png");
+  });
+});
+
+describe("stagedAttachmentDestPath", () => {
+  it("always names a UUID basename inside the attachments directory", () => {
+    const dir = path.join(os.tmpdir(), "ade-attachments-unit");
+    const dest = stagedAttachmentDestPath(dir, ".pdf");
+    expect(path.dirname(dest)).toBe(path.resolve(dir));
+    expect(path.basename(dest, ".pdf")).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+  });
+
+  it("drops an extension that was never validated", () => {
+    const dir = path.join(os.tmpdir(), "ade-attachments-unit");
+    expect(path.extname(stagedAttachmentDestPath(dir, "../../evil.sh"))).toBe("");
+  });
+
+  it("accepts an attachments directory that is itself a filesystem root", () => {
+    // The previous `startsWith(baseDir + path.sep)` check looked for `//` (or
+    // `C:\\` on Windows) here and refused a destination that is plainly
+    // contained. Nothing is written: this is pure path arithmetic.
+    const root = path.parse(os.tmpdir()).root;
+    expect(path.dirname(stagedAttachmentDestPath(root, ".png"))).toBe(root);
+  });
+
+  it("throws instead of returning a destination outside the attachments directory", async () => {
+    // Unreachable while the basename is a UUID, which is exactly the point:
+    // this recheck is the tripwire for someone loosening that rule, so the only
+    // way to prove it is live is to break the rule.
+    vi.resetModules();
+    vi.doMock("node:crypto", async () => ({
+      ...(await vi.importActual<typeof import("node:crypto")>("node:crypto")),
+      randomUUID: () => "../escaped",
+    }));
+    try {
+      const { stagedAttachmentDestPath: withBrokenBasename } =
+        await import("./chatAttachmentStagingFs");
+      expect(() => withBrokenBasename(path.join(os.tmpdir(), "ade-attachments-unit"), ".png"))
+        .toThrow("Invalid attachment destination.");
+    } finally {
+      vi.doUnmock("node:crypto");
+      vi.resetModules();
+    }
+  });
+});
+
+describe("stageAttachmentBytes", () => {
+  let attachmentsDir = "";
+
+  beforeEach(async () => {
+    attachmentsDir = path.join(
+      await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-stage-bytes-")),
+      ".ade",
+      "attachments",
+    );
+  });
+
+  afterEach(async () => {
+    await fs.promises.rm(path.dirname(path.dirname(attachmentsDir)), { recursive: true, force: true });
+  });
+
+  it("writes the bytes under a UUID basename, creating the directory", async () => {
+    const content = Buffer.from("\u0089PNG bytes");
+    const result = await stageAttachmentBytes({ content, filename: "shot.PNG", attachmentsDir });
+
+    expect(path.dirname(result.path)).toBe(attachmentsDir);
+    expect(path.extname(result.path)).toBe(".png");
+    expect(path.basename(result.path, ".png")).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+    await expect(fs.promises.readFile(result.path)).resolves.toEqual(content);
+  });
+
+  it("falls back to .png for a missing or unusable extension", async () => {
+    // Hardening over the two hand-rolled writers this replaced: they used
+    // `path.extname(filename)` unvalidated, so a display name could name its
+    // own on-disk extension. A rejected extension now takes the fallback.
+    for (const filename of [null, "", "clipboard", "payload.thisextensionistoolong"]) {
+      const result = await stageAttachmentBytes({
+        content: Buffer.from("x"),
+        filename,
+        attachmentsDir,
+      });
+      expect(path.extname(result.path)).toBe(".png");
+    }
+  });
+
+  it("keeps a traversal-shaped filename off the destination", async () => {
+    const result = await stageAttachmentBytes({
+      content: Buffer.from("payload"),
+      filename: "../../evil.sh",
+      attachmentsDir,
+    });
+
+    expect(path.dirname(result.path)).toBe(attachmentsDir);
+    const projectRoot = path.dirname(path.dirname(attachmentsDir));
+    expect(fs.existsSync(path.join(projectRoot, "evil.sh"))).toBe(false);
+  });
+});
+
+describe("stageAttachmentCopy", () => {
+  let attachmentsDir = "";
+  let sourceDir = "";
+
+  beforeEach(async () => {
+    attachmentsDir = path.join(
+      await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-stage-dest-")),
+      ".ade",
+      "attachments",
+    );
+    sourceDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ade-stage-src-"));
+  });
+
+  afterEach(async () => {
+    await fs.promises.rm(path.dirname(path.dirname(attachmentsDir)), { recursive: true, force: true });
+    await fs.promises.rm(sourceDir, { recursive: true, force: true });
+  });
+
+  it("copies a file from outside the project and leaves the original in place", async () => {
+    // The source lives outside the project on purpose (Downloads/Desktop).
+    const sourcePath = path.join(sourceDir, "notes.pdf");
+    const content = Buffer.from("%PDF-1.7 body bytes");
+    await fs.promises.writeFile(sourcePath, content);
+
+    const result = await stageAttachmentCopy({ sourcePath, attachmentsDir });
+
+    expect(path.dirname(result.path)).toBe(attachmentsDir);
+    expect(path.extname(result.path)).toBe(".pdf");
+    await expect(fs.promises.readFile(result.path)).resolves.toEqual(content);
+    expect(fs.existsSync(sourcePath)).toBe(true);
+  });
+
+  it("keeps a traversal-shaped filename on a UUID basename inside the attachments dir", async () => {
+    const sourcePath = path.join(sourceDir, "innocent.txt");
+    await fs.promises.writeFile(sourcePath, "payload");
+
+    const result = await stageAttachmentCopy({
+      sourcePath,
+      filename: "../../evil.sh",
+      attachmentsDir,
+    });
+
+    expect(path.dirname(result.path)).toBe(attachmentsDir);
+    expect(path.basename(result.path, path.extname(result.path))).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+    const projectRoot = path.dirname(path.dirname(attachmentsDir));
+    expect(fs.existsSync(path.join(projectRoot, "evil.sh"))).toBe(false);
+    expect(fs.existsSync(path.join(projectRoot, ".ade", "evil.sh"))).toBe(false);
+  });
+
+  it("rejects a source above the file attachment ceiling before copying a byte", async () => {
+    const sourcePath = path.join(sourceDir, "huge.bin");
+    // Sparse: no 50 MB of real bytes are written.
+    const handle = await fs.promises.open(sourcePath, "w");
+    await handle.truncate(MAX_CHAT_ATTACHMENT_BYTES + 1);
+    await handle.close();
+
+    await expect(stageAttachmentCopy({ sourcePath, attachmentsDir })).rejects.toThrow(/too large/i);
+    await expect(fs.promises.readdir(attachmentsDir)).rejects.toThrow();
+  });
+
+  it("rejects an empty, whitespace-only, or NUL-bearing source path", async () => {
+    await expect(stageAttachmentCopy({ sourcePath: "   ", attachmentsDir }))
+      .rejects.toThrow("Missing attachment source path.");
+    await expect(stageAttachmentCopy({ sourcePath: "/tmp/a\0b", attachmentsDir }))
+      .rejects.toThrow("Missing attachment source path.");
+  });
+
+  it("rejects a directory handed in as a source", async () => {
+    await expect(stageAttachmentCopy({ sourcePath: sourceDir, attachmentsDir }))
+      .rejects.toThrow("Attachment source is not a file.");
+  });
+});
diff --git a/apps/desktop/src/shared/chatAttachmentStagingFs.ts b/apps/desktop/src/shared/chatAttachmentStagingFs.ts
new file mode 100644
index 0000000000..8663de2762
--- /dev/null
+++ b/apps/desktop/src/shared/chatAttachmentStagingFs.ts
@@ -0,0 +1,163 @@
+/**
+ * The one disk-side rule for staging a chat attachment, shared by every process
+ * that writes into a project's `.ade/attachments` directory: the desktop main
+ * process (`registerIpc`), the ADE action registry the local brain serves, and
+ * the CLI sync host's streamed HTTP upload route.
+ *
+ * There used to be three copies of this rule and only two of them validated the
+ * extension, so the same drag-and-drop produced a differently-named file
+ * depending on which process happened to answer. The invariants below are the
+ * ones every caller now gets:
+ *
+ * - The destination basename is always a fresh UUID. Nothing about the source
+ *   path or the caller-supplied display name reaches it except a
+ *   regex-validated extension, so a traversal-shaped filename cannot smuggle a
+ *   path fragment through to the write.
+ * - The resolved destination is re-checked for containment inside the
+ *   attachments directory. That cannot fail while the basename is a UUID — it
+ *   fails loudly if either invariant is ever loosened.
+ * - Size is checked by `stat` before a byte is copied, against the product
+ *   ceiling for file-shaped attachments.
+ *
+ * Node-only: this module touches `node:fs`, so the renderer imports
+ * `chatAttachmentLimits` instead.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { MAX_CHAT_ATTACHMENT_BYTES, attachmentTooLargeMessage } from "./chatAttachmentLimits";
+
+/** Extensions are the only client-controlled part of a staged attachment name. */
+const SAFE_ATTACHMENT_EXTENSION_PATTERN = /^\.[A-Za-z0-9]{1,16}$/;
+
+/**
+ * Where a project's staged attachments live.
+ *
+ * Inside `.ade` so CLI subprocesses and the Files viewer can reach them. Six
+ * call sites across three processes used to spell this out by hand, which is
+ * one rename away from a host and its own upload route disagreeing about where
+ * a file just landed.
+ */
+export function projectAttachmentsDir(projectRoot: string): string {
+  return path.join(projectRoot, ".ade", "attachments");
+}
+
+/** `.PNG` → `.png`; anything with a separator, a dot, or excess length → "". */
+export function safeAttachmentExtension(candidate: string | null | undefined): string {
+  const raw = path.extname((candidate ?? "").trim()).toLowerCase();
+  return SAFE_ATTACHMENT_EXTENSION_PATTERN.test(raw) ? raw : "";
+}
+
+/**
+ * The extension a staged copy carries: the caller's display name when it has a
+ * usable one, else the source path's. `path.extname` is separator-agnostic on
+ * both, so a Windows source path is handled the same as a POSIX one.
+ */
+export function resolveStagedAttachmentExtension(
+  filename: string | null | undefined,
+  sourcePath: string | null | undefined,
+): string {
+  return safeAttachmentExtension(filename) || safeAttachmentExtension(sourcePath);
+}
+
+/**
+ * `<attachmentsDir>/<uuid><ext>`, resolved and re-checked for containment.
+ *
+ * `extension` must already be a validated safe extension (see
+ * {@link safeAttachmentExtension}); anything else is dropped rather than
+ * trusted.
+ */
+export function stagedAttachmentDestPath(attachmentsDir: string, extension: string): string {
+  const baseDir = path.resolve(attachmentsDir);
+  const ext = SAFE_ATTACHMENT_EXTENSION_PATTERN.test(extension) ? extension : "";
+  const destPath = path.resolve(path.join(baseDir, `${randomUUID()}${ext}`));
+  // `path.relative` rather than `startsWith(baseDir + path.sep)`. The prefix
+  // form false-rejects whenever the resolved base already ends in a separator
+  // — a filesystem root or a Windows drive root, where it looks for `//` or
+  // `C:\\` — and it is raw string comparison where path containment is not a
+  // string property. `relative` also gives the cross-drive case a name: with
+  // no relative route from one Windows drive to another it returns an absolute
+  // path, which the `isAbsolute` arm rejects.
+  const relative = path.relative(baseDir, destPath);
+  if (
+    !relative
+    || path.isAbsolute(relative)
+    || relative === ".."
+    || relative.startsWith(`..${path.sep}`)
+  ) {
+    throw new Error("Invalid attachment destination.");
+  }
+  return destPath;
+}
+
+type StageAttachmentCopyArgs = {
+  /** Absolute path to a file that already exists on THIS machine's disk. */
+  sourcePath: string;
+  /** The caller's display name for the file; only its extension is used. */
+  filename?: string | null;
+  /** Usually `<projectRoot>/.ade/attachments`. */
+  attachmentsDir: string;
+};
+
+/**
+ * Stage a file that already exists on this machine's disk by copying it, never
+ * by round-tripping its bytes through base64 and IPC.
+ *
+ * Deliberately NOT constrained to the project root: a user drags a file in from
+ * Downloads or Desktop, and refusing those would make the feature useless. The
+ * source path is only ever READ, and nothing about it reaches the destination.
+ * Because the source is unconstrained, this must only ever be reachable from
+ * the machine that owns the file — never from a remote peer.
+ */
+export async function stageAttachmentCopy(
+  args: StageAttachmentCopyArgs,
+): Promise<{ path: string }> {
+  const raw = typeof args.sourcePath === "string" ? args.sourcePath.trim() : "";
+  if (!raw || raw.includes("\0")) throw new Error("Missing attachment source path.");
+  const absolute = path.resolve(raw);
+  const stat = await fs.promises.stat(absolute);
+  if (!stat.isFile()) throw new Error("Attachment source is not a file.");
+  if (stat.size > MAX_CHAT_ATTACHMENT_BYTES) {
+    throw new Error(
+      attachmentTooLargeMessage(path.basename(absolute), stat.size, MAX_CHAT_ATTACHMENT_BYTES),
+    );
+  }
+  const baseDir = path.resolve(args.attachmentsDir);
+  await fs.promises.mkdir(baseDir, { recursive: true });
+  const destPath = stagedAttachmentDestPath(
+    baseDir,
+    resolveStagedAttachmentExtension(args.filename, absolute),
+  );
+  await fs.promises.copyFile(absolute, destPath);
+  return { path: destPath };
+}
+
+/**
+ * Stage bytes the caller already holds (a base64 IPC payload, a clipboard
+ * grab) under the same UUID-basename rule as {@link stageAttachmentCopy}.
+ *
+ * Callers keep their own size ceilings and their own wording for exceeding
+ * them: the base64 paths carry a smaller, image-shaped cap than the copy path,
+ * and the message a user sees names which one they hit.
+ *
+ * The extension falls back to `.png` because every writer of this path is an
+ * image producer, and a viewer that gets no extension at all shows nothing. An
+ * extension the regex rejects now takes that fallback instead of reaching the
+ * destination raw — the callers this replaced used `path.extname(filename)`
+ * unvalidated, so a display name could name its own on-disk extension.
+ */
+export async function stageAttachmentBytes(args: {
+  content: Buffer;
+  filename?: string | null;
+  attachmentsDir: string;
+}): Promise<{ path: string }> {
+  const baseDir = path.resolve(args.attachmentsDir);
+  const destPath = stagedAttachmentDestPath(
+    baseDir,
+    resolveStagedAttachmentExtension(args.filename, null) || ".png",
+  );
+  await fs.promises.mkdir(baseDir, { recursive: true });
+  await fs.promises.writeFile(destPath, args.content);
+  return { path: destPath };
+}
diff --git a/apps/desktop/src/shared/chatAutoResume.test.ts b/apps/desktop/src/shared/chatAutoResume.test.ts
new file mode 100644
index 0000000000..86a8859e2f
--- /dev/null
+++ b/apps/desktop/src/shared/chatAutoResume.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  AUTO_RESUME_BUFFER_MS,
+  AUTO_RESUME_SCHEDULED_WORK_SOURCE,
+  autoResumeFireAtMs,
+  autoResumeScheduleId,
+  formatAutoResumeTime,
+  isAutoResumeScheduledWork,
+  isPendingAutoResumeScheduledWork,
+  isUsageLimitChatError,
+} from "./chatAutoResume";
+
+describe("isUsageLimitChatError", () => {
+  it("recognises the structured classifier category", () => {
+    expect(isUsageLimitChatError({ message: "anything", errorInfo: { category: "rate_limit" } }))
+      .toBe(true);
+  });
+
+  it("recognises the opaque provider strings Codex forwards", () => {
+    expect(isUsageLimitChatError({ errorInfo: "usageLimitReached" })).toBe(true);
+    expect(isUsageLimitChatError({ errorInfo: "usage_limit_reached" })).toBe(true);
+    expect(isUsageLimitChatError({ errorInfo: "rate-limit-exceeded" })).toBe(true);
+  });
+
+  it("recognises the limit in the human message when no code is attached", () => {
+    expect(isUsageLimitChatError({ message: "You've hit your usage limit." })).toBe(true);
+    expect(isUsageLimitChatError({ message: "429 Rate limit reached for this model." })).toBe(true);
+  });
+
+  it("does not treat other failures as usage limits", () => {
+    expect(isUsageLimitChatError({ message: "The connection was reset." })).toBe(false);
+    expect(isUsageLimitChatError({ errorInfo: { category: "auth" }, message: "Not signed in." }))
+      .toBe(false);
+    // "limit" alone is not a usage limit — a context-window overflow is a
+    // different failure with a different recovery.
+    expect(isUsageLimitChatError({ message: "Prompt exceeds the context limit." })).toBe(false);
+    expect(isUsageLimitChatError({})).toBe(false);
+  });
+});
+
+describe("autoResumeFireAtMs", () => {
+  const now = Date.parse("2026-08-29T10:00:00.000Z");
+
+  it("waits out the buffer past the reset instant", () => {
+    const resetsAt = now + 30 * 60_000;
+    expect(autoResumeFireAtMs(resetsAt, now)).toBe(resetsAt + AUTO_RESUME_BUFFER_MS);
+  });
+
+  it("arms nothing when the provider reported no reset instant", () => {
+    expect(autoResumeFireAtMs(null, now)).toBeNull();
+    expect(autoResumeFireAtMs(undefined, now)).toBeNull();
+    expect(autoResumeFireAtMs(Number.NaN, now)).toBeNull();
+    expect(autoResumeFireAtMs(0, now)).toBeNull();
+    expect(autoResumeFireAtMs(-1, now)).toBeNull();
+  });
+
+  it("arms nothing once the buffered fire time has already passed", () => {
+    // The limit is already back: a schedule would fire immediately for no
+    // reason, and the manual retry affordance is the right answer.
+    expect(autoResumeFireAtMs(now - 10 * 60_000, now)).toBeNull();
+    expect(autoResumeFireAtMs(now - AUTO_RESUME_BUFFER_MS, now)).toBeNull();
+    // A reset that just passed is still worth arming: the buffer has not
+    // elapsed yet, so the fire time is genuinely in the future.
+    expect(autoResumeFireAtMs(now - AUTO_RESUME_BUFFER_MS + 1_000, now))
+      .toBe(now + 1_000);
+  });
+});
+
+describe("autoResumeScheduleId", () => {
+  it("is deterministic per chat so a repeat failure replaces rather than stacks", () => {
+    expect(autoResumeScheduleId("session-a")).toBe(autoResumeScheduleId("session-a"));
+    expect(autoResumeScheduleId("session-a")).not.toBe(autoResumeScheduleId("session-b"));
+    expect(isAutoResumeScheduledWork({ id: autoResumeScheduleId("session-a") })).toBe(true);
+  });
+});
+
+describe("isAutoResumeScheduledWork", () => {
+  it("accepts the tag as authoritative regardless of the id", () => {
+    expect(isAutoResumeScheduledWork({
+      id: "wakeup:session-a",
+      source: AUTO_RESUME_SCHEDULED_WORK_SOURCE,
+    })).toBe(true);
+  });
+
+  it("falls back to the id prefix for rows persisted before the tag existed", () => {
+    expect(isAutoResumeScheduledWork({ id: "auto-resume:session-a" })).toBe(true);
+    expect(isAutoResumeScheduledWork({ id: "auto-resume:session-a", source: null })).toBe(true);
+  });
+
+  it("never claims a user- or agent-created row", () => {
+    expect(isAutoResumeScheduledWork({ id: "wakeup:session-a" })).toBe(false);
+    expect(isAutoResumeScheduledWork({ id: "cron-tool:abc", source: "something-else" }))
+      .toBe(false);
+    expect(isAutoResumeScheduledWork(null)).toBe(false);
+    expect(isAutoResumeScheduledWork(undefined)).toBe(false);
+    expect(isAutoResumeScheduledWork({})).toBe(false);
+  });
+});
+
+describe("isPendingAutoResumeScheduledWork", () => {
+  const row = { id: "auto-resume:session-a", source: AUTO_RESUME_SCHEDULED_WORK_SOURCE } as const;
+
+  it("treats live statuses as pending", () => {
+    expect(isPendingAutoResumeScheduledWork({ ...row, status: "scheduled" })).toBe(true);
+    expect(isPendingAutoResumeScheduledWork({ ...row, status: "paused" })).toBe(true);
+    expect(isPendingAutoResumeScheduledWork({ ...row, status: "fired" })).toBe(true);
+    expect(isPendingAutoResumeScheduledWork({ ...row })).toBe(true);
+  });
+
+  it("accepts both vocabularies for the finished state", () => {
+    // The host record says `done`; the client item says `completed`. Neither is
+    // pending, and the shared predicate must not disagree with itself.
+    expect(isPendingAutoResumeScheduledWork({ ...row, status: "done" })).toBe(false);
+    expect(isPendingAutoResumeScheduledWork({ ...row, status: "completed" })).toBe(false);
+    expect(isPendingAutoResumeScheduledWork({ ...row, status: "cancelled" })).toBe(false);
+  });
+
+  it("never claims a row ADE did not create, whatever its status", () => {
+    expect(isPendingAutoResumeScheduledWork({ id: "wakeup:session-a", status: "scheduled" }))
+      .toBe(false);
+    expect(isPendingAutoResumeScheduledWork(null)).toBe(false);
+  });
+});
+
+describe("formatAutoResumeTime", () => {
+  it("renders a local-time label for a real instant", () => {
+    expect(formatAutoResumeTime(Date.parse("2026-08-29T10:00:00.000Z")).trim().length)
+      .toBeGreaterThan(0);
+  });
+
+  it("returns an empty label rather than 'Invalid Date' for a bad instant", () => {
+    expect(formatAutoResumeTime(Number.NaN)).toBe("");
+  });
+});
diff --git a/apps/desktop/src/shared/chatAutoResume.ts b/apps/desktop/src/shared/chatAutoResume.ts
new file mode 100644
index 0000000000..3ca947400b
--- /dev/null
+++ b/apps/desktop/src/shared/chatAutoResume.ts
@@ -0,0 +1,156 @@
+/**
+ * Auto-resume after a provider usage limit resets.
+ *
+ * When a turn fails at a provider usage/rate limit AND the provider told us
+ * when the limit resets, ADE arms one durable scheduled-work row per chat that
+ * asks the agent to continue the interrupted task. The row is an ordinary
+ * scheduled-work record — it survives brain restarts, shows up in Chat info,
+ * and is cancellable through the normal `chat.cancelScheduledWork` path.
+ *
+ * Shared between the main process (which arms and cancels the row) and the
+ * renderer (which recognises the row so a user schedule is never mistaken for
+ * an ADE-created one).
+ */
+
+/** Tag written to the scheduled-work record so cancel-on-activity is scoped. */
+export const AUTO_RESUME_SCHEDULED_WORK_SOURCE = "auto_resume_limit";
+
+/**
+ * Providers report the reset instant with minute granularity at best, and a
+ * request issued exactly at the boundary is still rejected often enough to
+ * matter. Wait out a short buffer instead of burning the resume on a 429.
+ */
+export const AUTO_RESUME_BUFFER_MS = 90_000;
+
+export const AUTO_RESUME_PROMPT =
+  "The provider usage limit has reset. Continue the interrupted task from where it stopped; do not restart work that already completed.";
+
+export const AUTO_RESUME_REASON = "Auto-resume after usage limit reset";
+
+const AUTO_RESUME_ID_PREFIX = "auto-resume:";
+
+/**
+ * Deterministic per-chat id. Dedupe is structural: a repeat failure upserts the
+ * same row instead of stacking a second resume.
+ */
+export function autoResumeScheduleId(sessionId: string): string {
+  return `${AUTO_RESUME_ID_PREFIX}${sessionId}`;
+}
+
+/**
+ * Recognises ADE-created auto-resume rows. The tag is authoritative; the id
+ * prefix is the fallback for rows persisted before the tag existed.
+ */
+export function isAutoResumeScheduledWork(
+  schedule: { id?: string | null; source?: string | null } | null | undefined,
+): boolean {
+  if (!schedule) return false;
+  if (schedule.source === AUTO_RESUME_SCHEDULED_WORK_SOURCE) return true;
+  return typeof schedule.id === "string" && schedule.id.startsWith(AUTO_RESUME_ID_PREFIX);
+}
+
+/**
+ * Both status vocabularies for one scheduled-work row.
+ *
+ * The host record (`ChatScheduledWorkStatus`) spells the finished state `done`;
+ * the client item (`AgentChatScheduledWorkItem`, and the wider
+ * `AgentChatScheduledWorkStatus`) spells it `completed`. Nothing translates
+ * between them at the boundary, so the shared predicate below has to accept
+ * both rather than silently disagreeing on which rows are still pending.
+ */
+type AutoResumeScheduledWorkStatus =
+  | "scheduled"
+  | "paused"
+  | "running"
+  | "fired"
+  | "missed"
+  | "done"
+  | "completed"
+  | "cancelled"
+  | "failed"
+  | "stopped";
+
+type AutoResumeScheduledWorkLike = {
+  id?: string | null;
+  source?: string | null;
+  status?: AutoResumeScheduledWorkStatus | null;
+};
+
+/**
+ * An ADE-created auto-resume row that has not finished or been cancelled — the
+ * one the main process sweeps on user activity and the one the renderer offers
+ * a Cancel for. Shared so the two surfaces cannot drift.
+ */
+export function isPendingAutoResumeScheduledWork(
+  schedule: AutoResumeScheduledWorkLike | null | undefined,
+): boolean {
+  if (!isAutoResumeScheduledWork(schedule)) return false;
+  const status = schedule?.status;
+  return status !== "done" && status !== "completed" && status !== "cancelled";
+}
+
+/**
+ * Fire time for a known reset instant, or `null` when there is nothing useful
+ * to arm — an unknown reset, or one whose buffered fire time already passed
+ * (the limit is already back, so the manual retry affordance is the right
+ * answer and a schedule would fire immediately for no reason).
+ */
+export function autoResumeFireAtMs(
+  resetsAtMs: number | null | undefined,
+  nowMs: number,
+): number | null {
+  if (typeof resetsAtMs !== "number" || !Number.isFinite(resetsAtMs) || resetsAtMs <= 0) return null;
+  const fireAt = resetsAtMs + AUTO_RESUME_BUFFER_MS;
+  return fireAt > nowMs ? fireAt : null;
+}
+
+/**
+ * Whether a chat `error` event is a provider usage/rate limit.
+ *
+ * Two shapes exist in the wild: the structured `errorInfo.category` the host
+ * classifiers produce, and the opaque provider string Codex forwards as
+ * `codexErrorInfo` (which spells its usage limit "usageLimitReached", not
+ * "usageLimitExceeded"). This is the single predicate: the host arms the
+ * schedule from it and the renderer's `classifyProviderFailure` delegates its
+ * `rate_limit` branch to it, so the card, the anchor, and the schedule can
+ * never disagree about what counts as a usage limit.
+ */
+export function isUsageLimitChatError(event: {
+  message?: string | null;
+  errorInfo?:
+    | string
+    | { category?: string | null }
+    | null;
+}): boolean {
+  const errorInfo = event.errorInfo;
+  if (errorInfo && typeof errorInfo === "object" && errorInfo.category === "rate_limit") return true;
+  const identity = `${typeof errorInfo === "string" ? errorInfo : ""} ${event.message ?? ""}`
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "");
+  return identity.includes("usagelimit") || identity.includes("ratelimit");
+}
+
+/** Local-time label used in the failure notice and the recovery card. */
+export function formatAutoResumeTime(fireAtMs: number): string {
+  const date = new Date(fireAtMs);
+  if (Number.isNaN(date.getTime())) return "";
+  try {
+    return new Intl.DateTimeFormat(undefined, {
+      hour: "numeric",
+      minute: "2-digit",
+      month: "short",
+      day: "numeric",
+    }).format(date);
+  } catch {
+    return date.toLocaleString();
+  }
+}
+
+/**
+ * The one "auto-resume is armed" sentence. The host writes it into the chat as
+ * a system notice; the renderer's recovery card shows it live next to Cancel.
+ * Shared so the two can never disagree about what was scheduled or when.
+ */
+export function autoResumeScheduledMessage(fireAtMs: number): string {
+  return `Auto-resume scheduled for ${formatAutoResumeTime(fireAtMs)}`;
+}
diff --git a/apps/desktop/src/shared/ipc.ts b/apps/desktop/src/shared/ipc.ts
index d8e58230ff..91b5546310 100644
--- a/apps/desktop/src/shared/ipc.ts
+++ b/apps/desktop/src/shared/ipc.ts
@@ -151,6 +151,8 @@ export const IPC = {
   remoteRuntimeCallSync: "ade.remoteRuntime.callSync",
   remoteRuntimeUpdateAndRestart: "ade.remoteRuntime.updateAndRestart",
   remoteRuntimeEnsurePortForward: "ade.remoteRuntime.ensurePortForward",
+  remoteRuntimeAttachmentUploadCapability: "ade.remoteRuntime.attachmentUploadCapability",
+  remoteRuntimeUploadChatAttachment: "ade.remoteRuntime.uploadChatAttachment",
   remoteRuntimeStreamEvents: "ade.remoteRuntime.streamEvents",
   remoteRuntimeDisconnect: "ade.remoteRuntime.disconnect",
   localRuntimeListActionRegistry: "ade.localRuntime.listActionRegistry",
@@ -332,6 +334,7 @@ export const IPC = {
   agentChatRewindFiles: "ade.agentChat.rewindFiles",
   agentChatFileSearch: "ade.agentChat.fileSearch",
   agentChatSaveTempAttachment: "ade.agentChat.saveTempAttachment",
+  agentChatCopyTempAttachment: "ade.agentChat.copyTempAttachment",
   agentChatListSubagents: "ade.agentChat.listSubagents",
   agentChatKillDroidWorker: "ade.agentChat.killDroidWorker",
   agentChatGetSessionCapabilities: "ade.agentChat.getSessionCapabilities",
diff --git a/apps/desktop/src/shared/types/chat.ts b/apps/desktop/src/shared/types/chat.ts
index 3e5b75c082..93a53c678f 100644
--- a/apps/desktop/src/shared/types/chat.ts
+++ b/apps/desktop/src/shared/types/chat.ts
@@ -350,6 +350,40 @@ export type AgentChatImageUrlRef = {
 
 export type AgentChatFileRef = AgentChatLocalFileRef | AgentChatImageUrlRef;
 
+/**
+ * Stage an attachment that already exists on the same machine as the main
+ * process, by path. Local-only by construction: `sourcePath` names a file on
+ * the client's disk, so this never routes to a remote runtime — a paired host
+ * gets the bytes over the attachment upload route (or base64) instead.
+ */
+export type AgentChatCopyTempAttachmentArgs = {
+  /** Absolute path on this machine, from `webUtils.getPathForFile`. */
+  sourcePath: string;
+  /** Display name; only its extension is used for the staged copy. */
+  filename: string;
+};
+
+/**
+ * How the composer must move an attachment to the machine that owns the chat,
+ * and the ceiling that path can carry.
+ *
+ * - `copy` — same machine. Send the path, the brain copies the file.
+ * - `upload` — paired host advertising the streamed HTTP route. Send the path,
+ *   the main process streams the bytes.
+ * - `base64` — everything else: a host predating the upload route, a
+ *   relay-routed socket, or a client with no real path for the file (clipboard
+ *   paste, hosted web). Read the bytes and use `saveTempAttachment`, which
+ *   keeps the legacy image-only contract capped at
+ *   `LEGACY_MAX_CHAT_ATTACHMENT_BYTES`.
+ *
+ * The cap travels WITH the mode on purpose. A renderer that hardcoded 50 MB
+ * would let a user stage a file the chosen transport then rejects halfway.
+ */
+export type ChatAttachmentStagingMode = {
+  mode: "copy" | "upload" | "base64";
+  maxBytes: number;
+};
+
 /** MIME/extension checks for photos from iPhone and other HEIF-producing cameras. */
 const HEIC_MIME_RE = /^image\/hei[cf](?:[-+;]|$)/i;
 const HEIC_EXTENSION_RE = /\.(heic|heif)$/i;
@@ -2805,6 +2839,11 @@ export type AgentChatScheduledWorkItem = {
   cancellable: boolean;
   late?: boolean;
   outcomeSummary?: string;
+  /**
+   * Provenance for rows ADE armed itself rather than the user or the agent.
+   * Additive and optional: older clients simply ignore it.
+   */
+  source?: "auto_resume_limit";
 };
 
 export type AgentChatListScheduledWorkArgs = {
diff --git a/apps/desktop/src/shared/types/sync.ts b/apps/desktop/src/shared/types/sync.ts
index 79a4ea7b10..8e3cf79aa5 100644
--- a/apps/desktop/src/shared/types/sync.ts
+++ b/apps/desktop/src/shared/types/sync.ts
@@ -686,6 +686,20 @@ export type SyncFeatureFlags = {
   chatHistoryPaging?: {
     enabled: true;
   };
+  /**
+   * Streamed HTTP attachment upload. When present, a client may mint a ticket
+   * with `chat.createAttachmentUpload` and POST the file body to `path` on this
+   * host's sync HTTP port instead of base64-ing it through the command channel,
+   * which lifts the attachment ceiling to `maxBytes` and allows non-image types.
+   * Older hosts omit this field; clients must fall back to
+   * `chat.saveTempAttachment` with the legacy image-only cap,
+   * `LEGACY_MAX_CHAT_ATTACHMENT_BYTES`.
+   */
+  attachmentUploadV1?: {
+    enabled: true;
+    path: string;
+    maxBytes: number;
+  };
   projectCatalog: {
     enabled: boolean;
   };
@@ -1839,6 +1853,7 @@ export type SyncRemoteCommandAction =
   | "chat.rewindFiles"
   | "chat.getTurnFileDiff"
   | "chat.saveTempAttachment"
+  | "chat.createAttachmentUpload"
   | "chat.listPromptStashes"
   | "chat.createPromptStash"
   | "chat.deletePromptStash"
diff --git a/apps/ios/ADE/Views/Work/WorkChatAttachmentTray.swift b/apps/ios/ADE/Views/Work/WorkChatAttachmentTray.swift
index 8698f9f52d..69582625ae 100644
--- a/apps/ios/ADE/Views/Work/WorkChatAttachmentTray.swift
+++ b/apps/ios/ADE/Views/Work/WorkChatAttachmentTray.swift
@@ -6,6 +6,10 @@ import UIKit
 private let workChatRemoteImageMaxBytes = 5 * 1024 * 1024
 private let workChatRemoteImageTimeoutSeconds: TimeInterval = 12
 private let workChatAttachmentPreviewMinimumPixels: CGFloat = 96
+// Mirrors `LEGACY_MAX_CHAT_ATTACHMENT_BYTES` in
+// apps/desktop/src/shared/chatAttachmentLimits.ts: the phone always stages
+// attachments as base64 over sync, which is the leg that cap governs. Change
+// both together.
 private let workChatInputAttachmentMaxBytes = 10 * 1024 * 1024
 private let workChatInputAttachmentInitialMaxDimension: CGFloat = 2400
 private let workChatInputAttachmentMinimumMaxDimension: CGFloat = 960
diff --git a/apps/ios/ADETests/ADETests.swift b/apps/ios/ADETests/ADETests.swift
index a85ced18b9..982d253be8 100644
--- a/apps/ios/ADETests/ADETests.swift
+++ b/apps/ios/ADETests/ADETests.swift
@@ -14694,6 +14694,64 @@ final class ADETests: XCTestCase {
     XCTAssertNil(summary.nextWakeAt)
   }
 
+  /// The other direction of the same contract: a host newer than this build.
+  ///
+  /// Desktop tags rows ADE armed itself (`source: "auto_resume_limit"`, the
+  /// auto-resume-after-usage-limit row) and iOS deliberately ships no UI for
+  /// that tag. The exclusion only holds if the tag is inert AND the row still
+  /// reaches the generic Chat info schedule list self-describing — its title
+  /// carries the host's reason, and `cancellable` keeps the Cancel affordance
+  /// that routes back through `chat.cancelScheduledWork`, which is where the
+  /// host clears its own re-arm state. A `CodingKeys` block or a stricter
+  /// decoder added later would drop the whole row, not just the tag.
+  func testScheduledWorkRowFromNewerHostDecodesAndRendersWithoutTagAwareness() throws {
+    let summaryData = Data(#"""
+    {
+      "sessionId":"chat-auto-resume",
+      "laneId":"lane-1",
+      "provider":"claude",
+      "model":"claude-sonnet",
+      "status":"idle",
+      "startedAt":"2026-07-08T00:00:00.000Z",
+      "lastActivityAt":"2026-07-08T00:00:03.000Z",
+      "scheduledWork":[{
+        "id":"auto-resume:chat-auto-resume",
+        "sessionId":"chat-auto-resume",
+        "kind":"wakeup",
+        "status":"scheduled",
+        "title":"Auto-resume after usage limit reset",
+        "prompt":"The provider usage limit has reset. Continue the interrupted task from where it stopped; do not restart work that already completed.",
+        "reason":"Auto-resume after usage limit reset",
+        "nextRunAt":"2026-07-08T01:00:00.000Z",
+        "createdAt":"2026-07-08T00:00:03.000Z",
+        "durable":true,
+        "cancellable":true,
+        "source":"auto_resume_limit"
+      }]
+    }
+    """#.utf8)
+
+    let summary = try JSONDecoder().decode(AgentChatSessionSummary.self, from: summaryData)
+    XCTAssertEqual(summary.scheduledWork?.count, 1)
+
+    let merged = mergeManagedWorkScheduledWorkSnapshots(
+      local: [],
+      managedWork: summary.scheduledWork
+    )
+    let row = try XCTUnwrap(merged.first)
+    XCTAssertEqual(row.id, "auto-resume:chat-auto-resume")
+    XCTAssertEqual(row.title, "Auto-resume after usage limit reset")
+    XCTAssertEqual(row.origin, "schedule_wakeup")
+    XCTAssertEqual(row.nextRunAt, "2026-07-08T01:00:00.000Z")
+    XCTAssertEqual(row.cancellable, true)
+    XCTAssertEqual(row.durable, true)
+    // Lands in the schedule section, not background, and is not filed as an
+    // already-finished item — so it shows as live work the user can cancel.
+    XCTAssertEqual(workChatInfoScheduleItems(merged).map(\.id), [row.id])
+    XCTAssertTrue(workChatInfoBackgroundItems(merged).isEmpty)
+    XCTAssertFalse(workScheduleItemIsEarlier(row))
+  }
+
   func testWorkTimelineKeepsSubagentsOutOfMainActivityBundles() {
     // The two activity updates are consecutive so they cluster into one bundle;
     // the real subagent's spawn row is a hard timeline boundary that sits
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index d198a2ba20..1f36a685e1 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -873,7 +873,14 @@ ade.agentChat.*              # agent chat sessions, model inventory, parallel la
                              # optional KV-backed scheduledWork management snapshot. The
                              # namespace also exposes explicit `regenerateSessionMetadata`,
                              # one structured title/lane/status request whose remote form is
-                             # optional for older mobile clients.
+                             # optional for older mobile clients. Attachment staging is two
+                             # channels, not one: saveTempAttachment is the base64 leg (10 MB;
+                             # the image MIME sniff applies on the sync leg only) and
+                             # copyTempAttachment stages a file that already
+                             # exists on this machine's disk by copying it (50 MB, any type,
+                             # bytes never enter the renderer). The preload picks between them
+                             # — and the remote upload route — from getAttachmentStagingMode.
+                             # See features/chat/composer-and-ui.md.
 ade.personalChats.*          # preload namespace over machine RPC: allowlisted personal-chat
                              # call + cursor event stream. Local/no-project windows target the
                              # local brain; a remote-bound project window targets that remote brain.
@@ -930,7 +937,16 @@ ade.keepAwake.*              # get / setLevel / fixSystemSleep for the opt-in
 ade.remoteRuntime.*          # remote target registry, connect/projects/project-open,
                              # action/sync/event dispatch, port forwards, and
                              # ade.remoteRuntime.updateAndRestart — the desktop half
-                             # of the host's `machine.updateAndRestart` (§2.1)
+                             # of the host's `machine.updateAndRestart` (§2.1).
+                             # attachmentUploadCapability answers whether a paired target
+                             # accepts a streamed HTTP attachment upload (and at what
+                             # ceiling); uploadChatAttachment mints a ticket over the
+                             # authenticated sync socket and POSTs the file body to the
+                             # host's sync port. The upload channel is one of the few with
+                             # a bespoke budget in ipcTimeouts.ts (6 min, above the upload
+                             # client's own 5 min) so a slow 50 MB transfer surfaces the
+                             # real reason instead of a transport timeout.
+                             # See features/sync-and-multi-device/README.md
 ```
 
 ### 5.3 Main-process handlers
diff --git a/docs/features/chat/README.md b/docs/features/chat/README.md
index e5838f3c7a..0014148bdf 100644
--- a/docs/features/chat/README.md
+++ b/docs/features/chat/README.md
@@ -133,7 +133,11 @@ for its separate RPC, sync, storage, and UI contracts.
 | `apps/desktop/src/renderer/components/chat/ChatBuiltInBrowserPanel.tsx` | Renderer panel for the in-app browser. Renders the address bar, tabs strip, navigation controls, an inspect/select toolbar, and a `BuiltInBrowserStatus`-derived empty/error state, then asks the main process to position the underlying `WebContentsView` over the panel's bounding rect through `ade.builtInBrowser.setBounds`. Its trusted-renderer-only **Profile** panel shows global cookie counts/domains, cache size, last safe flush, and remembered site permissions, with per-row Remove and Clear all controls. Because native `WebContentsView` content sits above the renderer, the panel hides it while ADE overlays, dialogs, menus, or popovers overlap the browser surface so ADE chrome remains reachable. Mounted by `WorkSidebar` under the `browser` tab and (indirectly) by any renderer code that calls `openUrlInAdeBrowser()` — the helper opens the sidebar Browser tab and dispatches the URL into a fresh tab. Selections committed through inspect-mode hit-testing fan out via the `onAddContext` callback as `BuiltInBrowserContextItem` payloads. |
 | `apps/desktop/src/renderer/components/work/WorkSurfaceHeader.tsx`, `ClaudeLoginPromptButton.tsx` | Shared Work surface header chrome for chat and CLI surfaces: title, lane chip, Claude cache badge, git toolbar, caller-provided trailing actions, and the dismissible Claude login CTA that starts `claude auth login` in a tracked PTY. The `WorkSurfaceTitle` sub-component plays a one-time CSS shimmer when the title transitions from a provider default (`Claude Chat`, `Codex Chat`, …) to a real auto-generated title while the surface stays mounted, and respects `prefers-reduced-motion`. `AgentChatPane` also reuses `ClaudeLoginPromptButton` as a sticky bar above the composer (keyed `composer-auth:<sessionId>`) while a Claude session is logged out. Settled state is rendered by `ChatLifecycleBanner` as a compact pill above the composer; the header takes a `snoozeSessionId` for the remaining snooze affordance — see [composer-and-ui.md › Header](composer-and-ui.md#header). |
 | `apps/desktop/src/renderer/components/chat/AgentCliAuthCard.tsx` | Inline install / re-login card for missing or unauthenticated agent CLIs, rendered in the transcript from a decorated `error` event's `errorInfo.agentCli` payload. Copy chips + a tracked-PTY Run button (`window.ade.pty.create`) for the install / auth command. The logged-out (`category: "unauthenticated"`) variant is terracotta-toned for Claude (amber for other agents), retitles to "&lt;Provider&gt; is logged out", and adds an always-on **Retry turn** button that resends the last user message via the `CHAT_RETRY_AUTH_TURN_EVENT` (`ade:chat:retry-auth-turn`) window event; it collapses to a "Reconnected" confirmation when `AgentChatPane` fires `CHAT_AUTH_RECOVERED_EVENT` (`ade:chat:auth-recovered`) after a later turn succeeds. The "missing CLI" variant keeps the red-free amber install card. |
-| `apps/desktop/src/renderer/components/chat/ProviderFailureRecoveryCard.tsx` | Classifies terminal provider capacity and usage-limit errors into actionable transcript cards. The card explains that the thread remains safe, offers an explicit same-thread **Retry turn**, and opens the composer model picker through a one-shot request for **Choose model**; neither action is enabled while another turn is active. |
+| `apps/desktop/src/renderer/components/chat/ProviderFailureRecoveryCard.tsx` | Classifies terminal provider capacity and usage-limit errors into actionable transcript cards. The card explains that the thread remains safe, offers an explicit same-thread **Retry turn**, and opens the composer model picker through a one-shot request for **Choose model**; neither action is enabled while another turn is active. When a usage-limit failure left an auto-resume armed, the card also shows `Auto-resume scheduled for <local time>` with a **Cancel auto-resume** button; the pending row arrives through `ChatAutoResumeContext`, which `AgentChatPane` fills from the chat's scheduled-work list. |
+| `apps/desktop/src/shared/chatAutoResume.ts` | Auto-resume after a provider usage limit resets. When a turn fails at a usage/rate limit **and** the provider published a reset instant (Claude's plan-quota snapshot, Codex's `account/rateLimits`), the chat service arms one durable scheduled-work row per chat at reset + a 90s buffer, prompting the agent to continue the interrupted task. The row uses the deterministic id `auto-resume:<sessionId>` and the `source: "auto_resume_limit"` tag, so a repeat failure replaces it rather than stacking, and ADE's own cancel-on-activity sweep never touches a user- or agent-created schedule. No reset time means no schedule — the manual recovery card stays the only path. The row is cancelled when the user sends a message or retries the turn, when the schedule is cancelled from the card or Chat Info, and when the chat is archived, deleted, or disposed. Delivery is ordinary scheduled work: a turn already active at the due time defers the resume to the next turn boundary instead of double-sending. This module is the shared half: the id/tag grammar, the buffer, the prompt, the local-time label, `autoResumeFireAtMs` (which returns null for an unknown or already-passed reset), `isPendingAutoResumeScheduledWork` (which accepts both status vocabularies — the host record spells the finished state `done`, the client item `completed`), and `isUsageLimitChatError`, the one predicate the host arms from *and* the renderer's `classifyProviderFailure` delegates its `rate_limit` branch to, so the card and the schedule can never disagree about what counts as a usage limit (Codex spells it `usageLimitReached`, not `usageLimitExceeded`). |
+| `apps/desktop/src/main/services/chat/chatAutoResumeCoordinator.ts` | The whole auto-resume subsystem on the host: per-chat streak state, the durable row, two system notices, and the races between arming, cancelling and firing. `agentChatService` keeps only thin call sites — it reports a limit error, a dispatch, a dismissal, and a turn finishing, and this decides what each means. Three contracts are load-bearing. **`cancelEpoch`**: arming is asynchronous (it waits for the scheduler, then upserts), so a user message can land while the upsert is in flight and find nothing to cancel; every cancel bumps the epoch and the arm undoes its own row if the epoch moved. **The re-arm cap** (`AUTO_RESUME_MAX_CONSECUTIVE_ARMS = 2`): the reset instant a provider publishes is not always the limit that rejected the turn — Claude's snapshot is session-scoped and can carry a stale `resetsAtMs` forward, so a weekly-limit rejection would arm against a session reset, fail again, and burn a turn every cycle. Two arms against *distinct* reset instants, then the chat emits `Auto-resume paused after two attempts` and waits for a human. A resume that runs without hitting the limit again resets the streak, which is why `noteResumeTurnStarted` / `noteTurnFinished` exist: a fired resume always carries `scheduledWake`, exactly what the cancel sweep skips, so without that watch the cap would be a lifetime budget and a healthy headless chat would pause itself after two limits days apart. **Notice ordering**: both notices are emitted after one microtask, because this runs inside the event commit before the error event has minted its sequence number and an inline emit would render the notice above the failure it explains. Notices are `system_notice` rows with `noticeKind: "rate_limit"`, attributed to the failed turn, de-duped one per armed fire time. |
+| `apps/desktop/src/main/services/chat/attachmentInlineGuard.ts` | The one check every adapter that base64s attachment bytes into a model request runs, plus the stand-in it substitutes. `MAX_PROVIDER_INLINE_IMAGE_BYTES` (10 MB) is deliberately smaller than the 50 MB attachment cap: most providers receive a *path* and do not care how large the file is, but Claude images (`buildClaudeV2Message`), the AI-SDK streaming content OpenCode uses (`buildStreamingUserContent`), and the Droid/Pi prompt blocks (`buildAgentPromptBlocks`) inline the bytes, where base64 inflates by a third and the provider rejects the request. Over the ceiling those three push `inlineAttachmentHintPart` instead — a text part naming the path, the size, and the limit, so the agent can read the file with its own tools and the turn still runs. `workerAttachmentImages.ts` uses the same constant for Cursor/Pi/Droid worker IPC, and it deliberately did not move when the attachment cap did. |
+| `apps/desktop/src/shared/chatAttachmentStagingFs.ts` | The disk-side rule for staging a chat attachment, shared by every process that writes into `<projectRoot>/.ade/attachments`: the desktop main process, the ADE action registry the local brain serves, the CLI sync host's HTTP upload route, and `imageAttachment.ts`. `projectAttachmentsDir` is the one spelling of the directory; `stageAttachmentCopy` copies a file that already exists on this machine's disk; `stageAttachmentBytes` writes bytes a caller already holds. Both give the destination a fresh UUID basename with only a regex-validated extension from the caller's display name (`safeAttachmentExtension`), then re-check containment with `path.relative` rather than a string prefix — the prefix form false-rejects a filesystem or Windows drive root and cannot see a cross-drive path at all. `stageAttachmentCopy` is deliberately *not* constrained to the project root (users drag files in from Downloads), stats for size before copying a byte, and must only ever be reachable from the machine that owns the file. There used to be three copies of this rule and only two validated the extension, so the same drag-and-drop produced a differently-named file depending on which process answered. |
 | `apps/desktop/src/renderer/components/chat/chatTurnState.ts` | Shared renderer turn-state invariant used by cache hydration, history snapshots, live event flushes, and locked-session summary refreshes. A terminal `status`/`done` at the end of the transcript outranks an eventually consistent `status: "active"` session summary, so failed/interrupted turns restore an idle composer. Also resolves the user message associated with a failed turn, including Codex optimistic user rows that predate assignment of a provider `turnId`. |
 | `apps/desktop/src/renderer/lib/claudeAuthPrompt.ts` | Renderer-side classifier for Claude logged-out / `/login`-required error text. Drives the header and sticky login CTAs; matches both Claude-first wording and ADE's own "Authentication failed for &lt;model&gt;" classified message. |
 | `apps/desktop/src/renderer/lib/openExternal.ts` | Renderer-side router for outbound URLs. Defines the `ADE_OPEN_BUILT_IN_BROWSER_EVENT` window event plus `openUrlInAdeBrowser(url)` and `openExternalUrl(url)`. `openUrlInAdeBrowser` dispatches the event (so any open `WorkSidebar` can flip to its Browser tab), then calls `window.ade.builtInBrowser.navigate({ url, newTab: true })`. Anything that is not a normal `http`/`https`/`about:blank` URL falls through to `window.ade.app.openExternal` (system browser). All in-renderer URL clicks (markdown links, lane-runtime open buttons, etc.) go through this helper so the user stays inside ADE. |
@@ -384,6 +388,55 @@ Controls and summaries project this runtime state rather than owning it:
   offers a compact, dismissible while-you-were-away card above the composer;
   its Review action jumps to the first stable divider row key.
 
+### Auto-resume after a usage limit
+
+ADE creates exactly one kind of schedule on the user's behalf. When a turn dies
+at a provider usage/rate limit **and** the provider published a reset instant,
+`chatAutoResumeCoordinator` arms a durable one-shot at reset + 90 s (providers
+report the boundary with minute granularity at best, and a request issued
+exactly at it is still rejected often enough to matter) whose prompt asks the
+agent to continue the interrupted task without redoing finished work. Only two
+providers publish a reset today: Claude's plan-quota snapshot and Codex's
+`account/rateLimits`. Every other provider — and Claude or Codex when the
+snapshot is empty — arms nothing, and the manual recovery card stays the only
+path.
+
+Everything else follows from that row being an ordinary scheduled-work record.
+It survives brain restarts, appears in Chat Info, and cancels through the normal
+`chat.cancelScheduledWork`. Delivery obeys the same boundary rule as every other
+wake: due during a live turn means retry, never a second prompt into that turn.
+
+Three rules are specific to it:
+
+- **The tag scopes the sweep.** The row carries `source: "auto_resume_limit"`
+  and the deterministic id `auto-resume:<sessionId>`, so a repeat failure
+  upserts the same row instead of stacking a second resume, and ADE's
+  cancel-on-user-activity sweep can find its own row without touching a cron,
+  wakeup, or `/loop` the user or the agent asked for. Cancellation fires from
+  both dispatch commit points — the ordinary send and the accepted branch of
+  the steer queue — which together cover send, steer, wake queue, continuity
+  capsule, and the headless `runSessionTurn`. A message refused upstream leaves
+  the resume armed, and a send carrying `scheduledWake` is exempt so a fired
+  resume cannot cancel itself. That exemption is also why the renderer strips
+  `scheduledWake` from replayed metadata on a **user-initiated retry**: without
+  it the retry would inherit the exemption and leave a schedule armed that the
+  transcript notice just promised retrying would cancel.
+- **Two arms, then it stops.** The reset instant ADE can see is not always the
+  limit that rejected the turn — Claude's snapshot is session-scoped and can
+  carry a stale `resetsAtMs` forward, so a weekly-limit rejection would arm
+  against a session reset, die at the same limit when it fires, and burn a real
+  turn every cycle. After two arms against distinct reset instants the chat
+  posts `Auto-resume paused after two attempts` and waits for a human. A resume
+  that runs *without* hitting the limit again proves the window was right and
+  resets the streak, so a healthy headless chat that hits limits days apart
+  never pauses itself.
+- **It announces itself in the transcript.** Both outcomes are
+  `system_notice` rows with `noticeKind: "rate_limit"`, attributed to the failed
+  turn, so `ProviderFailureRecoveryCard` renders them beside the failure they
+  explain — and the live schedule with its **Cancel auto-resume** button appears
+  only on the newest usage-limit card, never on every one in the thread's
+  history.
+
 ## Key concepts
 
 - **Claude Agent SDK pipeline.** The Claude adapter is built on the
@@ -1624,7 +1677,9 @@ handlers live in `apps/desktop/src/main/services/ipc/registerIpc.ts`.
 | `ade.agentChat.claudeOutputStyles.list` / `.set` | invoke | Claude-only: list and select discovered output styles (user + project + plugin roots). Backs `/output-style`. |
 | `ade.agentChat.claudeSessions.list` / `.info` / `.messages` | invoke | Claude-only: enumerate SDK sessions, fetch session info, and stream messages for `forkSession` handoff and resume flows. |
 | `ade.agentChat.fileSearch` | invoke | Debounced attachment picker backend. |
-| `ade.agentChat.saveTempAttachment` | invoke | Write pasted/dropped image bytes to a runtime-owned temp file (10 MB cap). Desktop and ADE Code clipboard-image paste use this route so local and remote chats both receive an attachment path the agent can read. |
+| `ade.agentChat.saveTempAttachment` | invoke | Write pasted image bytes to a runtime-owned temp file. This is the base64 leg, so it keeps `LEGACY_MAX_CHAT_ATTACHMENT_BYTES` (10 MB); the image MIME sniff runs on the sync leg only — the local IPC/action handlers check size and extension shape. Clipboard pastes, renderer-converted HEIC, and every file in the hosted web client take it, as does ADE Code clipboard-image paste, so local and remote chats both receive an attachment path the agent can read. |
+| `ade.agentChat.copyTempAttachment` | invoke | Stage a file that already exists on **this** machine's disk by copying it, so the bytes never enter the renderer. Backs the preload `agentChat.stageFileAttachment` whenever the chat's binding is `kind: "local"`, and carries the 50 MB `MAX_CHAT_ATTACHMENT_BYTES` product cap with no type restriction. Reached only after `getAttachmentStagingMode` answered `copy` — which preload answers itself, because "same machine as the main process" is a property of the caller, not of the target. It is also on the ADE action allowlist and therefore reachable over sync RPC from a paired peer; that is not an escalation, because opening that channel requires a runtime-host pairing grant and a peer holding one already reaches `chat.launchCli`. Pairing, not this allowlist, is where that trust is decided. |
+| `ade.remoteRuntime.attachmentUploadCapability` / `ade.remoteRuntime.uploadChatAttachment` | invoke | The remote half of the same preload calls. The capability probe answers a `ChatAttachmentStagingMode` directly (`upload` with the host's ceiling, or `base64` with the legacy one); the upload mints a ticket over the authenticated sync socket and streams the file body over HTTP. The upload channel carries a 6-minute IPC budget in `ipcTimeouts.ts` — above the client's own 5-minute budget, so a slow 50 MB upload reports the legible reason instead of a transport timeout that also drops the pending chip. |
 | `ade.agentChat.getImageDataUrl` | invoke | Read a bounded project-local image file through the active runtime and return a data URL for attachment previews. The service validates realpath containment, file type, and size before reading; the renderer falls back to the local guarded app reader only when no runtime preview is available or the runtime read fails for a local-only path. |
 | `ade.agentChat.listSubagents` | invoke | Provider-neutral subagent snapshot list. Snapshots are re-keyed on `agentId + parentToolUseId` (not just `taskId`) so multiple subagents spawned from the same parent tool call don't collide, and the renderer panel separates them into three tabs: Subagents, Teammates, and Background. Claude `subagent_*` envelopes are enriched with `agentType` (e.g. `code-reviewer`, `Explore`) by stashing the Task tool's `subagent_type` input at the assistant `tool_use` boundary and joining on `parentToolUseId` when the system-message `task_*` envelope arrives. Codex parallel-agent events carry an `Agent #N` label assigned at first announcement (1-based, per-turn) plus the raw threadId as `agentId`. OpenCode snapshots use the child session id, Cursor Task snapshots use the tool call id plus any returned child agent id, and Droid worker snapshots use the worker session id. |
 | `ade.agentChat.getSubagentTranscript` | invoke | Fetch the transcript of one subagent run within a chat session. Dispatch by runtime kind: Claude/ade-code reads the SDK's per-subagent JSONL at `~/.claude/projects/<projectDir>/<sessionId>/subagents/agent-<agentId>.jsonl`; OpenCode pulls the child session's messages over the OpenCode HTTP client (the child session id is the agentId); Codex returns captured child-thread stream rows for the registered collab thread and merges them with `thread/turns/list` app-server backfill, with the legacy parent `subagent_*` envelope filter only as fallback; Cursor filters the parent stream by either the returned child `agentId` or the Task tool call `taskId`, since failed starts may not return an agent id; LM Studio / Droid return `null`. Returns `AgentChatSubagentTranscriptMessage[]` (same shape as `AgentChatClaudeSessionMessage`). |
diff --git a/docs/features/chat/composer-and-ui.md b/docs/features/chat/composer-and-ui.md
index b5cf5ff7e2..a85ea5b712 100644
--- a/docs/features/chat/composer-and-ui.md
+++ b/docs/features/chat/composer-and-ui.md
@@ -22,7 +22,7 @@ subagents, computer use). The pane derives all visible state from the
 | `AgentChatMessageList.tsx` | Virtualized message list. The virtualizer is **hand-rolled**, not `@tanstack/react-virtual`: a `measuredHeights` row-key → height `Map` feeds top/bottom spacer divs around the rendered window, and each rendered row is wrapped in `MeasuredEventRow`, whose `ResizeObserver` reports its real height through `handleMeasure` → `reconcileMeasuredScrollTop` so a height correction above the viewport does not shift what the reader is looking at. Renders transcript rows and turn dividers, including a `Woke on schedule` divider before every synthetic scheduled turn and inline `SubagentSpawnCard` / `SubagentResultCard` / `BackgroundJobLine` rows (from `SubagentActivityCards.tsx`) for real subagents and backgrounded shell commands, and accepts stable row-key jump requests from the compact while-you-were-away card and the spawn/result jump affordances. Keeps sticky-bottom sessions pinned across streamed row growth and late virtual-height measurements. A Claude `queue_recovery: available` row renders one eight-second Undo card; later `restored`/`expired` rows settle the same recovery id so history replay cannot show a stale action. The last text block of a multi-block assistant turn exposes Copy turn, which joins only that turn's assistant text blocks with blank lines; legacy rows without a turn id and single-block turns keep only the normal block copy. Plan-approval rows with non-empty body text render a scrollable markdown block (capped at `360px`) beneath the header so the user can review plan content inline. Codex goal lifecycle rows use user-facing text such as `Goal set`, `Goal paused`, and `Goal cleared`. A stalled Codex turn renders a clickable Wait / Nudge / Retry / Resume recovery card wired to `agentChat.recoverCodexTurn`; terminal provider capacity/usage-limit errors render `ProviderFailureRecoveryCard` with same-thread retry and model-selection actions. User messages marked `metadata.hideFullPrompt` render and copy only their `displayText`, keeping internal handoff briefs out of the visible transcript details, and a handoff-brief user row shows a small brief chip. When a fork seeds pre-fork history into the new chat, the envelopes carry the `handoff_fork` provider origin and the list draws a single `Forked from the previous chat — full history above` divider (`computeForkHistoryDividerRowKey` pins it to the first live row after the seeded history) instead of one marker per seeded row. `WorkingIndicator` is the in-flight turn's status line — `<activity> · working for <elapsed>`, plus a `taking longer than usual` marker past `LONG_RUNNING_TURN_SECONDS`. The activity half comes from `resolveWorkingIndicatorLabel`: `ACTIVITY_LABELS` is keyed against the `activity` union in `shared/types/chat.ts` so a new runtime value is a compile error rather than a raw `web_searching` on screen, and an `editing_file` activity is named with its target (`Editing laneService.ts`) by walking back to the most recent unfinished write entry in the turn — `activity` events carry the tool name, not the file. Its elapsed is written imperatively (`textContent` on a ref) rather than through state, so the once-per-second tick never commits a render on the message list. The line swaps a bare `<span>` for an expander `<button>` the instant the turn's first tool entry arrives, which remounts the timer node, so the ref is a **callback** ref: it repaints the counter in the same commit it attaches, and the ticker re-reads the ref every tick. An element captured once when the ticker started would be detached by that swap and the display would sit frozen at `0s` while the long-running marker still appeared. `ChatInfoHostContext` also lives here — a boolean context reporting whether the *owning host* listens for `ade:chat:open-info`. `AgentChatPane` provides `true` (it owns the chat actions pane); `PersonalChatsPage` mounts the same transcript without it, so the `BackgroundJobLine` `open` button is absent there rather than dispatching into nothing. It must stay a context rather than a module-level registry: `App` renders every `ProjectSurface` and only toggles `active`, so each `AgentChatPane` stays mounted while Personal Chats is open, and a global "is any host alive" flag would read true on exactly the surface that has no pane. |
 | `AgentChatComposer.tsx`, `ComposerPromptStash.tsx`, `ComposerSmartLinkMenu.tsx`, `smartLinkChipMark.ts` | Text input, attachments, model selector, compact title-only permission controls (per-provider `PermissionModePickerOption` tables fed into the shared `components/shared/PermissionModePicker`, which the composer owns the option data for but not the control), slash commands, desktop prompt stashes, smart-link chips (`smartLinkChipMark.ts` returns the inline `currentColor` SVG brand mark each chip renders), **chat-context chips** (select assistant output → Add to chat; the chip label is `Chat context`, serializes an `<ade-chat-context>` block so the agent sees the highlighted passage, and click/backspace copy or remove it like a smart-link chip), pending-input answering (including Codex MCP form/URL elicitations), voice-dictation target registration, and parallel model-slot controls. A running chat's toolbar also shows a read-only amber tower plus the owning machine name beside the model and thinking controls; it identifies where the chat executes and directs moves to Chat actions → Handoff → Continue on another machine. A draft omits that label because its launch shelf owns the machine choice. `ComposerPromptStash` keeps its command surface mounted when the Appearance preference hides the bookmark, so Cmd/Ctrl+S remains available, but the visible bookmark stays out of the toolbar while both the composer and stash list are empty. Its menu is rendered in a viewport-clamped body portal with a bounded, scrolling list so composer overflow and short windows cannot crop it. A save first copies up to ten attached images into the owning project runtime, commits the text plus image references, then clears only the unchanged composer snapshot; restore reapplies both text and images before consuming the stash. The list renders an image thumbnail when the active runtime owns the bytes. On another synced runtime, the row retains its text and image count, labels the images as living on another machine, and refuses restore until the composer is connected to the origin runtime. Machine-bound context and non-image files are not stashed. Completed URLs are non-editable inline chips whose `data-composer-chip-text` preserves the literal URL during serialization; clicking or keyboard-activating a chip opens the Copy link / Remove link menu, and character deletion removes the whole URL token. Every chip also carries a kind-naming `data-composer-chip` attribute, and a scoped `selectionchange` effect marks intersecting chips with `data-composer-chip-selected` so the native selection paints continuously across them (overlay styling lives in `apps/desktop/src/renderer/index.css`). During an active Claude turn, its split Send control selects without dispatching among inline, after-turn, and interrupt delivery; the primary button and Enter execute the selected mode. A separate Claude split Stop control selects **Stop & clear queue** or **Stop only**, persists that choice per chat, and dismisses its custom popover immediately after selection. Staged rows expose send-during-turn, interrupt, cancel, and Edit-back-to-composer actions. It forwards one-shot open requests to the shared ModelPicker so transcript recovery cards can open model selection without synthetic DOM events; the picker acknowledges each request so remounts do not reopen it. Launch-prompt clipboard reminder text is controlled by `launchPromptClipboardNoticeEnabled`, separate from the `launchPromptClipboardEnabled` copy behavior. For orchestration model-selection pending inputs it decodes the agent briefing metadata (`workDescription`, `filesHint`, `dependsOn`) before rendering the selection card. It holds the last `@`/`/` popover dismissal in a ref (it gates the next open, never a render) and has **three** distinct close semantics: `closeCommandMenu()` closes and forgets the dismissal, for a trigger that is resolved (a selection was made, the trigger is gone, the composer locked or reset); `dismissCommandMenu(trigger)` closes and keeps it closed while the user extends this query, used for Escape (an explicit dismissal — typing the rest of the token must not bring the menu back), for Enter/Tab with no matching row, and for the menu's own dead-query report; and `closeCommandMenuKeepingDismissal()` is the third and the one that is easy to write by accident — this trigger cannot open a menu right now (it is already a confirmed token, or still covered by an earlier dismissal), but nothing is resolved and nothing new was dismissed, so clearing the dismissal here would reopen the menu the user just escaped and recording one would suppress the menu for a trigger the user never dismissed. |
 | `apps/desktop/src/main/services/chat/promptStashService.ts` | Runtime-backed prompt-stash persistence. Exact prompt text, up to ten image references, their origin sync-site id, provider/model labels, and creation time are stored in the PK-only, CRR-compatible `prompt_stashes` table; newest-first retention is capped at 20 entries. Text and metadata converge across runtimes. HTTP(S) image references remain portable, while local-image bytes stay on the originating runtime: off-origin readers receive the image count but no absolute paths and cannot consume the stash. Origin-owned image files referenced by live stashes are protected from the normal seven-day temporary-attachment cleanup. |
-| `ProviderFailureRecoveryCard.tsx` | Friendly recovery surface for terminal provider capacity and usage-limit failures. Shows human-readable error identity and guidance, then offers **Retry turn** and **Choose model** only after the failed turn has released the composer. |
+| `ProviderFailureRecoveryCard.tsx` | Friendly recovery surface for terminal provider capacity and usage-limit failures. Shows human-readable error identity and guidance, then offers **Retry turn** and **Choose model** only after the failed turn has released the composer. `classifyProviderFailure` delegates its `rate_limit` branch to the shared `isUsageLimitChatError`, so the card recognises exactly the set of shapes the host arms an auto-resume for. On a usage-limit failure with a known reset time it also reports the armed auto-resume (`Auto-resume scheduled for <local time>`) and a **Cancel auto-resume** button, read from `ChatAutoResumeContext` so only this card re-renders when the schedule appears or is cancelled. The context is **per chat**, so a card renders the schedule only when its own `providerFailureEventId` matches the context's `anchorEventId` — otherwise every usage-limit failure ever written to this transcript, including ones from days ago, would advertise the one armed row. That id is `<envelope timestamp>::<turnId>::<message>`: error events carry no id, `turnId` is optional on this path, and a usage limit produces the same message every time, so the timestamp is what separates two of them. |
 | `chatTurnState.ts` | Pure turn-state helpers shared by live and hydration paths. Terminal transcript evidence beats a stale active session summary, and failed-turn retry resolves the associated non-steer user message even when the optimistic row has no provider turn id. |
 | `ChatActionsDrawerPanel.tsx`, `ChatSourcesPanel.tsx`, `chatSources.ts` | Chat Actions tab shell plus Codex Sources view. The source derivation deduplicates files, web queries/results, MCP apps/tools, and external resource URLs from transcript events; safe web rows open in ADE's browser. |
 | `VoiceDictationButton.tsx`, `microphonePermissionGuidance.ts`, `apps/desktop/src/renderer/services/globalVoiceRecorder.ts`, `apps/desktop/src/renderer/components/voice/*`, `apps/desktop/src/main/services/transcription/microphoneAccess.ts` | Desktop dictation UI, platform permission boundary, and recorder. The module-level recorder owns mic capture across navigation, writes live state to the root app store, transcribes via `window.ade.transcription`, inserts cleaned text into the registered composer, and always copies the cleaned transcript to the clipboard. Main asks Electron for the platform microphone status; Windows denied/restricted states return explicit Privacy & security > Microphone guidance, while unknown/not-determined states are left to Chromium's origin permission flow. The header indicator and composer pill render the same recording state. |
@@ -31,7 +31,11 @@ subagents, computer use). The pane derives all visible state from the
 | `apps/desktop/src/renderer/components/work/SessionLifecycleChips.tsx` | Ambient snooze chip for the chat surface header, mounted by `WorkSurfaceHeader` through its `snoozeSessionId` prop (`AgentChatPane` passes the selected session id). Settled state is rendered by `ChatLifecycleBanner` as a compact pill above the composer. `useSessionLifecycleSnapshot(sessionId)` reads the row from the local per-project session cache the Work tab already mirrors into the app store, then falls back to the root cross-machine lane snapshot for a foreign chat; a bounded render-only deadline timer repaints an open snoozed row when it expires, with no extra IPC or lifecycle write. The snooze menu calls `wakeSessionNow` from `renderer/components/terminals/sessionLifecycleActions.ts`. |
 | `ChatSurfaceShell.tsx` | Floating chat header, body, footer layout. Backdrop-blur glass-morphism styling. |
 | `ChatComposerShell.tsx` | Input container chrome reused by the composer. |
-| `ChatAttachmentTray.tsx` | Inline file/image attachment tray inside the composer. Image attachments render an inline thumbnail, open a full-size lightbox on click, and expose a copy-to-clipboard button that ships the image bytes via `window.ade.app.writeClipboardImage` so the user can paste them into another app. Pasted images can pass a seeded preview URL from the composer while the temp file is being saved; tray-only image refs fall back to `window.ade.app.getImageDataUrl`. Non-image attachments fall back to the file glyph. |
+| `ChatAttachmentTray.tsx`, `ChatAttachmentPreviewModal.tsx` | Inline file/image attachment tray, used both inside the composer and on sent user messages in the transcript. Image attachments render an inline thumbnail and expose a copy-to-clipboard button that ships the image bytes via `window.ade.app.writeClipboardImage`. Every other attachment renders as a chip: file-type icon from the Files tab's `getFileIcon`, middle-truncated filename (so the extension survives), human size when the caller knows it, and a remove ×. Chips are focusable — Delete/Backspace removes, Enter/Space opens, arrows move between attachments. Clicking any attachment opens `ChatAttachmentPreviewModal`, which renders the file with the **Files tab's own viewer platform**: `resolveViewerKind` picks the viewer and `ViewerHost` renders it, so PDFs, CSVs, media, office documents, markdown and code all preview read-only without forking a viewer. The modal is `React.lazy`-loaded because that platform pulls in Monaco and the document renderers, and the composer is on a hot render path. It locates the attachment with `resolveAttachmentWorkspaceTarget` (deepest containing Files workspace, Windows-separator aware) using the session's machine pin, so an attachment staged on a paired host is read from that host; an image outside every workspace falls back to the thumbnail bytes the chip already holds. Size is shown only for attachments this composer staged — a chip replayed from transcript history has only a path, and statting each one would be a round trip per chip. |
+| `chatAttachmentStaging.ts` | How ONE file is staged, given what the destination machine supports. `readAttachmentStagingMode(pin)` asks the chat's machine once per batch (`agentChat.getAttachmentStagingMode`) and never throws — a machine that cannot answer gets `CONSERVATIVE_ATTACHMENT_STAGING_MODE`, the base64 contract every host has supported since attachments existed. `planAttachmentStaging` then decides per file: the machine-level answer is necessary but not sufficient, because three things force the bytes leg even on a capable host — no source path (a clipboard paste, and every file in the hosted web client, where `webUtils` does not exist), a renderer-side conversion (HEIC is decoded to JPEG here, so what gets staged is a buffer this process produced), or the host saying `base64` outright. Whenever the bytes leg is taken the ceiling drops to `LEGACY_MAX_CHAT_ATTACHMENT_BYTES`, because that is what `chat.saveTempAttachment` actually enforces on the other end; returning the larger number would only move the rejection later. `stageAttachmentBytesFromFile` is that leg (chunked base64 encode, HEIC conversion, `saveTempAttachment`), and `AttachmentConversionError` marks the one failure the composer offers no retry for. |
+| `apps/desktop/src/shared/chatAttachmentLimits.ts` | The three ceilings and the two rejection messages, shared by the renderer, the desktop main process, and the CLI sync host. `MAX_CHAT_ATTACHMENT_BYTES` (50 MB) governs attachments that move as *files* — a local disk-to-disk copy or a streamed HTTP upload, where the bytes never sit in a JS string. `LEGACY_MAX_CHAT_ATTACHMENT_BYTES` (10 MB) governs attachments that move as base64 inside a command payload, which is buffered in memory on both ends and chunked into 720 KiB frames under a 25 MB payload cap over sync. `MAX_PROVIDER_INLINE_IMAGE_BYTES` (10 MB) is independent of both — see `attachmentInlineGuard.ts` in the chat [README](README.md#source-file-map). `formatAttachmentSize`, `legacyAttachmentCapMessage`, and `attachmentTooLargeMessage` render every ceiling from its constant, so raising one cannot leave a stale "10 MB" behind in a message. |
+| `apps/desktop/src/shared/chatAttachmentStagingFs.ts` | Node-only disk rule for writing into `<projectRoot>/.ade/attachments` — UUID basename, validated extension, containment re-check, stat-before-copy. Shared by desktop main, the ADE action registry, and the CLI sync host's upload route; full contract in the chat [README](README.md#source-file-map). |
+| `attachmentViewerTarget.ts` | Locates a chat attachment inside a Files workspace so the Files viewers can open it. Attachments live at `<projectRoot>/.ade/attachments/<uuid><ext>`, already inside the primary workspace, so this is a containment question rather than a new capability — and resolving it on the client keeps the whole lookup pin-aware, so an attachment staged on a paired host is read from that host instead of silently matching a same-named path here. Splits on both separators (a Windows attachment path resolves too), compares segment-for-segment through the shared `normalizePathForComparison` so `/a/ADE-backup` cannot match `/a/ADE`, and the longest matching root wins — an attachment inside a lane worktree resolves to the lane's workspace, not the project containing it. |
 | `ChatCommandMenu.tsx` | Popover for slash commands and the mixed `@` menu: files, chats, lanes, and terminals ranked together by match quality (not grouped or biased by kind), each row showing a kind icon. Consumes a `ComposerTrigger` from `shared/composerTriggers.ts` (so the menu opens for a mid-draft trigger, not just a leading one). Files and mentions are two independently debounced (40 ms) `useDebouncedSuggestions` sources sharing one hook; `rankComposerAtMenuItems` then scores file paths (basename as subtitle) against entity titles with the same exact/prefix/substring/subsequence tiers. Each keeps a per-menu-session query cache (`QUERY_CACHE_MAX = 40`) so cached queries render same-frame while a background revalidation still runs, and both caches clear when the menu closes or the provider identity changes. A bare `@` is a browse of recency-ranked entities (file search returns nothing until there is a query). Multi-word `@` queries stay active through spaces and use the same cached/debounced search path. Flat keyboard-nav indices are precomputed in the sections memo (no render-time counters); all three row types share the `MenuRow` chrome. Selecting a mention inserts an opaque `@chat:<id>` / `@lane:<id>` / `@term:<id>` pointer while the composer displays a compact title chip with a kind icon (see `shared/chatMentions.ts`). An `onNoMatches?(trigger)` callback fires once when a **non-empty** `@` query settles with zero rows, so the owner can close the menu instead of leaving it parked over the draft while the user types the rest of a sentence; an empty query is a browse, not a search — it can legitimately show nothing now and match once the user types — so it never reports. `useDebouncedSuggestions` carries the `query` its results belong to alongside the provider identity, and results from a previous provider *or a previous query* are discarded **and count as still-loading**: state updates from this render's effects are not visible to consumers until the next render, so `loading` alone would read "settled" for one frame after every keystroke and fire a false no-match. |
 | `apps/desktop/src/shared/composerTriggers.ts` | Cursor-relative typed-trigger detection shared by the desktop chat composer (rich + textarea), the `WorkViewArea` continue composer, and the ade-code TUI (iOS mirrors the same regexes in Swift). `detectComposerTrigger(text, cursorPos)` finds an in-progress `/command` / `@` query ending at the cursor at any position; `@` queries may contain spaces for multi-word entity names but stop at a newline or another `@`; selecting a matching suggestion narrows the replacement span to its label so trailing prose is preserved; `replaceComposerTriggerSpan` splices exactly that span; `findConfirmedComposerTokens` locates confirmed chip tokens for overlay/prompt styling (`ComposerTokenKind` is `"file" | "command" | "mention"`; mention bodies are self-identifying via the `chat:`/`lane:`/`term:` prefix grammar, so callers pass a purely syntactic `isMention` predicate); `composerTriggerSpansWholeDraft` distinguishes a lone leading command from a mid-sentence one. It also owns popover dismissal: `ComposerTriggerDismissal` is `Pick<ComposerTrigger, "type" | "start" | "query">` and `isComposerTriggerDismissed(trigger, dismissal)` reports whether a trigger is still covered by an earlier one. Suggestion search only *narrows* as the query grows — once nothing matched `@cursor`, `@cursor agent` cannot match either — so any extension of a dismissed query stays dismissed, while backspacing out of it, editing it into a different query, or typing a new `@` elsewhere all produce a genuinely new search and reopen. |
 | `apps/desktop/src/shared/smartLinks.ts` | Cross-client URL catalog and deterministic fallback labels. Recognizes GitHub PR/issue/repo/commit/action-run links, Linear issues, `ade://` deeplinks, and generic HTTP(S) pages; trims sentence punctuation, caps each draft at 12 matches, and keeps the canonical URL separate from optional title/favicon metadata. Desktop, hosted web, and ADE Code import this contract; iOS mirrors it in `WorkSmartLinkDetector`. |
@@ -301,7 +305,31 @@ that could not work without it.
   the preview and provider payload use the converted bytes. Windows and
   Linux do not bundle a HEIF codec; those drops stay out of the attachment
   list and show a clear instruction to convert the photo to JPEG first.
-  Temp images keep the 10 MB cap and provider-specific MIME validation.
+  Before reading anything, the composer asks the machine that owns this
+  chat how it stages attachments — once per batch, because the answer is a
+  property of the machine and re-asking mid-batch would only widen the
+  window in which half the files were staged under a different contract.
+  The answer is a `ChatAttachmentStagingMode`, a mode plus the ceiling that
+  goes with it, so the renderer never hardcodes a cap the chosen transport
+  then rejects halfway. There are three: **`copy`** (the chat's machine is
+  this one, so only the path moves), **`upload`** (a paired host advertising
+  the streamed HTTP route), and **`base64`** (everything else). `copy` is
+  decided in preload rather than by the main process, because it is a
+  property of the caller, not of the target.
+  A drag-dropped or picked file carries a real disk path
+  (`window.ade.project.getDroppedPath`, backed by Electron `webUtils`), so
+  under `copy` or `upload` it is staged by path — the bytes never enter the
+  renderer — and any file type up to 50 MB is accepted. Clipboard pastes,
+  HEIC files the renderer converts first, and every file in the hosted web
+  client have no path, so they take the base64 leg with its 10 MB ceiling
+  whatever the machine said. The image MIME sniff on that leg runs on the
+  sync host only (remote peers); the local IPC/action handlers check size
+  and extension shape.
+  When staging fails for a reason a retry could fix, the
+  composer keeps the file handles and offers **Try again** beside the
+  error; a size rejection does not, because retrying it cannot succeed, and
+  neither does a HEIC the renderer could not convert, which would fail the
+  same way every time.
 - **Issue context.** The composer attach menu (~180px, opaque, Linear and GitHub rows, no subtitle) opens `LinearIssueSelectModal` or `GitHubIssueSelectModal`. GitHub is offered only when `detectRepo()` returns this project's repository; personal chats hide GitHub and still allow Linear. Each attachment is a `linear_issue` or `github_issue` context item built by `makeLinearIssueContextAttachment` / `makeGitHubIssueContextAttachment` from `chatContextAttachments.ts`. Sending the turn persists the issue on the chat session (`attachLinearIssueToSession` / `attachGitHubIssueToSession`); mixed Linear + GitHub attachments are allowed. GitHub PRs are not attachable. Clicking a chip reopens the same pane in details mode (Open + Remove). On send, the composer chip moves onto that user message. TUI `/issue attach ADE-123|owner/repo#42|#42` (slash-only on Windows) attaches without a picker. iOS **Attach issue** in the chat overflow menu reuses the Linear pane in attach mode when `lane.attachLinearIssueToSession` is advertised. PR bodies get Linear `Refs ADE-123` (`closeOnMerge: false`) and GitHub `Closes owner/repo#42` (`closeOnMerge: true`) — see [features/linear-integration/README.md](../linear-integration/README.md).
 - **Typed triggers anywhere.** `detectComposerTrigger(text, cursorPos)`
   (`shared/composerTriggers.ts`) finds an in-progress `/command` or
@@ -851,6 +879,30 @@ allowing a cross-provider fork.
   uploads are normalized to JPEG before that boundary, while Windows/Linux
   report the missing codec instead of relabeling HEIC bytes. Codex uses
   local path references; OpenCode uses runtime content blocks.
+- **The attachment cap and the provider inline cap are different numbers.**
+  `shared/chatAttachmentLimits.ts` single-sources both:
+  `MAX_CHAT_ATTACHMENT_BYTES` (50 MB) is what may be staged on disk, and
+  `MAX_PROVIDER_INLINE_IMAGE_BYTES` (10 MB) is what an adapter base64s into
+  a model request. Most providers receive a path and do not care about
+  size. The three that inline — Claude images, the AI-SDK streaming content
+  used by OpenCode, and the Droid/Pi prompt blocks — check the inline limit
+  and substitute a text hint naming the path when a file is over it, so an
+  oversized attachment degrades the message instead of failing the turn.
+  `WORKER_MAX_IMAGE_FILE_BYTES` (Cursor/Pi/Droid worker IPC) is the same
+  inline limit and deliberately did not move with the attachment cap.
+- **Remote hosts.** A chat pinned to a paired machine asks that machine how
+  it stages attachments before reading anything
+  (`agentChat.getAttachmentStagingMode`). A host advertising
+  `features.attachmentUploadV1` in `hello_ok` accepts a streamed HTTP
+  upload: the desktop mints a single-use ticket over the already
+  authenticated sync socket (`chat.createAttachmentUpload`), then POSTs the
+  file body to `/ade-attachments/upload` on the host's sync port with that
+  ticket as a bearer. The ticket is consumed before the first body byte, so
+  a retry needs a fresh one. Hosts predating the feature, relay-routed
+  sockets (the relay brokers WebSocket frames, not HTTP), and SSH targets
+  all fall back to `chat.saveTempAttachment` with the legacy 10 MB
+  image-only contract. The capability is purely additive; **iOS stays on
+  the legacy path** and is not offered the upload route.
 - Parallel launches reuse this same attachment path after the renderer
   validates the 12-file cap. Every child session receives identical
   attachment refs; provider-specific handling still happens inside
diff --git a/docs/features/storage-and-recovery/README.md b/docs/features/storage-and-recovery/README.md
index e894f88571..8386a95d27 100644
--- a/docs/features/storage-and-recovery/README.md
+++ b/docs/features/storage-and-recovery/README.md
@@ -43,6 +43,12 @@
 | `apps/ade-cli/src/services/diagnostics/diagnosticReport.ts` | The pure report builder, the redactor (`redactDiagnosticText`), and `buildDiagnosticIssueUrl`. No I/O, so both the desktop and the CLI produce byte-identical documents from the same sources. |
 | `apps/ade-cli/src/services/diagnostics/diagnosticSources.ts` | `collectMachineDiagnosticSources` — everything a headless box can read: both of the background service's output streams, the service definition (`readFileHead`), the project logs of the open **or most recently opened** project (`resolveMostRecentProjectRoot`), layout, disk figures, the storage-environment probe (`storageEnvironment`), and the redaction context. Both surfaces read it, so a source added for one appears in both. Command-backed sources (journald, `schtasks /XML`) go through the injectable `DiagnosticCommandRunner`, bounded and non-interactive. |
 | `apps/ade-cli/src/commands/reportIssue.ts` | `ade report-issue [--open] [--send]`, the headless equivalent. `--send` needs no project and no arguments: it posts the same redacted report to ADE (Clerk token when the machine is signed in, anonymous otherwise), saves a copy under `~/.ade/diagnostic-reports/` *before* attempting the upload, and prints the reference id or the plain-words failure alongside that path. Local files only: it never starts or contacts the brain, so it still works where ADE will not come up and on hosts with no error screen to press. |
+| `apps/ade-cli/src/commands/triage.ts` | `ade triage [--agent] [--provider <name>]` — the step after diagnosis. `ade doctor` says which check failed and `ade report-issue` produces something to file; neither fixes anything, and the person staring at either is usually the person least able to act on it. This builds the two files an agent needs — a redacted machine context and a maintained playbook — and gets out of the way. This module only **sequences**: it runs the doctor probe, the diagnostic collection, and the playbook resolution concurrently (none needs the others, and the brain is exactly what may be hanging), then assembles, writes, detects, and launches. `--agent` launches nothing and prints the handoff for a session that is already running; a machine with no agent CLI gets the same files and **exit 0**, because the files are the deliverable and the launch is a convenience. CLI-only by design — the desktop, TUI, and iOS clients all need the brain this command exists to repair. Every collector is allowed to fail: a rejected doctor probe, diagnostic collection, or ADE-layout resolution becomes a section in `context.md` saying so, and even a rejected playbook resolver falls to the embedded copy rather than taking the bundle down. If the report could not be collected, the redaction context is derived locally instead, so a failed collection cannot turn `context.md` into the one unredacted copy of this machine's paths and names. |
+| `apps/ade-cli/src/commands/triageContext.ts` | Assembles the two files and the prompt from already-collected material; nothing here probes the machine. `context.md` is Install → Health checks → Brain → Recent errors → Full diagnostic report, with `orderTriageDoctorRows` putting failures before warnings before passes and a header line naming how many rows failed. `extractRecentErrorLines` pulls up to 40 error-shaped lines (`ERROR_LINE_PATTERN` covers `EACCES`/`ENOSPC`/`EDEADLK` and friends) **out of the already-redacted report**, so it cannot become a second unredacted path for the same bytes. The whole document then goes through `redactDiagnosticText` on the way out — the pass is idempotent, so the embedded report is unchanged, and collection error messages ride it too, which is why they are written into the document rather than printed raw. The bundle dir is `mkdtemp`, not a bare `mkdir` of the timestamp: the temp directory is world-writable on POSIX and a predictable name there is something another user can pre-create as a symlink. A full or read-only temp directory raises `TriageCommandError` naming the path, because that is a plausible state on exactly the machine this command is for. |
+| `apps/ade-cli/src/commands/triageLaunch.ts` | Provider detection and the launch plan. `TRIAGE_PROVIDERS` is the detection order — claude, codex, cursor-agent, opencode, droid — resolved with `resolveExecutableFromKnownLocations` (PATHEXT-aware, because on Windows `npm i -g codex` drops an extension-less sh script beside `codex.cmd` and `codex.ps1` and only the latter two can run); a resolver that throws on an unreadable PATH entry drops that provider rather than the command. `--provider` accepts aliases (`cursor`, `factory`) and raises `TriageUsageError` on anything else. Prompt delivery is per provider: claude, codex, cursor-agent and droid document a trailing `[prompt]`, but OpenCode's positional argument is a *project directory*, so it launches bare and the prompt is printed to paste. The same paste path is taken whenever `resolveCliSpawnInvocation` has to **wrap** the executable — a `.cmd` through `cmd.exe`, a `.ps1` through PowerShell — because both rewrite the command line before argv and the multi-line, path-bearing triage prompt would arrive corrupted. The spawn inherits stdio (the user talks to their agent directly), hides the extra Windows console a `.cmd` shim would pop, and the command exits with the agent's code. |
+| `apps/ade-cli/src/commands/triagePlaybook.ts` | Playbook resolution. The maintained copy on `main` is fetched **first** when the network answers inside 3 s; everything else is the fallback. The fetch is pinned to `raw.githubusercontent.com`, refuses redirects outright (a redirect means a captive portal, proxy, or hijacked DNS rewrote the request, and following it would fetch *instructions for a coding agent* from an origin nobody pinned), caps at 512 KiB checked against `content-length` before the body is read, and treats every failure — offline, DNS, TLS interception, timeout — as "use what is on this machine". The local candidates, in order: `ADE_TRIAGE_PLAYBOOK`, the packaged copy under `process.resourcesPath`, the ADE install this CLI was launched from, then the working directory. The install-anchored rung is an **anchored** walk (stop at the first `ade-cli` ancestor, take that install's playbook, containment-check the result via `realpath` on both ends) rather than "try every ancestor", which would climb out of an npm-global install into `$HOME` and let any `~/docs/triage/PLAYBOOK.md` out-rank the shipped copy. Both entry points are walked because neither covers both builds — `__dirname` is absent under an ESM loader, `argv[1]` is what a `tsx src/cli.ts` run has — and both outrank cwd so a checkout the shell happens to sit in cannot win. `embeddedTriagePlaybook()` is the floor: safety rules plus where to read the real thing, deliberately not a second full copy, since a stale duplicate is worse than a short one. `ADE_TRIAGE_NO_FETCH=1` disables the fetch. |
+| `apps/ade-cli/src/commands/triageErrors.ts` | `TriageUsageError` and `TriageCommandError`, in their own module so every triage module can throw them without importing each other. `cli.ts` maps them onto `CliUsageError` / `CliToolError`, which print the message alone; a bare `Error` would reach the catch-all and print a stack trace over the wording, on the one machine whose owner is least able to read one. |
+| `docs/triage/PLAYBOOK.md` | The playbook `ade triage` hands to the agent: safety rules first (read-only diagnosis before mutation, never delete under `.ade/` or `$ADE_HOME`, never kill by name or pattern, exact PIDs only, ask before destructive steps), then one section per failure class keyed to the doctor rows. Fetched from `main` at run time so it can be improved without an ADE release, falling back to the copy on this machine and then to the reduced built-in one; `playbookSource`/`playbookOrigin` record which won and appear in the file's own header and in `--json`. Packaged builds ship it beside the CLI through a single `extraResources` entry — one guessed layout only, because a second would mask a packaging change that should fail loudly — and both `validate-mac-artifacts.mjs` and `validate-win-artifacts.mjs` assert `<Resources>/docs/triage/PLAYBOOK.md` exists, since electron-builder only *warns* on a missing source and a dropped entry would silently degrade triage to its built-in minimum on every installed machine. |
 | `apps/desktop/src/main/services/diagnostics/autoDiagnosticsStore.ts` | The consent flag **and** the spend ledger for automatic uploads, in one file (`<adeHome>/secrets/diagnostics-autosend.json`) that both senders open — the desktop main process and the brain — because "three a day from this computer" is a property of the install, not of a process, and two private ledgers would quietly mean six. Deliberately dependency-free (`node:fs`, no Electron, no logger) for exactly that reason. Owns `AUTO_DIAGNOSTICS_WINDOW_MS` (24 h), `MAX_AUTO_DIAGNOSTICS_PER_CODE` (1), `MAX_AUTO_DIAGNOSTICS_PER_WINDOW` (3), `normalizeAutoDiagnosticsFailureCode` (coerced to the Worker's `FAILURE_CODE_PATTERN`, re-exported rather than rewritten), the mkdir lock — whose `isLockContention` names the Windows delete-pending `EPERM`/`EACCES`/`EBUSY` window as well as `EEXIST` — and the pending-notice queue the toast acknowledgement retires. Consent defaults **on**; an unreadable or locked ledger fails closed. |
 | `apps/desktop/src/main/services/diagnostics/autoDiagnosticsSend.ts` | `runAutoDiagnosticsSend` — the policy every automatic send obeys, written once. The two senders differ in exactly three things (what they build, how they upload, which analytics surface they report as) and bring those as structural seams; consent, the pre-request reservation, the local copy, silence on failure, the pending flag, the log lines and the analytics dedupe key live here. Also owns the `AutoDiagnosticsOutcome` vocabulary (`completed`, `skipped_disabled`, `skipped_budget`, `skipped_ineligible`, `failed`) and `AUTO_DIAGNOSTICS_ANALYTICS_DEDUPE_MS` (1 h). |
 | `apps/desktop/src/main/services/diagnostics/autoDiagnosticsService.ts` | The desktop sender: what is specific to this process — how a report gets built (no `diagnoseProject`, since a diagnosis is itself a trigger), that it uploads anonymously, the `onSent` fast path for an open window, and the getter/setter the Settings toggle reads and writes. |
@@ -1000,6 +1006,53 @@ the computer unless the user posts the issue or chooses **Send to ADE** — and
 the automatic path adds one more way, which is announced every time it happens
 and switched off in one click.
 
+### Handing the repair to an agent (`ade triage`)
+
+Diagnosis and repair are different jobs. `ade doctor` names the failing check
+and `ade report-issue` produces something to file, but neither fixes anything,
+and the person reading either one is usually the person least able to act on it.
+`ade triage` closes that gap: it runs the same doctor checks and the same
+redacted collection, writes them plus a maintained repair playbook into a fresh
+temp directory, and then hands the machine to whichever coding-agent CLI is
+installed.
+
+```bash
+ade triage                       # launch the first installed agent CLI
+ade triage --provider codex      # pick one
+ade triage --agent --text        # print the handoff for an agent already running
+```
+
+The two files are the product. `context.md` is Install → Health checks → Brain →
+Recent errors → Full diagnostic report, with failing doctor rows sorted first
+and the error-shaped log lines lifted to the top so an agent reads the decisive
+ones before the 30 KB of tails they came from. `PLAYBOOK.md` is
+[docs/triage/PLAYBOOK.md](../../triage/PLAYBOOK.md) — safety rules first, then a
+section per failure class keyed to the doctor rows — fetched from `main` at run
+time so it can be improved without shipping an ADE release.
+
+Four properties define the command:
+
+- **Degrade, never die.** Every collector may fail, because on this machine
+  something is broken by definition: the doctor probe talks to a brain that may
+  be hung, the report reads a disk that may be full, the layout resolver reads an
+  `ADE_HOME` that may be unset. Each rejection becomes a section in `context.md`
+  saying so — often the most useful section in the file. An agent with a partial
+  context can still work; an agent with no context cannot.
+- **Redacted by construction.** The whole assembled document, collection error
+  messages included, goes through `redactDiagnosticText` on the way out, so a
+  section added later cannot leak by forgetting to call it. The error lines are
+  extracted from the *already-redacted* report rather than from raw logs, and
+  when report collection failed the redaction context is derived locally rather
+  than skipped.
+- **The launch is optional.** `--agent` prints the paths and the prompt for a
+  session that is already running (an ADE Work chat, say). A machine with no
+  agent CLI gets exactly the same output and **exits 0**. When an agent *is*
+  launched it owns the terminal: the paths go to stderr first, stdio is
+  inherited, and triage exits with the agent's own code.
+- **CLI-only, brain-free.** There is no desktop, TUI, or iOS surface for this,
+  and there will not be one — those clients all need the brain this command
+  exists to repair.
+
 ## Gotchas
 
 - The interrupted-rebuild recovery pass **must run before `migrate()`**. An
diff --git a/docs/features/sync-and-multi-device/README.md b/docs/features/sync-and-multi-device/README.md
index 0cd07f032d..c529a18834 100644
--- a/docs/features/sync-and-multi-device/README.md
+++ b/docs/features/sync-and-multi-device/README.md
@@ -1264,7 +1264,31 @@ Cross-machine Work chat handoff:
   `remoteConnectionService.ts`, and `apps/desktop/src/main/services/ipc/runtimeBridge.ts`
   — destination machine capability checks, storage preflight dispatch, route
   pinning, paired/SSH runtime JSON-RPC routing, request-local timeout policy,
-  and non-replayable action reconciliation when confirmation is lost.
+  and non-replayable action reconciliation when confirmation is lost. The
+  pool also retains each paired target's live `SyncRuntimeTransport` (not
+  just the port-forward client derived from it), because
+  `connection.hello.features` is the host's capability advertisement and
+  `connection.endpoint` is the only place its address and port exist on this
+  side — both are needed by `getAttachmentUploadRoute`.
+- `apps/desktop/src/main/services/remoteRuntime/attachmentUploadRoute.ts`
+  and `attachmentUploadClient.ts` — the desktop client half of streamed
+  attachment upload. `resolveRemoteAttachmentUploadRoute` composes the route
+  from three independent facts, each of whose absence is an ordinary
+  fall-back to base64 rather than an error: the host advertised
+  `features.attachmentUploadV1`; `hello_ok.connectionTransport` is
+  `direct`, because a relay-routed connection terminates at the relay, which
+  brokers WebSocket frames and nothing else; and the endpoint is a
+  `ws:`/`wss:` URL that maps to `http:`/`https:` (the sync HTTP server and
+  the WebSocket share one port, so the origin is the endpoint's with the
+  scheme swapped and the path replaced). SSH targets are not paired
+  transports at all and return null. `uploadRemoteAttachment` then pipes the
+  file from disk — never buffered, which is the entire point of the leg —
+  with the ticket as its only credential, bounds the response read so a
+  misbehaving host cannot stream into this process's memory, and stops at a
+  5-minute budget. The ticket names the route path and the capability names
+  the origin; they are composed rather than either being trusted alone, so a
+  host that moves the route in a later version is followed with no client
+  change.
 - `apps/desktop/src/preload/preload.ts` — source project-runtime routing plus
   the renderer bridge for machine-level project setup and destination actions,
   including the bound `agentChat.regenerateSessionMetadata` call.
@@ -1615,6 +1639,32 @@ Canonical files (`apps/ade-cli/src/services/sync/`):
   grace after a project host detaches so reconnecting phones still park for
   adoption by the next project host. A self-owned server path remains for
   tests/standalone hosts.
+  The listener's `http.Server` also serves the streamed attachment-upload
+  route: every plain HTTP request is offered to
+  `getAttachmentUploadRegistry().handleRequest` first and falls through to
+  the loopback 426 probe otherwise. There is **one registry per listener
+  instance**, shared by every candidate bind and by every project host that
+  adopts the listener, because a ticket is only redeemable by the request
+  handler holding its map — a host-local registry would mint tickets no
+  route recognises, and a ticket minted before a port migration is still
+  honoured after it.
+- `attachmentUploadService.ts` — that registry. The sync stack has no HTTP
+  authentication of its own (before this route the listener answered exactly
+  one request shape, an unconditional 426), so authorization is **delegated
+  to the already-authenticated WebSocket session**: a peer that finished
+  `hello` mints a short-lived ticket over the command channel and presents
+  it as an HTTP bearer on `POST /ade-attachments/upload`. A ticket names one
+  project root and one validated extension, expires in two minutes, and is
+  consumed *before the first body byte is read*, so a replay cannot resume a
+  partial upload. `issue` and `handleRequest` both prune expired tickets
+  rather than running a timer, which would have to be unref'd to keep a
+  short-lived CLI process from hanging on exit. The body streams to a
+  `.part` file and is renamed only after the full body lands, so a torn
+  upload never leaves a half file at the final path for a chat to pick up;
+  the running byte counter is the real ceiling, because a chunked upload
+  declares no `Content-Length`. The destination name comes from the shared
+  `stagedAttachmentDestPath`, so this route and the local copy path cannot
+  disagree about where a file just landed.
 - `syncListenerPortInspect.ts` — platform port-holder diagnosis used by
   zombie reap and `ade doctor` (`inspectSyncListenerPort`). Extracted from
   `sharedSyncListener` so the probe path can stay small and the listener
@@ -1754,6 +1804,17 @@ Canonical files (`apps/ade-cli/src/services/sync/`):
   `work.runQuickCommand`,
   `work.startCliSession`, `work.listExternalSessions`,
   `work.importExternalSession`, `chat.recoverCodexTurn`, `chat.regenerateSessionMetadata`, `modelPicker.*`, …).
+  `chat.createAttachmentUpload` mints one ticket for the streamed HTTP
+  upload route from the host's single `AttachmentUploadRegistry`. It is how
+  a mobile or browser sync client stages a file-shaped attachment; a paired
+  *desktop* arrives instead through the runtime RPC channel, on the action
+  registry's `chat.createAttachmentUpload`, which reaches the same registry
+  through `syncHostService.issueAttachmentUploadTicket`. There is
+  deliberately no remote "copy this path" command on this channel:
+  `chat.copyTempAttachment` takes an unconstrained absolute source path, and
+  the mobile command allowlist is the one place ADE draws that line, so the
+  exclusion narrows what a phone can do rather than what a paired desktop
+  can.
   The cross-machine handoff family (`chat.prepareCrossMachineHandoff`,
   `chat.validateCrossMachineSource`, `chat.preflightCrossMachineDestination`,
   `chat.fastForwardCrossMachineHandoffLane`,
@@ -3006,6 +3067,49 @@ keeps its WebSocket `maximumMessageSize` at 32 MiB. This protects large chat /
 terminal snapshots, `file_response`, and `command_result` payloads without
 letting abandoned chunk sets retain memory indefinitely.
 
+#### Chat attachments ride HTTP, not the envelope stream
+
+A chat attachment large enough to matter should not travel as base64 inside a
+command payload: it inflates by a third, is buffered in memory on both ends, and
+lands under the same 25 MiB decoded-envelope cap and 720 KiB framing as every
+other message. So a host that can accept a file *as a file* says so, and a
+client that can send one that way does.
+
+The advertisement is `hello_ok.features.attachmentUploadV1`, an additive
+capability carrying `{ enabled: true, path, maxBytes }`. The host emits it only
+when its remote command service actually registered
+`chat.createAttachmentUpload` — the route is useless without the mint — so an
+injected or custom command service that omits the command also omits the
+advertisement rather than promising an endpoint nothing serves.
+
+Using it is two legs, in this order and only this order:
+
+1. **Mint over the authenticated socket.** `chat.createAttachmentUpload` (sync
+   command channel, for phones and browsers) or the action registry's
+   `chat.createAttachmentUpload` (runtime RPC channel, for a paired desktop)
+   returns `{ ticket, path, maxBytes, expiresAtMs }`. Both reach the host's one
+   ticket registry.
+2. **POST the body.** `POST <origin><path>` with
+   `Authorization: Bearer <ticket>` and the raw bytes as
+   `application/octet-stream`. The origin is the sync endpoint with `ws:`/`wss:`
+   swapped for `http:`/`https:` — the sync HTTP server and the WebSocket share
+   one port. The response is `{ path }`, the staged absolute path on the host.
+
+The HTTP leg carries no standing authority: it never sees the pairing secret,
+the ticket is consumed before a single body byte is read, and an unspent ticket
+expires on its own after two minutes. The ticket names the route path and the
+capability names the origin; a client composes them rather than trusting either
+alone.
+
+Three cases fall back to `chat.saveTempAttachment` with the legacy
+image-only 10 MB contract, and all three are ordinary outcomes rather than
+errors: a host predating the capability, a **relay-routed** connection (the
+relay brokers WebSocket frames and cannot forward an HTTP POST to the host's own
+listener — `hello_ok.connectionTransport` is the host's own statement of which
+it is), and an SSH target, which is not a paired sync transport at all. **iOS
+stays on the legacy path** and is not offered the route; `workChatInputAttachmentMaxBytes`
+in `WorkChatAttachmentTray.swift` mirrors the legacy constant for that reason.
+
 ### Transport readiness and path truth
 
 Relay controllers negotiate bridge readiness before sending an ADE envelope.
diff --git a/docs/logging.md b/docs/logging.md
index aeb0a70836..011e838d18 100644
--- a/docs/logging.md
+++ b/docs/logging.md
@@ -228,6 +228,43 @@ per session** — a bulk settle on the peer arrives as a single apply covering N
 sessions, and reporting each would turn one remote action into an N-event
 burst.
 
+Chat auto-resume after a provider usage limit records one coarse workflow
+outcome per transition, on the same `ade_feature_used` event with
+`feature: "work"` and `action: "auto_resume"`, at the coordinator that owns the
+loop (`chatAutoResumeCoordinator`, through an injected emitter — it never
+reaches the analytics service or a session id itself). `outcome` is a closed set
+of exactly three values: `armed` (a resume was scheduled), `resumed` (an
+auto-resume-originated turn started), and `paused` (the consecutive-arm cap
+stopped re-arming). `provider` rides along, the same coarse slug through the
+same sanitizer as the settle-teardown event, because a limit whose published
+reset instant is the wrong one is a provider-specific failure and is the whole
+reason the cap exists. The product question is only whether auto-resume rescues
+a chat a limit stopped, so nothing finer crosses the boundary: no session id, no
+reset timestamp, no provider error text, no prompt or notice copy, and no
+schedule id.
+
+A cancelled resume is deliberately **not** recorded. Cancellation fires on
+ordinary user activity — any message or retry in the chat clears the pending
+row — so counting it would report typing rather than the workflow, and the
+number that matters is already derivable as `armed` minus `resumed`. No new
+deduplication key was added because the volume is bounded by construction
+instead: arms are capped at two per streak (and collapse to one event per
+distinct reset instant, so the duplicate error events a single failure commits
+do not double-count), `paused` is emitted once per capped streak rather than
+once per failure, and `resumed` is emitted once per fired resume on the
+not-pending-to-pending edge. Worst case is therefore five events per chat per
+streak — two `armed`, two `resumed`, one `paused` — and a streak requires a
+usage limit plus a reset window to elapse, so realistic volume is single digits
+per installation per day, far inside the existing `ade_feature_used`
+140-per-day / 30-per-minute limits and the shared 200-event ceiling. No ceiling
+was raised. The dashboard spec is deliberately untouched: there is no product
+question attached to these events yet, so they stay out of
+`scripts/posthog/dashboard-spec.mjs` until there is one. The loop's local
+operational lines (`agent_chat.auto_resume_scheduled`,
+`agent_chat.auto_resume_cancelled`, `agent_chat.auto_resume_schedule_failed`),
+which do carry session ids, schedule ids, and fire times, are not PostHog
+events.
+
 Applying an update is one transaction — app swap, background service reinstalled,
 service restarted, service answering — and the brain half failing (the app
 updated but the background service never came back) is its own product-level
diff --git a/docs/playbooks/ship-lane.md b/docs/playbooks/ship-lane.md
index 49395db6b5..60cceadf11 100644
--- a/docs/playbooks/ship-lane.md
+++ b/docs/playbooks/ship-lane.md
@@ -477,6 +477,16 @@ revalidate again.
 
 **PR creation: prefer the ADE CLI.** Opening the PR via `ade` registers it in ADE's PR tracking (lane ↔ PR link, check/comment inventory, review-thread state). `gh pr create` is the fallback, not the default. Falling back too eagerly defeats the purpose — do it only after you've genuinely confirmed the ADE path is broken.
 
+**PR body house style (both creation paths — never rely on `--fill` alone).** Write the body in this order, per the AGENTS.md "Pull requests" section:
+
+1. **Problem** — one or two sentences.
+2. **Cause** — when known; omit the heading otherwise.
+3. **Change and boundary** — what moved, and what deliberately did not.
+4. **Verification** — the exact focused tests/typechecks run and their counts (mirror the quality/test summaries).
+5. Final line — the model and harness that did the work (e.g. `Authored with <model> via <harness>.`).
+
+UI changes attach before/after images; motion attaches a short video. Upload evidence to GitHub — never commit it to the repo.
+
 ### Discovery protocol (for the agent — not a script)
 
 The `ade` surface evolves. Don't assume flag names or output shapes from this playbook; discover them live.
diff --git a/docs/triage/PLAYBOOK.md b/docs/triage/PLAYBOOK.md
new file mode 100644
index 0000000000..fd1b118728
--- /dev/null
+++ b/docs/triage/PLAYBOOK.md
@@ -0,0 +1,327 @@
+# ADE triage playbook
+
+You are fixing a broken ADE install on someone's own machine. `ade triage` handed you a
+redacted `context.md` and this file. Read both before you run anything.
+
+ADE is a local-first dev environment. The parts that break are: the **brain** (a background
+process holding the local RPC endpoint, the project catalog, and sync), the **login service**
+that keeps the brain running (launchd / systemd / a Windows scheduled task), the **credential
+store**, the **project database** under `<project>/.ade/`, and the **pinned agent CLIs** under
+the machine tools cache.
+
+---
+
+## 1. Safety rules — these bind you
+
+1. **Diagnose read-only first.** Every command in section 3 marked *(read-only)* is safe. Run
+   those, form a diagnosis, and state it before you change anything.
+2. **Propose before you mutate.** Say what you are about to run, what it changes, and how to
+   undo it. Wait for the user to agree. Restarting the brain interrupts whatever agent sessions
+   are running on this machine — including, possibly, the one you are talking through.
+3. **Never delete user data.** `~/.ade/` (or `$ADE_HOME`) and every `<project>/.ade/` directory
+   hold the user's databases, secrets, artifacts, and transcripts. Do not `rm -rf` them, do not
+   "clean them up", do not delete `ade.db`, `credentials.json.enc`, `artifacts/`, or
+   `transcripts/`. Moving a file aside with a dated suffix, after the user agrees, is the most
+   destructive thing you may propose.
+4. **Never kill by name or pattern.** No `pkill -f ade`, no `pgrep … | xargs kill`, no
+   `Stop-Process -Name`. Those patterns match this agent's own process, other ADE channels
+   (stable / beta / alpha each run their own brain), and unrelated dev runtimes. If a process
+   truly must stop, get its exact PID from `ade brain status --text` or `ade runtime
+   service-status --text`, verify the PID's own command line and working directory, then stop
+   that one PID — or better, use `ade brain stop`, which stops the right thing by construction.
+5. **Prefer the ADE command over the OS command.** `ade brain restart` over `launchctl`,
+   `ade runtime install-service` over hand-editing a plist, `ade brain repair-credentials` over
+   touching the keychain. The ADE commands know about channels, roles, and the handover
+   protocol; the raw ones do not.
+6. **Do not reinstall as a first move.** Reinstalling loses the evidence and usually not the
+   bug. Find the failing row first.
+7. **Never print or copy secrets.** `~/.ade/secrets/` is off limits as content: report whether
+   a file exists and whether it can be read, never what is in it. The context file you were
+   given is redacted; keep anything you add to it redacted too.
+8. **Do not touch the user's git work.** Lanes are real git worktrees with real uncommitted
+   changes. Triage never runs `git checkout`, `git reset`, `git clean`, or worktree removal.
+9. **One change at a time**, then re-run `ade doctor --text` and report the row that moved.
+
+---
+
+## 2. Start here
+
+```bash
+ade doctor --text          # (read-only) one ok/warn/fail row per check; exits non-zero on any fail
+```
+
+`ade doctor` is the map. Work the failing rows, top to bottom, and stop when they are green.
+Row → section:
+
+| Doctor row | Section |
+| --- | --- |
+| Brain (`fail`) | 3.1 brain not answering |
+| Brain (`warn`, `starting`) | 3.2 brain still coming up |
+| Wedge history | 3.3 wedged brain |
+| Sync port | 3.4 port conflicts |
+| Publish health / Relay / Account | 3.5 sync, pairing, and account |
+| Credentials | 3.6 credential store lockout |
+| Storage | 3.7 disk full and dataless files |
+| App | 3.8 version drift and updates |
+
+Not in a doctor row, but common: 3.9 database locked or corrupt, 3.10 agent CLI binary missing,
+3.11 the CLI itself is not on PATH.
+
+If `ade doctor` itself will not run, go to 3.11.
+
+---
+
+## 3. Failure classes
+
+### 3.1 Brain not answering (socket unbound or stale)
+
+The brain listens on a per-channel endpoint: `~/.ade/sock/ade.sock` on macOS and Linux
+(`$ADE_HOME/sock/ade.sock` when `ADE_HOME` is set), and a named pipe
+`\\.\pipe\ade-runtime-<channel>-<hash>` on Windows. Clients that cannot reach it report
+"couldn't open project" or "ADE couldn't be set up".
+
+Read-only:
+
+```bash
+ade brain status --text            # endpoint state, service state, sync state, last failure
+ade runtime status --text          # the endpoint alone (also reports `starting`)
+ade runtime service-status --text  # is the login service registered and loaded?
+ade doctor --text
+```
+
+Then read the brain's own log tail — `ade report-issue --text` already contains it, and so does
+the context file you were given (look for `Brain` and `Background service`). The files, if you
+want them directly, are under `$ADE_HOME/runtime/`: `brain.jsonl`, and `launchd.err.log` /
+`launchd.out.log` on macOS, the supervisor log on Windows, `journalctl --user -u <unit>` on
+Linux.
+
+Diagnosis:
+
+- Service not registered → 3.12.
+- Service registered, socket unbound, brain young → 3.2, wait.
+- Service registered, brain alive, socket unbound for minutes, heartbeat stale → 3.3.
+- Endpoint answers but reports a build-hash mismatch → the CLI and the running brain are
+  different builds. Propose `ade brain restart` (or `ade brain update --text` if the desktop app
+  was updated underneath it).
+
+Mutating, in escalation order — propose each one first:
+
+```bash
+ade brain restart          # re-exec the service (interrupts running sessions)
+ade brain stop             # unload the login service
+ade brain start            # register + load it again, pinned to the cto role
+```
+
+Do not delete the socket file to "unstick" it. A stale socket with no owner is cleaned up by the
+brain's own startup path; deleting one that *is* owned makes every running client unreachable
+with no way back except a restart.
+
+### 3.2 Brain still coming up
+
+`starting: true` in `ade brain status` / `ade runtime status`, or a `warn` Brain row that says
+starting, means the service is registered and the brain process is alive and younger than the
+young-brain window (about 2 minutes). First launch, a cold disk, or a large project database all
+land here.
+
+This is "wait", not "repair". Restarting only resets its clock. Re-run `ade brain status --text`
+after a minute. Escalate to 3.1 only if it is still starting well past the window.
+
+### 3.3 Wedged brain (event loop blocked / stale heartbeat)
+
+The Wedge history row reports the last recovered wedge. Two things write it: the in-process loop
+watchdog (names the blocking command and how long it blocked) and the external watchdog.
+
+Read-only:
+
+```bash
+ade runtime watchdog-check --text   # reads the heartbeat; stops a brain that has stopped beating
+```
+
+That command is the sanctioned way to deal with a wedged brain: it never opens the runtime
+socket and never starts anything, and the service supervisor restarts what it stops. Use it
+instead of finding a PID and killing it. A wedge inside the last 24h with a healthy brain now is
+history, not a live failure — report it and move on.
+
+### 3.4 Port conflicts (sync host bound off its default port)
+
+The Sync port row is `warn` when the brain bound something other than the default sync port, and
+names what it found holding the base port. Usually it is a second ADE channel (stable and beta
+both running), a leftover brain, or an unrelated dev server.
+
+Read-only:
+
+```bash
+ade sync status --text     # listener port, relay state, publish state
+ade brain status --text    # port + connectedPeers
+```
+
+To see who holds a port, use the OS tool in read-only form — `lsof -nP -iTCP:<port> -sTCP:LISTEN`
+on macOS/Linux, `netstat -ano | findstr :<port>` on Windows — and report the owner. Do not kill
+it. If it is another ADE channel, that is expected and the warn is cosmetic; if it is a stray
+process the user recognises, let them stop it themselves.
+
+### 3.5 Sync, pairing, relay, and account
+
+Read-only:
+
+```bash
+ade auth status --text      # account identity + credential source
+ade sync status --text      # listener, relay, publish health, failing-since
+ade machines list --text    # what the account directory believes about this machine
+ade sync devices            # paired devices
+```
+
+Common shapes:
+
+- **Signed out** → `ade login` (browser loopback), or `ade login --headless` over SSH / on a
+  display-less host. Ask first: sign-in is the user's action, not yours.
+- **Relay slot claimed by another ADE process on this machine** → the row names it. The fix is
+  to quit the rival ADE process; propose it, do not kill it.
+- **Publish failing** → the brain must stay running to publish. Confirm 3.1 is green first, then
+  `ade sync refresh`.
+- **Phone will not pair** → `ade brain pin generate` (or `ade brain pin set 123456`), and
+  `ade sync web --open` for the web client link. A PIN that reads as correct but is refused is
+  usually a machine that is not published: check `ade machines list --text`.
+- **This machine was removed from the account** → `ade machines reconnect`.
+
+### 3.6 Credential store lockout
+
+The shared store is `$ADE_HOME/secrets/credentials.json.enc`. The Credentials row is read
+straight off disk — it works on a machine where the brain will not start, which is the whole
+point of it.
+
+- **Sealed with a key this process cannot obtain** (a GUI-written, OS-bound store that the
+  background brain cannot open): the remedy is to open the ADE desktop app on this computer
+  once. Say that; do not go digging in the keychain.
+- **Anything else unreadable**: a fresh sign-in.
+- **A quarantined store waiting to be restored** (`warn`): that is what
+  `ade brain repair-credentials` is for.
+
+```bash
+ade brain repair-credentials   # local only; never contacts the network
+```
+
+Never delete `credentials.json.enc`. Never read its contents. Never re-run a "repair" in a loop.
+
+### 3.7 Disk full, and files that are not on the disk
+
+The Storage row covers two different failures:
+
+- **No room left.** The full report (`ade report-issue --text`, and the context file) prints free
+  space for the ADE home and the project volume. Under a few GB, everything downstream —
+  database writes, tool fetches, brain updates — fails in confusing ways. Report the number and
+  let the user free space. Do not delete anything to make room; ADE caches under `~/.ade/tools`
+  belong to the user, and `ade tools gc --dry-run --text` is the only sanctioned way to look at
+  reclaiming them (`--dry-run` first, always).
+- **Bytes not present.** A project on iCloud Drive / OneDrive whose files have been evicted, read
+  by a background service that is not allowed to hydrate them, fails with `EDEADLK` /
+  "Unknown system error -11" while every other row stays green. The remedy the row names is
+  `ade runtime install-service`, which rewrites the launch agent with the permission to
+  materialize dataless files. Propose it — it re-registers the login service.
+
+### 3.8 Version drift and updates
+
+The App row compares the installed desktop version against the latest known. `ade doctor
+--online --text` also checks the network (best effort, short timeout).
+
+```bash
+ade brain update --text          # stage + apply the latest standalone brain, then restart
+ade brain update status --text   # (read-only) what the last headless update did
+```
+
+An update is a mutation and a restart: propose it, and never run it while the user has work in
+flight.
+
+### 3.9 Database locked or corrupt
+
+Each project keeps its state in `<project>/.ade/ade.db`, with `ade.db-wal` and `ade.db-shm`
+siblings while it is open. Symptoms: "database is locked", "database disk image is malformed",
+or a project that will not open while the rest of ADE is healthy.
+
+Read-only:
+
+```bash
+ade projects list --text                 # what this machine has registered
+ade status --text --project-root <path>  # can this specific project be reached?
+```
+
+Rules for this one, because it is the easiest place to destroy someone's work:
+
+- **The WAL and SHM files are part of the database.** Deleting `ade.db-wal` discards committed
+  transactions that have not been checkpointed. Never delete a sibling without the `.db`, never
+  delete any of them without the user's explicit agreement, and never while a brain is running.
+- "Locked" almost always means *another live process holds it* — a second brain, a desktop app,
+  a stray `ade serve`. Resolve that (3.1), do not break the lock.
+- Genuine corruption: propose a copy-aside (`ade.db` → `ade.db.broken-<date>`, all three files
+  together, with the brain stopped) and let the user decide. Say plainly what is lost.
+
+### 3.10 Agent CLI binary missing
+
+ADE pins exact versions of the agent CLIs into a machine-level cache (`ADE_TOOLS_ROOT`, else
+`%LOCALAPPDATA%\ADE\tools` on Windows, else `~/.ade/tools`).
+
+```bash
+ade tools status --text       # (read-only) installed version + entry path per pinned tool
+ade tools ensure --text       # fetch whatever is pinned and missing (network)
+ade tools ensure codex --text # just one
+```
+
+Failures come back with a typed `errorKind` — `network`, `integrity`, `disk-space`,
+`lock-timeout` — read it rather than the message. `disk-space` sends you to 3.7; `lock-timeout`
+usually means a background fetch is already running, so wait and re-run. If the environment sets
+`ADE_DISABLE_TOOLS_FETCH=1`, background fetching is off on purpose; say so instead of unsetting
+it behind the user's back.
+
+### 3.11 `ade` itself will not run
+
+If `ade doctor` cannot even start:
+
+```bash
+ade --version                 # is the CLI on PATH at all?
+```
+
+- **Command not found**: the release install puts the binary at `$ADE_HOME/bin/ade`
+  (`ade.exe` on Windows). On POSIX the installer writes `$ADE_HOME/env`, which is safe to source
+  repeatedly: `. "$HOME/.ade/env"`. On Windows the installer adds the install directory to the
+  user's PATH — a new terminal is required. Check whether the binary exists before concluding
+  anything about the install.
+- **Runs but crashes immediately**: native dependencies live under
+  `$ADE_HOME/runtime/<platform>-<arch>/`. A CLI that starts and then dies on a missing native
+  module usually means a half-finished update; `ade brain update --text` re-stages it. Capture
+  the exact error first.
+- **Wrong ADE**: `ADE_HOME` and `ADE_PACKAGE_CHANNEL` select a channel. If the user has stable
+  and beta installed, confirm which one you are talking to before diagnosing anything.
+
+### 3.12 Login service not registered or not loaded
+
+```bash
+ade runtime service-status --text   # (read-only) registration + load state
+ade brain status --text             # includes the same service block
+```
+
+The service is a launchd LaunchAgent (`com.ade.runtime`, plus `.beta` / `.alpha`) on macOS, a
+user systemd unit on Linux, and a per-user scheduled task on Windows whose name carries a hash —
+which is exactly why you should read `ade runtime service-status --text` instead of guessing the
+task name in `schtasks`.
+
+Register with `ade brain start`. Use that, not `ade serve --install-service`: only
+`ade brain start` pins the runtime's default role to `cto`, which is what `ade connect` and the
+desktop app require. A service registered the other way lands on the `agent` role and makes
+sign-in fail on every clean install.
+
+`ade connect` runs the whole account + service + machine-publish sequence idempotently, and
+`ade connect --status --text` reports all three without changing anything.
+
+---
+
+## 4. Finishing
+
+1. Re-run `ade doctor --text` and quote the rows that changed.
+2. Tell the user, in plain words: what was broken, what you changed, and what you deliberately
+   did not touch.
+3. If a row still fails and nothing here explains it, that is a bug worth filing:
+   `ade report-issue --open` copies a redacted report and opens a prefilled GitHub issue.
+   `ade report-issue --send` hands the same redacted report to ADE and prints a reference id.
+   Both read local files only, so they work on a machine where the brain will not come up.
+4. Delete nothing on your way out. The triage directory (`context.md` and this playbook) is in a
+   temp dir; leave it for the user.
diff --git a/reference/cli.mdx b/reference/cli.mdx
index 0155891991..a98a4e6c4e 100644
--- a/reference/cli.mdx
+++ b/reference/cli.mdx
@@ -150,6 +150,8 @@ ade lanes list --json   # stable JSON for scripts and agents
     ade actions list --text                 # full service-backed action catalog
     ade actions run git.stageFile --arg laneId=<lane-id> --arg path=src/index.ts
     ade doctor                              # local runtime, git, provider readiness
+    ade triage                              # hand a broken install to your own coding agent
+    ade triage --agent --text               # print the context + playbook paths instead of launching one
     ade skill list --text                   # bundled agent skills
     ```
   </Accordion>
diff --git a/reference/troubleshooting.mdx b/reference/troubleshooting.mdx
index 74339c4755..f191a6dc90 100644
--- a/reference/troubleshooting.mdx
+++ b/reference/troubleshooting.mdx
@@ -15,6 +15,8 @@ ade doctor                # local runtime, git, GitHub, Linear, and provider rea
 `ade doctor` reports local readiness only — it never calls provider, GitHub, or Linear networks and never prints secret values. It's safe to run anytime.
 </Tip>
 
+If a check fails and you'd rather not work it by hand, `ade triage` hands the whole thing to your own coding agent: it writes a redacted machine context plus a repair playbook to a temp directory and starts the first agent CLI it finds (`claude`, `codex`, `cursor-agent`, `opencode`, `droid`). Inside an agent session already, run `ade triage --agent` — it prints the two file paths and a prompt instead of launching anything.
+
 <AccordionGroup>
   <Accordion title="The app won't connect / nothing loads" icon="plug">
     The desktop app, `ade code`, and the iOS app are all clients of the **brain** — the always-on ADE process for your channel. If it isn't running, clients have nothing to attach to.

From 0b7e6cec24928cb56f80f7be7ba4ac1ad8921962 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Sat, 29 Aug 2026 21:01:57 -0400
Subject: [PATCH 2/2] test(chat): bound the steer pump by wall clock and
 isolate leaked mock services

The pump's 800-iteration budget was worth ~16ms of real time, losing a race
on loaded CI runners and then recycling the runtime it was waiting on; a
failed test's leaked service also wrote into the next test's send ledger.
Patience is now wall-clock (5s) with the fake-tick cap kept; connections
stamp a per-test generation so late sends stop recording.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../services/chat/agentChatService.test.ts    | 72 ++++++++++++++++---
 1 file changed, 63 insertions(+), 9 deletions(-)

diff --git a/apps/desktop/src/main/services/chat/agentChatService.test.ts b/apps/desktop/src/main/services/chat/agentChatService.test.ts
index 83c27b17e8..5dd3e00154 100644
--- a/apps/desktop/src/main/services/chat/agentChatService.test.ts
+++ b/apps/desktop/src/main/services/chat/agentChatService.test.ts
@@ -54,6 +54,15 @@ vi.mock("@cursor/sdk", () => ({
 // vi.hoisted mock state
 // ---------------------------------------------------------------------------
 const mockState = vi.hoisted(() => ({
+  /**
+   * Bumped by `beforeEach`. A chat service outlives the test that built it when
+   * that test fails mid-turn, and its in-flight Cursor turn then records into
+   * the NEXT test's freshly-emptied `cursorSdkSendCalls` — which shifts every
+   * index the next test asserts on and turns one honest failure into three
+   * unreadable ones. Connections stamp the generation they were acquired in and
+   * stop recording once it has moved on.
+   */
+  generation: 0,
   sessions: new Map<string, any>(),
   sessionLinearLinks: new Map<string, any[]>(),
   uuidCounter: 0,
@@ -755,6 +764,7 @@ vi.mock("./cursorSdkPool", () => ({
     && pooled?.process?.connected !== false
   ),
   acquireCursorSdkConnection: vi.fn(async (args: Record<string, unknown>) => {
+    const acquiredGeneration = mockState.generation;
     mockState.cursorSdkAcquireCalls.push(args);
     if (mockState.cursorAcquireErrorOnCall === mockState.cursorSdkAcquireCalls.length) {
       throw new Error("Cursor SDK worker failed to start.");
@@ -810,7 +820,11 @@ vi.mock("./cursorSdkPool", () => ({
         return {};
       }),
       sendPrompt: vi.fn(async (payload: Record<string, unknown>) => {
-        mockState.cursorSdkSendCalls.push(payload);
+        // A service leaked by a failed earlier test must not write into this
+        // test's ledger; see `mockState.generation`.
+        if (acquiredGeneration === mockState.generation) {
+          mockState.cursorSdkSendCalls.push(payload);
+        }
         mockState.onCursorSendPrompt?.(pooled);
         if (mockState.cursorSendPromptGate) await mockState.cursorSendPromptGate;
         if (mockState.cursorSendPromptError) throw mockState.cursorSendPromptError;
@@ -2107,6 +2121,7 @@ beforeEach(() => {
   // (~/.claude/commands, ~/.codex/prompts) doesn't leak the developer's real
   // home dir into tests, while project-local .claude roots remain distinct.
   vi.spyOn(os, "homedir").mockReturnValue(tmpHomeRoot);
+  mockState.generation += 1;
   mockState.sessions.clear();
   mockState.sessionLinearLinks.clear();
   mockState.uuidCounter = 0;
@@ -2451,6 +2466,32 @@ const tripCursorSdkSilenceWatchAndRecycle = async (): Promise<void> => {
   await flushCursorSdkSilenceRecycle();
 };
 
+/**
+ * Real wall clock and a real event-loop yield, captured before any test can
+ * install fake timers. `vi.useFakeTimers()` replaces the global `Date` and
+ * `setImmediate`, so a faked test that measures elapsed time or waits for the
+ * poll phase has to hold the originals.
+ */
+const pumpRealNow = Date.now.bind(Date);
+const pumpRealSetImmediate = globalThis.setImmediate;
+
+/**
+ * How long `pumpUntil` waits in REAL time. The work it waits on is genuinely
+ * async — fs reads for the injected Cursor system prompt, sqlite persistence —
+ * so the budget has to be wall-clock. An iteration count is not a budget: with
+ * no fake timer pending, one iteration costs microseconds, so a loaded runner
+ * burns the whole thing while the very first read is still queued behind the
+ * libuv pool. Locally the slowest wait in this file converges in 11 iterations.
+ */
+const PUMP_REAL_BUDGET_MS = 5_000;
+/**
+ * Fake-clock advancing stays capped by iteration so 1ms-per-tick pumping can
+ * never drift the virtual clock into the 90s silence watchdog by itself.
+ */
+const PUMP_FAKE_TICK_BUDGET = 800;
+/** Real stall time before `pumpUntil` starts tripping the silence watchdog. */
+const PUMP_WATCHDOG_STALL_MS = 1_000;
+
 /**
  * Real async setup work still needs event-loop turns while the clock is faked,
  * so pump the fake clock instead of assuming a fixed number of ticks.
@@ -2460,14 +2501,27 @@ const tripCursorSdkSilenceWatchAndRecycle = async (): Promise<void> => {
  * the test queued its steer, and the later recovery wait timed out.
  */
 const pumpUntil = async (label: string, ready: () => boolean): Promise<void> => {
-  // A silence-watchdog recycle can arm the next attempt's timer after the
-  // first 90s jump, so keep extra trips in the budget once setup has flushed.
-  for (let tick = 0; tick < 800 && !ready(); tick += 1) {
-    const tripWatchdog = tick >= 300 && tick % 50 === 0;
-    await vi.advanceTimersByTimeAsync(tripWatchdog
-      ? CURSOR_SILENCE_WATCHDOG_TRIP_MS
-      : 1);
-    if (tripWatchdog) await flushCursorSdkSilenceRecycle();
+  const startedAt = pumpRealNow();
+  // A silence-watchdog recycle can arm the next attempt's timer after the first
+  // 90s jump, so extra trips stay available — but keyed off real stall time
+  // rather than a tick index. Tripping on a tick index recycles the runtime
+  // whose recovery this is waiting for whenever the loop spins faster than the
+  // pending I/O completes, which is exactly what a loaded runner does.
+  let nextWatchdogTripAt = startedAt + PUMP_WATCHDOG_STALL_MS;
+  let fakeTicksLeft = PUMP_FAKE_TICK_BUDGET;
+  while (!ready() && pumpRealNow() - startedAt < PUMP_REAL_BUDGET_MS) {
+    if (pumpRealNow() >= nextWatchdogTripAt) {
+      nextWatchdogTripAt = pumpRealNow() + PUMP_WATCHDOG_STALL_MS;
+      await vi.advanceTimersByTimeAsync(CURSOR_SILENCE_WATCHDOG_TRIP_MS);
+      await flushCursorSdkSilenceRecycle();
+    } else if (fakeTicksLeft > 0) {
+      fakeTicksLeft -= 1;
+      await vi.advanceTimersByTimeAsync(1);
+    } else {
+      // Fake budget spent: keep handing the real event loop turns so pending
+      // fs/sqlite callbacks can still land, without moving the virtual clock.
+      await new Promise<void>((resolve) => { pumpRealSetImmediate(resolve); });
+    }
     await Promise.resolve();
   }
   if (!ready()) throw new Error(`pumpUntil timed out waiting for: ${label}`);