diff --git a/docs/go-mcp-minimal-plan.md b/docs/go-mcp-minimal-plan.md index c9d0f9b..1242f9f 100644 --- a/docs/go-mcp-minimal-plan.md +++ b/docs/go-mcp-minimal-plan.md @@ -25,6 +25,7 @@ N0 Baseline cleanup and direction lock -> N9 MCP stdio smoke verification -> N10 Operator runbook and process scripts -> N11 Commit/review checkpoint + -> N12-pre Offline evidence intake -> N12 Real logged-in UIA capture gate ``` @@ -752,7 +753,84 @@ Pass if: - Unrelated generated files are staged. - Worktree contains ignored build outputs outside `runs/`. -**Next node:** N12. +**Next node:** N12-pre if the current environment cannot log in; otherwise N12 may start only when the real logged-in current-environment preconditions below are met. + +--- + +## N12-pre: Offline evidence intake + +**Purpose:** Define and validate offline evidence copied from a separate logged-in test sandbox when the current repository environment cannot log in to iSphere. + +**Preconditions:** + +- N11 accepted. +- Current environment cannot manually log in to iSphere / IMPlatformClient. +- Business manager approves offline evidence intake as a pre-gate only. + +**Actions:** + +- Follow `docs/offline-evidence-intake-plan.md`. +- Prefer mode A, **Full sandbox artifact bundle**. The user does not need to understand or generate JSON; they only copy folders from the logged-in test sandbox. +- Recommended full-bundle shape: + +```text +runs/offline-evidence-intake// + copy-notes.txt + raw/ + install/ + user-profile/ + programdata/ + shortcuts/ + temp-importal-localcache/ + other-candidates/ + metadata/ + notes/ +``` + +- Common candidate source paths include install directories, `%APPDATA%`, `%LOCALAPPDATA%`, `%PROGRAMDATA%`, `Documents`, Desktop/Start Menu shortcuts, and `%TEMP%\importal` or `localcache` folders. +- Pay attention to historical iSphere anchors such as `importal\localcache`, `LoginLog`, `IMPP.Util.dll`, `IMPlatformClient`, and `iSphere`. +- Optional mode B, **Minimal redacted UIA package**, is only for advanced operators who already know how to produce JSON: + +```text +runs/offline-evidence-intake// + manifest.json + scan_windows-redacted.json + dump_uia-main-redacted.json +``` + +- For optional mode B, confirm the package states `n12_status = offline_pre_only_not_n12_pass` and uses only: + +```text +version +self_check +scan_windows +dump_uia +``` + +**Expected outputs:** + +- Full sandbox artifact bundle for read-only offline inventory, or optional minimal UIA JSON package for advanced users. +- No claim that the current environment has a logged-in iSphere window. +- No claim that N12 passed. + +**Acceptance conditions:** + +Pass if: + +- In mode A, the copied bundle preserves directory structure and includes at least one useful `raw/` source area plus `copy-notes.txt` when available. +- In mode A, repository-side handling is read-only inventory: do not directly run unknown binaries and do not modify original copied files. +- In mode B, required JSON files exist and parse as JSON, and the manifest records offline pre-evidence only, not N12 pass. +- For both modes, the route does not design or perform automatic login, send message, send file, receive file, injection, hook, memory reading, or endpoint-security bypass. + +**Stop conditions:** + +- Any step requires the user to understand JSON before they can provide the recommended full bundle. +- Any step directly runs unknown binaries from the copied bundle. +- Any step modifies original copied files. +- Package is used to design automatic login, sending, file transfer, injection, hook, memory reading, or endpoint-security bypass. +- Any reader treats the offline package as a replacement for true N12. + +**Next node:** N12 remains blocked until the current environment can manually log in and perform a live current-environment UIA capture. --- @@ -763,7 +841,7 @@ Pass if: **Preconditions:** - N11 accepted. -- User has copied real install/user files if needed. +- Optional N12-pre offline evidence, if used, has been validated only as pre-gate context and not as N12 pass evidence. - User manually opens and logs in to iSphere. - iSphere main window is visible. @@ -808,6 +886,7 @@ Pass if: - No candidate window appears. - UIA tree is empty or inaccessible. - Captured data contains sensitive secrets that need redaction before reporting. +- Current environment cannot log in; in that case, use only N12-pre offline analysis and do not mark N12 passed. **Next node:** Future selector design. Do not implement selectors until N12 passes. @@ -829,16 +908,16 @@ Every node must satisfy these rules: ## 4. Current Next Node -Current next node is: +Current guidance after N0-N11 completion is: ```text -N0 -> N1 -> N2 +N12-pre if the current environment cannot log in; N12 only after current-environment manual login is possible. ``` Immediate next action: ```text -Run N1 C# baseline verification, then start N2 Go module skeleton. +If login is unavailable here, collect/validate the full sandbox artifact bundle described in docs/offline-evidence-intake-plan.md. Minimal manifest/scan/dump JSON is optional and only for advanced operators. ``` -Do not start N8 or N12 early. +Do not treat offline evidence as N12 pass. Do not start selector/action design until true N12 passes in the current environment. diff --git a/docs/go-mcp-runbook.md b/docs/go-mcp-runbook.md index db3470b..010a86c 100644 --- a/docs/go-mcp-runbook.md +++ b/docs/go-mcp-runbook.md @@ -211,7 +211,17 @@ Procedure: During this procedure, the operator must not click, type, send, upload, download, modify client state, or capture passwords/tokens. -## 10. Troubleshooting +## 10. If this environment cannot log in + +Do not run or mark the real-login UIA capture gate as passed. + +If login is only possible in another test sandbox, follow `docs/offline-evidence-intake-plan.md` and use the recommended **Full sandbox artifact bundle** route. The user does not need to generate JSON. Ask them to copy the logged-in test sandbox's install directory, user-data directories, ProgramData directories, shortcuts, `%TEMP%\importal` / `localcache` candidates, and simple copy notes into `runs\offline-evidence-intake\\`. + +The minimal `manifest.json` / `scan_windows-redacted.json` / `dump_uia-main-redacted.json` route is optional and only for advanced operators. In either route, the package is `N12-pre` context only. It can support offline inventory and reverse analysis, but it does not replace live current-environment `win_helper_scan_windows` and `win_helper_dump_uia` evidence. + +After receiving a full bundle, first do read-only inventory. Do not directly run unknown copied binaries, do not modify original copied files, do not use copied credential-like material to log in, and do not design automatic login, send message, send file, receive file, injection, hook, memory reading, or endpoint-security bypass behavior. + +## 11. Troubleshooting - If C# helper build fails, run `scripts\build-win-helper.ps1` directly and check for missing .NET Framework reference assemblies. - If `win_helper_version` fails, rerun `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1` first. diff --git a/docs/handoff-2026-07-06.md b/docs/handoff-2026-07-06.md new file mode 100644 index 0000000..ede0173 --- /dev/null +++ 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// +``` + +Recommended package structure: + +```text +runs/offline-evidence-intake// + 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\\ +``` + +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\\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\\Desktop\ +C:\Users\\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: +windows user: +iSphere manually logged in: yes/no +client opened before copy: yes/no +copy time: