feat: add send file preview tool

docs/current-status-card.md

@@ -14,7 +14,7 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor
 ## Current completed state
 
 - Go MCP foundation exists: `cmd/isphere-mcp`, `internal/mcpserver`, `internal/helperclient`, and `internal/tools` build a stdio MCP server.
-- The current MCP surface exposes nine tools: four WinHelper observation tools, four read-oriented business tools, and one send-message preview-only tool:
+- The current MCP surface exposes ten tools: four WinHelper observation tools, four read-oriented business tools, one send-message preview-only tool, and one send-file preview-only tool:
   - `win_helper_version`
   - `win_helper_self_check`
   - `win_helper_scan_windows`
@@ -24,8 +24,9 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor
   - `isphere_search_groups`
   - `isphere_receive_files`
   - `isphere_send_message` preview/dry-run only; production is blocked
+  - `isphere_send_file` preview/dry-run only; production file upload is blocked
 - C# `ISphereWinHelper` exists under `native/ISphereWinHelper` and uses the `isphere.helper.v1` stdin/stdout JSON contract. Helper `0.4.0` adds read-only `probe_send_entrypoints` and `probe_send_uia_controls` for R6a/C31 send connector preflight.
-- `scripts/verify-win-helper.ps1` and `scripts/verify-go-mcp.ps1` provide repeatable local checks for the helper, nine-tool MCP surface, default empty-source receive/contact/group/file calls, send-message preview/production-blocked behavior, synthetic configured-file receive/contact/group/file smoke, and synthetic configured-directory receive/contact/group/file smoke.
+- `scripts/verify-win-helper.ps1` and `scripts/verify-go-mcp.ps1` provide repeatable local checks for the helper, ten-tool MCP surface, default empty-source receive/contact/group/file calls, send-message preview/production-blocked behavior, send-file preview/production-blocked behavior, synthetic configured-file receive/contact/group/file smoke, and synthetic configured-directory receive/contact/group/file smoke.
 - `isphere_receive_messages` now returns the contract-facing `ok`, `conversation`, `messages`, `next_cursor`, and `audit` envelope while retaining legacy parser-native message fields for compatibility.
 - `isphere_receive_messages` accepts the read-contract argument set for the current local-readonly path: `conversation_id`, `query`, `since`, `limit`, `include_attachment_metadata`, `source_preference`, `preview`, and empty `cursor`.
 - `isphere_search_contacts` and `isphere_search_groups` accept and validate the safe search-contract args for the current local-readonly path and can optionally enrich results from the env-configured C29 `MsgLib.db` display-entity reader; default behavior remains log/JID-backed when MsgLib env vars are absent.
@@ -37,7 +38,7 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor
 
 ## What cannot be claimed externally
 
-- The project has not yet implemented production message sending, file download, or file sending; `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode have operator-local encrypted log-file/log-directory support but not a production ingestion path.
+- The project has not yet implemented production message sending, file download, or production file sending; `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode have operator-local encrypted log-file/log-directory support but not a production ingestion path.
 - The project has not completed production iSphere integration.
 - The project has not proven a stable real message source for the full business workflow beyond decrypted PacketReader log evidence and synthetic/redacted tests.
 - The project has not implemented real message sending or real file upload. R6b adds preview/dry-run only; it does not prove send invocation, success/ack, or idempotent production behavior.
@@ -49,7 +50,7 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor
 - The repository has a Go MCP + C# WinHelper foundation for controlled Windows-side read-only observation.
 - The helper protocol boundary is explicit and keeps Windows/UIA work separate from the Go MCP service layer.
 - The current code can support future MCP business tools by routing low-level Windows/UIA fallback work through a bounded helper layer.
-- The project has repeatable verification scripts for the helper/MCP foundation and the current nine-tool surface.
+- The project has repeatable verification scripts for the helper/MCP foundation and the current ten-tool surface.
 - The project now has a corrected business contract and plan for core MCP communication tools, plus registered receive/contact/group/file-list read tools that can use `ISPHERE_PACKET_LOG_FILE` for one operator-local encrypted PacketReader log-line file or `ISPHERE_PACKET_LOG_DIR` for an operator-local directory of encrypted `.log`/`.txt` PacketReader files.
 
 ## N13/N14/N15 positioning
@@ -58,7 +59,7 @@ N13/N14/N15 are pre-business validation results. They can help identify UI eleme
 
 ## Current loop
 
