Implement binary hex editor: CLI/TUI workspace, safe byte operations and recovery #94

Scheduling update, 2026-11-01: the user requested implementing #94 now, ahead of #92/#93. Shared snapshot, permission and FileChanged requirements remain dependencies for their integrations.

Implement the approved binary hex editor extension from PR #54. Implementation started from main 6099e1327a79f32ed33fd5f418f1123f5ed0bded. Merged PR #95 adds the live-view increment; merged PR #96 adds the native storage/draft foundation. The complete editor scope and native save/recovery proof remain required.

Proposal · Design · Authoritative task list.

Scope: polished CLI/TUI hex/ASCII workspace and inspector; exact-offset navigation, literal search and bookmarks; staged overwrite/insert/delete and draft undo/redo; byte-diff review and recoverable save/restore; bounded authenticated owner API/SDK/model operations; Git/non-Git snapshot and acknowledged file-change integration. Preserve text editing and existing permission/Mode/native ownership boundaries.

Implementation progress

PR #95 is merged: bounded live bytes, Session/Location-scoped owner routes, CLI/TUI hex/ASCII inspection, exact goto/search/bookmarks, SDK helpers and a real README terminal screenshot. The viewer has real-binary SDK and large sparse-file PTY evidence; it does not complete editing.

PR #96 is merged at 037fdc4b93704416f0f3a9f264dc86a27e4334d8 after all 39 current-head checks passed. It adds bounded durable piece-table drafts/history, original-offset byte review, private owner-scoped recovery/discard primitives, Linux/macOS native replacement and durable-intent proof, Windows private storage/draft proof (not native replacement), private-root launch fencing and shared workspace mutation coordination. Native Linux/macOS/Windows CI passed, including the explicit Linux distinct-filesystem refusal proof. At that foundation stage, production save and terminal editing were not yet activated.

PR #97 is merged at d6a9b1ae after all 24 current-head checks passed. It adds authenticated owner draft preparation, staged patches/history/review/status/receipt lookup and recovery, fresh permissions, Session deletion protection and retained filesystem-worker ownership.

PR #98 merged at 69372bab after all 22 checks passed, adding quota reservation and exclusive-document execution-recovery proof.

PR #99 is merged at 5a345966: Rust binary mutations do not automatically retry after transport loss. PR #100 is merged at 0c304e75: acknowledged saved-version evidence and final commit-authority checks.

PR #101 is merged at 8eb4d3a6: durable acknowledged source handoff into the native FileChanged producer. PR #102 is merged at fd38deaa: conservative retention primitives and saved-view leases; configured cleanup/checkpoint adapters are still pending.

PR #103 is merged at 40ec5f44: reviewed owner save/restore, terminal staged editing/undo/redo, shared saved history and binary references in Session diffs, with real terminal screenshots.

PR #104 merged at 4d873e51 after all 24 checks passed. It adds model inspect/read/search and reviewed expected-digest patches in isolated invocation drafts, with canonical tool catalog/golden coverage.

PR #105 merged at a6165c18 after all 19 current-head checks passed, including Linux/macOS/Windows native proof. It adds scoped model receipt discovery/reconciliation and a reproducible 16 MiB core benchmark with explicit end-to-end limitations. Local verification includes 84 core tests, 20 production-router binary tests and SDK checks. PR #106 adds explicit kept-manual-draft CLI recovery with fresh edit admission. Its rebase onto #105 passed all 16 hex TUI tests, the production recovery regression, SDK typecheck/127 tests and strict OpenSpec validation; CI is pending. It also records the user-approved switch to #93.

Status clarification, 2026-11-03: this issue was manually closed by the owner after #104. Its closed state is preserved; it does not establish that the unchecked retention/checkpoint/rewind and acceptance tasks below are complete. The user has now prioritized #93; this body retains the outstanding binary scope for follow-up.

Remaining delivery includes configured retention/checkpoint/rewind adapters, model-recovery integration acceptance, unfinished UI recovery/accessibility work, named performance/platform acceptance and final specification reconciliation. Task checkboxes below describe completed implementation increments; the complete feature and merge acceptance remain open. The remaining scope is not counted as accepted merely because the issue is closed.

Remaining tasks

• 1.4 Record the approved native support/storage matrix and relevant unchanged-main baseline; align the accepted Daily coding snapshot and Plugins/hooks FileChanged contracts.

• 2.1 Add typed byte-document/revision/offset/identity primitives with regular-file and project-root admission, exact integer transport and preserved permission ceilings.

• 2.2 Implement bounded pages, cancellable literal search and stable revision/continuation behavior without eager whole-file allocation or decoding.

• 2.3 Prove native private immutable base preparation, same-filesystem atomic replacement with displaced preimage, metadata preservation and durable intent/outcome recovery; define unsupported outcomes honestly before write integration.

• 2.4 Test native file/parent replacement, symlink/hardlink refusal, every byte value, NUL/invalid UTF-8, sparse/large files, offsets above 2^53 and resource exhaustion with positive controls.

• 3.1 Add expected-revision overwrite/insert/delete splice batches, exact preimage checks, bounded payloads and atomic draft undo/redo.

• 3.2 Add stable byte-diff review with original offsets, base/proposed fingerprints, length/changed-range totals, metadata and effect disclosure.

• 3.3 Implement edit permission/Mode/checkout lease gates, capacity reservation and journaled save with operation idempotency and queryable acknowledged/conflict/unknown outcomes.

• 3.4 Preserve dirty drafts and unresolved receipts over disconnect/restart; add explicit discard and reviewed Restore Last Save without unguarded overwrite.

• 3.5 Test stale revision/review, same-size/same-mtime edits, all-or-nothing multi-splice changes, concurrent Sessions/external writers, cancel/kill cuts, retry identity and backup integrity.

• 4.1 Implement authenticated fs document/page/search/patch/history/review/save/restore/operation/close routes with exact Session/Location scope and no raw-byte URLs/logging.

• 4.2 Generate OpenAPI/TypeScript types and shared client helpers with lossless offsets, bounded decoding, operation lookup and revision validation; preserve text content routes.

• 4.3 Register the capability-owned binary tool and implement bounded inspect/read/search/patch through the shared service, isolated from unsaved owner drafts.

• 4.4 Enforce read+edit, plan/read-only/deny ceilings, existing output budgets, permission byte-diff review and plugin filesystem intersections; retain normal text-tool behavior.

• 4.5 Test owner auth/Origin, cross-document/Session/Location access, stale generation, read-denied/write-allowed cases, malformed encodings, oversize payloads and secret-safe errors.

• 5.1 Build the virtualized themed hex/ASCII workspace, shared cursor/selection, adaptive rows, inspector and change rail with explicit view/edit/review/save/conflict states.

• 5.2 Add goto, literal search, bookmarks, encoding-labelled text/hex input, partial-nibble cancellation, bounded copy/share, draft undo/redo and unsaved-change navigation.

• 5.3 Add explorer entry/palette/keybindings, /hex and cyber hex without inference, preserve Session selection and global interrupt/permission/native Stop priority; regenerate CLI documentation.

• 5.4 Add wide/narrow/light/dark/NO_COLOR keyboard/mouse/accessibility snapshots and actual terminal captures; verify dirty-state, byte-diff totals and stale response fencing visually.

• 6.1 Integrate durable binary preimages/receipts, byte diffs, conflict-aware restore and retention for Git/non-git Locations even when ordinary snapshots skip the file.

• 6.2 Publish only acknowledged successful file-change observations through the existing producer contract; preserve unknown effects and avoid duplicate notification after save retry.

• 6.3 Benchmark first viewport, bounded memory, navigation/search responsiveness and cancellation on a named reference machine; publish fixture sizes and limitations.

• 6.4 Run relevant native Rust/integration/real-binary/TUI tests, SDK typecheck/tests, generated artifact checks, strict OpenSpec/lint, formatting/Clippy and scoped platform CI. Record skipped/unperformed acceptance.

• 6.5 Perform code/security review using the code-review skill; resolve findings, update README/feature/roadmap/operator guides with actual scope and deliver reviewable PRs. Do not claim format repair or arbitrary external-writer atomicity.

• 6.6 After authorized acceptance/merge, archive and reconcile canonical specs; do not close the existing combined implementation goal based on this specification alone.

Completion evidence

Native storage/save proof must precede write integration. Verify exact offsets beyond 2^53, bounded memory, revision/preimage/identity checks, recoverable acknowledged/conflict/unknown outcomes, platform limits and real terminal UX. Include named-machine performance evidence, visual wide/narrow/theme/accessibility checks, generated artifacts, native/integration/client tests, substantive review and accepted PRs. Do not claim arbitrary external-writer atomicity or file-format repair.

Track the remaining approved implementation scope, not a new scope proposal. The new user request prioritizes binary implementation now; issues #92 and #93 retain their unfinished scope. Normally keep one implementation PR open (maximum two for independently reviewable work); merge ready PRs only under the existing user authorization with current-head CI and review. Preserve meaningful regressions, generated artifacts, documentation, substantive code/security review, and explicit native/design gates. Green probes, universal refusal, or a merged specification do not prove production completion.

Related workstreams

hooks: #92 · daily: #93