docs: add host affordance bridge roadmap

[donbeave]

Summary

Implements the opt-in host affordance bridge foundation behind JACKIN_HOST_ATTACH=1 and keeps the roadmap as the live implementation contract. The PR started as roadmap/preflight work, but now includes the first working slices for host-owned attach, clipboard image staging, explicit host image paste/stage commands, GitHub/CI host-open actions, visible URL open actions, host-link opt-out, host-open URL log redaction, host notices, Linux clipboard setup diagnostics, and chunked file export.

The default attach path still uses the existing in-container Capsule client. Host attach remains opt-in until we finish live validation in a new isolated throwaway jackin' instance.

Implemented

• Shared binary attach protocol in jackin-protocol.
• jackin-capsule attach-proxy stdio relay and host transport selection: direct Unix socket when available, proxy fallback when direct connect fails.
• Opt-in host-owned attach loop for foreground attach paths with shared terminal color probing.
• Construct image installs xclip, xauth, and wl-clipboard for Linux CLI/runtime compatibility, while documenting that these do not bridge the macOS host clipboard.
• Bumped docker/construct/VERSION to 0.9-trixie because the construct image now bakes clipboard helper packages and CI confirmed 0.8-trixie was already published.
• Host clipboard image paste through typed ClipboardImage frames, including chunked large-image transfer with offsets, SHA-256, and a 64 MiB first cap.
• Capsule image validation, /jackin/run/clipboard/ staging, bracketed-paste-aware staged-path insertion, and visible image paste/rejection feedback.
• macOS PNG coercion and Finder file-url fallback; Linux host-side wl-paste/xclip image readers gated by host display env.
• Explicit command-palette actions for Paste image from host clipboard, Stage image without pasting, and Stage image from clipboard path.
• The stage-without-pasting action uses the same host clipboard image reader as paste, stages the accepted image under /jackin/run/clipboard/, reports the staged path, and leaves focused pane input untouched.
• Explicit host clipboard image/path actions now preserve host probe errors in Capsule feedback, including missing Linux WAYLAND_DISPLAY/DISPLAY, missing host-side wl-paste, and missing host-side xclip.
• GitHub context open actions for PR and best-effort CI URL resolution from gh pr checks link fields plus statusCheckRollup.detailsUrl fallback.
• Host-open attach frame for allowlisted http, https, and mailto URLs, Alt/Ctrl modified-click opening of visible HTTP(S) URLs in mouse-disabled panes, OSC 8 mailto targets, and command-palette Open link under cursor.
• JACKIN_OPEN_LINKS=deny|off|no disables jackin' host browser-open actions in Capsule and the host attach client without disabling normal terminal OSC 8 passthrough.
• Host-open URL telemetry redacts query strings and fragments in default logs and host attach errors while preserving the full URL in the typed attach frame.
• Debug launches inject JACKIN_RUN_DIAGNOSTICS_PATH so Capsule Debug info copies the exact host diagnostics JSONL path instead of guessing from the container home.
• Command-palette file export over chunked server-to-host frames, with Capsule path validation, host-side digest verification, collision-safe destination names, and temp cleanup for interrupted or malformed transfers.
• Bounded HostNotice frames so host-open and export results show up in Capsule instead of only host logs.
• Operator-facing [Host Affordances] docs and updated roadmap/preflight pages with Phase 0 evidence and remaining validation gates.

Remaining before default-on

• Live-validate JACKIN_HOST_ATTACH=1 in Ghostty against a new isolated throwaway jackin' instance: text paste, mouse routing, resize, focus, pane switching, bracketed paste, OSC 52 copy, selection copy, clean detach, and image paste into real agent prompts.
• Validate macOS screenshot/browser/Finder image paths through Ctrl+V, Paste image from host clipboard, and Stage image without pasting.
• Validate Stage image from clipboard path rejection/success cases.
• Validate GitHub PR/CI open, visible URL Alt/Ctrl click, Open link under cursor, JACKIN_OPEN_LINKS denial, and file export through the opt-in host attach loop.
• Validate Linux host clipboard readers and missing-tool messages on real Wayland and X11 hosts.
• Decide after validation whether host attach can become default and whether very large transfers need a negotiated side stream.

Verification

• cargo fmt --check

• cargo check -p jackin-runtime

• cargo check -p jackin-capsule -p jackin-runtime -p jackin-protocol

• cargo check -p jackin-capsule -p jackin-runtime -p jackin-core

• cargo clippy -p jackin-protocol -p jackin-runtime -p jackin-capsule --all-targets -- -D warnings

• cargo clippy --workspace --all-targets --all-features --locked -- -D warnings

• cargo xtask construct assert-version-unpublished

• cargo test -p jackin-core open_links_allowed -- --nocapture

• cargo test -p jackin-core redact_url_for_log -- --nocapture

• cargo test -p jackin-runtime host_open_command -- --nocapture

• cargo test -p jackin-runtime host_clipboard -- --nocapture

• cargo test -p jackin-runtime linux_clipboard_backend -- --nocapture

• cargo test -p jackin-runtime explicit_clipboard_image_request_returns_probe_error_to_capsule -- --nocapture

• cargo test -p jackin-runtime host_file_export_abort_removes_temp_and_rejects_end -- --nocapture

• cargo test -p jackin-runtime debug_runtime_envs_include_run_id_and_host_diagnostics_path -- --nocapture

• cargo test -p jackin-protocol attach::tests::server_frames_roundtrip -- --nocapture

• cargo test -p jackin-capsule host_url_open_policy -- --nocapture

• cargo test -p jackin-capsule diagnostics_path -- --nocapture

• cargo test -p jackin-capsule stage_image -- --nocapture

• cargo test -p jackin-capsule stage_only_clipboard_image_response_does_not_paste_path -- --nocapture

• cargo test -p jackin-capsule clipboard -- --nocapture

• cargo test -p jackin-term hyperlink -- --nocapture

• cargo test -p jackin-capsule palette_command_route_keeps_dialog_drill_down_semantics -- --nocapture

• cargo test -p jackin-capsule palette_routes_map_to_visible_frame_plans -- --nocapture

• cargo test -p jackin-capsule frame_plans_keep_diff_tier_reasons_out_of_full_redraws -- --nocapture

• cargo test -p jackin-capsule paste_image_palette_action_sends_typed_protocol_frame -- --nocapture

• cargo test -p jackin-capsule modified_primary_press_maps_to_visible_url_open_intent -- --nocapture

• cargo test -p jackin-capsule modified_click_visible_url_sends_typed_protocol_frame -- --nocapture

• cargo test -p jackin-capsule open_link_under_cursor -- --nocapture

• cargo test -p jackin-capsule open_host_url_dialog_action_sends_typed_protocol_frame -- --nocapture

• cargo test -p jackin-capsule github_context_unavailable_ci_row_is_not_clickable -- --nocapture

• git diff --check

• cd docs && bun run build

• cd docs && bun run check:repo-links

• cd docs && bun run check:roadmap-sidebar

• cd docs && bunx tsc --noEmit

• cd docs && bun test

• cargo test -p jackin-capsule open_link_under_cursor_palette -- --nocapture

• cargo test -p jackin-capsule modified_url_hover -- --nocapture

• cargo test -p jackin-capsule link_hover_notice -- --nocapture

• cargo test -p jackin-capsule open_link_under_cursor_palette -- --nocapture

• cargo test -p jackin-capsule --lib

• cargo test -p jackin-capsule pointer_shape -- --nocapture

• cargo test -p jackin-capsule modified_url_hover -- --nocapture

• cargo test -p jackin-capsule --lib

• cargo test -p jackin-capsule modified_click -- --nocapture

• cargo test -p jackin-capsule chunked_transfer_rejects_oversize_start -- --nocapture