-Current loop: `R6l send-message production path gate closure complete; next R7 send-file preview tool`.
+Current loop: `R7 send-file preview tool complete`; next R8 send-file idempotency and audit hardening.
 
 Active continuous execution plan: `docs/superpowers/plans/2026-07-10-r6f-r14-continuous-execution-plan.md`.
 
@@ -239,8 +240,8 @@ Continuous execution plan R6f-R14 is approved and execution has started:
 - Plan file: `docs/superpowers/plans/2026-07-10-r6f-r14-continuous-execution-plan.md`.
 - Scope: 15 ordered rounds covering send-message connector/gate hardening, send-file preview/idempotency/package, receive-file download preview, receive-message reconciliation, end-to-end business smoke, and release-candidate report.
 - Execution rule after approval: one round at a time, status-card update, verification, commit, push, then continue automatically until an evidence-only blocker requires user action.
-- Last completed round: R6l send-message production path gate closure.
-- Next active round: R7 send-file preview tool.
+- Last completed round: R7 send-file preview tool.
+- Next active round: R8 send-file idempotency and audit hardening.
 
 R6g send audit and idempotency replay diagnostics is complete:
 
@@ -295,3 +296,12 @@ R6l send-message production path gate closure is complete:
 - Added an explicit skipped gated-production test with reason `strict v2 send evidence not present in this repository state`.
 - Standard verification still reports 9 tools and `production_send_enabled=false`.
 - Next node: R7 send-file preview tool.
+
+R7 send-file preview tool is complete:
+
+- Added `isphere_send_file` as the tenth MCP tool.
+- Preview validates target, idempotency key, `ISPHERE_SEND_FILE_ALLOWED_DIR`, file existence, file SHA256, and file size.
+- Preview returns `send_status="planned"`, `real_send_attempted=false`, `production_send_enabled=false`, `file_sha256`, `file_size_bytes`, and all upload/send side-effect flags false.
+- `execution_mode="production"` returns structured blocked metadata; no upload, click, type, hook, network capture, or client mutation is introduced.
+- Verification passed: focused send-file tests, 10-tool MCP registration test, `go test ./...`, `go build ./cmd/isphere-mcp`, `scripts\verify-go-mcp.ps1`, and `go run ./cmd/isphere-capability-smoke`.
+- Next node: R8 send-file idempotency and audit hardening.

docs/go-mcp-runbook.md

@@ -2,7 +2,7 @@
 
 This runbook is for the first Go MCP phase of `isphere-ai-bridge`. It lets an operator build and verify the Windows helper and the Go MCP server without reading the source code.
 
-Current scope: expose four WinHelper observation operations, four business read tools, and one preview-only send-message tool through Go MCP. Read tools are `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode. The send tool is `isphere_send_message` preview/dry-run only; production send is blocked. Read tools use an empty default message source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file or `ISPHERE_PACKET_LOG_DIR` points to an operator-local directory of encrypted PacketReader `.log`/`.txt` files. Contact/group display names can also be optionally enriched from an operator-local copied `MsgLib.db` through the bounded read-only `MsgLibReadSidecar`; receive messages can use copied DB rows only when the caller explicitly passes `source_preference="msglib_readonly"`.
+Current scope: expose four WinHelper observation operations, four business read tools, and two preview-only send tools through Go MCP. Read tools are `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode. Send tools are `isphere_send_message` and `isphere_send_file` preview/dry-run only; production send/file upload is blocked. Read tools use an empty default message source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file or `ISPHERE_PACKET_LOG_DIR` points to an operator-local directory of encrypted PacketReader `.log`/`.txt` files. Contact/group display names can also be optionally enriched from an operator-local copied `MsgLib.db` through the bounded read-only `MsgLibReadSidecar`; receive messages can use copied DB rows only when the caller explicitly passes `source_preference="msglib_readonly"`.
 
 ## 1. Prerequisites
 
@@ -90,7 +90,7 @@ The verification confirms:
 - C# helper can be built.
 - Go MCP binary can be built.
 - MCP initialize/list/call flow works through the SDK harness.
-- Exactly nine tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, `isphere_receive_files`, and preview-only `isphere_send_message`.
+- Exactly ten tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, `isphere_receive_files`, preview-only `isphere_send_message`, and preview-only `isphere_send_file`.
 - `win_helper_version` returns `ISphereWinHelper`.
 - `isphere_receive_messages` is callable and returns an empty `messages` array from the default empty source.
 - `isphere_receive_messages` returns the contract-facing `ok`, `conversation`, `messages`, `next_cursor`, and `audit` envelope, while preserving legacy message aliases such as `id`, `text`, and `timestamp`.
