@masstensor/diagnose 0.8.0 → 0.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -7
- package/USER_GUIDE.md +32 -717
- package/dist/discover.js +1 -1
- package/dist/mcp.js +16 -3
- package/dist/peer.d.ts +1 -0
- package/dist/peer.js +11 -1
- package/dist/skill-session.js +18 -3
- package/docs/guide/automation.md +184 -0
- package/docs/guide/diagnose.md +93 -0
- package/docs/guide/on-site.md +139 -0
- package/docs/guide/procedures.md +183 -0
- package/docs/guide/reconnect.md +58 -0
- package/docs/guide/troubleshooting.md +77 -0
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -1
- package/skills/connect/SKILL.md +8 -2
- package/skills/connect/scripts/run.mjs +1 -1
- package/src/discover.ts +1 -1
- package/src/mcp.ts +16 -4
- package/src/peer.ts +10 -1
- package/src/skill-session.ts +15 -3
- package/test/skill-session.test.ts +20 -6
package/USER_GUIDE.md
CHANGED
|
@@ -1,40 +1,24 @@
|
|
|
1
1
|
# Diagnose user guide
|
|
2
2
|
|
|
3
|
-
Diagnose
|
|
3
|
+
Diagnose lets a remote AI agent inspect and troubleshoot a device through a computer on site. The person on site connects the equipment and controls access. The diagnostician runs the AI agent on their own computer. An encrypted relay connects the two computers.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Choose your scenario
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
Diagnose lets the expert's AI use an authorized connection through a nearby computer. The on-site user still controls access, but no longer has to relay every command and result by hand.
|
|
10
|
-
|
|
11
|
-
## What: a general-purpose bridge to the device
|
|
12
|
-
|
|
13
|
-
The **probe** is the Diagnose program running on the on-site computer. It gives the remote agent tools to inspect that computer's environment, read exposed serial logs, run installed device utilities, and reach accessible network services. It does not require an AI agent to be installed on the target device.
|
|
14
|
-
|
|
15
|
-
The same probe can serve different devices. A **skill or Markdown procedure** supplies device-specific knowledge: the model, connection method, protocol, useful checks, and acceptable repair steps. Access still depends on available interfaces, drivers, credentials, and tools; Diagnose does not automatically support every device or protocol.
|
|
16
|
-
|
|
17
|
-
For example, an owner connects a gateway's exposed serial interface to a laptop. A remote diagnostician asks the AI to find why readings have stopped. The agent can inspect available logs, check communication, perform an authorized operation if the interface supports it, and check for new readings. If physical work or another interface is needed, it reports that instead.
|
|
18
|
-
|
|
19
|
-
## How: connect the site, then direct the agent
|
|
20
|
-
|
|
21
|
-
> Remote AI agent ↔ encrypted relay ↔ on-site computer running Diagnose ↔ target device
|
|
22
|
-
|
|
23
|
-
The relay carries encrypted traffic between the computers. The on-site computer accesses the device through USB, serial, or its local network. Diagnose's end-to-end encryption protects the connection between the two computers; the device's local protocol has its own security properties.
|
|
24
|
-
|
|
25
|
-
| Role | What they do |
|
|
7
|
+
| If you want to… | Go to |
|
|
26
8
|
| --- | --- |
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
31
|
-
|
|
9
|
+
| Connect for the first time | [Quick start](#quick-start) |
|
|
10
|
+
| Get help with your device | [Receive remote help](docs/guide/on-site.md) |
|
|
11
|
+
| Use Claude Code, Codex, or Gemini to diagnose a device | [Diagnose a remote device](docs/guide/diagnose.md) |
|
|
12
|
+
| Reconnect without exchanging a new invitation | [Return to a saved device](docs/guide/reconnect.md) |
|
|
13
|
+
| Load a device procedure or learn from a completed diagnosis | [Reuse and improve procedures](docs/guide/procedures.md) |
|
|
14
|
+
| Start Diagnose from a script or use your own MCP client | [Automation and tool reference](docs/guide/automation.md) |
|
|
15
|
+
| Fix a setup problem, recover access, or review activity | [Troubleshoot and review a session](docs/guide/troubleshooting.md) |
|
|
32
16
|
|
|
33
17
|
## Quick start
|
|
34
18
|
|
|
35
19
|
### 1. Prepare both computers
|
|
36
20
|
|
|
37
|
-
|
|
21
|
+
If you already have Node.js 20.10 or later, npm, and npx, skip the installer. Otherwise, run the one-line setup command for your computer. It installs Node.js, npm, and npx when Node.js is absent and leaves existing installations in place.
|
|
38
22
|
|
|
39
23
|
**Windows:** open the Start menu, type **Windows PowerShell**, and open it. Paste:
|
|
40
24
|
|
|
@@ -48,7 +32,7 @@ curl.exe -fsSL https://diagnose.fenginwind.com/setup/setup-node.ps1 | Out-String
|
|
|
48
32
|
curl -fsSL https://diagnose.fenginwind.com/setup/setup-node.sh | bash
|
|
49
33
|
```
|
|
50
34
|
|
|
51
|
-
Wait for **Setup complete** and three version numbers. Then close the terminal and open a fresh one before continuing, so a newly installed Node.js is available. On Windows, close all terminal windows and reopen Windows PowerShell from the Start menu. On Windows, use `npx.cmd` and `npm.cmd` wherever this guide says `npx` and `npm`; this avoids PowerShell script-policy errors without changing your security settings. See [setup details and troubleshooting](#first-time-setup-install-nodejs-and-npm) if setup fails.
|
|
35
|
+
Wait for **Setup complete** and three version numbers. Then close the terminal and open a fresh one before continuing, so a newly installed Node.js is available. On Windows, close all terminal windows and reopen Windows PowerShell from the Start menu. On Windows, use `npx.cmd` and `npm.cmd` wherever this guide says `npx` and `npm`; this avoids PowerShell script-policy errors without changing your security settings. See [setup details and troubleshooting](docs/guide/on-site.md#first-time-setup-install-nodejs-and-npm) if setup fails.
|
|
52
36
|
|
|
53
37
|
Only the **diagnostician** needs an installed, signed-in Codex CLI, Claude Code, or Gemini CLI. The person receiving help needs no AI account.
|
|
54
38
|
|
|
@@ -65,57 +49,45 @@ Then run this on the on-site computer:
|
|
|
65
49
|
npx @masstensor/diagnose@latest start
|
|
66
50
|
```
|
|
67
51
|
|
|
68
|
-
If npm asks to install the package, type `y`. In v0.8+, choose the [approval mode](#
|
|
52
|
+
If npm asks to install the package, type `y`. In v0.8+, choose the [approval mode](docs/guide/on-site.md#start-the-probe) before sharing the invitation. Press Enter for review, `a` for automatic tasks and results, or `e` to also preapprove the connection. Keep this terminal open and share the nine-letter invitation privately.
|
|
69
53
|
|
|
70
|
-
### 3.
|
|
54
|
+
### 3. Choose how to start the diagnosis
|
|
71
55
|
|
|
72
|
-
|
|
56
|
+
#### Manual agent mode (recommended for your first session)
|
|
57
|
+
|
|
58
|
+
Open the agent you already use and start the diagnosis in chat. You give the agent the invitation, describe the problem, and direct follow-up checks as results come in. A device procedure is optional.
|
|
59
|
+
|
|
60
|
+
If you [installed the native Diagnose skill](docs/guide/diagnose.md#use-diagnose-as-a-native-agent-skill), invoke `/diagnose:connect` in Claude Code, `$diagnose:connect` in Codex, or ask Gemini to use the `connect` skill. You can also launch an agent with Diagnose already configured by running:
|
|
73
61
|
|
|
74
62
|
```sh
|
|
75
63
|
npx @masstensor/diagnose@latest agent codex
|
|
76
64
|
# Or replace codex with claude or gemini.
|
|
77
65
|
```
|
|
78
66
|
|
|
79
|
-
In the agent conversation, provide the code, device model, connection method, and a concrete goal
|
|
80
|
-
|
|
81
|
-
> Use Diagnose to connect to this code: abc-def-ghi . The on-site laptop is connected to an OWON SEG-X3-C gateway through its exposed USB serial interface. The gateway is online, but no plug readings are arriving. Inspect the available logs and identify the cause. Explain any proposed repair, apply only authorized changes, and check whether readings resume. If the interface does not support a required action, tell us what is needed on site.
|
|
82
|
-
|
|
83
|
-
### 4. Approve, diagnose, and finish
|
|
84
|
-
|
|
85
|
-
Unless the on-site user chose **Approve everything**, they check the diagnostician's label and connection fingerprint and approve the connection. If they selected auto approval at startup, `y` confirms it for this session and `r` connects with per-task review. Otherwise, `y` uses per-task review and `a` grants auto approval. Auto approval covers both execution **and result transmission**. Commands run with that user's OS permissions, and results can reach the diagnostician and their AI provider.
|
|
67
|
+
In the agent conversation, provide the code, device model, connection method, and a concrete goal.
|
|
86
68
|
|
|
87
|
-
|
|
69
|
+
> Use Diagnose with invitation abc-def-ghi. An OWON SEG-X3-C gateway is connected to the on-site laptop by USB serial. Plug readings have stopped. Inspect the logs, explain any proposed repair, and check whether readings resume after an authorized change.
|
|
88
70
|
|
|
89
|
-
|
|
71
|
+
#### Start automatically with a device procedure
|
|
90
72
|
|
|
91
|
-
|
|
73
|
+
Use this when you have a Markdown procedure for a device or a recurring problem. Replace `./device.md` with the path to your own file:
|
|
92
74
|
|
|
93
75
|
```sh
|
|
94
|
-
|
|
95
|
-
#
|
|
96
|
-
diagnose pair --name workshop-laptop
|
|
97
|
-
# User: explicitly approve remembering this diagnostician.
|
|
98
|
-
# Diagnostician: use this whenever diagnosis is needed again.
|
|
99
|
-
diagnose agent codex --device workshop-laptop --skill ./devices/owon.md
|
|
76
|
+
npx @masstensor/diagnose@latest agent codex --skill ./device.md
|
|
77
|
+
# Or replace codex with claude or gemini.
|
|
100
78
|
```
|
|
101
79
|
|
|
102
|
-
The
|
|
103
|
-
|
|
104
|
-
## From a reported problem to a verified result
|
|
80
|
+
The agent loads the procedure and starts working through it. If it needs an invitation, share it in the agent conversation. The same on-site permissions apply in both modes. See [how to prepare a device procedure](docs/guide/procedures.md#start-with-a-device-skill-or-markdown-task).
|
|
105
81
|
|
|
106
|
-
|
|
82
|
+
### 4. Approve, diagnose, and finish
|
|
107
83
|
|
|
108
|
-
|
|
109
|
-
2. **Investigate first.** Ask the agent to identify the available interface and tools, then inspect device logs, network responses, or other relevant evidence. Distinguish confirmed facts from possible causes.
|
|
110
|
-
3. **Review a repair plan.** Have the agent explain what it intends to change, why, the expected impact, and any recovery option. Where practical, preserve the original configuration before editing it.
|
|
111
|
-
4. **Apply authorized changes.** The agent can use commands, scripts, file edits, and device tools under the user's existing permission mode. Only proceed within the agreed scope.
|
|
112
|
-
5. **Verify the result.** Check the device itself: repeat the failing exchange, observe new readings, or run its supported health check. Ask for a summary of what changed, the verification evidence, and anything still unresolved. An executed command alone does not establish that the user's problem is fixed.
|
|
84
|
+
Unless the on-site user chose **Approve everything**, they check the diagnostician's label and connection fingerprint before approving. The probe shows which permissions each choice grants. Auto approval covers both execution and result transmission. Commands run with the user's OS permissions, and results can reach the diagnostician and their AI provider.
|
|
113
85
|
|
|
114
|
-
|
|
86
|
+
The agent reports [pairing status and the first device check](docs/guide/diagnose.md#run-a-diagnostic-session) separately. Ask it to start with a read-only check, explain what it finds, and verify the original symptom after any authorized repair. See [what the skill can do](docs/guide/diagnose.md#what-the-native-skill-can-do) and [a worked diagnosis example](docs/guide/diagnose.md#from-a-reported-problem-to-a-verified-result).
|
|
115
87
|
|
|
116
|
-
|
|
88
|
+
The user can type `permissions ask` to revoke automatic approval or `exit` to stop access. See [how to review what was collected and sent](docs/guide/troubleshooting.md#review-local-history-and-clean-up).
|
|
117
89
|
|
|
118
|
-
##
|
|
90
|
+
## Requirements
|
|
119
91
|
|
|
120
92
|
The on-site computer must have a working connection to the target device, plus any drivers, credentials, or vendor utilities needed for the intended checks. Diagnose cannot bypass a missing interface or perform physical repairs.
|
|
121
93
|
|
|
@@ -123,661 +95,4 @@ Both computers need **Node.js 20.10 or later**, npm, an interactive terminal, an
|
|
|
123
95
|
|
|
124
96
|
For an AI session, the diagnostician must separately install and sign in to Codex CLI, Claude Code, or Gemini CLI. Diagnose does not install an agent, provide a model subscription, or change the agent's approval mode.
|
|
125
97
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
Use the latest package on both endpoints. Session agent launchers require 0.3.1 or later; live resource features require 0.3 or later. macOS probes and the Linux relay have been tested. Automated CI runs the full suite on macOS/Linux and targeted history, transfer-conflict, long-session, encryption, and npm-launcher tests on Windows. Windows ConPTY, interactive authentication, and physical USB/serial behavior still need real-environment validation.
|
|
129
|
-
|
|
130
|
-
## First-time setup: install Node.js and npm
|
|
131
|
-
|
|
132
|
-
If you are the person receiving help, this is the only software setup you need. You do **not** need a Codex, Claude, Gemini, or npm account. Your diagnostician runs the AI on their own computer.
|
|
133
|
-
|
|
134
|
-
**Node.js** runs Diagnose. **npm** downloads it. **npx** starts it without requiring a separate global installation. The official Node.js installer includes npm and npx; do not download them from separate websites.
|
|
135
|
-
|
|
136
|
-
### Windows: copy and paste setup
|
|
137
|
-
|
|
138
|
-
Open the **Start** menu, type **Windows PowerShell**, and open it normally. Copy the complete block below, paste it into that window, and press Enter:
|
|
139
|
-
|
|
140
|
-
```powershell
|
|
141
|
-
curl.exe -fsSL https://diagnose.fenginwind.com/setup/setup-node.ps1 | Out-String | Invoke-Expression
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
The script detects x64 or ARM64 automatically, checks Node.js/npm/npx, and installs into your user profile only if Node.js is absent. An existing version is never upgraded or replaced. Wait for **Setup complete**, close all terminal windows, and open Windows PowerShell again from the Start menu. Then run `npx.cmd @masstensor/diagnose@latest start`. No execution-policy change or administrator terminal is required. Windows support remains experimental; this installer has not yet had Windows hardware validation.
|
|
145
|
-
|
|
146
|
-
### Mac or Linux: copy and paste setup
|
|
147
|
-
|
|
148
|
-
On a Mac, press **Command + Space**, type **Terminal**, and press Return. On Linux, open Terminal. Copy the entire block, paste it, and press Return:
|
|
149
|
-
|
|
150
|
-
```sh
|
|
151
|
-
curl -fsSL https://diagnose.fenginwind.com/setup/setup-node.sh | bash
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
Wait for **Setup complete**, then close Terminal and open it again to load the new PATH. Run `npx @masstensor/diagnose@latest start` in the new window. If Node.js is absent, the script selects Intel/x64 or ARM64 automatically. It needs curl, tar, and a SHA-256 utility, which are included on macOS and common Linux desktop distributions. Linux requires a compatible official Node.js binary; minimal, musl-based or older distributions may need help from the diagnostician.
|
|
155
|
-
|
|
156
|
-
### What setup changes
|
|
157
|
-
|
|
158
|
-
- Reuses a working Node.js **20.10+**, npm and npx without changes. If any Node.js installation exists, setup does not update it, replace it, change PATH, or repair missing npm automatically. An older or incomplete installation stops setup and explains the requirement.
|
|
159
|
-
- Only when Node.js is absent, downloads Node.js 22 binaries and SHA-256 checksums from **nodejs.org**, verifies the download, and installs under `~/.diagnose/node` on Mac/Linux or `%USERPROFILE%\.diagnose\node` on Windows.
|
|
160
|
-
- For a new installation only, configures the current user's PATH. On Mac it adds a guarded environment line to `.zshrc` and `.bash_profile`; on Linux, to `.bashrc` and `.profile`. It preserves other profile contents and avoids duplicate lines. On Windows it prepends the private runtime directory to your user PATH.
|
|
161
|
-
- Prints Node.js, npm and npx versions and stops on a download, checksum or verification error. It does not install an AI agent or start a diagnosis automatically.
|
|
162
|
-
|
|
163
|
-
You can read the [Mac/Linux script](https://diagnose.fenginwind.com/setup/setup-node.sh), [Windows script](https://diagnose.fenginwind.com/setup/setup-node.ps1), or [their source on GitHub](https://github.com/zkwasm/diagnose/tree/main/scripts) before running setup. The installer needs internet access to this website and nodejs.org. If installation is blocked by an organization policy, ask your diagnostician or IT administrator for help.
|
|
164
|
-
|
|
165
|
-
### Check the installation
|
|
166
|
-
|
|
167
|
-
The setup script performs these checks automatically. To check again in Terminal or Windows Command Prompt, paste one line at a time (in PowerShell use `npm.cmd` and `npx.cmd`):
|
|
168
|
-
|
|
169
|
-
```sh
|
|
170
|
-
node --version
|
|
171
|
-
npm --version
|
|
172
|
-
npx --version
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
Each command should print a version number. The Node.js number begins with `v` and must be **20.10.0 or later**. npm and npx have their own version numbers; they do not need to match Node.js. If your installed Node.js already meets the requirement, you do not need to reinstall it.
|
|
176
|
-
|
|
177
|
-
You are now ready. Paste this single command into the same window and press Enter/Return:
|
|
178
|
-
|
|
179
|
-
```sh
|
|
180
|
-
npx @masstensor/diagnose@latest start
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
The first run downloads Diagnose and may take a little time. If npm asks whether to install `@masstensor/diagnose`, type `y` and press Enter. You do not need to run `npm login` or create an npm account. When the pairing code appears, installation is complete: keep the window open and send the code privately to your diagnostician. Continue with [Start on the user's computer](#2-start-on-the-users-computer) for the connection and approval details.
|
|
184
|
-
|
|
185
|
-
Copy only the command, not a leading dollar-sign prompt, the surrounding code-box marks, or example output. On a Mac, stopping the probe is **Control + C**, not Command + C.
|
|
186
|
-
|
|
187
|
-
### If something goes wrong
|
|
188
|
-
|
|
189
|
-
| What you see | What to do |
|
|
190
|
-
| --- | --- |
|
|
191
|
-
| “node is not recognized” or “command not found” | Close and reopen Command Prompt/Terminal, then try again. If it still fails, run the setup block above again, or ask your diagnostician for help. |
|
|
192
|
-
| An older Node.js version | Setup leaves it unchanged. Share the detected version with your diagnostician; a separate runtime can be considered with your agreement. |
|
|
193
|
-
| npm or npx is missing | Setup leaves the existing Node.js unchanged. Ask your diagnostician to repair npm/npx or discuss a separate runtime. |
|
|
194
|
-
| PowerShell says `npm.ps1` or `npx.ps1` cannot run because scripts are disabled | Open **Command Prompt (cmd)** and run the same commands there. You do not need to change PowerShell's execution policy. |
|
|
195
|
-
| “EACCES”, “EPERM”, or “permission denied” during a global install | Use the `npx … start` command above instead of `npm install -g`. If that also fails, share the error with your diagnostician; do not add `sudo` or change folder permissions at random. |
|
|
196
|
-
| A download, certificate, or network error | Check your internet connection and ask your diagnostician or IT administrator for help. Do not disable certificate checks or your firewall. |
|
|
197
|
-
| A build/driver error, or the device is not listed | Share the error with the diagnostician. Node.js installation does not install every device's USB or serial driver. |
|
|
198
|
-
|
|
199
|
-
Official references: [Node.js downloads](https://nodejs.org/en/download) and [npm's Node.js/npm installation guide](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/).
|
|
200
|
-
|
|
201
|
-
## 2. Start on the user's computer
|
|
202
|
-
|
|
203
|
-
```sh
|
|
204
|
-
npx @masstensor/diagnose@latest start
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
Or install once:
|
|
208
|
-
|
|
209
|
-
```sh
|
|
210
|
-
npm install -g @masstensor/diagnose@latest
|
|
211
|
-
diagnose start
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
With v0.8+, a probe starting a new pairing asks which approval mode to use before displaying its invitation.
|
|
215
|
-
|
|
216
|
-
| Startup choice | What it allows |
|
|
217
|
-
| --- | --- |
|
|
218
|
-
| Enter | Confirm the connection and review each task and result transfer. |
|
|
219
|
-
| `a` · Auto tasks only | Confirm the connection once. Tasks and result transfers then proceed automatically. |
|
|
220
|
-
| `e` · Approve everything | Let the holder of this one-time invitation connect automatically, run tasks, and receive results for the temporary session. |
|
|
221
|
-
|
|
222
|
-
Share an **Approve everything** invitation only with the intended diagnostician. Type `permissions ask` to cancel that choice before pairing or revoke auto approval after pairing. The next invitation does not inherit it. Requests to remember a diagnostician still require confirmation.
|
|
223
|
-
|
|
224
|
-
With v0.7+, the terminal shows a **nine-letter invitation**, such as `abc-def-ghi`, and the audit log path. Keep it open. Share the code privately by message or read it aloud. It lasts **30 minutes** and is consumed by successful pairing. Case, spaces and hyphens do not matter when entering it. Treat the code as a secret; do not post it publicly or put it in shell arguments. After expiry or five attempted handshakes, the running probe generates a new code.
|
|
225
|
-
|
|
226
|
-
The probe will show the connecting party's self-reported label and the session fingerprint. Check these with the intended diagnostician before accepting. A code proves possession of the secret, not a person's identity.
|
|
227
|
-
|
|
228
|
-
## 3. Start the diagnostician's agent
|
|
229
|
-
|
|
230
|
-
Choose one:
|
|
231
|
-
|
|
232
|
-
```sh
|
|
233
|
-
npx @masstensor/diagnose@latest agent codex
|
|
234
|
-
npx @masstensor/diagnose@latest agent claude
|
|
235
|
-
npx @masstensor/diagnose@latest agent gemini
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
With a global installation, these become:
|
|
239
|
-
|
|
240
|
-
```sh
|
|
241
|
-
diagnose agent codex
|
|
242
|
-
diagnose agent claude
|
|
243
|
-
diagnose agent gemini
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
Do **not** separately run `diagnose mcp` or register a global MCP server. The launcher starts your chosen CLI with Diagnose MCP loaded for this launch, using the exact installed Diagnose version.
|
|
247
|
-
|
|
248
|
-
Then tell the agent what to inspect and provide the pairing code in the agent conversation. For example:
|
|
249
|
-
|
|
250
|
-
> Use Diagnose to connect to pairing code abc-def-ghi . Help resolve the user's application startup failure. First investigate without changing anything. Explain the cause, proposed fix, and risks. Apply only authorized changes, then check whether the application starts successfully. Summarize what changed and anything still unresolved.
|
|
251
|
-
|
|
252
|
-
The code and diagnostic results enter your chosen AI provider's context. The user must still accept the connection on their own computer. Ask the agent to use the `diagnose_*` tools for remote actions: its normal shell and file tools still act on the diagnostician's computer.
|
|
253
|
-
|
|
254
|
-
### Keep a device paired for future diagnosis
|
|
255
|
-
|
|
256
|
-
Requires **0.5.0+ on both computers**. Use this when the same diagnostician will return later. The user starts the probe as usual and shares the temporary code privately. On the diagnostician's computer, pair once:
|
|
257
|
-
|
|
258
|
-
```sh
|
|
259
|
-
diagnose pair --name workshop-laptop
|
|
260
|
-
# Enter the user's code, then your label and AI provider when prompted.
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
The user's terminal explicitly asks whether to **remember** this diagnostician. Check the label and fingerprint with each other before agreeing. Choose `y` to remember the relationship with per-task approval, or `a` to also grant automatic execution **and transmission for one hour**. The invitation is replaced by a new random private credential exchanged only inside the approved encrypted connection. Neither side prints that credential or sends it in process arguments. Each later connection has a fresh Noise handshake and encryption keys.
|
|
264
|
-
|
|
265
|
-
After pairing, the diagnostician can start, stop, and restart any supported agent using the same device name:
|
|
266
|
-
|
|
267
|
-
```sh
|
|
268
|
-
diagnose agent codex --device workshop-laptop --skill ./devices/owon.md
|
|
269
|
-
diagnose agent claude --device workshop-laptop --skill ./devices/owon.md
|
|
270
|
-
diagnose agent gemini --device workshop-laptop --skill ./devices/owon.md
|
|
271
|
-
# --skill is optional.
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
Tell the agent what problem to resolve and to use Diagnose. The MCP tools connect to the saved device when first used; no pairing code is needed. The device name identifies the user's computer, not a particular USB device. The selected task can identify the actual device to investigate. Each agent still uses its own login and local tool permissions.
|
|
275
|
-
|
|
276
|
-
Keep `diagnose start` running on the user's computer. It re-registers with the relay after a dropped connection. If it is stopped or the computer restarts, run `diagnose start` again: the pairing and its saved permission expiry remain. This release does not install a background service or start at login. One probe accepts one remembered diagnostician at a time; a diagnostician can save multiple user computers. Use local `unpair` before pairing a different diagnostician.
|
|
277
|
-
|
|
278
|
-
**Remembering is separate from automatic approval.** The default is still per-task approval. In the user's running probe terminal:
|
|
279
|
-
|
|
280
|
-
| Command | Effect |
|
|
281
|
-
| --- | --- |
|
|
282
|
-
| `pairing` | Show the remembered diagnostician and automatic grant expiry. |
|
|
283
|
-
| `permissions auto`, then `permissions allow-auto` | Grant one hour of automatic execution and transmission, across reconnects and restarts. |
|
|
284
|
-
| `permissions auto forever`, then `permissions allow-auto` | Explicitly grant automatic execution and transmission until revoked locally. |
|
|
285
|
-
| `permissions ask` | Revoke automatic permission, cancel work/resources, keep the pairing. |
|
|
286
|
-
| `pause` | Disconnect and block access while retaining the pairing and its original grant expiry. |
|
|
287
|
-
| `resume` | Allow connections again. An expired grant does not become valid again. |
|
|
288
|
-
| `unpair` | Revoke the private credential, cancel work/resources, and return to a new invitation. |
|
|
289
|
-
| `exit` or `Ctrl+C` | Stop access and close resources. Remembered pairing remains for the next start. |
|
|
290
|
-
|
|
291
|
-
Time disconnected counts toward a timed grant. Restarting an agent, probe, or relay does not renew it. Pausing does not extend it. The remote agent cannot change this policy. A continuously authorized diagnostician still has the user's OS permissions; results may reach their AI provider.
|
|
292
|
-
|
|
293
|
-
On the diagnostician's computer:
|
|
294
|
-
|
|
295
|
-
```sh
|
|
296
|
-
diagnose devices
|
|
297
|
-
diagnose connect --device workshop-laptop
|
|
298
|
-
diagnose terminal --device workshop-laptop
|
|
299
|
-
diagnose mcp --device workshop-laptop
|
|
300
|
-
diagnose forget --device workshop-laptop
|
|
301
|
-
```
|
|
302
|
-
|
|
303
|
-
`devices` lists local pairings, not live online status. `forget` removes only the diagnostician's local copy. To invalidate a credential, the user must run `unpair` in their probe terminal. If initial pairing is interrupted before the diagnostician saves it, use `unpair` and pair again. Losing local pairing files requires pairing again.
|
|
304
|
-
|
|
305
|
-
A new MCP operation will reconnect to a remembered device for up to 30 seconds if needed. **No already-sent command, input, upload commit, or other modification is automatically retried.** An interrupted task can have an uncertain outcome; inspect state before retrying. Old task IDs are not carried into a new connection. Retained resources require their original resource ID, recovery credential, and authorization; see [Disconnect and recover](#6-disconnect-and-recover).
|
|
306
|
-
|
|
307
|
-
## Record a device diagnosis and improve your procedures
|
|
308
|
-
|
|
309
|
-
These knowledge features require Diagnose 0.6.0 or later on the diagnostician computer. Older probes can still perform their supported operations.
|
|
310
|
-
|
|
311
|
-
The paired computer is a bridge. Create a **case** for the actual gateway, controller or other target. Tell your agent: “Create a diagnosis case for this device, collect evidence, verify any authorized repair, and propose a reusable skill or an improvement to the selected skill.” The agent uses `diagnose_case`, `diagnose_capabilities` and `diagnose_skill_draft`; no agent-specific syntax is needed.
|
|
312
|
-
|
|
313
|
-
A case records the goal, target model/identity/interface, optional paired computer and pinned skill reference. Subsequent received task results, resource interactions and connection events are saved locally with encryption. Data is not sent to library storage. Redaction is best effort. Case evidence is untrusted data, never permission or instructions. File transfers and tunnels are not a full byte-for-byte evidence archive; ordinary task/resource events capture their control operations, not every transferred byte. Arbitrary scripts are not a filesystem change monitor.
|
|
314
|
-
|
|
315
|
-
To create a case before launching, save a small JSON file:
|
|
316
|
-
|
|
317
|
-
```json
|
|
318
|
-
{
|
|
319
|
-
"goal": "Find why the gateway stopped reporting sensor readings",
|
|
320
|
-
"host": "workshop-laptop",
|
|
321
|
-
"target": { "name": "Workshop gateway", "model": "SEG-X3-C", "interface": "serial" }
|
|
322
|
-
}
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
```sh
|
|
326
|
-
diagnose cases create ./gateway-case.json
|
|
327
|
-
diagnose cases list
|
|
328
|
-
diagnose agent codex --device workshop-laptop --case CASE_ID
|
|
329
|
-
```
|
|
330
|
-
|
|
331
|
-
Replace `CASE_ID` with the printed UUID. Use `claude` or `gemini` in the same command. Include a `skill` field containing a complete `library:NAME@REVISION` reference to pin a procedure; the launcher loads it automatically. A different explicit skill or paired computer is rejected. Reusing a case does not replay old commands; existing remembered-pairing rules apply. Check device availability again after reconnecting.
|
|
332
|
-
|
|
333
|
-
For Markdown startup tasks, the agent is instructed to create a case before operating. The agent must actually call the tool; launching is not proof that a case was created. Only one MCP session can write a selected case at a time. After an unclean termination, use `diagnose cases unlock CASE_ID`; it refuses to unlock while the recorded writer process is alive. Cases are optional for ordinary MCP operations. In a selected case, only results actually received by the diagnostician are recorded.
|
|
334
|
-
|
|
335
|
-
```sh
|
|
336
|
-
diagnose cases show CASE_ID
|
|
337
|
-
diagnose cases export CASE_ID > reviewed-report.json
|
|
338
|
-
diagnose cases remove CASE_ID
|
|
339
|
-
```
|
|
340
|
-
|
|
341
|
-
Export omits raw results, command arguments and target addresses. Review free-text summaries for sensitive details before sharing. Cases retain at most 200 evidence records each (32 KiB per record; larger values are marked as previews), with at most 100 local cases. Limits are reported, not silently interpreted as a complete investigation. Remove old cases explicitly; `diagnose cleanup` does not delete cases or skills.
|
|
342
|
-
|
|
343
|
-
An agent can report **resolved**, **unresolved**, **needs physical work**, or **insufficient evidence**. Resolved requires baseline and later successful verification evidence IDs from the same case. This proves the cited evidence exists; it does not automatically prove the agent interpreted it correctly. A successful command is not necessarily a healthy device. Connection status distinguishes confirmed relay/probe connectivity from evidence-linked agent assessments of the device interface and response; untested layers remain unknown.
|
|
344
|
-
|
|
345
|
-
### Review a new skill or improvement
|
|
346
|
-
|
|
347
|
-
The agent proposes a structured draft with applicability, prerequisites, identity checks, read-only checks, repair authorization conditions, recovery, verification and failed approaches. Improvements must refer to the exact library version selected in the case. Reference files and scripts from that base are retained unchanged. Raw logs are not automatically copied. For changes to supporting scripts/resources, edit a separate source directory, review it and import a new version.
|
|
348
|
-
|
|
349
|
-
```sh
|
|
350
|
-
diagnose drafts list
|
|
351
|
-
diagnose drafts review DRAFT_ID
|
|
352
|
-
diagnose drafts accept DRAFT_ID
|
|
353
|
-
# Or keep the existing procedure:
|
|
354
|
-
diagnose drafts reject DRAFT_ID
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
Acceptance displays the full before/after entry and evidence references and asks you to confirm in an interactive terminal. The agent has no acceptance MCP tool. Confirm the evidence supports the procedure and remove customer-specific values. Potential-secret warnings assist review; they are not a guarantee. A case result or device log cannot itself authorize an instruction. Accepted drafts become new pinned library versions; older versions remain available.
|
|
358
|
-
|
|
359
|
-
If another version appeared since drafting, acceptance stops and preserves the draft. Ask the agent to reconcile against the version you select, using the original evidence. `diagnose drafts show DRAFT_ID` shows structured input for editing; `diagnose drafts create INPUT.json` creates another proposal. `diagnose drafts remove DRAFT_ID` removes a local draft record after confirmation. At most 100 draft records are retained; removal never removes an imported version.
|
|
360
|
-
|
|
361
|
-
### Share your private skill library across computers
|
|
362
|
-
|
|
363
|
-
Library sharing is optional and independent of device pairing. Initialize it on the diagnostician computer and save the recovery file somewhere private that you can back up:
|
|
364
|
-
|
|
365
|
-
```sh
|
|
366
|
-
diagnose vault init ./diagnose-library-recovery.txt
|
|
367
|
-
diagnose vault push library:NAME@FULL_REVISION
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
Push asks you to confirm publication of the complete bundle. Every file in the imported directory is included. The client encrypts the name, instructions, references, scripts and provenance before uploading. The relay sees opaque IDs, sizes and traffic metadata. Cases, drafts and raw diagnosis logs are not synced automatically. Instructions read by an AI agent can still be sent to its provider.
|
|
371
|
-
|
|
372
|
-
On a second diagnostician computer, securely transfer the recovery file yourself (never through an AI prompt) and run:
|
|
373
|
-
|
|
374
|
-
```sh
|
|
375
|
-
diagnose vault restore ./diagnose-library-recovery.txt
|
|
376
|
-
diagnose vault pull
|
|
377
|
-
diagnose skills list
|
|
378
|
-
diagnose agent claude --skill library:NAME@FULL_REVISION
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
Pull verifies and caches complete versions but does not execute or select them. Divergent versions coexist. Cached skills work offline; connecting to a remote probe still needs connectivity. A duplicate concurrent push may report 409; rerun push to verify that version, without rerunning diagnosis. Library sync does not transfer paired-computer credentials.
|
|
382
|
-
|
|
383
|
-
```sh
|
|
384
|
-
diagnose vault status
|
|
385
|
-
diagnose vault backup ./another-private-recovery-copy.txt
|
|
386
|
-
diagnose vault revoke
|
|
387
|
-
diagnose vault forget
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
**Protect the recovery file like a password.** It grants full library access. Losing every copy means server-only data cannot be decrypted. The local copy lives at `~/.diagnose/vault/recovery`; private permissions are applied where supported. Do not commit it to Git. Backup refuses to overwrite an existing file. If initialization succeeds but backup fails, use `vault backup` with a new path.
|
|
391
|
-
|
|
392
|
-
Revoke permanently deletes that relay library and blocks its credential on that relay; local copies remain. Forget removes only the local recovery credential. To rotate access, cache wanted versions, revoke the old library, forget locally, initialize a new key, and explicitly push selected versions. Restore the new recovery file only on trusted computers. Previously downloaded data cannot be recalled. Use `--relay https://your-relay.example` consistently for a self-hosted library. Its operator must enable `VAULT_PATH`; the default public relay supports this API in v0.6.
|
|
393
|
-
|
|
394
|
-
Limits are 128 versions / 128 MiB per relay library and 12 MiB per encrypted object. The relay is not your only backup. See [knowledge security and operations](https://github.com/zkwasm/diagnose/blob/main/KNOWLEDGE_SECURITY.md) for formats, limits, retention, threat model and deployment details.
|
|
395
|
-
|
|
396
|
-
## Start with a device skill or Markdown task
|
|
397
|
-
|
|
398
|
-
Version **0.4.0+** can start the agent with a selected diagnostic procedure. The syntax is identical for all three agents:
|
|
399
|
-
|
|
400
|
-
```sh
|
|
401
|
-
diagnose agent codex --skill ./devices/owon.md
|
|
402
|
-
diagnose agent claude --skill ./devices/owon.md
|
|
403
|
-
diagnose agent gemini --skill ./devices/owon.md
|
|
404
|
-
```
|
|
405
|
-
|
|
406
|
-
Use a local UTF-8 `.md` or `.markdown` file, up to 256 KiB. A directory containing `SKILL.md` also works:
|
|
407
|
-
|
|
408
|
-
```sh
|
|
409
|
-
diagnose agent codex --skill ./skills/my-device
|
|
410
|
-
```
|
|
411
|
-
|
|
412
|
-
For example:
|
|
413
|
-
|
|
414
|
-
```text
|
|
415
|
-
skills/my-device/
|
|
416
|
-
SKILL.md
|
|
417
|
-
references/device-profile.md
|
|
418
|
-
scripts/check-device.js
|
|
419
|
-
```
|
|
420
|
-
|
|
421
|
-
The launcher reads and validates the entry before starting the agent, saves a private `0600` session snapshot with its source path, reference directory, and SHA-256, and supplies an initial task to read that snapshot and begin. The instruction text is not placed in process arguments. The adapter adds only the private task subdirectory to the agent's session working directories so its file tools can read the snapshot. Gemini's temporary settings and login links are outside that task subdirectory. The original skill directory is not automatically added; reading its references may still require the agent's normal local permission. The snapshot is removed when the launcher exits normally or handles termination. An uncatchable kill or power loss can leave temporary files behind.
|
|
422
|
-
|
|
423
|
-
The agent follows the entry, reads references as needed, and works toward diagnosis, authorized repair, and verification. If a pairing code, target identity, or necessary detail is missing, it asks before continuing. Do not store pairing codes, credentials, or other secrets in reusable task files; selected instructions and referenced material that the agent reads can enter the AI provider's context.
|
|
424
|
-
|
|
425
|
-
Relative references resolve against the original entry directory, not the temporary snapshot. Keep that directory available during the session. Only the entry is snapshotted; referenced files are read from the original directory. Scripts are not executed by the launcher merely because they exist. The agent runs them only as required by the task and existing permissions.
|
|
426
|
-
|
|
427
|
-
Referenced scripts initially live on the diagnostician computer. To use one remotely, the agent must explicitly submit its contents or transfer it to the user's computer with authorization. A path on one endpoint is not automatically a path on the other.
|
|
428
|
-
|
|
429
|
-
### Writing a reusable procedure
|
|
430
|
-
|
|
431
|
-
Describe:
|
|
432
|
-
|
|
433
|
-
- The supported device or problem and the desired verification check.
|
|
434
|
-
- How to identify the target, and what missing information to ask for.
|
|
435
|
-
- Read-only evidence to collect and how to interpret it.
|
|
436
|
-
- Permitted repairs, their impact, prohibited actions, and available recovery steps.
|
|
437
|
-
- How to verify the original problem and report unresolved issues.
|
|
438
|
-
|
|
439
|
-
A minimal task could be:
|
|
440
|
-
|
|
441
|
-
```markdown
|
|
442
|
-
# Local service troubleshooting
|
|
443
|
-
|
|
444
|
-
Start now using Diagnose MCP. Ask for the pairing code and target service
|
|
445
|
-
if missing. Pair and wait for local consent. Inspect logs and configuration
|
|
446
|
-
without changing them first. Explain the likely cause and repair plan.
|
|
447
|
-
Apply only authorized changes, repeat the original failing check, and
|
|
448
|
-
report what changed, the evidence, and anything unresolved.
|
|
449
|
-
```
|
|
450
|
-
|
|
451
|
-
The package includes `examples/skills/owon.md` and `examples/skills/device-troubleshooting/SKILL.md` with a referenced profile template. They are templates, not verified universal repair recipes. Customize them for the actual device and authorization scope. [Browse or download the examples](https://github.com/zkwasm/diagnose/tree/main/examples/skills).
|
|
452
|
-
|
|
453
|
-
### Local versioned library (v0.6+)
|
|
454
|
-
|
|
455
|
-
The local library requires Diagnose 0.6.0 or later.
|
|
456
|
-
|
|
457
|
-
Import a reviewed skill directory once, then use the exact reference printed by the command:
|
|
458
|
-
|
|
459
|
-
```sh
|
|
460
|
-
diagnose skills import owon ./examples/skills/device-troubleshooting
|
|
461
|
-
diagnose skills list
|
|
462
|
-
diagnose agent codex --device workshop-laptop --skill library:owon@FULL_SHA256_FROM_IMPORT
|
|
463
|
-
```
|
|
464
|
-
|
|
465
|
-
Replace `FULL_SHA256_FROM_IMPORT` with the complete digest printed by import, or copy the complete `library:...` reference. The same `--skill` argument works with Claude and Gemini. It pins the complete bundle, including references and scripts. Changing any file creates a different version; older versions remain available and there is no implicit “latest” version. Importing identical contents again reuses the same version. Stored contents are verified before launch. Permission bits are not part of the portable content digest.
|
|
466
|
-
|
|
467
|
-
You can also import a single Markdown file; it becomes `SKILL.md` without copying neighboring files. Use a dedicated directory when the procedure needs references or scripts. Directory imports include all files: review the directory for credentials, customer logs and unrelated files first. Symbolic links, special files, non-portable names, case-colliding paths, more than 128 files, more than 256 directory entries, nesting beyond 16 levels, and bundles over 8 MiB are rejected. The entry retains the 256 KiB Markdown limit. Importing does not execute scripts.
|
|
468
|
-
|
|
469
|
-
The library lives in `~/.diagnose/skills` with private permissions where supported. It is local plaintext, not an encrypted backup; protect it like your other local source files. Do not edit stored versions directly. Edit the original source and import again. Reading or executing the skill still uses your agent's normal permissions and may send its contents to the AI provider.
|
|
470
|
-
|
|
471
|
-
Import/list commands are local. See the diagnosis case and private library sections for reviewed drafts and optional encrypted synchronization.
|
|
472
|
-
|
|
473
|
-
### Permissions and compatibility
|
|
474
|
-
|
|
475
|
-
The task starts automatically; permissions do not change automatically. Remote pairing and local user consent still apply. For continuous execution and transmission, the user can explicitly choose session auto mode. The coding agent's own tool approvals may still appear; Diagnose does not bypass them.
|
|
476
|
-
|
|
477
|
-
This is portable Markdown task loading, not native installation of a Codex, Claude, or Gemini skill. Frontmatter can remain in the file as text. Vendor-specific hooks, tool names, scripts, and dependencies are not automatically translated or installed. Use `diagnose_*` names for remote tools and adapt any agent-specific instructions.
|
|
478
|
-
|
|
479
|
-
With `--skill`, use native startup flags such as `--model` after `--`; do not also supply a separate prompt, headless prompt option, resume command, or another CLI subcommand. Gemini explicitly rejects a second prompt option. Use the normal launcher without `--skill` for those other modes.
|
|
480
|
-
|
|
481
|
-
### Short invitation compatibility
|
|
482
|
-
|
|
483
|
-
Nine-letter invitations require **0.7.0+ on both computers** and an updated relay. The latest client also accepts legacy `D1` codes from older probes. Existing remembered pairings keep working without a new code. The 30-minute invitation deadline is separate from diagnostic session idle/total timeouts, which begin after pairing. Knowledge-library recovery files remain long private credentials; do not shorten them or use them as pairing codes.
|
|
484
|
-
|
|
485
|
-
### Session configuration and extra arguments
|
|
486
|
-
|
|
487
|
-
```sh
|
|
488
|
-
diagnose agent codex --relay https://your-relay.example -- --model your-model
|
|
489
|
-
```
|
|
490
|
-
|
|
491
|
-
Options before `--` belong to Diagnose. Everything after it is passed literally to the agent, without a shell. Do not put pairing codes, passwords, or recovery credentials in these arguments.
|
|
492
|
-
|
|
493
|
-
- **Codex:** receives temporary `-c` MCP overrides.
|
|
494
|
-
- **Claude Code:** receives a temporary `--mcp-config` value.
|
|
495
|
-
- **Gemini CLI:** uses a private temporary user configuration directory. Diagnose copies the user settings, adds its MCP entry, and links existing login/history files. Administrator policies and workspace trust checks remain in effect. On Windows, directories use junctions and login files are copied into the private temporary directory, avoiding administrator-only file symlinks. Sign in with the native Gemini CLI first; changes to copied login files in this session are not saved back. The directory is removed on normal exit; changes to user settings in this Gemini session are not written back to the original `settings.json`.
|
|
496
|
-
|
|
497
|
-
The launcher does not add a permanent MCP entry. Other MCP servers already configured in your agent may still load. If you previously registered Diagnose globally, remove that entry separately if you no longer want it in ordinary sessions. An uncatchable kill or power loss may leave a temporary directory behind.
|
|
498
|
-
|
|
499
|
-
## 4. Choose permissions on the user's computer
|
|
500
|
-
|
|
501
|
-
At the connection prompt:
|
|
502
|
-
|
|
503
|
-
| Choice | Effect |
|
|
504
|
-
| --- | --- |
|
|
505
|
-
| `y` | Approve the session, then review each operation or batch and its result transmission. |
|
|
506
|
-
| `a` | Authorize automatic execution **and automatic transmission** for this temporary session. Subsequent tasks do not prompt again. |
|
|
507
|
-
| `N` or Enter | Refuse the connection. |
|
|
508
|
-
|
|
509
|
-
In manual mode, a batch has one execution approval and one combined result approval, rather than one prompt per step. Complete scripts are approved as a whole, not line by line.
|
|
510
|
-
|
|
511
|
-
Opening a live process, file transfer, or network tunnel asks for permission to its **continuing raw input/output before the resource is created**. Once granted, input, reads, resizing, signals, and connections within that handle's scope do not prompt again.
|
|
512
|
-
|
|
513
|
-
Automatic mode is powerful: commands run with the user's OS permissions and results go directly to the diagnostician and their AI. The probe is not a sandbox. Arbitrary programs can have side effects that Diagnose cannot fully observe or undo.
|
|
514
|
-
|
|
515
|
-
### Local session controls
|
|
516
|
-
|
|
517
|
-
Type these into the user's probe terminal:
|
|
518
|
-
|
|
519
|
-
| Command | Effect |
|
|
520
|
-
| --- | --- |
|
|
521
|
-
| `permissions` | Show the current mode. |
|
|
522
|
-
| `permissions ask` | Revoke automatic approval, cancel active work and resources, and require approval again. |
|
|
523
|
-
| `permissions auto` | Show the automatic execution/transmission explanation. |
|
|
524
|
-
| `permissions allow-auto` | Confirm the preceding request within 60 seconds. |
|
|
525
|
-
| `jobs` | List locally known resources. |
|
|
526
|
-
| `recover <resource-id>` | Rotate a resource's recovery credential; share the new value privately. |
|
|
527
|
-
| `secret <resource-id>` | Send hidden local input directly to an approved live process on macOS/Linux. A program may still echo it into output. |
|
|
528
|
-
| `cancel` | Cancel current work and retained resources without changing the permission mode. |
|
|
529
|
-
| `exit` or `Ctrl+C` | End the probe and close its resources. |
|
|
530
|
-
|
|
531
|
-
Only the user can enable automatic mode. Remote requests cannot switch it on. New pairings start with manual approval unless the user explicitly chooses `a` again. Already transmitted data cannot be recalled. Completed changes are not automatically rolled back.
|
|
532
|
-
|
|
533
|
-
Do not ask the AI to collect OS passwords. For interactive authentication, the user can use local hidden input with a trusted foreground program; Diagnose does not automatically elevate privileges. Hidden input has not been validated on Windows. On macOS/Linux, ordinary descendants in a managed process group are terminated when its leader exits or the resource is closed. This is not OS sandbox containment: a deliberately detached daemon can escape that group; Windows process-tree termination still requires real-device validation.
|
|
534
|
-
|
|
535
|
-
## 5. What the agent can do
|
|
536
|
-
|
|
537
|
-
The MCP interface provides 15 tools:
|
|
538
|
-
|
|
539
|
-
| Tool | Purpose |
|
|
540
|
-
| --- | --- |
|
|
541
|
-
| `diagnose_pair` | Connect using the complete code and a self-reported diagnostician/AI-provider label. |
|
|
542
|
-
| `diagnose_start` | Submit one operation and receive its task ID. |
|
|
543
|
-
| `diagnose_batch` | Submit up to 32 finite operations as one sequential plan. |
|
|
544
|
-
| `diagnose_wait` | Poll a task for up to 25 seconds; release completed output when finished. |
|
|
545
|
-
| `diagnose_cancel` | Cancel a task, including one awaiting approval. |
|
|
546
|
-
| `diagnose_process` | Open a live process or persistent PTY with cwd/env, stdin, signals, and resizing. |
|
|
547
|
-
| `diagnose_resource` | List, inspect, read, input to, resize, signal, or close an authorized handle. |
|
|
548
|
-
| `diagnose_resume` | Request attachment to an existing resource with its ID and recovery credential. |
|
|
549
|
-
| `diagnose_transfer` | Upload/download files in the background; query progress or cancel. |
|
|
550
|
-
| `diagnose_forward` | Open, inspect, or close a local endpoint for an authorized TCP forward. |
|
|
551
|
-
| `diagnose_disconnect` | Disconnect the diagnostic session. |
|
|
552
|
-
| `diagnose_capabilities` | Query operation schemas and conservative discovery guidance. |
|
|
553
|
-
| `diagnose_case` | Create/show a case, record assessments, report connection layers and finish with evidence references. |
|
|
554
|
-
| `diagnose_skill_draft` | Propose a new skill or improvement for local human review. |
|
|
555
|
-
| `diagnose_skills` | List or read locally available pinned skill versions without executing them. |
|
|
556
|
-
|
|
557
|
-
A task returning `ok` for `process.open` means the process handle was created. Inspect its output, `ended`, and `exitCode` to determine whether the actual program succeeded. Diagnostic output is untrusted data, not instructions to the AI.
|
|
558
|
-
|
|
559
|
-
### Finite commands, scripts, and batches
|
|
560
|
-
|
|
561
|
-
`process.run` spawns an explicit executable and argument array without implicitly adding a shell. `process.script` passes a complete script to an explicit interpreter's stdin. Scripts need not be written to temporary files.
|
|
562
|
-
|
|
563
|
-
A batch runs sequentially, stops on error by default, and cannot contain nested batches or persistent resource creation. Set `stopOnError:false` only when later steps are independent. Outputs are named by step, for example `0.stdout` and `1.file`.
|
|
564
|
-
|
|
565
|
-
```json
|
|
566
|
-
{
|
|
567
|
-
"operation": "batch.run",
|
|
568
|
-
"reason": "Collect system and runtime information in one approved plan",
|
|
569
|
-
"arguments": {
|
|
570
|
-
"steps": [
|
|
571
|
-
{"operation":"system.inspect","arguments":{}},
|
|
572
|
-
{"operation":"process.script","arguments":{"interpreter":"node","script":"const os = require('node:os');\nconsole.log(JSON.stringify({uptime: os.uptime(), freeMemory: os.freemem()}));","timeoutMs":10000}}
|
|
573
|
-
],
|
|
574
|
-
"stopOnError": true,
|
|
575
|
-
"timeoutMs": 60000
|
|
576
|
-
}
|
|
577
|
-
}
|
|
578
|
-
```
|
|
579
|
-
|
|
580
|
-
A batch's text-file writes are previewed and hashed before approval. If an earlier step changes the same target, a later guarded write is refused instead of silently overwriting the new state.
|
|
581
|
-
|
|
582
|
-
### Live processes and native terminals
|
|
583
|
-
|
|
584
|
-
```sh
|
|
585
|
-
diagnose terminal
|
|
586
|
-
```
|
|
587
|
-
|
|
588
|
-
Enter the pairing code and label interactively. After local approval, you get a real PTY. Shell cwd and environment persist within that process. `Ctrl+C` goes to the remote terminal; `Ctrl+]` detaches. A process is closed on disconnect unless explicitly retained.
|
|
589
|
-
|
|
590
|
-
Agents use `diagnose_process` for the same live capabilities. Non-PTY processes preserve stdout/stderr separately and support exact byte input. PTYs behave as terminals, not general binary transports.
|
|
591
|
-
|
|
592
|
-
### Files
|
|
593
|
-
|
|
594
|
-
`file.read` returns a bounded range of up to 1 MiB. `file.write` previews text and checks the previous hash before replacing a target. File listing, stat, mkdir, removal, rename, and chmod are available; rename refuses an existing destination unless overwrite is explicit. File transfers preserve existing destination permission bits. New transfer destinations are committed without replacing a concurrently created file; downloads with overwrite enabled reject a destination changed during transfer. Existing-file replacement checks the target immediately before commit, but does not lock out unrelated local writers.
|
|
595
|
-
|
|
596
|
-
Use `diagnose_transfer` for large or binary files. It takes paths rather than placing base64 file contents into the AI context. `localPath` refers to the diagnostician's computer; `remotePath` refers to the user's computer.
|
|
597
|
-
|
|
598
|
-
Uploads use a private staging file. Exact size, SHA-256, destination hash, and parent-directory checks must pass before replacement. Downloads use `.diagnose.part` plus a private `.diagnose.json` recovery sidecar. A completed download is verified before replacement. Overwriting an existing destination must be explicit. Raw file bytes are not redacted.
|
|
599
|
-
|
|
600
|
-
### TCP forwarding
|
|
601
|
-
|
|
602
|
-
First authorize `net.forward`, wait for its resource ID, then use `diagnose_forward` to open the corresponding endpoint.
|
|
603
|
-
|
|
604
|
-
- `local`: a loopback listener on the diagnostician's computer reaches a fixed target accessible from the user's computer.
|
|
605
|
-
- `remote`: a loopback listener on the user's computer forwards to a declared target on the diagnostician's side.
|
|
606
|
-
- `socks`: a SOCKS5 TCP listener on the diagnostician's loopback interface reaches targets from the user's side, restricted by `allowedHosts`.
|
|
607
|
-
|
|
608
|
-
SOCKS defaults to `allowedHosts:["*"]`, which permits any target. Narrow it when possible. Listeners are loopback-only. UDP, TUN, public listeners, SSH agent forwarding, and X11 forwarding are not implemented. Tunnel bytes are not redacted.
|
|
609
|
-
|
|
610
|
-
### Serial devices
|
|
611
|
-
|
|
612
|
-
`system.inspect` lists serial ports. `serial.capture` reads a selected port; `serial.exchange` first sends explicitly authorized `dataHex`. Both use 8N1 with DTR/RTS set false. Opening a port can still reset some hardware. Verify the selected device and avoid opening unrelated ports.
|
|
613
|
-
|
|
614
|
-
## 6. Disconnect and recover
|
|
615
|
-
|
|
616
|
-
When a connection drops, finite jobs are cancelled and serial handles close. With a remembered pairing, the probe stays available and the next new MCP operation reconnects without another code. For temporary sessions, the probe displays a new code and requires local connection consent again. Resume retained resources explicitly using their original IDs and recovery credentials. Diagnose never silently replays a creation command.
|
|
617
|
-
|
|
618
|
-
Ordinary live processes default to `retainOnDisconnect:false`; file transfers default to retained. A retained live process survives network loss only while the original probe process remains running. If the probe itself disappears, a new probe can recover encrypted saved output and supported file staging, but cannot take over the old process's PTY. Network connections must be recreated.
|
|
619
|
-
|
|
620
|
-
For download resume, keep the partial file and sidecar together. Upload resume uses the resource ID and recovery credential reported in progress. If a response is lost during a modifying action, inspect resource status before retrying; do not blindly restart the command.
|
|
621
|
-
|
|
622
|
-
## 7. Limits and timeouts
|
|
623
|
-
|
|
624
|
-
| Limit | Default / maximum |
|
|
625
|
-
| --- | --- |
|
|
626
|
-
| New short invitation | 30 minutes; one-time; up to five attempted handshakes |
|
|
627
|
-
| Temporary session idle / total | Six hours idle / no fixed total by default in v0.8+ |
|
|
628
|
-
| Remembered pairing | Until revoked locally; requires the foreground probe |
|
|
629
|
-
| Remembered automatic grant | 1 hour, or until locally revoked if explicitly chosen |
|
|
630
|
-
| Finite command or script | 60 seconds by default; 300 seconds maximum |
|
|
631
|
-
| Batch | Up to 32 steps; 300 seconds; 10 MiB combined output |
|
|
632
|
-
| Concurrent finite jobs | 4 |
|
|
633
|
-
| Active live resource handles | 128 |
|
|
634
|
-
| Live process | 1 hour by default; `timeoutMs:0` removes its timer |
|
|
635
|
-
| Retained output per live process | 64 MiB by default; 1 GiB maximum; reaching the cap terminates the process |
|
|
636
|
-
| Relay session | The updated relay renews an active room without a fixed total. Older relays may cap a room at seven days. |
|
|
637
|
-
|
|
638
|
-
```sh
|
|
639
|
-
diagnose start --session-minutes 240 --idle-minutes 30
|
|
640
|
-
```
|
|
641
|
-
|
|
642
|
-
Session and idle options apply to temporary connections. Remembered connections disable these endpoint timers, while automatic approval has its own saved expiry. Set a temporary session or idle timeout to `0` to disable that endpoint timer; relay and cipher limits still apply. Both endpoints should use a compatible current version. POSIX processes that deliberately detach from their process group cannot always be terminated by group cancellation.
|
|
643
|
-
|
|
644
|
-
## Use Diagnose as a native agent skill
|
|
645
|
-
|
|
646
|
-
Install the skill once through your agent's GitHub installation flow. All three agents use the same `skills/connect/` directory in the repository. The helper runs Diagnose 0.8.0 locally on demand with `npx` and needs Node.js 20.10 or later. There is no separate global Diagnose CLI installation for this workflow.
|
|
647
|
-
|
|
648
|
-
### Claude Code
|
|
649
|
-
|
|
650
|
-
In Claude Code 2.1.275 or later, enter:
|
|
651
|
-
|
|
652
|
-
```text
|
|
653
|
-
/plugin install diagnose --marketplace zkwasm/diagnose
|
|
654
|
-
```
|
|
655
|
-
|
|
656
|
-
Choose the installation scope. Open a new session, or use `/reload-plugins` in the current one. Invoke `/diagnose:connect` with the private invitation and, if known, the device and symptom. [Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins#add-a-marketplace-and-install-in-one-command)
|
|
657
|
-
|
|
658
|
-
### Codex CLI
|
|
659
|
-
|
|
660
|
-
In your terminal, run:
|
|
661
|
-
|
|
662
|
-
```sh
|
|
663
|
-
codex plugin marketplace add zkwasm/diagnose
|
|
664
|
-
codex plugin add diagnose@diagnose
|
|
665
|
-
```
|
|
666
|
-
|
|
667
|
-
Alternatively, add the marketplace and install Diagnose from `/plugins`. Open a new session and invoke `$diagnose:connect` with your private invitation. [Codex CLI plugin documentation](https://learn.chatgpt.com/docs/cli/reference#codex-plugin)
|
|
668
|
-
|
|
669
|
-
### Gemini CLI
|
|
670
|
-
|
|
671
|
-
In your terminal, run:
|
|
672
|
-
|
|
673
|
-
```sh
|
|
674
|
-
gemini skills install https://github.com/zkwasm/diagnose.git --path skills/connect
|
|
675
|
-
```
|
|
676
|
-
|
|
677
|
-
Approve the installation prompt. In a new session, ask Gemini to use the `connect` skill and provide the invitation. Use `/skills reload` if a Gemini session is already open. [Gemini CLI Skills documentation](https://geminicli.com/docs/cli/skills/#managing-skills)
|
|
678
|
-
|
|
679
|
-
### Run a diagnostic session
|
|
680
|
-
|
|
681
|
-
The on-site user starts the normal probe and shares its one-time invitation. The skill uses it to request pairing through the relay. The on-site user confirms the connection if their startup choice requires it. The agent starts with a relevant read-only check, such as listing visible serial ports. It keeps the connection for follow-up checks, authorized changes, and verification. Normal local execution and transfer permissions still apply.
|
|
682
|
-
|
|
683
|
-
The first result informs the next step. For example, the agent may compare device logs with two related settings, correct one setting, and rerun the original check. If the symptom persists, it uses that result to choose the next test. The skill keeps the connection open after progress reports and verification so you can ask follow-up questions. Ask the agent to close the session when you are done. The on-site user can also stop access.
|
|
684
|
-
|
|
685
|
-
A temporary session normally expires after six hours without diagnostic activity. Task requests, result polling, and live resource interactions renew the timer. Automatic heartbeats keep the network connection alive without renewing the diagnostic idle timer. A probe configured with an explicit total limit can expire the session earlier. A network or process loss can still interrupt a live connection. If interruptions are expected, a remembered pairing can reconnect without a fresh code. A direct stdio MCP session ends when its client stops the MCP process. The native skill keeps its MCP process running across separate shell calls and conversation turns.
|
|
686
|
-
|
|
687
|
-
This path uses temporary pairing and finite diagnostic operations. It supports system inspection, bounded file operations, finite commands, and serial diagnostics. The full agent launcher remains available for remembered connections, live terminals, and case management.
|
|
688
|
-
|
|
689
|
-
For prerelease testing, build the source checkout, install from its local marketplace or skill directory, and set `DIAGNOSE_SKILL_CLI` in the agent's environment to the absolute path of `dist/cli.js`. The GitHub install commands require the repository manifests to be published. The helper's default runtime requires the pinned npm version to be published.
|
|
690
|
-
|
|
691
|
-
## 8. Manual operation and other MCP clients
|
|
692
|
-
|
|
693
|
-
For scripts and CI, install the npm client and start it directly. The native Skill is optional for these workflows.
|
|
694
|
-
|
|
695
|
-
```sh
|
|
696
|
-
npm install -g @masstensor/diagnose
|
|
697
|
-
diagnose agent claude --device workshop-laptop --skill ./devices/owon.md
|
|
698
|
-
# Or use diagnose mcp --device workshop-laptop as the MCP server subprocess.
|
|
699
|
-
```
|
|
700
|
-
|
|
701
|
-
Use `agent codex` or `agent gemini` for the other launchers. You can also run the npm launcher directly with `npx @masstensor/diagnose@latest agent claude`. The `--skill` launcher flag takes your device procedure. It does not require the native Diagnose Skill to be installed.
|
|
702
|
-
|
|
703
|
-
```sh
|
|
704
|
-
diagnose connect
|
|
705
|
-
```
|
|
706
|
-
|
|
707
|
-
Enter task JSON on one line. Requests return a task ID. Use `wait <task-id>`, `cancel <task-id>`, `resources`, `read <resource-id> [cursor]`, `input <resource-id> "text\n"`, `resize <resource-id> 120 40`, `signal <resource-id> SIGINT`, and `close <resource-id>`.
|
|
708
|
-
|
|
709
|
-
`forward <resource-id> [local-port]` opens an approved forward. `upload` and `download` accept JSON with `localPath`, `remotePath`, `reason`, and optional `overwrite`, `resumeId`, and `resumeToken`.
|
|
710
|
-
|
|
711
|
-
For another stdio MCP client, configure it to launch:
|
|
712
|
-
|
|
713
|
-
```json
|
|
714
|
-
{"mcpServers":{"diagnose":{"command":"diagnose","args":["mcp"]}}}
|
|
715
|
-
```
|
|
716
|
-
|
|
717
|
-
This is a local child process, not a public HTTP MCP endpoint. Running `diagnose mcp` in a separate terminal does not automatically connect it to an agent.
|
|
718
|
-
|
|
719
|
-
The direct commands accept an optional relay URL, for example `diagnose start https://your-relay.example` and `diagnose mcp https://your-relay.example`. Remote relays require HTTPS/WSS; HTTP/WS is allowed only for loopback testing.
|
|
720
|
-
|
|
721
|
-
## Security and local data
|
|
722
|
-
|
|
723
|
-
Remembered pairing credentials and policy are stored encrypted under `~/.diagnose/pairings`, with a local key in that protected directory (directory `0700`, files `0600` where supported). This protects stored contents from casual access, not a compromised OS account or a backup containing both ciphertext and key. Possession of a relationship credential authenticates that relationship, not a person’s legal identity. Revocation removes the user-side credential and terminates access. Stable relay routing identifiers can correlate repeated connections; the relay still sees connection metadata.
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
Short invitations use OPAQUE between the two endpoints to derive a strong Noise PSK. Only a two-letter locator reaches the relay; the other seven random letters remain the PAKE secret. The probe itself enforces expiry and attempt limits. Remembered relationships and legacy D1 invitations use independent random 256-bit secrets. The transport uses Noise `NNpsk0_25519_ChaChaPoly_BLAKE2b`, ephemeral X25519 keys, independent direction counters, and routing/role/version binding. See the [short invitation protocol](https://github.com/zkwasm/diagnose/blob/main/PAIRING_PROTOCOL.md) for the exact design and limits. Tests include a public Cacophony test vector. Each direction is limited to one million frames, below the dependency's 32-bit counter boundary. WSS also validates the relay certificate. No independent security audit has been completed.
|
|
727
|
-
|
|
728
|
-
The relay keeps rooms and ciphertext buffers in memory. It does not persist diagnostic contents, endpoint decryption keys, or offline messages. It can see IP addresses, routing identifiers, connection timing, and traffic volume, and can deny service. A self-reported label is not verified identity.
|
|
729
|
-
|
|
730
|
-
The diagnostician, their endpoint software, and their AI provider can see results. Do not share a code or approve a session with someone you do not intend to trust.
|
|
731
|
-
|
|
732
|
-
### Audit logs
|
|
733
|
-
|
|
734
|
-
`~/.diagnose/audit-*.jsonl` uses mode `0600`. Events record task IDs, operation types, target paths/executables/interpreters, ranges and serial settings, argument digests, decisions, collection/transmission byte counts, cancellations, and outcomes. Batch steps include their parent task and individual status. Automatic mode records its permission changes and automatic approvals.
|
|
735
|
-
|
|
736
|
-
Built-in file mutations record paths and, where available, before/after hashes and byte counts. JSONL audit logs contain metadata only; the separate encrypted history below stores full tasks and finite collected results. Neither is a filesystem monitor: arbitrary programs can change files, services, and devices outside the built-in operations. Audit writes are flushed; an unwritable audit log stops the affected operation. Metadata logs rotate at 8 MiB; inactive archives are pruned after seven days or when their aggregate budget exceeds 32 MiB.
|
|
737
|
-
|
|
738
|
-
### Review local history and clean up
|
|
739
|
-
|
|
740
|
-
Available in **0.5.0+** on the computer receiving help:
|
|
741
|
-
|
|
742
|
-
```sh
|
|
743
|
-
diagnose history
|
|
744
|
-
diagnose show TASK_ID
|
|
745
|
-
diagnose show RESOURCE_ID --cursor 0
|
|
746
|
-
diagnose cleanup
|
|
747
|
-
# Remove all inactive local history and resources now:
|
|
748
|
-
diagnose cleanup --days 0
|
|
749
|
-
```
|
|
750
|
-
|
|
751
|
-
History records exact requested commands or scripts, approval previews, decisions, finite collected results (including results the user declined to send), attempted transfers, and known built-in changes. A completed send records that the local transport accepted it, not proof that a human read it. Continuous process output is stored in the resource journal; `show` returns a page with a cursor for the next page. Remote process input is recorded locally; hidden input entered with `secret` records only its byte count. Raw tunnel traffic and exact transferred file bodies are not duplicated in task history; their scope, paths, hashes, and traffic counts are recorded. Arbitrary script side effects and automatic rollback are not provided.
|
|
752
|
-
|
|
753
|
-
Full history can contain sensitive data, even if results were never sent. It is encrypted locally in `~/.diagnose/history`, with the key beside it under the same user account. This protects against casual file inspection, not someone controlling that account. History is not automatically uploaded and has no dedicated remote MCP tool. An authorized remote command still has your OS account's file access.
|
|
754
|
-
|
|
755
|
-
History and resource journals each have a **256 MiB / 2,000-record** budget. Inactive records expire after **seven days** and may be evicted sooner to stay within budget. Maintenance runs when storage is used and when `cleanup` is requested. Live retained resources are protected; if they exhaust the budget, collection stops rather than growing without bound. Close unused jobs before cleaning up. Abandoned upload staging files are removed with expired resource records; destination files and remembered pairings are never deleted by cleanup. Upload staging bytes are separate from the journal budget and consume space beside the destination.
|
|
756
|
-
|
|
757
|
-
Both endpoints at 0.5.0+ use increasing task sequence numbers, so a connection can run more than 1,000 tasks while rejecting replayed sequences. The diagnostician retains at most 128 task results and 32 MiB in memory; save needed results or use local history before they expire. Older clients retain the 1,000-task limit and require an explicit reconnect. Neither path automatically repeats a modifying command.
|
|
758
|
-
|
|
759
|
-
### Saved output and recovery data
|
|
760
|
-
|
|
761
|
-
Raw live output and recovery metadata are stored under `~/.diagnose/resources` using AES-256-GCM records. The local key has mode `0600` in the same account's directory. This protects stored ciphertext from casual inspection, not an attacker who controls that OS account and can read the key. Saved output is not automatically pruned; clean it up when it is no longer needed.
|
|
762
|
-
|
|
763
|
-
Finite text results receive best-effort common-credential redaction and terminal-control filtering. Regexes cannot identify every secret. Live terminals, exact file transfers, and TCP channels retain raw data and are not redacted. Collection and transmission are audited separately.
|
|
764
|
-
|
|
765
|
-
Commands run with the current user's OS permissions. Diagnose neither provides a sandbox nor automatically elevates privileges. It cannot completely observe arbitrary process side effects, undo completed modifications, or isolate against hostile local concurrent changes.
|
|
766
|
-
|
|
767
|
-
## Troubleshooting
|
|
768
|
-
|
|
769
|
-
- **Agent CLI not found:** install and sign in to that CLI separately, and ensure it is on `PATH`.
|
|
770
|
-
- **No Diagnose tools:** use `diagnose agent <name>` to start a new agent session. An already running unrelated agent will not acquire the new MCP automatically.
|
|
771
|
-
- **Invitation expired or connection refused:** keep the probe open and use its latest complete code; the user must accept locally.
|
|
772
|
-
- **Gemini trust or account error:** complete its normal workspace trust and authentication flow. Diagnose does not bypass these checks.
|
|
773
|
-
- **Resource not attached:** request `diagnose_resume` after the new pairing, with the original ID and recovery credential.
|
|
774
|
-
- **Upload/download hash mismatch:** do not replace the destination. Confirm the source has not changed and inspect transfer status before retrying.
|
|
775
|
-
- **Missing serial device:** verify the cable carries data, check OS drivers and permissions, and list ports again. Opening a port may reset the device.
|
|
776
|
-
|
|
777
|
-
## Source, hosting, and video
|
|
778
|
-
|
|
779
|
-
[Source and issues](https://github.com/zkwasm/diagnose) · [npm package](https://www.npmjs.com/package/@masstensor/diagnose)
|
|
780
|
-
|
|
781
|
-
The public relay is hosted at `diagnose.fenginwind.com`. You can self-host using the deployment templates in the repository. Keep local credentials, hardware logs, firmware, and resource journals out of server deployments and public packages.
|
|
782
|
-
|
|
783
|
-
The [one-minute English walkthrough](https://diagnose.fenginwind.com/#walkthrough) covers the current agent launcher, local permissions, encrypted transport, investigation, authorized repair, and verification. It includes English narration and captions. The port-mismatch repair is an illustrative example, not a live diagnosis. The earlier Chinese video is retained separately.
|
|
98
|
+
Use the latest package on both endpoints. macOS probes and the Linux relay have been tested. Windows coverage includes targeted automated tests. Interactive terminals, authentication, and physical USB/serial behavior on Windows still need real-environment validation.
|