# DSH handoff preparation and recovery (https://powercontext.oceanbase.io/en/development/dsh-handoff-delivery/)

This component implements preparation and local delivery records for [RFC #2528](https://powercontext.oceanbase.io/en/llms.mdx/rfcs/2528-dsh-plugin-ui-and-agent-handoff/content.md).
The authenticated DSH Host, target preflight, and launch services are separate. This component does not add a
browser route or enable delivery in the DSH UI on its own.

## Preparing a delivery [#preparing-a-delivery]

Construct `LocalDeliveryService` from `integrations/dsh/plugins/powercontext/src/handoff/delivery.ts` with an
absolute delivery directory, the Host's real `PreflightGate`, and a connection resolver. The shared types are
in `handoff/contracts.ts`. The Host supplies the authenticated owner and call cancellation signal in
`CallContext`. It verifies the selected session, message, inclusive event cutoff, directory, and workspace
observation time through the gate. The connection resolver must use the verified Server, connection
generation and Scope, or fail. Binding fields are identifiers; the resolver keeps credentials in memory.

The first request waits for preparation to settle. A concurrent repeat can return the same delivery in
`preparing`; use `get` to read its state. A request key belongs to one owner and one input. A replay with
different input fails. Equivalent requests on the same verified binding reuse the delivery. To replace a
result, supply a new request key and the old `supersedesDeliveryId` after explicit user selection. The old
result and receipt attempt remain available under their original ID.

| Input | Preparation |
| --- | --- |
| Inspected `workInput` | Validate the existing `CurrentWorkHandoff` fields, evidence and 32 KiB input limit; call `handoff_current_work` once. Save its full Prepared value and boundary receipt. |
| Configured generation and a trusted boundary reader | Capture bounded task evidence using the Source API. Call `prepare_handoff` once, validate the draft and send it unchanged to `finalize_handoff`. Save the complete result and the actual capture receipt. |
| Explicit exact Handoff Revision | Verify the exact `ArtifactReference` in the bound Scope and save that reference. The reference uses the existing integer `revision` field. |
| No usable generation or inspected fields | Report `needs_input`; ask for inspected work fields and prepare a new version. |

The Host's `BoundaryReader` supplies the selected reply and observations at that boundary. Its underlying
read must honor the requested limits; the collector also enforces 512 events including the selected reply,
256 KiB overall and 32 KiB for workspace evidence, subject to the lower Source and configured model input
limits. It preserves known test statuses, exact citations when supplied, revisions and working tree
observations. It considers at most 16 Host omission entries and records a summary omission if any
entries cannot be included. No observed check means the result is unknown. An explicit check that did
not run is different from a failure, interruption, or missing evidence. The reader must not run tests or replace an
unavailable workspace observation with the current directory state. For configured generation, use a
client configured for the intended generation deadline; the service caps the model call at 90 seconds.
There is no generation fallback or automatic milestone commit.

## Package integrity and recovery [#package-integrity-and-recovery]

The Host uses a private directory on a local filesystem below its user data. The store holds an exclusive
kernel lock on the open directory until the service closes or the Host process exits. It uses macOS
file locking or Linux util-linux `/usr/bin/flock`; an unavailable lock prevents the store from opening.
Legacy PID marker files are ignored. Stop any Host running the PID marker implementation before opening
the same directory with this implementation.

Records and packages use `powercontext.dsh-delivery.v1` and are stored separately by delivery ID. The
service writes identity, binding and the `content` ACK source ID before dispatch. It persists the expected
size and file checksum before atomically publishing the complete package. Recovery verifies those bytes and
the original source, binding, receipt attempt and carrier before publishing `prepared`. An interruption
without a valid package becomes `unknown`; recovering from a Source or re-finalizing would not recover the
original package. A cancelled call before dispatch stops preparation. Once a call may have run, interruption
can leave its outcome unknown. Cancellation preserves a complete saved package.

`getForLaunch` checks authorization and package integrity. It returns the exact stored binding, selection,
path, checksum and ACK identity. The Prepared digest is the Core Work digest of the canonical Prepared
value. The package SHA-256 checks the bytes of the whole JSON file. Keep both values; neither can substitute
for the other. Export returns the full validated bytes. If a launch path will be consumed asynchronously,
use `withLaunchBundle` while reading or copying it into a verified location; explicit deletion and pruning
are blocked while that reader holds the path. Call `close` on Host shutdown.

The default capacity is 100 carrier slots or 50 MiB, with space reserved for in-flight preparations. The
service never evicts pending or pinned packages to make room. Owners can pin, export or explicitly delete
a delivery. Deletion leaves an idempotency tombstone for 30 days. Automatic package expiry requires the
future exact ACK verifier to supply confirmation for that receipt attempt. An unpinned confirmed package can
expire after seven days; its metadata is kept for 30 days after confirmation. Cleanup does not touch Server
records or write an acceptance state. Unsupported record versions are rejected and left on disk.

Host integration still needs to wire real authenticated boundary reads and connection resolution, map the
safe delivery errors into Host responses, and coordinate path consumption with launch and deletion. Native
target launch and receipt verification require separate acceptance tests.