@@ -100,11 +100,12 @@ The verification confirms:
 - `isphere_search_groups` is callable and returns JID-derived group candidates from the configured synthetic groupchat fixture; exact ID/display-name matches rank before prefix/substring matches and case-insensitive duplicates are collapsed.
 - `isphere_receive_files` is callable in list mode and returns one file metadata candidate from the configured synthetic file-transfer fixture.
 - `isphere_send_message` is callable in preview mode and returns `send_status="planned"` without raw content in the response; the default runtime still returns `execution_mode="production"` as `send_status="blocked"` and `production_send_enabled=false`.
+- `isphere_send_file` is callable in preview mode when `ISPHERE_SEND_FILE_ALLOWED_DIR` points to the allowed local directory; it returns file SHA256/size metadata only, does not return file content, and keeps production upload blocked with `production_send_enabled=false`.
 - `isphere_send_message` also exposes sandbox-only connector metadata and idempotency state: duplicate reuse of the same key for the same target/content is detectable, while conflicting reuse of the same key for different content/target is blocked.
 - R6f adds a test-only fake/sandbox connector contract for accepted/failed connector outcomes. This is an injected unit-test boundary only; the production MCP server still registers no real connector and performs no real send.
 - Verification uses synthetic/local helper checks and does not load raw N12-pre evidence.
 - The deterministic verification path clears MsgLib env variables, so it proves the default no-MsgLib behavior remains stable.
-- File download/cache mapping, send-file, and production send remain later-stage work.
+- File download/cache mapping, production message send, and production file upload remain later-stage work.
 
 ## 6. Configure optional message source
 
@@ -240,7 +241,7 @@ E:\coding\codex\isphere-ai-bridge\isphere-mcp.exe
 
 ## 9. Allowed tools
 
-These nine tools are currently allowed:
+These ten tools are currently allowed:
 
 | Tool | Source/op | Purpose |
 | --- | --- | --- |
@@ -253,6 +254,7 @@ These nine tools are currently allowed:
 | `isphere_search_groups` | log-backed groupchat JIDs plus optional MsgLib display enrichment | Search group candidates extracted from groupchat/conference/MUC bare JIDs in the configured message source, with deterministic exact-match-first ranking, case-insensitive de-duplication, and preserved `source`/`raw_ref`. |
 | `isphere_receive_files` | log-backed file-transfer messages | List file metadata candidates extracted from file-transfer message bodies. Download/cache mapping is not implemented yet. |
 | `isphere_send_message` | B-route preview/dry-run contract | Plan a text-message send with target/content hash/idempotency/audit metadata. Production send is blocked. |
+| `isphere_send_file` | file-send preview/dry-run contract | Plan a file send with target/file SHA256/size/idempotency metadata. Production upload is blocked. |
 
 Allowed parameters:
 
@@ -265,6 +267,7 @@ Allowed parameters:
 - `isphere_search_groups`: `query`, `cursor`, `source_preference`, `include_archived`, `limit` only. `source_preference` currently supports empty/`auto`/`local_readonly`; `cursor` must be empty until pagination is implemented.
 - `isphere_receive_files`: `conversation_id`, `message_id`, `file_id`, `name_contains`, `mode`, `output_dir`, `cursor`, `source_preference`, `preview`, `limit` only. C22 supports `mode` empty or `list`; `source_preference` currently supports empty/`auto`/`local_readonly`; `cursor` and `output_dir` must be empty in current list-only mode; download is deferred.
 - `isphere_send_message`: `target_type`, `target_id`, `content_text`, `content_sha256`, `idempotency_key`, `execution_mode` only. R6b supports `execution_mode` empty/`preview`/`dry_run` as planned preview. The default runtime returns `execution_mode="production"` as blocked until sandbox-send evidence passes. R6f adds a Go `SendMessageConnector` interface for fake/sandbox tests so accepted, failed, duplicate, and conflict paths can be validated without login. The response and audit store `content_sha256` and `idempotency_key_sha256`, not raw message body or raw idempotency key.
+- `isphere_send_file`: `target_type`, `target_id`, `file_path`, `file_sha256`, `idempotency_key`, `execution_mode`, `preview` only. `file_path` must stay inside `ISPHERE_SEND_FILE_ALLOWED_DIR`; preview computes/validates `file_sha256` and `file_size_bytes`, returns `real_send_attempted=false`, and does not upload or return file content. The default runtime returns `execution_mode="production"` as blocked.
 
 Optional send audit/idempotency paths:
 
