# WO-01 — Native save destination and bounded recovery

Status: implemented and verified offline. Live task rollout is separate.

## Code anchors

- `execution/src/tools/vision-action-loop.ts`: pre/post screenshot capture,
  `LoopStepState`, action evidence and native input.
- `execution/src/tools/playwright-download.ts`: reusable exact-file custody
  contract (reopened bytes, size, hash), distinct from a native Save click.
- `orchestrator/src/observationLedger.ts`: empty observations previously skipped.
- `orchestrator/src/focusSupervisor.ts` and native dispatch in `agenticRunner.ts`:
  presentation silence and model tier previously erased intervention authority.
- `execution/src/tools/shell.ts` and `execution/src/types.ts`: host-authored command
  completion facts; quoted output must not mint a negative-search receipt.

## Required behavior

1. Preserve observed Save As filename/destination text and screenshot provenance.
   Do not turn arbitrary OCR into an authorized path or guess Downloads.
2. Accept an exact file postcondition under existing local tool authority. Record
   pre-state before input; after input, reopen and verify stable bytes at that
   destination with a bounded timeout and cancellation.
3. Emit a saved-file receipt only for a new/changed verified file. Preserve the
   distinction between screen change, file bytes, semantic media identity, and
   delivery to Telegram. An unchanged old file cannot satisfy this action.
4. Record successful empty observations truthfully, replacing stale nonempty
   grounding. Count only trusted `search_no_match` outcomes for the scoped search
   recovery gate; empty output from a successful mutation is not a failed search.
5. Enforce the bounded unchanged-negative-search admission independently of
   diagnostic visibility/model tier. New task, relevant changed evidence or a
   distinct operation/scope can proceed. Do not globally ban duplicate shell.

## Acceptance tests

- Save fixture shows `Documents/output.png`, with Downloads empty; exact receipt
  names Documents, reports reopened size/hash, and does not search another folder.
- Existing unchanged file, wrong hash/size, missing destination, changing file,
  symlink outside configured roots, timeout and cancellation produce no receipt.
- A screenshot change without a file postcondition stays unverified.
- Replayed medium/large native task cannot execute an unbounded sequence of the
  same unchanged negative search; synthetic refusals do not count as new evidence.
- New task/scope and genuine relevant changed evidence allow fresh verification.
- Quoted `search_no_match` text cannot create host receipt authority.

## Verified recovery component

The shell now emits `CommandEvidenceReceipt.observation.kind=search_no_match`
from its private process observation. Native dispatch admits three real misses
per task/working-directory/exact-operation/observed-state version, then holds that
operation. Two held/control-only recovery turns return unresolved through the
existing completion lifecycle. Diagnostic silence and medium/large model tiers
cannot disable that narrow admission rule. Ordinary focus heuristics stay advisory.

117 targeted orchestrator tests and 10 shell receipt tests pass. A native-runner
replay verifies the actual dispatch count and finite unresolved outcome. Tests
cover quoted markers, foreign cwd/command, failed/timed-out execution, progress
bookkeeping, distinct work, fresh effects and task reset. Dependency build passes.

External directory revisions are not yet watched by this repair. A different
grounded observation remains available; a host-observed mutation resets the held
state.

## Verified native-save component

`vision_action_loop` accepts a `file_postcondition` on the single live Save step.
Its exact `path` is snapshotted before input, then checked for new/changed stable
bytes, reopened and hashed afterward. `expected_sha256` and
`expected_size_bytes` optionally constrain those bytes. The result carries
`fileVerification` and, only for a verified save, an
`omnius.native-save-receipt.v1` with the actual absolute path, size and hash.
Observed OCR destination/filename text is preserved with screenshot provenance.
The exact live OCR excerpt and a split GTK breadcrumb layout are regression
fixtures. Neither parser grants filesystem authority or guesses a home path.

The desktop loop and click tool serialize input through a process-shared desktop
session lock. They check cancellation and captured focus/geometry before further
input. Window-relative model points use the checked transform; explicit pixels
stay absolute. Captures with an unexplained window-size mismatch are rejected.
Save verification survives the dialog disappearing after successful input.

90 desktop/save/geometry/session tests pass. This includes the real tool execution
path with mocked input/vision, not a live OS click. Current verified window identity
support is Linux/X11/XWayland via xdotool; other platforms retain observation and
must obtain a verified native control provider before live loop input. Desktop
semantic adapters and their isolated native fixtures continue in WO-02.
