docs: add offline evidence handoff plan

2026-07-06 20:46:49 +08:00
parent bbd2be876c
commit d773571402
6 changed files with 1014 additions and 8 deletions
--- a/docs/handoff-2026-07-06.md
+++ b/docs/handoff-2026-07-06.md
@@ -0,0 +1,381 @@
+# iSphere AI Bridge Handoff - 2026-07-06
+
+## 1. Handoff summary
+
+This repository is ready to hand off for the next operator.
+
+Current branch:
+
+```text
+codex/isphere-win-helper-first-phase
+```
+
+Current direction:
+
+```text
+Go MCP server + C# ISphereWinHelper.exe
+```
+
+The Python MCP path has been removed from the active plan. The current first-phase surface exposes only four read-only WinHelper-backed MCP tools:
+
+```text
+win_helper_version
+win_helper_self_check
+win_helper_scan_windows
+win_helper_dump_uia
+```
+
+No search, conversation opening, message sending, file sending/receiving, automatic login, injection, hook, memory reading, or endpoint-security bypass is implemented.
+
+## 2. Current completed state
+
+Completed plan nodes:
+
+```text
+N0   Baseline cleanup and direction lock
+N1   C# WinHelper baseline verification
+N2   Go module skeleton
+N3   Go helper protocol contract
+N4   Go helper process client
+N5   Helper client live verification
+N6   MCP library decision
+N7   Go MCP server skeleton
+N8   Four read-only MCP tool handlers
+N9   MCP stdio smoke verification
+N10  Operator runbook and process scripts
+N11  Commit and review checkpoint
+```
+
+N11 was completed with verification and commits. The latest checkpoint commits at handoff time are:
+
+```text
+bbd2be8 docs: record final go mcp checkpoint reviews
+57f1d42 docs: add go mcp runbook
+17fa9dd test: add go mcp verification script
+8956f33 feat: add go helper client and mcp tools
+63cda71 docs: add go mcp plan and process logs
+87e0e47 chore: remove temporary python mcp layer
+```
+
+After N11, the plan was adjusted because the current environment cannot log in to iSphere. The next step is not true N12 yet. It is now:
+
+```text
+N12-pre: Offline evidence intake
+```
+
+## 3. Current stop point
+
+Do not mark N12 as passed yet.
+
+True N12 still requires all of the following in the current environment:
+
+```text
+1. User manually opens iSphere in this environment.
+2. User manually logs in.
+3. iSphere main window is visible.
+4. Go MCP read-only tools run against that live visible window.
+5. win_helper_scan_windows finds the candidate window.
+6. win_helper_dump_uia captures the UIA tree.
+7. Output is saved under runs/real-loggedin-lab/uia-dumps/.
+```
+
+The user currently cannot log in inside this environment. Therefore, the next operator should start with offline evidence intake only.
+
+## 4. New next step: N12-pre offline evidence intake
+
+The user has full permission over the test sandbox and can copy files from another sandbox where iSphere can be manually logged in.
+
+Do not ask the user to manually generate UIA JSON first. The practical route is:
+
+```text
+Full sandbox artifact bundle
+```
+
+Expected location inside this repo after the user provides it:
+
+```text
+runs/offline-evidence-intake/<evidence-id>/
+```
+
+Recommended package structure:
+
+```text
+runs/offline-evidence-intake/<evidence-id>/
+  raw/
+    user-profile/
+    install/
+    programdata/
+    temp/
+    shortcuts/
+  metadata/
+  notes/
+    copy-notes.txt
+```
+
+Important: `runs/*` is ignored by Git. Do not commit raw evidence packages.
+
+## 5. What to ask the user to copy
+
+Ask the user to copy these from the sandbox that can log in to iSphere.
+
+### 5.1 Full test user profile
+
+```text
+C:\Users\<logged-in-test-user>\
+```
+
+Place it under:
+
+```text
+raw/user-profile/
+```
+
+### 5.2 iSphere / IMPlatformClient install directory
+
+Common parent locations:
+
+```text
+C:\Program Files\
+C:\Program Files (x86)\
+D:\...
+```
+
+Everything keywords:
+
+```text
+iSphere
+IMPlatformClient
+IMPlatform
+IMPP
+importal
+```
+
+Place install folders under:
+
+```text
+raw/install/
+```
+
+### 5.3 ProgramData
+
+If size is acceptable, copy:
+
+```text
+C:\ProgramData\
+```
+
+Otherwise copy only directories matching:
+
+```text
+iSphere
+IMPlatformClient
+IMPlatform
+IMPP
+importal
+```
+
+Place under:
+
+```text
+raw/programdata/
+```
+
+### 5.4 Temp/importal/localcache
+
+High-priority path:
+
+```text
+C:\Users\<logged-in-test-user>\AppData\Local\Temp\importal\
+```
+
+Important names:
+
+```text
+importal\localcache
+LoginLog
+```
+
+Place under:
+
+```text
+raw/temp/importal/
+```
+
+### 5.5 Shortcuts
+
+Copy relevant shortcuts from:
+
+```text
+C:\Users\<logged-in-test-user>\Desktop\
+C:\Users\<logged-in-test-user>\AppData\Roaming\Microsoft\Windows\Start Menu\
+C:\ProgramData\Microsoft\Windows\Start Menu\
+```
+
+Place under:
+
+```text
+raw/shortcuts/
+```
+
+### 5.6 Optional metadata
+
+If convenient, ask the user to include:
+
+```text
+metadata/process-list.txt
+metadata/installed-programs.txt
+metadata/os-version.txt
+metadata/env.txt
+metadata/tree-user-profile.txt
+metadata/tree-install.txt
+metadata/tree-programdata.txt
+```
+
+### 5.7 Copy notes
+
+Ask the user to write:
+
+```text
+notes/copy-notes.txt
+```
+
+Minimal content:
+
+```text
+source sandbox: <name>
+windows user: <test user>
+iSphere manually logged in: yes/no
+client opened before copy: yes/no
+copy time: <time>
+package is from test sandbox: yes
+```
+
+## 6. Everything search keywords
+
+If the user uses Everything, ask them to search these keywords and copy the containing directories:
+
+```text
+iSphere
+IMPlatformClient
+IMPlatform
+IMPP
+importal
+localcache
+LoginLog
+IMPP.Util.dll
+csimlog.dll
+iSphere.exe
+IMPlatformClient.exe
+```
+
+## 7. First action after evidence arrives
+
+Do not run copied executables directly.
+
+First action should be read-only inventory:
+
+```text
+1. Unpack evidence under runs/offline-evidence-intake/<evidence-id>/.
+2. Preserve original tree.
+3. Produce a directory inventory.
+4. Hash key executables and DLLs.
+5. Identify install paths, config files, cache/log/database candidates.
+6. Identify whether LoginLog / importal/localcache exists.
+7. Decide whether local-data discovery is possible from copied files.
+```
+
+Recommended next analysis skills/workstreams:
+
+```text
+comm-app-inventory
+local-data-discovery
+reverse-evidence-report
+```
+
+## 8. Verification commands for current repo
+
+Before handing off or after pulling on a new machine, run:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
+go test ./...
+go build ./cmd/isphere-mcp
+```
+
+Expected high-level result:
+
+```text
+verify-win-helper: ok=true
+verify-go-mcp: ok=true, tool_count=4, helper_name=ISphereWinHelper
+go test: pass
+go build: pass
+```
+
+## 9. Important repository files
+
+```text
+docs/go-mcp-minimal-plan.md
+  Active node plan, now including N12-pre before true N12.
+
+docs/offline-evidence-intake-plan.md
+  Detailed offline artifact intake plan.
+
+docs/go-mcp-runbook.md
+  Operator runbook.
+
+docs/go-csharp-helper-boundary.md
+  Helper protocol and Go/C# boundary.
+
+scripts/verify-win-helper.ps1
+  Builds/verifies C# helper.
+
+scripts/verify-go-mcp.ps1
+  Builds/verifies Go MCP and calls win_helper_version.
+
+native/ISphereWinHelper/
+  C# helper source.
+
+internal/helperclient/
+  Go helper protocol and process client.
+
+internal/mcpserver/
+  Go MCP stdio server skeleton.
+
+internal/tools/
+  Four read-only WinHelper MCP tool registrations.
+```
+
+## 10. Hard boundaries for the next owner
+
+Do not implement these until explicitly planned and approved later:
+
+```text
+search contacts
+open conversation
+send message
+send file
+receive/download file
+automatic login
+process injection
+hook
+memory reading
+security bypass/evasion
+```
+
+Do not treat the offline evidence package as N12 pass.
+
+Do not commit raw copied evidence under `runs/`.
+
+## 11. Current handoff expectation
+
+The next owner should first get the offline evidence package from the user, then perform read-only inventory and report what local files are actually useful.
+
+Only after that should the team decide whether to:
+
+```text
+1. Continue offline local-data discovery.
+2. Ask for a better evidence package.
+3. Wait until current-environment live login becomes possible.
+4. Re-plan true N12.
+```