• cargo test -p jackin-capsule clipboard_image_notice_takes_priority -- --nocapture

• cargo test -p jackin-capsule --lib

• cd docs && bun run build

• cd docs && bun run check:repo-links

• cd docs && bunx tsc --noEmit

• cd docs && bun test

• cargo test -p jackin-runtime attach_protocol_preserves_bracketed_paste_and_mouse_bytes -- --nocapture

• cargo test -p jackin-runtime attach_protocol_writes_osc52_output_unchanged -- --nocapture

• cargo test -p jackin-runtime host_attach::tests::attach_protocol -- --nocapture

• cargo test -p jackin-runtime --lib

• cd docs && bun run build

• cd docs && bun run check:repo-links

• cd docs && bunx tsc --noEmit

• cd docs && bun test

• cd docs && bun run check:repo-links

• cd docs && bunx tsc --noEmit

• cd docs && bun test

• cd docs && bun run build

• cargo test -p jackin-capsule open_host_url_dialog_action_honors_operator_opt_out -- --nocapture

• cargo test -p jackin-capsule --lib

• cargo fmt --check

• cd docs && bun run check:repo-links

• cd docs && bunx tsc --noEmit

• cd docs && bun test

• cd docs && bun run build (rerun passed after one prerender 404 race on /reference/roadmap/host-affordance-bridge-preflight)

• cd docs && bun run check:repo-links

• cd docs && bunx tsc --noEmit

• cd docs && bun test

• cd docs && bun run build

• cargo test -p jackin-capsule cleanup_removes_staged_files_but_leaves_non_files -- --nocapture

• cargo test -p jackin-capsule --lib

• cargo fmt --check

• cd docs && bun run check:repo-links

• cd docs && bunx tsc --noEmit

• cd docs && bun test

• cd docs && bun run build

• cargo test -p jackin-core host_open_url_policy_allows_http_https_mailto_only -- --nocapture

• cargo test -p jackin-protocol --lib

• cargo test -p jackin-runtime host_open_command_accepts_mailto_urls -- --nocapture

• cargo test -p jackin-runtime --lib

• cargo test -p jackin-capsule modified_click_accepts_mailto_osc8_target -- --nocapture

• cargo test -p jackin-capsule --lib

• cargo fmt --check

• git diff --check

• cd docs && bun run check:repo-links

• cd docs && bunx tsc --noEmit

• cd docs && bun test

• cd docs && bun run build

• cargo test -p jackin-capsule osc8_uri -- --nocapture

• cargo test -p jackin-capsule modified_click_accepts_visible_mailto_token -- --nocapture

• cd docs && bun run build (rerun passed after one prerender 404 race on /guides/host-affordances)

Follow-up 2026-06-12:

• Added debug-only file export telemetry for transfer id, source category, basename, byte count, SHA-256, destination category, final path, and digest mismatch details without logging file contents.
• Updated clipboard-image bridge roadmap to mark that telemetry slice as implemented.

Additional verification:

• cargo fmt --check
• cargo test -p jackin-capsule file_export -- --nocapture
• cargo test -p jackin-runtime host_file_export -- --nocapture
• cargo test -p jackin-runtime export_source_path_category -- --nocapture
• cargo test -p jackin-capsule export_source_category -- --nocapture
• cd docs && bun run check:repo-links
• cd docs && bunx tsc --noEmit
• cd docs && bun test
• cd docs && bun run build
• git diff --check

Follow-up 2026-06-12b:

• Added explicit unsafe-scheme feedback for modified-click visible URLs and OSC 8 targets. Unsafe file: / javascript: / data: style targets now consume the host-open gesture, show Host link rejected: unsupported URL scheme, and do not forward mouse bytes to the pane or emit host-open frames.
• Updated clipboard-image bridge roadmap to mark unsafe-scheme rejection feedback as implemented for the landed modified-click path.