@@ -275,6 +278,14 @@ $env:ISPHERE_SEND_IDEMPOTENCY_PATH = "E:\coding\codex\isphere-ai-bridge\runs\sen
 
 If `ISPHERE_SEND_IDEMPOTENCY_PATH` is set, the send preview path records hashed idempotency state. Reusing the same idempotency key for the same target/content sets `duplicate_detected=true`; reusing it for different content or target returns blocked metadata with `conflict_detected=true`. Raw message body and raw idempotency key are not stored in the JSONL state.
 
+Send-file preview requires an explicit allowed directory. Put only the files you want the digital employee to plan against inside that directory:
+
+```powershell
+$env:ISPHERE_SEND_FILE_ALLOWED_DIR = "E:\coding\codex\isphere-ai-bridge\runs\send-file-preview"
+```
+
+`isphere_send_file` rejects `file_path` values outside that directory. It computes file SHA256 and size, but does not upload, click, type, or return file content.
+
 R6g adds a local diagnostic for replaying the redacted audit/idempotency files without opening iSphere:
 
 ```powershell
@@ -298,7 +309,7 @@ R6l closes the current send-message production path after R6k: because `strict_v
 
 ## 10. Current tool surface and next-stage route
 
-The current runbook verifies nine tools:
+The current runbook verifies ten tools:
 
 - `win_helper_version`
 - `win_helper_self_check`
@@ -309,10 +320,11 @@ The current runbook verifies nine tools:
 - `isphere_search_groups`
 - `isphere_receive_files`
 - `isphere_send_message`
+- `isphere_send_file`
 
-The current log-backed business read tools have parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored `runs/` paths and is not committed. The current command entry point can read an operator-local encrypted PacketReader log-line file via `ISPHERE_PACKET_LOG_FILE` or a directory of `.log`/`.txt` files via `ISPHERE_PACKET_LOG_DIR`; this is still not a production ingestion claim because raw evidence remains local and uncommitted. `isphere_receive_messages` now exposes contract-facing fields for digital-employee consumption while preserving older aliases for compatibility, supports `conversation_id`, keyword `query`, and RFC3339 `since` filtering, and validates the remaining safe contract args without pretending unsupported connectors/pagination exist. Contact and group search also accept the safe local-readonly contract args, rank exact matches before prefix/substring matches, collapse case-insensitive duplicates across log-derived candidates and optional `MsgLibReadSidecar` display metadata, and preserve `source`/`raw_ref`; receive-message `sender_name` and `conversation.display_name` can use that same optional metadata when MsgLib env is configured. `isphere_receive_files` supports list mode with safe contract arg validation; download/cache mapping remains deferred. `isphere_send_message` supports preview/dry-run metadata, sandbox-only connector-shell metadata, duplicate/conflict idempotency detection, redacted audit, and a test-only `SendMessageConnector` contract for fake accepted/failed outcomes; the default MCP server still has no real connector and production send remains blocked until dynamic observation, a full send evidence gate, and a controlled sandbox connector pass prove success/ack behavior.
+The current log-backed business read tools have parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored `runs/` paths and is not committed. The current command entry point can read an operator-local encrypted PacketReader log-line file via `ISPHERE_PACKET_LOG_FILE` or a directory of `.log`/`.txt` files via `ISPHERE_PACKET_LOG_DIR`; this is still not a production ingestion claim because raw evidence remains local and uncommitted. `isphere_receive_messages` now exposes contract-facing fields for digital-employee consumption while preserving older aliases for compatibility, supports `conversation_id`, keyword `query`, and RFC3339 `since` filtering, and validates the remaining safe contract args without pretending unsupported connectors/pagination exist. Contact and group search also accept the safe local-readonly contract args, rank exact matches before prefix/substring matches, collapse case-insensitive duplicates across log-derived candidates and optional `MsgLibReadSidecar` display metadata, and preserve `source`/`raw_ref`; receive-message `sender_name` and `conversation.display_name` can use that same optional metadata when MsgLib env is configured. `isphere_receive_files` supports list mode with safe contract arg validation; download/cache mapping remains deferred. `isphere_send_message` supports preview/dry-run metadata, sandbox-only connector-shell metadata, duplicate/conflict idempotency detection, redacted audit, and a test-only `SendMessageConnector` contract for fake accepted/failed outcomes; `isphere_send_file` now exposes preview/dry-run file SHA256/size planning behind `ISPHERE_SEND_FILE_ALLOWED_DIR` with all upload/send side-effect flags false. The default MCP server still has no real message/file connector and production send/file upload remains blocked until dynamic observation, full evidence gates, and controlled sandbox connector passes prove success/ack behavior.
 
-Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send-message preview metadata and audit records are now in place; production send still waits for the later online sandbox-send gate.
+Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send-message preview metadata and audit records are now in place; send-file preview metadata is in place with allowed-directory validation. Production message send and file upload still wait for later online sandbox evidence gates.
 
 ## 11. Real-login UIA capture procedure
 
@@ -495,16 +507,18 @@ Expected final JSON includes:
 ```json
 {
   "ok": true,
-  "tool_count": 9,
+  "tool_count": 10,
   "helper_name": "ISphereWinHelper",
   "send_preview_tool_present": true,
   "production_send_enabled": false,
+  "send_file_preview_tool_present": true,
+  "send_file_production_enabled": false,
   "local_login_required": false,
   "no_real_send": true
 }
 ```
 
-This package includes `isphere-capability-smoke.exe` and `runs\win-helper\ISphereWinHelper.exe`. It verifies the nine-tool MCP surface, fixture-backed receive/search/file-list behavior, send preview, and the production-send block. It does not log in, click, type, upload, hook, inject, or send.
+This package includes `isphere-capability-smoke.exe` and `runs\win-helper\ISphereWinHelper.exe`. It verifies the ten-tool MCP surface, fixture-backed receive/search/file-list behavior, send preview, send-file preview, and the production-send/file-upload blocks. It does not log in, click, type, upload, hook, inject, or send.
 
 ## 16. Troubleshooting
 

docs/superpowers/plans/2026-07-10-r6f-r14-continuous-execution-plan.md

@@ -535,23 +535,23 @@ git push gitea main
 - Env: `ISPHERE_SEND_FILE_ALLOWED_DIR` required for previewing real local file paths.
 - Response fields: `ok`, `send_status`, `file_sha256`, `file_size_bytes`, `target_ref`, `production_send_enabled`, `side_effect_flags`.
 
-- [ ] **Step 1: Write file-preview test**
+- [x] **Step 1: Write file-preview test**
 
 Add `TestISphereSendFilePreviewComputesHashAndSize`, creating a temp allowed directory and `hello.txt`, then asserting preview returns `ok=true`, `send_status="planned"`, `file_size_bytes=5`, and `real_send_attempted=false`.
 
-- [ ] **Step 2: Write path rejection test**
+- [x] **Step 2: Write path rejection test**
 
 Add `TestISphereSendFileRejectsPathOutsideAllowedDir` asserting paths outside `ISPHERE_SEND_FILE_ALLOWED_DIR` return `ok=false` and `send_status="blocked"`.
 
-- [ ] **Step 3: Implement tool and registration**
+- [x] **Step 3: Implement tool and registration**
 
 Register the tenth MCP tool. Production execution returns blocked with `production_send_enabled=false`.
 
-- [ ] **Step 4: Update smoke scripts**
+- [x] **Step 4: Update smoke scripts**
 
 `verify-go-mcp.ps1` and `isphere-capability-smoke` must assert tool count includes `isphere_send_file`, preview works with a temp fixture file, and production remains blocked.
 
-- [ ] **Step 5: Verify and commit**
+- [x] **Step 5: Verify and commit**
 
 ```powershell
 git diff --check
@@ -566,6 +566,15 @@ git push gitea main
 
 **Acceptance gate:** 数字员工能看到“发文件”工具，但默认路径只做 preview，不上传。
 
+**R7 Result:**
+
+- Added `internal/tools/isphere_send_file.go` and `internal/tools/isphere_send_file_test.go`.
+- Registered `isphere_send_file` as the tenth MCP tool.
+- Preview requires `ISPHERE_SEND_FILE_ALLOWED_DIR`, validates target/idempotency/file existence/path boundary/SHA256/size, and returns `send_status="planned"` with `real_send_attempted=false`.
+- Production `execution_mode="production"` remains structured blocked with `production_send_enabled=false` and all send/upload/UI/network side-effect flags false.
+- Updated `scripts/verify-go-mcp.ps1` and `cmd/isphere-capability-smoke` to assert 10 tools, send-file preview readiness, and send-file production disabled.
+- Verification passed: `git diff --check`, focused send-file tests, 10-tool registration test, `go test ./...`, `go build ./cmd/isphere-mcp`, `scripts\verify-go-mcp.ps1`, and `go run ./cmd/isphere-capability-smoke`.
+
 ---
 
 ### R8: Send-file idempotency and audit hardening