file-handoff-inbox-backstop
App boot-loops after receiving a share — every cold launch is jetsam-killed mid-import (a 24MP EXIF-rotated image decodes to a ~880MB bitmap), and widget-timeline launches keep re-triggering the same crash; or shared items import twice / silently vanish because the host drained a half-written batch. Use when a share/action extension hands files to its host app through an App Group inbox — the drain needs a manifest ready-marker, a per-batch attempt cap persisted BEFORE heavy work, quarantine for poison batches, a launch re-entrancy guard, and an injectable inbox root for tests/CI.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 1
- Forks
- 1
01 前言 Front Matter
- name
- file-handoff-inbox-backstop
- description
- App boot-loops after receiving a share — every cold launch is jetsam-killed mid-import (a 24MP EXIF-rotated image decodes to a ~880MB bitmap), and widget-timeline launches keep re-triggering the same crash; or shared items import twice / silently vanish because the host drained a half-written batch. Use when a share/action extension hands files to its host app through an App Group inbox — the drain needs a manifest ready-marker, a per-batch attempt cap persisted BEFORE heavy work, quarantine for poison batches, a launch re-entrancy guard, and an injectable inbox root for tests/CI.
02 资源文件 1
- 参考文档references/inbox-drain.md3.2 KB
03 SKILL.md 正文
Share-Extension Inbox: Backstop the Drain Against Poison Batches
Symptom
- App crashes on launch, every launch, after a user shares a large item. A private document-scanner app's case: a 24MP EXIF-rotated shared image decoded to a ~880MB bitmap → jetsam during the inbox drain → drain died before clearing the batch → cold-launch boot-loop. Widget timeline launches re-triggered it too.
- Shared items imported twice (drain ran concurrently) or never appeared (host drained a batch the extension was still writing).
Root cause
The naive inbox — extension writes files into the App Group container, host
imports-then-deletes on launch — has no failure story. A crash during import
leaves the batch in place, so the very work that crashed runs again on the next
launch, unconditionally. And launch has multiple triggers (onAppear,
scenePhase .active, widget timeline reloads), so drains overlap.
Fix
Layout — batch dir per share; manifest.json written LAST is the ready marker:
<AppGroup>/ShareInbox/<batchID>/item-0.jpg … manifest.json
<AppGroup>/ShareInboxFailed/ # quarantined poison batches
Read references/inbox-drain.md before implementing — has the full
extension-side manifest writer, the host-side drain loop (attempt cap +
quarantine + re-entrancy guard), and the injectable ShareInbox root
wrapper. Rules that live only in that code and matter before you open it:
- The manifest's
fileslist stores paths relative to the batch dir, never absolute URLs. onAppearANDscenePhase == .activeboth fire on cold launch — the drain loop must guard re-entrancy, not try to dedupe its callers.importBatch's heavy decode work happens off-main, inside the guarded drain loop.- A caught import error leaves the batch in place — the already-burned attempt count is the backstop, not a retry-immediately.
ShareInbox.appGroup(id:)returnsnilsilently when the App Group entitlement is missing on that specific target — check the entitlement per target, not once app-wide.
Image normalization — the actual jetsam trigger. UIGraphicsImageRenderer
defaults to device scale, so a 24MP image renders at 3× pixels:
let format = UIGraphicsImageRendererFormat()
format.scale = 1 // NOT device scale — 24MP @3x ≈ 880 MB bitmap → jetsam
let out = UIGraphicsImageRenderer(size: targetSize, format: format).image { _ in
image.draw(in: CGRect(origin: .zero, size: targetSize)) // also bakes in EXIF rotation
}
Invariants
- Manifest written last; no manifest ⇒ batch does not exist to the drain.
- Attempt counter hits disk before decode work — a crash burns an attempt.
- After
maxDrainAttempts(3): quarantine toShareInboxFailed/, never delete. - One drain at a time; every launch path (view appear, scene activation, widget-triggered launch) funnels through the same guarded entry point.
- Renderer
scale = 1when normalizing shared images. - Inbox root is injected, never read from the entitlement inside the logic.
Evidence
- a private document-scanner app (5 targets incl. share extension +
ShareExtensionInboxhelper):stop launch boot-loop on large rotated shared images,cap drain attempts and quarantine poison batches.
Related skills
widget-appgroup-snapshot-bridge— the read-only sibling over the same App Group; its timeline reloads are one of the launch paths that re-trigger drains.deep-link-resolver-applock-pathtraversal— hardening the other cold-launch entry point (URLs) with the same one-guarded-funnel discipline.mainactor-launch-watchdog-audit— the general launch rule this instantiates: record progress before the loop body, and keep heavy launch work off-main.swiftdata-inmemory-test-harness— same injectable-root discipline applied to the persistence layer.swift6-mainactor-compile-fixes— if movingimportBatchdecode work off-main trips "main actor-isolated X" errors.
04 同仓库更多 Skills
second-wind
Orchestrate long unattended Claude Code runs across multiple repos with the wind CLI. Use when the user wants to run Claude Code overnight, resume sessions after the 5-hour usage limit, run Claude in many repos at once via tmux, or says "set up second wind", "wind up", "overnight run", "resume after limit", "usage limit orchestrator".
structured-output-adaptive-thinking-token-bloat
A Claude API call using output_config.format (json_schema structured outputs) with thinking:{type:"adaptive"} burns most of its output budget on thinking (observed ~21k of ~24k tokens) without improving JSON quality, making the run up to ~5x more expensive than the same call with thinking omitted — use when calling the Messages API with a json_schema output format for extraction, ranking, classification, or summarization tasks, or when a schema-constrained call's usage.output_tokens is far larger than the returned JSON.
review
Apply a code-review lens to a diff, branch, or file — find correctness bugs, security issues, and quality problems, ranked by severity, with a concrete fix for each. Use when the user says "review this", "review my diff", "check this PR", "look this over before I commit", or "is this safe". Skip when the user wants the code written, not reviewed.
refresh
Rebuild the prompt-craft command registry and usage profile, and print a summary of installed commands and your personalized recommendations. Use when you install or update plugins and want the advisor to pick them up immediately, or say "refresh prompt-craft", "rebuild the command registry".
refactor
Apply a refactoring lens — restructure code without changing behavior, guarded by tests that pass before and after. Use when the user says "refactor", "clean this up", "extract this", "simplify this", "reduce duplication", or "make this readable" on existing working code. Skip when the change is meant to alter behavior (that's a feature or a fix).
plan
Decompose a non-trivial task into an explicit, tracked plan with goals and per-step acceptance criteria before writing code. Use when the user says "plan this", "break this down", "what's the plan", or asks for a multi-step feature/refactor that touches more than one file. Pairs with plan mode. Skip for single-edit changes that need no decomposition.