Additional verification:

• cargo fmt --check
• cargo test -p jackin-capsule modified_click_rejects_unsafe -- --nocapture
• cargo test -p jackin-capsule modified_click_accepts_visible_mailto_token -- --nocapture
• cargo test -p jackin-capsule modified_click_visible_url_sends_typed_protocol_frame -- --nocapture
• cargo test -p jackin-capsule modified_url_hover_renders_visible_target_without_forwarding_to_pty -- --nocapture
• cd docs && bun run check:repo-links
• cd docs && bunx tsc --noEmit
• cd docs && bun test
• cd docs && bun run build
• git diff --check
  Follow-up 2026-06-12c:
• Synced operator guide and preflight roadmap with unsafe host-link rejection behavior.
• Added focused-cursor command-palette coverage: unsafe visible file: URLs now reject with notice and emit no host-open frame.

Additional verification:

• cargo fmt --check
• cargo test -p jackin-capsule open_link_under_cursor_palette_rejects_unsafe_visible_url -- --nocapture
• git diff --check
  Follow-up 2026-06-12d:
• Fixed host-open cursor resolution so ordinary non-URL words report the normal no-link notice instead of unsafe-scheme rejection.
• Added shared scheme detection for explicit scheme-bearing unsafe tokens.

Additional verification:

• cargo fmt --check
• cargo test -p jackin-core has_url_scheme -- --nocapture
• cargo test -p jackin-capsule open_link_under_cursor_palette -- --nocapture
• git diff --check

Follow-up 2026-06-12e:

• Image-stage notices now include the staged container path and byte count.
• File-export completion notices now include the host destination path and byte count.
• Updated the host affordance guide and clipboard-image roadmap to match the surfaced transfer cues.

Additional verification:

• cargo fmt --check
• cargo test -p jackin-capsule stage_only_clipboard_image_response_does_not_paste_path -- --nocapture
• cargo test -p jackin-capsule stage_image -- --nocapture
• cargo test -p jackin-runtime host_file_export -- --nocapture
• cd docs && bun run check:repo-links
• cd docs && bunx tsc --noEmit
• cd docs && bun test
• cd docs && bun run build
• git diff --check

Follow-up 2026-06-12f:

• Clarified the preflight page is now a promotion/live-validation gate for opt-in host attach, not a blocker for narrow implementation work that has already started.
• Renamed the stale completion gate language to a promotion gate.

Additional verification:

• cd docs && bun run check:repo-links
• cd docs && bunx tsc --noEmit
• cd docs && bun test
• cd docs && bun run build
• git diff --check

Follow-up 2026-06-12g:

• Added explicit Export file and reveal command-palette action. Capsule carries a reveal flag through file-export frames; host attach reveals only after size/SHA-256 verification and final rename. Normal Export file remains non-revealing.
• Documented reveal host-side effects in Host Affordances and both roadmap/preflight pages.

Additional verification:

• cargo fmt --check
• git diff --check
• cargo test -p jackin-protocol -p jackin-capsule -p jackin-runtime
• cd docs && bun run check:repo-links
• cd docs && bunx tsc --noEmit
• cd docs && bun test
• cd docs && bun run build

Follow-up 2026-06-12h

Added explicit Debug info diagnostics reveal over host attach:

• R in Debug info sends a typed HostRevealPath attach frame for the debug diagnostics JSONL path.
• The host attach client canonicalizes the requested path, requires it under jackin's data/diagnostics/runs/ directory, requires .jsonl, then reveals it with the host file manager.
• In-container attach clients ignore this host-only frame safely.
• Docs now cover Copy diagnostics path and Reveal diagnostics log as separate explicit host affordances.

Verification:

• cargo test -p jackin-protocol -p jackin-capsule -p jackin-runtime
• cargo fmt --check
• git diff --check
• cd docs && bun run check:repo-links
• cd docs && bunx tsc --noEmit
• cd docs && bun test
• cd docs && bun run build\n\n### Follow-up 2026-06-12i\n\nAdded launch failure artifact reveal:\n\n- R in the rich launch failure popup reveals the hovered diagnostics/docker-output row, or diagnostics first when no revealable row is hovered.\n- Launch host terminals now share the same host desktop reveal helper used by host attach file export/debug diagnostics.\n- The failure popup shows Revealed! feedback while staying open for copy/retry/ack actions.\n- Docs now cover the launch failure reveal affordance and keep the roadmap/preflight gates current.\n\nVerification:\n\n- cargo fmt --check\n- git diff --check\n- cargo test -p jackin-launch -p jackin-runtime\n- cd docs && bun run check:repo-links\n- cd docs && bunx tsc --noEmit\n- cd docs && bun test\n- cd docs && bun run build\n\n### Follow-up 2026-06-12j\n\nFixed stale image-paste request mode:\n\n- Paste image from host clipboard and Stage image from clipboard path now explicitly reset Capsule request mode to paste-path before emitting host frames.\n- This prevents an older pending Stage image without pasting request from suppressing a later explicit paste/path-stage response.\n- Roadmap test coverage note updated.\n\nVerification:\n\n- cargo fmt --check\n- git diff --check\n- cargo test -p jackin-capsule stage_image_path_palette_action_sends_typed_protocol_frame -- --nocapture\n- cargo test -p jackin-capsule image_palette_action_sends_typed_protocol_frame -- --nocapture\n- cargo test -p jackin-capsule --lib\n- cd docs && bun run check:repo-links\n- cd docs && bunx tsc --noEmit\n- cd docs && bun test\n- cd docs && bun run build\n\n### Follow-up 2026-06-12k\n\nAccepted clipboard text file:// image URLs for explicit path staging:\n\n- Stage image from clipboard path now accepts either an absolute host path or a file:// URL and resolves it through the maintained url crate.\n- Plain text paste remains inert; explicit palette action still required.\n- Operator guide and roadmap now document path-or-file-URL behavior.\n\nVerification:\n\n- cargo fmt --check\n- git diff --check\n- cargo test -p jackin-runtime image_from_path_text -- --nocapture\n- cd docs && bun run check:repo-links\n- cd docs && bunx tsc --noEmit\n- cd docs && bun test\n- cd docs && bun run build

Follow-up 2026-06-12l:

• Added macOS TIFF clipboard fallback after PNG coercion and before Finder/file-url fallback, matching Phase 0 browser-copy evidence that exposed public.tiff.
• Updated host affordance guide and roadmap/preflight notes so /goal docs describe PNG -> TIFF -> Finder/file-url reader order.
• Verified cargo fmt --check, git diff --check, cargo test -p jackin-runtime host_clipboard -- --nocapture, cd docs && bun run check:repo-links, bunx tsc --noEmit, bun test, and bun run build.

Follow-up 2026-06-12m:

• Clarified roadmap /goal text: code-level Debug info and launch-failure reveal paths are implemented; remaining work is live validation plus future dialog/file-row export targets.
• Verified git diff --check, cd docs && bun run check:repo-links, and bunx tsc --noEmit.

Follow-up 2026-06-12n:

• Added a first-class Debug info Reveal diagnostics row and O shortcut for the same host diagnostics JSONL reveal as R.
• Scoped read-only dialog O/C shortcuts to the active dialog, so Debug info cannot accidentally open GitHub PR/CI actions from background PR context.
• Made the reveal-only diagnostics row advertise as clickable for host cursor feedback.
• Verified cargo fmt --check, git diff --check, cargo test -p jackin-capsule container_info -- --nocapture, cargo test -p jackin-tui container_info -- --nocapture, cd docs && bun run check:repo-links, bunx tsc --noEmit, bun test, and bun run build.

Follow-up 2026-06-12o:

