@masstensor/diagnose 0.3.2 → 0.7.0

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.
Files changed (107) hide show
  1. package/DEVELOPMENT_PLAN.md +69 -0
  2. package/KNOWLEDGE_SECURITY.md +47 -0
  3. package/PAIRING_PROTOCOL.md +37 -0
  4. package/README.md +56 -9
  5. package/USER_GUIDE.md +460 -20
  6. package/deploy/Caddyfile +1 -1
  7. package/deploy/ecosystem.config.cjs +1 -1
  8. package/dist/agent-command.d.ts +4 -0
  9. package/dist/agent-command.js +33 -0
  10. package/dist/agent.d.ts +1 -1
  11. package/dist/agent.js +48 -8
  12. package/dist/cases.d.ts +118 -0
  13. package/dist/cases.js +115 -0
  14. package/dist/cli.js +187 -25
  15. package/dist/crypto.d.ts +7 -0
  16. package/dist/crypto.js +16 -1
  17. package/dist/discover.js +1 -1
  18. package/dist/engine.d.ts +3 -0
  19. package/dist/engine.js +49 -9
  20. package/dist/history.d.ts +13 -0
  21. package/dist/history.js +57 -0
  22. package/dist/journal.d.ts +23 -1
  23. package/dist/journal.js +82 -5
  24. package/dist/knowledge-cli.d.ts +2 -0
  25. package/dist/knowledge-cli.js +164 -0
  26. package/dist/knowledge-drafts.d.ts +47 -0
  27. package/dist/knowledge-drafts.js +76 -0
  28. package/dist/knowledge-mcp.d.ts +5 -0
  29. package/dist/knowledge-mcp.js +65 -0
  30. package/dist/maintenance.d.ts +2 -0
  31. package/dist/maintenance.js +46 -0
  32. package/dist/mcp.d.ts +1 -1
  33. package/dist/mcp.js +42 -20
  34. package/dist/operator.d.ts +4 -0
  35. package/dist/operator.js +33 -8
  36. package/dist/pairing.d.ts +40 -0
  37. package/dist/pairing.js +92 -0
  38. package/dist/peer.d.ts +13 -0
  39. package/dist/peer.js +87 -11
  40. package/dist/relay-main.js +1 -1
  41. package/dist/relay.d.ts +1 -0
  42. package/dist/relay.js +27 -4
  43. package/dist/resources.js +47 -26
  44. package/dist/schema.d.ts +2 -0
  45. package/dist/schema.js +2 -2
  46. package/dist/short-pairing.d.ts +25 -0
  47. package/dist/short-pairing.js +73 -0
  48. package/dist/skill-library.d.ts +27 -0
  49. package/dist/skill-library.js +226 -0
  50. package/dist/skill.d.ts +9 -0
  51. package/dist/skill.js +59 -0
  52. package/dist/transfers.js +28 -11
  53. package/dist/util.d.ts +2 -0
  54. package/dist/util.js +17 -3
  55. package/dist/vault-crypto.d.ts +11 -0
  56. package/dist/vault-crypto.js +30 -0
  57. package/dist/vault-server.d.ts +10 -0
  58. package/dist/vault-server.js +156 -0
  59. package/dist/vault.d.ts +19 -0
  60. package/dist/vault.js +72 -0
  61. package/examples/skills/device-troubleshooting/SKILL.md +35 -0
  62. package/examples/skills/device-troubleshooting/references/device-profile.md +16 -0
  63. package/examples/skills/owon.md +27 -0
  64. package/npm-shrinkwrap.json +209 -3
  65. package/package.json +15 -5
  66. package/scripts/setup-node.ps1 +54 -0
  67. package/scripts/setup-node.sh +52 -0
  68. package/src/agent-command.ts +25 -0
  69. package/src/agent.ts +37 -7
  70. package/src/cases.ts +74 -0
  71. package/src/cli.ts +57 -22
  72. package/src/crypto.ts +14 -1
  73. package/src/discover.ts +1 -1
  74. package/src/engine.ts +28 -7
  75. package/src/history.ts +43 -0
  76. package/src/journal.ts +41 -5
  77. package/src/knowledge-cli.ts +67 -0
  78. package/src/knowledge-drafts.ts +55 -0
  79. package/src/knowledge-mcp.ts +35 -0
  80. package/src/maintenance.ts +30 -0
  81. package/src/mcp.ts +26 -18
  82. package/src/operator.ts +25 -9
  83. package/src/pairing.ts +64 -0
  84. package/src/peer.ts +42 -14
  85. package/src/relay-main.ts +1 -1
  86. package/src/relay.ts +18 -6
  87. package/src/resources.ts +35 -13
  88. package/src/schema.ts +4 -4
  89. package/src/short-pairing.ts +57 -0
  90. package/src/skill-library.ts +162 -0
  91. package/src/skill.ts +45 -0
  92. package/src/transfers.ts +14 -3
  93. package/src/util.ts +15 -3
  94. package/src/vault-crypto.ts +25 -0
  95. package/src/vault-server.ts +72 -0
  96. package/src/vault.ts +51 -0
  97. package/test/agent.test.ts +79 -7
  98. package/test/cli.test.ts +3 -3
  99. package/test/knowledge-mcp.test.ts +37 -0
  100. package/test/knowledge.test.ts +112 -0
  101. package/test/mcp.test.ts +1 -1
  102. package/test/pairing.test.ts +124 -0
  103. package/test/review.test.ts +129 -0
  104. package/test/setup.test.ts +16 -0
  105. package/test/short-pairing.test.ts +100 -0
  106. package/test/skill-library.test.ts +62 -0
  107. package/test/skill.test.ts +25 -0
package/USER_GUIDE.md CHANGED
@@ -1,21 +1,200 @@
1
1
  # Diagnose user guide
2
2
 
3
- Diagnose gives an AI agent a temporary connection to a consenting user's computer. The same probe can inspect the computer itself, a USB device, or a device reachable on its local network.
3
+ Diagnose connects a remote AI agent to **devices an on-site computer can access**: a home IoT gateway, a factory controller, an industrial PC, or other equipment with a usable USB, serial, or local-network interface. The computer is the bridge; the device is the main target. Computer and software problems can also be investigated when needed.
4
4
 
5
- There are two people in a session:
5
+ ## Why: stop making the user carry every clue
6
6
 
7
- - **User:** the person whose computer or connected device needs diagnosis. They run `diagnose start` and control permissions locally.
8
- - **Diagnostician:** the person directing the AI agent. They run `diagnose agent codex`, `diagnose agent claude`, or `diagnose agent gemini` and give the agent the user's pairing code.
7
+ A device fails at a home or factory, while the person who can help is elsewhere. Remote support often means asking someone on site to run commands, copy logs, send screenshots, and repeat the process. That person may not know the tools. The expert and their AI cannot directly inspect the next clue or verify a change.
9
8
 
10
- The AI runs on the diagnostician's side. The user does not need to install an AI agent or configure MCP.
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 |
26
+ | --- | --- |
27
+ | **On-site user** | Connect the device, run the probe, share the pairing code privately, and control local permissions. They need no AI account or agent installation. |
28
+ | **Remote diagnostician** | Launch Codex, Claude Code, or Gemini CLI with Diagnose, provide a concrete goal and any device procedure, and review the investigation and proposed repair. |
29
+ | **AI agent** | Use the authorized tools to collect evidence, carry out permitted changes, and check the device's actual behavior. |
30
+
31
+ The following quick start takes both people through this process.
32
+
33
+ ## Quick start
34
+
35
+ ### 1. Prepare both computers
36
+
37
+ Run the one-line setup command for your computer. It downloads our open-source installer, reuses existing Node.js without updating it, and installs Node.js/npm/npx only if Node.js is absent. No administrator access is normally needed.
38
+
39
+ **Windows:** open the Start menu, type **Windows PowerShell**, and open it. Paste:
40
+
41
+ ```powershell
42
+ curl.exe -fsSL https://diagnose.fenginwind.com/setup/setup-node.ps1 | Out-String | Invoke-Expression
43
+ ```
44
+
45
+ **Mac:** press **Command + Space**, type **Terminal**, and press Return. **Linux:** open Terminal. Paste:
46
+
47
+ ```sh
48
+ curl -fsSL https://diagnose.fenginwind.com/setup/setup-node.sh | bash
49
+ ```
50
+
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.
52
+
53
+ Only the **diagnostician** needs an installed, signed-in Codex CLI, Claude Code, or Gemini CLI. The person receiving help needs no AI account.
54
+
55
+ ### 2. Connect the device and start the on-site probe
56
+
57
+ Ask the diagnostician which connection to use:
58
+
59
+ - **USB or serial:** connect the device to the on-site computer using the appropriate data cable or adapter. Install any required driver. A USB port may provide power only; the device must expose a usable interface.
60
+ - **Local network:** use a computer that can reach the device's network address and service. Provide any required device credentials through the agreed private or local method.
61
+
62
+ Then run this on the on-site computer:
63
+
64
+ ```sh
65
+ npx @masstensor/diagnose@latest start
66
+ ```
67
+
68
+ If npm asks to install the package, type `y`. Keep this terminal open. Send the nine-letter invitation, such as `abc-def-ghi`, privately to your diagnostician.
69
+
70
+ ### 3. On the diagnostician's computer
71
+
72
+ ```sh
73
+ npx @masstensor/diagnose@latest agent codex
74
+ # Or replace codex with claude or gemini.
75
+ ```
76
+
77
+ In the agent conversation, provide the code, device model, connection method, and a concrete goal:
78
+
79
+ > 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.
80
+
81
+ ### 4. Approve, diagnose, and finish
82
+
83
+ The person receiving help checks the diagnostician's label and connection fingerprint, then chooses `y` to review tasks and result transfers. Choosing `a` instead grants automatic execution **and transmission** under the displayed terms. Commands run with that user's OS permissions; results can reach the diagnostician and their AI provider.
84
+
85
+ The diagnostician directs the agent to investigate the device, repair within permission, and verify a device result: for example, new sensor readings or a successful communication check. The user can type `permissions ask` to revoke automatic approval or `exit` to stop access. Afterward, `diagnose history` lists local task records and `diagnose show TASK_ID` shows what was requested, collected, and sent.
86
+
87
+ ### Return later or load a device procedure
88
+
89
+ **Requires v0.5.0+ on both computers.** Use a release supporting these options before following the additional commands below.
90
+
91
+ ```sh
92
+ npm install -g @masstensor/diagnose@latest
93
+ # Diagnostician: pair once while the user's probe is running.
94
+ diagnose pair --name workshop-laptop
95
+ # User: explicitly approve remembering this diagnostician.
96
+ # Diagnostician: use this whenever diagnosis is needed again.
97
+ diagnose agent codex --device workshop-laptop --skill ./devices/owon.md
98
+ ```
99
+
100
+ The saved name identifies the on-site computer, not the gateway or controller attached to it. Confirm which device is currently connected before starting work. The skill file is your local Markdown procedure; create it first or omit `--skill`. The same flags work with `claude` and `gemini`. The user must keep `diagnose start` running, or start it again after a restart. Pairing survives; execution approval remains separately controlled. See [remembered pairing](#keep-a-device-paired-for-future-diagnosis) and [skills](#start-with-a-device-skill-or-markdown-task) for full details.
101
+
102
+ ## From a reported problem to a verified result
103
+
104
+ For a device session, work toward an observable device outcome:
105
+
106
+ 1. **Describe the problem.** Identify the device model, its connection to the on-site computer, what fails, and what you expected. Agree on the check that will show whether the problem is resolved.
107
+ 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.
108
+ 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.
109
+ 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.
110
+ 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.
111
+
112
+ These are instructions for directing the agent, not a separate enforced plan-approval system. The local task/channel permissions described below still apply. Automatic mode continues to allow execution and transmission under the user's grant; general automatic rollback is not provided.
113
+
114
+ You can also request a read-only investigation and stop after the explanation. The on-site computer’s drivers, software, configuration, and network can also be investigated when they are part of the problem; successful fixes depend on the issue, available access, and the user's authorization.
11
115
 
12
116
  ## 1. Requirements
13
117
 
14
- Both computers need **Node.js 22.18 or later**, npm, an interactive terminal, and outbound access to the relay. The default relay is `https://diagnose.fenginwind.com`. No inbound port, router change, or SSH server is required.
118
+ 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.
119
+
120
+ Both computers need **Node.js 20.10 or later**, npm, an interactive terminal, and outbound access to the relay. The default relay is `https://diagnose.fenginwind.com`. No inbound port, router change, or SSH server is required.
15
121
 
16
122
  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.
17
123
 
18
- 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. Linux and Windows probes, including Windows ConPTY and Gemini symlink permissions, remain experimental.
124
+ Node.js 20.10+ runtime compatibility is available in Diagnose 0.5.0+. Earlier Diagnose packages declare Node.js 22.18+; use a compatible Diagnose version rather than automatically upgrading the user's Node.js. The relay deployment wrapper requires Node.js 22+ separately.
125
+
126
+ 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.
127
+
128
+ ## First-time setup: install Node.js and npm
129
+
130
+ 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.
131
+
132
+ **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.
133
+
134
+ ### Windows: copy and paste setup
135
+
136
+ Open the **Start** menu, type **Windows PowerShell**, and open it normally. Copy the complete block below, paste it into that window, and press Enter:
137
+
138
+ ```powershell
139
+ curl.exe -fsSL https://diagnose.fenginwind.com/setup/setup-node.ps1 | Out-String | Invoke-Expression
140
+ ```
141
+
142
+ 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.
143
+
144
+ ### Mac or Linux: copy and paste setup
145
+
146
+ On a Mac, press **Command + Space**, type **Terminal**, and press Return. On Linux, open Terminal. Copy the entire block, paste it, and press Return:
147
+
148
+ ```sh
149
+ curl -fsSL https://diagnose.fenginwind.com/setup/setup-node.sh | bash
150
+ ```
151
+
152
+ 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.
153
+
154
+ ### What setup changes
155
+
156
+ - 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.
157
+ - 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.
158
+ - 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.
159
+ - 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.
160
+
161
+ 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.
162
+
163
+ ### Check the installation
164
+
165
+ 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`):
166
+
167
+ ```sh
168
+ node --version
169
+ npm --version
170
+ npx --version
171
+ ```
172
+
173
+ 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.
174
+
175
+ You are now ready. Paste this single command into the same window and press Enter/Return:
176
+
177
+ ```sh
178
+ npx @masstensor/diagnose@latest start
179
+ ```
180
+
181
+ 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.
182
+
183
+ 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.
184
+
185
+ ### If something goes wrong
186
+
187
+ | What you see | What to do |
188
+ | --- | --- |
189
+ | “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. |
190
+ | 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. |
191
+ | npm or npx is missing | Setup leaves the existing Node.js unchanged. Ask your diagnostician to repair npm/npx or discuss a separate runtime. |
192
+ | 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. |
193
+ | “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. |
194
+ | 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. |
195
+ | 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. |
196
+
197
+ 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/).
19
198
 
20
199
  ## 2. Start on the user's computer
21
200
 
@@ -30,7 +209,7 @@ npm install -g @masstensor/diagnose@latest
30
209
  diagnose start
31
210
  ```
32
211
 
33
- The terminal shows a pairing code beginning with `D1.` and the local audit log path. Keep it open. Share the **complete code privately** with the intended diagnostician. The initial invitation lasts 10 minutes. Treat the code as a secret; do not post it publicly or place it in shell arguments.
212
+ 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. The user must still approve locally. 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.
34
213
 
35
214
  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.
36
215
 
@@ -56,10 +235,241 @@ Do **not** separately run `diagnose mcp` or register a global MCP server. The la
56
235
 
57
236
  Then tell the agent what to inspect and provide the pairing code in the agent conversation. For example:
58
237
 
59
- > Use Diagnose to connect to pairing code D1.… . Inspect the user's USB-connected gateway, collect its logs, and explain why it is offline. Only read data. Do not reset, flash, or modify configuration.
238
+ > 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.
60
239
 
61
240
  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.
62
241
 
242
+ ### Keep a device paired for future diagnosis
243
+
244
+ 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:
245
+
246
+ ```sh
247
+ diagnose pair --name workshop-laptop
248
+ # Enter the user's code, then your label and AI provider when prompted.
249
+ ```
250
+
251
+ 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.
252
+
253
+ After pairing, the diagnostician can start, stop, and restart any supported agent using the same device name:
254
+
255
+ ```sh
256
+ diagnose agent codex --device workshop-laptop --skill ./devices/owon.md
257
+ diagnose agent claude --device workshop-laptop --skill ./devices/owon.md
258
+ diagnose agent gemini --device workshop-laptop --skill ./devices/owon.md
259
+ # --skill is optional.
260
+ ```
261
+
262
+ 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.
263
+
264
+ 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.
265
+
266
+ **Remembering is separate from automatic approval.** The default is still per-task approval. In the user's running probe terminal:
267
+
268
+ | Command | Effect |
269
+ | --- | --- |
270
+ | `pairing` | Show the remembered diagnostician and automatic grant expiry. |
271
+ | `permissions auto`, then `permissions allow-auto` | Grant one hour of automatic execution and transmission, across reconnects and restarts. |
272
+ | `permissions auto forever`, then `permissions allow-auto` | Explicitly grant automatic execution and transmission until revoked locally. |
273
+ | `permissions ask` | Revoke automatic permission, cancel work/resources, keep the pairing. |
274
+ | `pause` | Disconnect and block access while retaining the pairing and its original grant expiry. |
275
+ | `resume` | Allow connections again. An expired grant does not become valid again. |
276
+ | `unpair` | Revoke the private credential, cancel work/resources, and return to a new invitation. |
277
+ | `exit` or `Ctrl+C` | Stop access and close resources. Remembered pairing remains for the next start. |
278
+
279
+ 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.
280
+
281
+ On the diagnostician's computer:
282
+
283
+ ```sh
284
+ diagnose devices
285
+ diagnose connect --device workshop-laptop
286
+ diagnose terminal --device workshop-laptop
287
+ diagnose mcp --device workshop-laptop
288
+ diagnose forget --device workshop-laptop
289
+ ```
290
+
291
+ `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.
292
+
293
+ 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).
294
+
295
+ ## Record a device diagnosis and improve your procedures
296
+
297
+ These knowledge features require Diagnose 0.6.0 or later on the diagnostician computer. Older probes can still perform their supported operations.
298
+
299
+ 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.
300
+
301
+ 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.
302
+
303
+ To create a case before launching, save a small JSON file:
304
+
305
+ ```json
306
+ {
307
+ "goal": "Find why the gateway stopped reporting sensor readings",
308
+ "host": "workshop-laptop",
309
+ "target": { "name": "Workshop gateway", "model": "SEG-X3-C", "interface": "serial" }
310
+ }
311
+ ```
312
+
313
+ ```sh
314
+ diagnose cases create ./gateway-case.json
315
+ diagnose cases list
316
+ diagnose agent codex --device workshop-laptop --case CASE_ID
317
+ ```
318
+
319
+ 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.
320
+
321
+ 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.
322
+
323
+ ```sh
324
+ diagnose cases show CASE_ID
325
+ diagnose cases export CASE_ID > reviewed-report.json
326
+ diagnose cases remove CASE_ID
327
+ ```
328
+
329
+ 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.
330
+
331
+ 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.
332
+
333
+ ### Review a new skill or improvement
334
+
335
+ 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.
336
+
337
+ ```sh
338
+ diagnose drafts list
339
+ diagnose drafts review DRAFT_ID
340
+ diagnose drafts accept DRAFT_ID
341
+ # Or keep the existing procedure:
342
+ diagnose drafts reject DRAFT_ID
343
+ ```
344
+
345
+ 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.
346
+
347
+ 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.
348
+
349
+ ### Share your private skill library across computers
350
+
351
+ 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:
352
+
353
+ ```sh
354
+ diagnose vault init ./diagnose-library-recovery.txt
355
+ diagnose vault push library:NAME@FULL_REVISION
356
+ ```
357
+
358
+ 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.
359
+
360
+ On a second diagnostician computer, securely transfer the recovery file yourself (never through an AI prompt) and run:
361
+
362
+ ```sh
363
+ diagnose vault restore ./diagnose-library-recovery.txt
364
+ diagnose vault pull
365
+ diagnose skills list
366
+ diagnose agent claude --skill library:NAME@FULL_REVISION
367
+ ```
368
+
369
+ 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.
370
+
371
+ ```sh
372
+ diagnose vault status
373
+ diagnose vault backup ./another-private-recovery-copy.txt
374
+ diagnose vault revoke
375
+ diagnose vault forget
376
+ ```
377
+
378
+ **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.
379
+
380
+ 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.
381
+
382
+ 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.
383
+
384
+ ## Start with a device skill or Markdown task
385
+
386
+ Version **0.4.0+** can start the agent with a selected diagnostic procedure. The syntax is identical for all three agents:
387
+
388
+ ```sh
389
+ diagnose agent codex --skill ./devices/owon.md
390
+ diagnose agent claude --skill ./devices/owon.md
391
+ diagnose agent gemini --skill ./devices/owon.md
392
+ ```
393
+
394
+ Use a local UTF-8 `.md` or `.markdown` file, up to 256 KiB. A directory containing `SKILL.md` also works:
395
+
396
+ ```sh
397
+ diagnose agent codex --skill ./skills/my-device
398
+ ```
399
+
400
+ For example:
401
+
402
+ ```text
403
+ skills/my-device/
404
+ SKILL.md
405
+ references/device-profile.md
406
+ scripts/check-device.js
407
+ ```
408
+
409
+ 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.
410
+
411
+ 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.
412
+
413
+ 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.
414
+
415
+ 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.
416
+
417
+ ### Writing a reusable procedure
418
+
419
+ Describe:
420
+
421
+ - The supported device or problem and the desired verification check.
422
+ - How to identify the target, and what missing information to ask for.
423
+ - Read-only evidence to collect and how to interpret it.
424
+ - Permitted repairs, their impact, prohibited actions, and available recovery steps.
425
+ - How to verify the original problem and report unresolved issues.
426
+
427
+ A minimal task could be:
428
+
429
+ ```markdown
430
+ # Local service troubleshooting
431
+
432
+ Start now using Diagnose MCP. Ask for the pairing code and target service
433
+ if missing. Pair and wait for local consent. Inspect logs and configuration
434
+ without changing them first. Explain the likely cause and repair plan.
435
+ Apply only authorized changes, repeat the original failing check, and
436
+ report what changed, the evidence, and anything unresolved.
437
+ ```
438
+
439
+ 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).
440
+
441
+ ### Local versioned library (v0.6+)
442
+
443
+ The local library requires Diagnose 0.6.0 or later.
444
+
445
+ Import a reviewed skill directory once, then use the exact reference printed by the command:
446
+
447
+ ```sh
448
+ diagnose skills import owon ./examples/skills/device-troubleshooting
449
+ diagnose skills list
450
+ diagnose agent codex --device workshop-laptop --skill library:owon@FULL_SHA256_FROM_IMPORT
451
+ ```
452
+
453
+ 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.
454
+
455
+ 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.
456
+
457
+ 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.
458
+
459
+ Import/list commands are local. See the diagnosis case and private library sections for reviewed drafts and optional encrypted synchronization.
460
+
461
+ ### Permissions and compatibility
462
+
463
+ 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.
464
+
465
+ 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.
466
+
467
+ 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.
468
+
469
+ ### Short invitation compatibility
470
+
471
+ 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.
472
+
63
473
  ### Session configuration and extra arguments
64
474
 
65
475
  ```sh
@@ -70,7 +480,7 @@ Options before `--` belong to Diagnose. Everything after it is passed literally
70
480
 
71
481
  - **Codex:** receives temporary `-c` MCP overrides.
72
482
  - **Claude Code:** receives a temporary `--mcp-config` value.
73
- - **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. The directory is removed on normal exit; changes to user settings in this Gemini session are not written back to the original `settings.json`.
483
+ - **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`.
74
484
 
75
485
  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.
76
486
 
@@ -108,11 +518,11 @@ Type these into the user's probe terminal:
108
518
 
109
519
  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.
110
520
 
111
- 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.
521
+ 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.
112
522
 
113
523
  ## 5. What the agent can do
114
524
 
115
- The MCP interface provides 11 tools:
525
+ The MCP interface provides 15 tools:
116
526
 
117
527
  | Tool | Purpose |
118
528
  | --- | --- |
@@ -127,6 +537,10 @@ The MCP interface provides 11 tools:
127
537
  | `diagnose_transfer` | Upload/download files in the background; query progress or cancel. |
128
538
  | `diagnose_forward` | Open, inspect, or close a local endpoint for an authorized TCP forward. |
129
539
  | `diagnose_disconnect` | Disconnect the diagnostic session. |
540
+ | `diagnose_capabilities` | Query operation schemas and conservative discovery guidance. |
541
+ | `diagnose_case` | Create/show a case, record assessments, report connection layers and finish with evidence references. |
542
+ | `diagnose_skill_draft` | Propose a new skill or improvement for local human review. |
543
+ | `diagnose_skills` | List or read locally available pinned skill versions without executing them. |
130
544
 
131
545
  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.
132
546
 
@@ -165,7 +579,7 @@ Agents use `diagnose_process` for the same live capabilities. Non-PTY processes
165
579
 
166
580
  ### Files
167
581
 
168
- `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.
582
+ `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.
169
583
 
170
584
  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.
171
585
 
@@ -187,7 +601,7 @@ SOCKS defaults to `allowedHosts:["*"]`, which permits any target. Narrow it when
187
601
 
188
602
  ## 6. Disconnect and recover
189
603
 
190
- When a connection drops, finite jobs are cancelled and serial handles close. The user's probe stays running and displays a **new pairing code**. Pair again, obtain new local consent, then resume a retained resource using its original ID and recovery credential. Diagnose never silently replays a creation command.
604
+ 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.
191
605
 
192
606
  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.
193
607
 
@@ -197,8 +611,10 @@ For download resume, keep the partial file and sidecar together. Upload resume u
197
611
 
198
612
  | Limit | Default / maximum |
199
613
  | --- | --- |
200
- | Invitation | 10 minutes |
201
- | Idle session / total session | 10 minutes / 60 minutes by default |
614
+ | New short invitation | 30 minutes; one-time; up to five attempted handshakes |
615
+ | Temporary session idle / total | 10 minutes / 60 minutes by default |
616
+ | Remembered pairing | Until revoked locally; requires the foreground probe |
617
+ | Remembered automatic grant | 1 hour, or until locally revoked if explicitly chosen |
202
618
  | Finite command or script | 60 seconds by default; 300 seconds maximum |
203
619
  | Batch | Up to 32 steps; 300 seconds; 10 MiB combined output |
204
620
  | Concurrent finite jobs | 4 |
@@ -211,7 +627,7 @@ For download resume, keep the partial file and sidecar together. Upload resume u
211
627
  diagnose start --session-minutes 240 --idle-minutes 30
212
628
  ```
213
629
 
214
- Set a 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.
630
+ 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.
215
631
 
216
632
  ## 8. Manual operation and other MCP clients
217
633
 
@@ -235,7 +651,10 @@ The direct commands accept an optional relay URL, for example `diagnose start ht
235
651
 
236
652
  ## Security and local data
237
653
 
238
- Diagnose uses Noise `NNpsk0_25519_ChaChaPoly_BLAKE2b`, a random 256-bit pairing secret, ephemeral X25519 keys, independent direction counters, and routing/role/version binding. 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.
654
+ 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.
655
+
656
+
657
+ 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.
239
658
 
240
659
  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.
241
660
 
@@ -245,7 +664,28 @@ The diagnostician, their endpoint software, and their AI provider can see result
245
664
 
246
665
  `~/.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.
247
666
 
248
- Built-in file mutations record paths and, where available, before/after hashes and byte counts. Default audit logs do not store full command arguments, script source, or raw collected contents. They are not a complete command replay or filesystem monitor. Audit writes are flushed; an unwritable audit log stops the affected operation.
667
+ 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.
668
+
669
+ ### Review local history and clean up
670
+
671
+ Available in **0.5.0+** on the computer receiving help:
672
+
673
+ ```sh
674
+ diagnose history
675
+ diagnose show TASK_ID
676
+ diagnose show RESOURCE_ID --cursor 0
677
+ diagnose cleanup
678
+ # Remove all inactive local history and resources now:
679
+ diagnose cleanup --days 0
680
+ ```
681
+
682
+ 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.
683
+
684
+ 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.
685
+
686
+ 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.
687
+
688
+ 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.
249
689
 
250
690
  ### Saved output and recovery data
251
691
 
@@ -271,4 +711,4 @@ Commands run with the current user's OS permissions. Diagnose neither provides a
271
711
 
272
712
  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.
273
713
 
274
- The existing one-minute explainer video remains in Chinese. It demonstrates version 0.2's batch and permission flow and predates live resources and the one-command agent launcher. Its screen content is an illustration, not a live session.
714
+ 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.
package/deploy/Caddyfile CHANGED
@@ -1,6 +1,6 @@
1
1
  diagnose.fenginwind.com {
2
2
  encode zstd gzip
3
- @relay path /v1/connect /healthz /downloads/*
3
+ @relay path /v1/connect /v1/library /v1/library/* /healthz /downloads/*
4
4
  handle @relay {
5
5
  reverse_proxy 127.0.0.1:8792
6
6
  }
@@ -1 +1 @@
1
- module.exports = { apps: [{ name: 'diagnose-relay', cwd: '/home/ubuntu/diagnose-relay', script: 'deploy/start-relay.sh', interpreter: '/bin/sh', instances: 1, exec_mode: 'fork', max_memory_restart: '200M', kill_timeout: 5000, env: { NODE_ENV: 'production', HOST: '127.0.0.1', PORT: '8792', DOWNLOAD_PATH: '/home/ubuntu/diagnose-relay/diagnose-0.1.0.tgz' } }] };
1
+ module.exports = { apps: [{ name: 'diagnose-relay', cwd: '/home/ubuntu/diagnose-relay', script: 'deploy/start-relay.sh', interpreter: '/bin/sh', instances: 1, exec_mode: 'fork', max_memory_restart: '200M', kill_timeout: 5000, env: { NODE_ENV: 'production', HOST: '127.0.0.1', PORT: '8792', VAULT_PATH: '/home/ubuntu/diagnose-data/library', DOWNLOAD_PATH: '/home/ubuntu/diagnose-relay/diagnose-0.1.0.tgz' } }] };