• Synced preflight wording for Stage image from clipboard path with implemented absolute-path or file:// URL behavior.
• Verified git diff --check, cd docs && bun run check:repo-links, and bunx tsc --noEmit.

Follow-up 2026-06-12p:

• Updated host-attach clipboard-path rejection copy to mention supported file:// image URLs, matching implemented path staging behavior.
• Added a focused runtime test for that user-visible error string.
• Synced clipboard-image roadmap current-state text with absolute-path-or-file-URL staging.
• Verified cargo fmt --check, cargo test -p jackin-runtime explicit_clipboard_path_request_mentions_file_url_support -- --nocapture, git diff --check, cd docs && bun run check:repo-links, and bunx tsc --noEmit.

Follow-up 2026-06-12q:

• Added file:// image URL to the live Stage image from clipboard path validation checklist.
• Verified git diff --check, cd docs && bun run check:repo-links, and bunx tsc --noEmit.

Follow-up 2026-06-12r:

• Added launch-cockpit Debug info parity for Reveal diagnostics: debug launches now show the reveal-only row before entering Capsule, R / O reveal the run JSONL through the host launch terminal, and reveal-only hyperlink hits set the pointer/reveal path without copying.
• Updated the shared Debug info hint bar to advertise R/O reveal diagnostics and synced Host Affordances plus roadmap/preflight wording with launch-cockpit and Capsule behavior.
• Verified cargo fmt --check, cargo test -p jackin-launch container_info -- --nocapture, git diff --check, cd docs && bun run check:repo-links, bunx tsc --noEmit, bun test, and bun run build.

Follow-up 2026-06-12s:

• Added explicit launch-failure artifact opening: O opens the hovered run diagnostics / docker output artifact through the host file opener, falls back to diagnostics when no artifact row is hovered, and keeps the failure popup open with Opened! feedback.
• Added host file opener command selection beside reveal (open, xdg-open, explorer.exe) and wired it through the launch cockpit host-terminal boundary.
• Updated Host Affordances and both host bridge roadmap pages so the /goal handoff documents reveal/open behavior and live validation expectations.
• Verified cargo fmt --check, cargo test -p jackin-launch -p jackin-runtime failure -- --nocapture, cargo clippy -p jackin-launch -p jackin-runtime -p jackin-tui --all-targets -- -D warnings, git diff --check, cd docs && bun run check:repo-links, bunx tsc --noEmit, bun test, bun run check:roadmap-sidebar, and bun run build.

Follow-up 2026-06-12t:

• Added explicit Export file and open command-palette action. Capsule carries an open flag through file-export frames; host attach opens only after size/SHA-256 verification and final rename. Normal Export file and Export file and reveal keep their existing behavior.
• Updated Host Affordances, Capsule internals, roadmap, preflight, and roadmap index docs so the /goal handoff describes export/reveal/open behavior and remaining live validation.
• Verified cargo fmt --check, cargo test -p jackin-protocol -p jackin-capsule -p jackin-runtime file_export -- --nocapture, cargo test -p jackin-capsule palette_command_route -- --nocapture, cargo test -p jackin-capsule frame_plans_keep_diff_tier_reasons_out_of_full_redraws -- --nocapture, cargo clippy -p jackin-protocol -p jackin-capsule -p jackin-runtime -p jackin-tui --all-targets -- -D warnings, git diff --check, cd docs && bun run check:repo-links, bunx tsc --noEmit, bun test, bun run check:roadmap-sidebar, and bun run build.

Follow-up 2026-06-12u:

• Clarified Host Affordance Bridge roadmap readiness: opt-in implementation READY; default-on host attach NOT READY until throwaway live validation proves parity.
• Fixed preflight safety language: OrbStack live transport proof must use code inspection or a separate throwaway non-jackin' socket container, never existing jackin' containers.
• Added a construct Dockerfile regression test proving wl-clipboard, xauth, and xclip stay installed for Amp/Linux CLI clipboard-helper compatibility.