worktrust 0.11.11 → 0.11.13

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/CHANGELOG.md CHANGED
@@ -2,6 +2,68 @@
2
2
 
3
3
  The WorkTrust CLI, newest first. What the tool is and how to use it: [README.md](README.md).
4
4
 
5
+ ## 0.11.13: computer health in Remote Agent, and continue a session on this computer
6
+
7
+ **This computer's health, live on your phone and in the browser.** The Remote Agent service reads memory pressure, free
8
+ memory, swap and its growth over two minutes, the load per core, the GPU's utilisation (Apple silicon) and the three
9
+ programs using the most memory (by name only) every 15 seconds, with no model and no sudo, and sends them sealed to your
10
+ linked phones and browsers; the relay passes them on and keeps none. Red (critical pressure, or under 5 % free while swap
11
+ grows for two minutes) shows in `remote status` and the Remote Agent menu, and a new session is refused with "This
12
+ computer is under heavy memory load" until it eases; running sessions continue.
13
+
14
+ **Continue a session on this computer.**
15
+ **Carry on in the chat from your phone or a browser.** Remote Agent now lists this computer's recent Claude Code sessions
16
+ (the last 20 by activity) to the WorkTrust app and the web Remote Console, and continues the one you pick through the same
17
+ start as a session begun from the phone: Claude Code's own `--resume`, the approval tool, the deny rules (no release,
18
+ pipeline or deploy from a remote session) and the agent modes you allowed here. From then on it is a remote session like
19
+ any other, in the normal sessions list, and its turns from the phone are not your AI Hours.
20
+
21
+ **Only what it needs, only from folders you granted.** The CLI opens Claude Code's own transcript folders for your granted
22
+ projects and roots' projects only, never the store as a whole, and drops a transcript whose recorded folder is another. Per
23
+ session it sends, sealed end to end, only its id, the project's id, the last activity time, a title (Claude Code's own
24
+ summary when there is one, else the first line you typed, cut to 80 characters) and the model when recorded. Nothing
25
+ else of a transcript leaves this computer, and WorkTrust's servers see none of it. The list goes only to a phone or
26
+ browser that asks for it; an older app never receives it.
27
+
28
+ **One owner per conversation.** A session is refused while it is open here: its transcript was written in the last 30
29
+ seconds, a Claude Code process names it (`--resume`), or a Claude Code window open in that project folder started before
30
+ its last line. The phone and the browser say "This session is open on the computer. Close it there first." Agents running
31
+ in that window do not come along. On Windows, where the CLI cannot read the process list without a shell, the list stays
32
+ empty for now.
33
+
34
+ ## 0.11.12: a smaller code to link a phone, access chosen at once, Esc stops a command, and decoy keys
35
+
36
+ **Decoy keys beside the real one.** `connect` and `update` write a few decoy credential files next to the computer's key,
37
+ in the same format, and register only their fingerprints with WorkTrust. Someone who copies the folder and tries one of
38
+ them is caught at once: every Remote Agent link of the account is cut, the computer's key is revoked, and the owner gets an
39
+ alert and an e-mail. If you restored a file from `~/.worktrust` yourself, run `npx worktrust connect` again.
40
+
41
+ **A smaller code to link a phone, and ten minutes to scan it.** The QR that links a phone carries a short code instead of
42
+ the computer's two keys: a one-time secret and a 128-bit commitment to those keys, which the phone checks against the
43
+ computer's signed key when it first connects. With a narrower margin it is drawn 37 characters wide and 19 lines high,
44
+ where it was 61 by 31. It needs the WorkTrust app build 17 or later. The code and the QR work for ten minutes, with the
45
+ time left counting down under the QR, and an empty line above and below the code gives it room. The pairing link is no
46
+ longer printed with its secret (`--show-link` prints it).
47
+
48
+ **The phone is named the moment it links, then you choose what it may reach.** `✓ Phone linked` shows the phone's device
49
+ id and its type, and the next step asks right away: allow all your usual project folders (Desktop, Projects, code and the
50
+ like, as roots) or tick the projects to grant. Both go through the same grants as Remote Agent › Roots and › Projects.
51
+ Nothing is shared until you choose: close the CLI before that and the phone reaches no folder, and the next
52
+ `npx worktrust` asks again (`npx worktrust remote access` does it directly).
53
+
54
+ **Esc stops a running command in the menu.** While a command the menu started is busy, Esc stops it and the menu says
55
+ `Stopped. Enter: back to the menu · Esc: close`. A read or a wait stops at once; a write is finished first (`Finishing a
56
+ write, then stopping…`), so no file is left half-written. Typed directly, nothing changes: Ctrl+C stops a command as before.
57
+
58
+ **The spinner stays on one line.** A key typed while "Counting what this computer measured" turned was echoed by the
59
+ terminal and pushed the spinner onto a second line. In the menu the keys are no longer echoed while a command is busy, and
60
+ the spinner is cut to the terminal's width.
61
+
62
+ **The key goes into the OS vault by itself.** `connect` protects a new coupling's key with the macOS Keychain, Windows
63
+ Credential Manager or the Secret Service, and `update` moves a key still in its plain file once, after saying so
64
+ (`--keep-key-file` keeps the file). Where there is no vault, or over SSH, the private file stays and one line says how to
65
+ retry (`npx -y worktrust protect-key`). Reading the key never raises a system prompt.
66
+
5
67
  ## 0.11.11: faster file sending, another model in the same chat, and no release from a phone for Codex and OpenCode
6
68
 
7
69
  **Files travel faster.** Remote Agent checks and encodes a file's pieces without decoding them first and gives the
package/README.md CHANGED
@@ -67,7 +67,7 @@ computer in WorkTrust under Sources, Devices. More under [Undo](#undo).
67
67
  On a computer that is not connected yet:
68
68
 
69
69
  ```
70
- WorkTrust CLI 0.11.11
70
+ WorkTrust CLI 0.11.13
71
71
  Not connected yet
72
72
 
73
73
  > 1 Look at this computer npx worktrust look
@@ -84,13 +84,13 @@ On a computer that is not connected yet:
84
84
  Once it is connected (80 columns; on a wide terminal each row's sentence stands on the row itself, as a fourth column):
85
85
 
86
86
  ```
87
- WorkTrust CLI 0.11.11
87
+ WorkTrust CLI 0.11.13
88
88
  Account you@example.com
89
89
  This computer imac · connected since 2026-11-03
90
90
  Remote Agent approved, 2 connections
91
91
  Sharing session hook on · AI apps on (7) · Remote Agent approved
92
92
 
93
- 1 Update WorkTrust · up to date (0.11.11) npx worktrust update
93
+ 1 Update WorkTrust · up to date (0.11.13) npx worktrust update
94
94
  > 2 Check this computer npx worktrust
95
95
  3 Remote Agent › npx worktrust remote …
96
96
  4 Import earlier history › npx worktrust history …
@@ -113,6 +113,12 @@ switches that exist: `mcp off | on` and Remote Agent's pause. Remote Agent › C
113
113
  browser, and disconnecting one runs `remote disconnect` with its typed confirmation. Esc quits at the top and goes back
114
114
  one level below it.
115
115
 
116
+ **Esc stops a running command.** While a command the menu started is busy (counting, reading, sending, waiting for an
117
+ approval or a phone), Esc stops it and the menu says `Stopped. Enter: back to the menu · Esc: close`. A read or a wait
118
+ stops at once. A write is never cut in half: a stop that comes during one says `Finishing a write, then stopping…` and
119
+ the command ends the moment the write is whole. At a question the command's own keys apply, and Ctrl+C keeps its meaning.
120
+ Typed directly (`npx worktrust status`, no menu) Esc is not read and Ctrl+C stops the command as it always did.
121
+
116
122
  Every item shows the command it runs, so you can type it next time. Without a terminal (a script, a hook, the MCP door)
117
123
  there is no menu and nothing waits for a key.
118
124
 
@@ -132,7 +138,7 @@ there is no menu and nothing waits for a key.
132
138
  | `npx worktrust mcp off` | Hours only: the WorkTrust door out of every AI app here. The session hook keeps measuring. |
133
139
  | `npx worktrust mcp on` | The door back in, so your AI can log finished work. |
134
140
  | `npx worktrust mcp` | Says which of the two this computer is in. |
135
- | `npx worktrust protect-key` | After an update: moves the key's protection into the operating system's vault. Asks first. |
141
+ | `npx worktrust protect-key` | Moves the key's protection into the operating system's vault. Asks first. `connect` and `update` do it by themselves where the vault is there (`update --keep-key-file` keeps the file); this is the retry when it was not. |
136
142
  | `npx worktrust orchestration report --file recording.jsonl` | Inspects a local recording of agent metadata. Sends nothing. |
137
143
  | `npx worktrust mod` | The WorkTrust mod for Claude Code: what it counts and whether it is on. `mod install` turns it on, `mod remove` turns it off. |
138
144
  | `npx worktrust git` | Sends your own commits as counts and kinds, measured on this computer: never a file name, a message, code or the commit's id. Asks once. |
@@ -157,8 +163,9 @@ made; for any other repository a code that names nothing. The full list is in
157
163
 
158
164
  **What it never sends.** Your prompts, the AI's answers, your code, file contents or file paths.
159
165
 
160
- **Where the key lives.** In a private file on this computer, and after `protect-key` wrapped by the operating system's
161
- vault (Keychain, Credential Manager or the Secret Service). See [Credential protection](#credential-protection).
166
+ **Where the key lives.** Encrypted in a private file on this computer, its key in the operating system's vault
167
+ (Keychain, Credential Manager or the Secret Service): `connect` does this by itself, and `update` once. Where there is no
168
+ vault, or over SSH, the key stays in the private file and one line says so. See [Credential protection](#credential-protection).
162
169
 
163
170
  **What you can check.** The package has no dependencies and is published with provenance. Each release is signed, and the
164
171
  launcher checks the package's files against that signature before it starts. A signature shows that a release is ours. It
@@ -191,6 +198,14 @@ here with `remote modes allow`. The computer refuses a mode above what you allow
191
198
  **Sealed end to end.** The computer holds one outbound connection and opens no port. Messages are sealed between your
192
199
  phone and this computer; the relay passes them on and cannot read a prompt, a file, a path, an output or a model name.
193
200
 
201
+ **This computer's health, on your phone.** While Remote Agent runs, it reads a few numbers of this computer every 15
202
+ seconds, itself, with no model and no sudo: memory pressure, free memory, swap and how fast it grows, the CPU load per
203
+ core, the GPU's utilisation on Apple silicon, and the three programs using the most memory, by name only (never their
204
+ arguments, paths or window titles). The newest reading stays in `~/.worktrust/remote/health.json`; it goes sealed to
205
+ your linked phones and browsers only, and the relay keeps none of it. When memory runs out (critical pressure, or under
206
+ 5 % free while swap keeps growing), `remote status` and the menu say so in red, and a phone cannot start a new session
207
+ until it eases; sessions already running continue.
208
+
194
209
  A session steered from a phone is recorded as an agent run. It never counts as your AI Hours.
195
210
 
196
211
  The details: [Remote Agent: steer this computer's agents](#remote-agent-steer-this-computers-agents-from-your-phone-or-browser-npx-worktrust-remote).
@@ -616,10 +631,17 @@ the proof of possession the pairing binds, for nothing your record would gain.
616
631
 
617
632
  ## Credential protection
618
633
 
619
- Existing installations keep private file storage until the person opts in. From 0.10.26,
620
- run `worktrust update`, quit the AI apps, then run `worktrust protect-key` and restart
621
- those apps. A new computer can run `worktrust protect-key` before connecting. `worktrust status`
622
- shows the storage mode. This command is local and does not publish or change a Passport.
634
+ From 0.11.12 a new coupling stores the key this way by itself (`connect`, after the key is saved), and `update` moves
635
+ a key still in its plain file once, after saying so in its plan; `update --keep-key-file` keeps the file. Neither ever
636
+ fails over it: where the vault is not there or refuses, the private file stays exactly as it was and one line names
637
+ `npx -y worktrust protect-key` to try again. Over SSH, and on Linux without a desktop, it is not tried: the login
638
+ keychain or the secret collection can be locked there when an AI app later starts the hook, and a read never asks to
639
+ unlock, so the hook would stop measuring. Reading never raises a prompt: on macOS every read goes through
640
+ `/usr/bin/osascript`, the program that created the item, with user interaction off, whichever Node, npx cache or CLI
641
+ version asks. Quit and reopen your AI apps after an update (the update says so): an AI app still running a bridge older
642
+ than 0.10.26 cannot read a protected key until it restarts. `worktrust protect-key` remains the explicit command, and
643
+ a new computer can run it before connecting. `worktrust status` shows the storage mode. This is local and does not
644
+ publish or change a Passport.
623
645
 
624
646
  Protected mode encrypts the token, pending renewal token, device private key and coupling metadata
625
647
  with AES-256-GCM in `~/.worktrust/key.json`. Its random encryption key lives in macOS Keychain,
@@ -760,6 +782,11 @@ Off until you run `npx worktrust remote app` (or `remote web`) at this keyboard;
760
782
  told why.
761
783
  - One outbound connection to the WorkTrust gateway, end-to-end encrypted: the gateway relays sealed messages and reads no
762
784
  prompt, file, path, output or model name. No port is opened on this computer.
785
+ - Continue a session on this computer (0.11.13): the phone or the browser lists this computer's recent Claude Code
786
+ sessions in your granted folders (the last 20; per session only its id, the project, the last activity, a title of at
787
+ most 80 characters and the model, sealed end to end) and continues the one you pick with Claude Code's own `--resume`,
788
+ under the same rules as a session started from the phone. A session open here (written in the last 30 seconds, named
789
+ by a running Claude Code, or in a Claude Code window open in that folder) is refused until you close it here.
763
790
  - A session steered from a phone is never your AI Hours: the service records it in `~/.worktrust/remote/steered.jsonl`
764
791
  before the agent starts, and the session hook sends it as an agent run (`session_kind` headless, `steered_from`
765
792
  remote).
package/SECURITY.md CHANGED
@@ -29,13 +29,21 @@ private transcripts or account data in a public issue.
29
29
 
30
30
  ## Where the key is, and how long it lives
31
31
 
32
- - Existing installations use a private local file until explicit `worktrust protect-key` migration
33
- (0.10.26 and later). Base64 in that legacy file is not encryption.
32
+ - From 0.11.12 `connect` protects a new coupling's key by default and `update` migrates a plain file once (said in
33
+ its plan; `--keep-key-file` declines), through the same code path as `worktrust protect-key`. Where the OS store is
34
+ unavailable or refuses, in an SSH session or on Linux without a desktop (where a locked store would later stop the
35
+ hook, since reads never prompt), or when HOME is not the OS account's own home (the store belongs to the account, so
36
+ a key file elsewhere is never paired with it automatically), the private 0600 file stays unchanged and one line names
37
+ the retry command. Base64
38
+ in that plain file is not encryption.
34
39
  - Protected mode uses AES-256-GCM for all coupling secrets and OS storage for a separate random
35
40
  wrapping key: macOS Keychain, Windows Credential Manager with local-machine persistence, or
36
41
  Linux Secret Service. Only a random identifier, provider, nonce, ciphertext and authentication
37
42
  tag remain in `key.json`. Private file checks and atomic replacement still apply. Locked,
38
- missing or unavailable OS storage fails closed, without a new key or plaintext fallback.
43
+ missing or unavailable OS storage fails closed, without a new key or plaintext fallback. Reads never request
44
+ interaction: on macOS the item is created and read only by `/usr/bin/osascript` with user interaction disabled for
45
+ reads (the default access list trusts its creator), so a Node update, an npx cache path or a new CLI version does not
46
+ change the requesting program and cannot raise a Keychain prompt.
39
47
  - This is exportable software credential protection, not hardware attestation. Other software
40
48
  authorized as the OS user can request decryption; an attacker controlling the launcher or OS
41
49
  can bypass local checks. Local activity remains untrusted for independent public claims.
@@ -57,6 +65,30 @@ private transcripts or account data in a public issue.
57
65
  - Local `disconnect` is distinct from server revocation and archive deletion. Revoke through
58
66
  WorkTrust's device settings when the server credential must stop working.
59
67
 
68
+ ## Decoy credentials (the next release; owner 2026-11-15)
69
+
70
+ Beside the real coupling, `connect` (and `update`, once) writes credential files in `~/.worktrust` that look exactly like
71
+ the real one (the same legacy format: base64 of the same JSON with a `wt_` token, an Ed25519 device key, the dates, the
72
+ masked account), each with its own random token and key: `credentials.json`, `mcp-key.json`, `api-key.json`, `token.json`,
73
+ `auth.json`, and in file mode also `session-key.json`, `bridge-key.json`, `access-token.json`, `device-key.json`. None of
74
+ them is a backup of `key.json`: never restore one. If you restored a file from `~/.worktrust` yourself, run
75
+ `npx worktrust connect`.
76
+ Nothing in this package ever reads or sends them: the CLI, the session hook and the MCP bridge read only `key.json`. WorkTrust
77
+ receives only their SHA-256 hashes, once, signed by this computer's own key (`POST /api/cli/decoys`), and keeps them under
78
+ your account. The first time one of them is presented to WorkTrust, that computer's real coupling is revoked (reconnect
79
+ with `npx worktrust connect`), every Remote Agent link of your account (computers, phones, browsers) is cut at once, the
80
+ attempt is recorded and you get an e-mail naming the computer (one a day at most). A later use is recorded, never cuts
81
+ again. Deleting the computer in Sources retires its decoys.
82
+
83
+ - With protected credentials (`protect-key`, the OS keystore) the real secret is in no readable file: `key.json` is an
84
+ envelope that opens nowhere else, so every readable credential in the folder is a decoy (five of them) and a copy of
85
+ the folder can only trip the wire.
86
+ - In file mode the real `key.json` stays readable beside nine decoys. Its name is the one this open-source package reads,
87
+ so someone who reads the code knows which is real; the decoys catch a copy used without that care (a file picked blind is
88
+ a decoy nine times in ten; trying them all always trips). Protect your key: that is the real protection.
89
+ - The decoys are written only after WorkTrust confirmed their hashes, and never trip on your own use. Deleting them is
90
+ harmless; `update` writes them again only when none are present.
91
+
60
92
  ## What you agreed to: `~/.worktrust/consent.json` (0.10.30)
61
93
 
62
94
  - One private file (mode 0600, written through the same exclusive-temp, atomic-replace path as the credential file,
@@ -232,6 +264,13 @@ What it is: standing remote execution of AI agents on this computer, steered fro
232
264
  grant only folders whose code you trust. The phone's keys are on the phone: until you revoke it, whoever unlocks it can
233
265
  steer agents within these rules. macOS asks for folder access per program, so the access you grant the service's `node`
234
266
  covers every script that `node` runs.
267
+ - Continuing a desk session (0.11.13). The daemon reads Claude Code's transcript folders of granted projects only (the
268
+ encoded folder of each granted path, never the whole store; a transcript whose recorded folder is another is dropped),
269
+ at most the first and last 64 KB of a file, and sends per session only its id, the project's id, the last activity, an
270
+ 80-character title and the model, sealed, to a phone that asked. A resume is refused unless the id is in that list,
271
+ under the project named, and nothing on this computer holds it (`ps`, and `lsof` or /proc for a window's folder; a
272
+ process list it cannot read counts as holding it). The title is the first line typed when Claude Code wrote no summary:
273
+ what you typed first in a session reaches your own phones and browsers.
235
274
  - Hours. A remote-steered session is never your AI Hours (see README).
236
275
 
237
276
  ## Python distribution and explicit agent observations
package/cli-colour.mjs CHANGED
@@ -68,11 +68,15 @@ const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "
68
68
  * A spinner in the accent colour while something runs: → stop(). Only on a real terminal with colours on; anywhere else it
69
69
  * writes nothing at all, so a pipe, a hook and CI read the same bytes as before. stop() removes the line it drew.
70
70
  * It draws on the line the cursor is on, which must be empty: start it between lines, never in the middle of one.
71
+ * ONE LINE, ALWAYS (0.11.12, owner 2026-11-15: the line stood twice): each frame is cut to the terminal's width less one
72
+ * column, read again at every frame, so a line never wraps and `\r` always lands on the spinner's own line. A key the
73
+ * terminal ECHOES is the other way down a line (an Enter is CR LF on the screen); a command the menu started reads keys in
74
+ * raw mode while a spinner turns, so nothing is echoed there (cli-stop.mjs watchKeys).
71
75
  */
72
76
  export function spinner(words, { stream = process.stdout, paint = coloursFor(stream), interval = 80, delay = 150 } = {}) {
73
77
  if (!paint.on || !stream?.isTTY) return () => {};
74
78
  let at = 0, shown = false, stopped = false, timer = null;
75
- const frame = () => { shown = true; stream.write(`\r ${paint.accent(FRAMES[at % FRAMES.length])} ${paint.dim(words)}\x1b[K`); at += 1; };
79
+ const frame = () => { shown = true; stream.write(`\r ${paint.accent(FRAMES[at % FRAMES.length])} ${paint.dim(clip(words, Math.max(1, (stream.columns || 80) - 5)))}\x1b[K`); at += 1; };
76
80
  // Work that ends at once shows no spinner at all: a line that flashes is worse than none.
77
81
  const wait = setTimeout(() => { frame(); timer = setInterval(frame, interval); timer.unref?.(); }, delay);
78
82
  wait.unref?.();
package/cli-look.mjs CHANGED
@@ -165,6 +165,7 @@ export function lookItems(connected = false) {
165
165
  export async function lookMenu(term, io, levels) {
166
166
  const menu = await import("./cli-menu.mjs");
167
167
  const code = await menu.runShown(term, io, ["look"], null, { pause: false });
168
+ if (typeof code === "boolean") return code; // stopped with Esc (0.11.12): Enter is the menu, Esc closes it
168
169
  if (code !== 0) { term.write(`\n ! It ended with a message above. ${menu.muted("Press any key for the menu.")}\n`); const k = await term.anyKey(); return !(k.ctrl && k.name === "c"); }
169
170
  const picked = await menu.choose(term, { title: "What next", items: lookItems(false) });
170
171
  if (picked === "quit") return false;
@@ -11,9 +11,10 @@ import { homedir } from "node:os";
11
11
  import { join } from "node:path";
12
12
  import { choose, muted, remoteState, runShown, typed } from "./cli-menu.mjs";
13
13
  import { makeProjectsFolder, pickFolder, pickerCommand, suggestedFolders } from "./folder-picker.mjs";
14
- import { connections } from "./remote-connections.mjs";
14
+ import { awaitingName, awaitingRow, connections } from "./remote-connections.mjs";
15
15
  import { loadIdentity, loadProjects, loadRoots, loadSettings } from "./remote-store.mjs";
16
16
  import { allowedModes } from "./remote-settings.mjs";
17
+ import { HEALTH_REFUSAL, keptHealth } from "./remote-health.mjs";
17
18
 
18
19
  const BACK = { label: "← Back", hint: "Esc", back: true }; // its name and its key say it: no sentence of its own (owner, 2026-11-14)
19
20
  const tilde = (path) => (path.startsWith(homedir()) ? `~${path.slice(homedir().length)}` : path);
@@ -211,7 +212,11 @@ export async function remoteMenu(term, io, header) {
211
212
  const approved = approval(), paused = (() => { try { return loadSettings().paused !== null; } catch { return false; } })();
212
213
  // The two roads; one that leaves this computer approved returns to the list above, which now opens on Link a phone.
213
214
  const road = (which) => async () => ((await runShown(term, io, ["remote", which, ...(approved ? ["--repair"] : [])])) === false ? false : approved === false && approval() === true ? "back" : true);
214
- return remoteItems(approved, paused, {
215
+ // 0.11.12: a linked phone with no reach chosen yet is said first, and its row opens the access step (awaitingRow).
216
+ const waiting = state?.remoteAccess === "premium_required" ? null : awaitingName();
217
+ // HEAVY MEMORY LOAD (remote-health.mjs): the remote service's newest sample, red, is said first, in red; Enter shows the figures.
218
+ const red = keptHealth()?.level === "red" ? [{ label: "Health: heavy memory load", note: { text: "red", tone: "red" }, hint: "npx worktrust remote status", info: `${HEALTH_REFUSAL}. New sessions wait; running ones continue. Enter shows the figures.`, run: () => runShown(term, io, ["remote", "status"]) }] : [];
219
+ return [...red, ...(waiting ? [awaitingRow(waiting, (args) => runShown(term, io, args))] : []), ...remoteItems(approved, paused, {
215
220
  approve: () => level(term, header, approved ? "Approve this computer again (new keys)" : "Approve this computer", () => [
216
221
  { label: "With the WorkTrust app", hint: `npx worktrust remote app${approved ? " --repair" : ""}`, info: "One QR: the app approves and links this phone.", run: road("app") },
217
222
  { label: "In the browser", hint: `npx worktrust remote web${approved ? " --repair" : ""}`, info: "Opens WorkTrust in your browser, where you approve.", run: road("web") },
@@ -222,7 +227,7 @@ export async function remoteMenu(term, io, header) {
222
227
  pause: () => runShown(term, io, ["remote", paused ? "resume" : "pause"]),
223
228
  status: () => runShown(term, io, ["remote", "status"]),
224
229
  upgrade: () => showUpgrade(term, io, state?.upgrade ?? null), upgradeHint: state?.upgrade ? String(state.upgrade).replace(/^https?:\/\//, "") : undefined,
225
- }, state?.remoteAccess ?? null);
230
+ }, state?.remoteAccess ?? null)];
226
231
  }, reading);
227
232
  }
228
233
 
package/cli-menu.mjs CHANGED
@@ -8,7 +8,7 @@
8
8
  * Each item runs the direct command it shows in its muted line, as a child of this CLI with the terminal handed over
9
9
  * (io.runCli), so people learn the short form and every command keeps its own questions and its own guards. Keys: ↑/↓
10
10
  * move, Enter opens, Esc or ← goes back one level, q quits from the top, 1 to 9 jump, Ctrl+C quits. Raw mode and the
11
- * cursor are restored on every way out (quit, Ctrl+C, an error).
11
+ * cursor are restored on every way out (quit, Ctrl+C, an error). 0.11.12: Esc while a command runs stops it (cli-stop.mjs).
12
12
  *
13
13
  * 0.11.8 (owner, 2026-11-13): Update comes first and says whether there is something to update; every item carries one plain
14
14
  * sentence under it; the menu is redrawn IN PLACE (createTerminal) and never left in the scrollback; colours carry meaning
@@ -28,8 +28,9 @@
28
28
  import { emitKeypressEvents } from "node:readline";
29
29
  import { createInterface } from "node:readline/promises";
30
30
  import { busyWith, clip, coloursFor, visibleLength } from "./cli-colour.mjs";
31
+ import { STOPPED } from "./cli-stop.mjs";
31
32
  import { loadIdentity, loadPhones, loadSettings } from "./remote-store.mjs";
32
-
33
+ import { awaitingName, awaitingRow } from "./remote-connections.mjs";
33
34
  /** Whether bare `npx worktrust` opens the menu here. Pure: the caller passes what it knows. */
34
35
  export function menuWanted({ args: given = [], env = {}, stdinTTY = false, stdoutTTY = false, agentShell = null } = {}) {
35
36
  const args = given.filter((arg) => arg !== "--no-color" && arg !== "--no-colour"); // how it looks, not what it does
@@ -167,8 +168,7 @@ export async function typed(term, question, value = "") {
167
168
  return text || null;
168
169
  }
169
170
 
170
- /** While a command runs, Ctrl+C is the command's (it reaches the child too); the menu stays. */
171
- let busy = false;
171
+ let busy = false; // while a command runs, Ctrl+C is the command's (it reaches the child too) and Esc stops it (cli-stop.mjs); the menu stays
172
172
 
173
173
  /**
174
174
  * Run one direct command with the terminal handed over, then wait for a key before the menu comes back. The menu's own
@@ -183,12 +183,19 @@ export async function runShown(term, io, args, label = null, { pause = true } =
183
183
  let code = 1;
184
184
  try { code = await io.runCli(args); } catch { code = 1; } finally { busy = false; }
185
185
  term.enter();
186
+ if (code === STOPPED) return stoppedAsk(term); // Esc stopped it (0.11.12): true is the menu again, false closes it
186
187
  if (!pause) return code;
187
188
  term.write(`\n ${code === 0 ? paint.green("✓ Done.") : paint.yellow("! It ended with a message above.")} ${muted("Press any key for the menu.")}\n`);
188
189
  const k = await term.anyKey();
189
190
  return !(k.ctrl && k.name === "c");
190
191
  }
191
192
 
193
+ /** STOPPED WITH ESC (0.11.12, owner 2026-11-15; cli-stop.mjs): one line; Enter is the menu, Esc (or Ctrl+C) closes it. */
194
+ export async function stoppedAsk(term) {
195
+ term.write(`\n ${paint.yellow("Stopped.")} ${muted("Enter: back to the menu · Esc: close")}\n`);
196
+ for (;;) { const k = await term.anyKey(); if (k.name === "return" || k.name === "enter") return true; if (k.name === "escape" || (k.ctrl && k.name === "c")) return false; }
197
+ }
198
+
192
199
  /** What the Remote Agent item says where this Node has no WebSocket; Enter opens the ways forward (node-guide.mjs). */
193
200
  export const REMOTE_NEEDS = "Needs Node 22.4 or later. Enter shows the ways to get it.";
194
201
 
@@ -244,8 +251,7 @@ export function headerLines(state) {
244
251
  /** The account's plan in words (owner, 2026-11-14), as WorkTrust answered it; anything else, or no answer, is "not known". */
245
252
  const PLAN_WORDS = { free: "Free", premium: "Premium" };
246
253
  const HELP = (open) => ({ label: "Help · all commands", hint: "npx worktrust help", info: "Lists all commands. npx -y worktrust skips npm's question.", run: () => open(["help"]) });
247
- const QUIT = { label: "Quit", hint: "q", info: "Leaves the menu. Nothing keeps running.", quit: true };
248
- const PRESERVE = (sub, info) => ({ label: "Preserve evidence ›", hint: "npx worktrust preserve …", info, run: () => sub.preserve?.() });
254
+ const QUIT = { label: "Quit", hint: "q", info: "Leaves the menu. Nothing keeps running.", quit: true }, PRESERVE = (sub, info) => ({ label: "Preserve evidence ›", hint: "npx worktrust preserve …", info, run: () => sub.preserve?.() });
249
255
  /** 0.11.10 (owner, 2026-11-14): the first row before sign-in; the table, then what to do with it (cli-look.mjs lookMenu). */
250
256
  const LOOK = (sub) => ({ label: "Look at this computer", hint: "npx worktrust look", info: "Reads what your AI apps recorded here. Nothing is sent.", run: () => sub.look?.() });
251
257
 
@@ -267,7 +273,7 @@ export function firstItems(open = () => true, sub = {}) {
267
273
  /** Why the first menu still stands after Connect ran, in one line, by how the command ended (0 without a key: a No or a dry run). */
268
274
  export function connectReason(code) {
269
275
  if (code === 0) return "Connect stopped before the sign-in; nothing was written. 2 tries again.";
270
- if (code === 130) return "Connect was cancelled; this computer is not connected. 2 tries again.";
276
+ if (code === 130 || code === STOPPED) return "Connect was cancelled; this computer is not connected. 2 tries again.";
271
277
  return "Connect ended with the message above; not connected. 2 tries again.";
272
278
  }
273
279
 
@@ -285,7 +291,7 @@ export function topItems(state, open = () => true, sub = {}) {
285
291
  : same ? "Newest version not checked. Enter changes nothing here."
286
292
  : "Sets up this computer's hook and AI-app doors again.";
287
293
  return [
288
- { label: "Update WorkTrust", note, hint: "npx worktrust update", info: updateInfo, run: () => open(["update"]), ...(note.settled ? { disabled: true, quiet: "Already up to date." } : {}) },
294
+ ...(state.awaiting ? [awaitingRow(state.awaiting, open)] : []), { label: "Update WorkTrust", note, hint: "npx worktrust update", info: updateInfo, run: () => open(["update"]), ...(note.settled ? { disabled: true, quiet: "Already up to date." } : {}) },
289
295
  { label: "Check this computer", hint: "npx worktrust", info: "Shows what is coupled here and finishes what waits.", run: () => open([]) },
290
296
  // Node before 22.4 has no WebSocket (0.11.8): the item stays, says why, and Enter opens the ways forward, not the levels.
291
297
  state.remoteBlocked
@@ -308,7 +314,7 @@ export function topItems(state, open = () => true, sub = {}) {
308
314
  */
309
315
  export async function menuLoop(term, io, levels) {
310
316
  let last = null, state = null; // the command the top level ran last and how it ended; this computer's state as last read
311
- const read = async () => (state = { ...(await busyWith("Reading this computer's state", () => io.state())), remoteBlocked: typeof globalThis.WebSocket !== "function" });
317
+ const read = async () => (state = { ...(await busyWith("Reading this computer's state", () => io.state())), remoteBlocked: typeof globalThis.WebSocket !== "function", awaiting: awaitingName() });
312
318
  // A deeper level reads the state again after each of its commands (inner.state), so the head above it is true at once.
313
319
  const inner = { runCli: (args) => io.runCli(args), state: read, openUrl: (url) => io.openUrl?.(url) };
314
320
  for (;;) {
package/cli-stop.mjs ADDED
@@ -0,0 +1,158 @@
1
+ /**
2
+ * STOP WITH ESC (CLI 0.11.12, owner 2026-11-15: "while a command is running, stop it early with Esc: then it stops and you
3
+ * get a message: go back to the menu, or press Esc to close"). Two halves, one file, no dependency.
4
+ *
5
+ * THE CHILD (a command the MENU started: WORKTRUST_MENU_CHILD=1 and an IPC channel to the menu, cli-menu.mjs runShown).
6
+ * Only while the command shows it is busy (a spinner, the history progress line, the approval's countdown, the phone link
7
+ * wait) does it read keys, in raw mode: Esc tells the menu, which stops the command (below); Ctrl+C keeps its meaning (the
8
+ * command's own SIGINT path). Raw mode there also means a key typed while a spinner turns is never ECHOED by the terminal:
9
+ * an echoed Enter moved the cursor down a line, and the spinner's `\r` went on drawing on the new line while the old frame
10
+ * stayed above (the doubled "Counting what this computer measured", owner 2026-11-15; reproduced under a pty). Everywhere
11
+ * else the command reads the terminal as before: its questions are its own and no key is taken from them.
12
+ *
13
+ * WHAT A STOP DOES, by what the command is doing (the stop is SIGINT, SIGTERM later; on Windows the menu's IPC "stop"):
14
+ * reading, waiting it ends at once (exit 130); the scripts it started for the read are ended with it. A wait for an
15
+ * approval or a phone ends its request (the phone link's invite is removed, remote-connections.mjs).
16
+ * writing inside critical() a stop is held: one line "Finishing a write, then stopping…", the menu is told to
17
+ * wait, and the command exits 130 the moment the write step is whole. A file is never left half-written.
18
+ * its own safe stop a command that already stops safely on SIGINT (the history send, preserve, the phone link) keeps
19
+ * that path; the menu is told to wait for it.
20
+ * A menu child holds the stop handler for its whole life, so a stop lands between two steps, never inside a synchronous one
21
+ * (Node runs a signal handler on its event loop). The exception is a command that only reads and asks nothing (status, look,
22
+ * help: WORKTRUST_MENU_KEYS=menu): the MENU reads its keys, and outside a busy phase a stop ends it at once, mid-read.
23
+ * Direct use (`npx worktrust <command>`, no menu) is untouched: no raw mode, no key read, Ctrl+C exactly as before.
24
+ *
25
+ * THE MENU (superviseChild): on the child's "esc" it sends SIGINT; when the child is still there after a short grace and has
26
+ * not said it is finishing a write, SIGTERM, then SIGKILL as the last resort. A child finishing a write is given up to a
27
+ * minute before that last resort; every file the CLI writes is replaced whole (temp file, then rename), so even then no file
28
+ * is half one version and half the other.
29
+ */
30
+ export const STOPPED = -130; // what the menu's runCli answers for a command stopped with Esc: never a real exit code
31
+
32
+ const env = process.env;
33
+ const MENU_CHILD = env.WORKTRUST_MENU_CHILD === "1" && typeof process.send === "function";
34
+ const MENU_KEYS = MENU_CHILD && env.WORKTRUST_MENU_KEYS === "menu"; // a read-only command: the menu reads its keys
35
+ const ALWAYS = MENU_CHILD && !MENU_KEYS; // the stop handler stands for the whole command
36
+ const tell = (message) => { try { process.send?.(message); } catch { /* the menu is gone */ } };
37
+
38
+ const children = new Set();
39
+ /** A script this command started; a stop during a read or a wait ends it with the command. */
40
+ export function track(child) { children.add(child); child.once?.("exit", () => children.delete(child)); return child; }
41
+
42
+ let writing = 0, watching = 0, wanted = false, said = false, input = null, raw = false;
43
+ function restore() {
44
+ if (raw && input) { try { input.setRawMode(false); } catch { /* gone */ } raw = false; }
45
+ try { process.stdout.write("\r\x1b[K\x1b[?25h"); } catch { /* closed */ }
46
+ }
47
+ function end() {
48
+ for (const child of children) { try { child.kill("SIGTERM"); } catch { /* gone */ } }
49
+ restore();
50
+ process.exit(130);
51
+ }
52
+ function onStop() {
53
+ if (writing > 0) {
54
+ wanted = true;
55
+ tell({ wt: "finishing" });
56
+ if (!said) { said = true; process.stderr.write("\r\x1b[K Finishing a write, then stopping…\n"); }
57
+ return;
58
+ }
59
+ if (process.listenerCount("SIGINT") > 1) { tell({ wt: "finishing" }); return; } // the command's own safe stop runs
60
+ end();
61
+ }
62
+ const listen = () => { if (!ALWAYS && writing + watching === 1) { process.on("SIGINT", onStop); process.on("SIGTERM", onStop); } };
63
+ const unlisten = () => { if (!ALWAYS && writing + watching === 0) { process.off("SIGINT", onStop); process.off("SIGTERM", onStop); } };
64
+ if (MENU_CHILD) {
65
+ process.channel?.unref?.(); // the channel never keeps a finished command alive
66
+ // Windows has no SIGINT for one process: the menu's "stop" is the same stop.
67
+ process.on("message", (message) => { if (message?.wt === "stop") { if (process.listenerCount("SIGINT") > 0) process.emit("SIGINT", "SIGINT"); else process.exit(130); } });
68
+ process.on("exit", () => { if (raw && input) { try { input.setRawMode(false); } catch { /* gone */ } } }); // never leave the terminal raw
69
+ if (ALWAYS) { process.on("SIGINT", onStop); process.on("SIGTERM", onStop); }
70
+ }
71
+
72
+ /** Run one write step whole: a stop that comes during it waits for its end (menu children only; elsewhere it just runs). */
73
+ export async function critical(work) {
74
+ if (!MENU_CHILD) return work();
75
+ writing += 1; listen();
76
+ try { return await work(); }
77
+ finally { writing -= 1; unlisten(); if (writing === 0 && wanted) end(); }
78
+ }
79
+
80
+ /**
81
+ * Read keys while the command is busy: → release(). Esc asks the menu to stop the command; Ctrl+C is the command's SIGINT,
82
+ * as in a terminal (raw mode turns the terminal's own Ctrl+C off). Any other key is swallowed, never echoed. No-op outside
83
+ * a menu child or without a terminal.
84
+ */
85
+ export function watchKeys(stream = process.stdin) {
86
+ if (!MENU_CHILD) return () => {};
87
+ watching += 1; listen();
88
+ if (MENU_KEYS || !stream?.isTTY) { let done = false; return () => { if (!done) { done = true; watching -= 1; unlisten(); } }; } // the menu reads the keys
89
+ const first = watching === 1;
90
+ const onData = (chunk) => {
91
+ const text = String(chunk);
92
+ if (/^\x1b+$/.test(text)) tell({ wt: "esc" }); // a lone Esc: an arrow key is ESC [ A, one chunk
93
+ else if (text.includes("\x03")) process.emit("SIGINT", "SIGINT");
94
+ };
95
+ if (first) { input = stream; try { stream.setRawMode(true); raw = true; } catch { raw = false; } stream.resume(); }
96
+ stream.on("data", onData);
97
+ let released = false;
98
+ return () => {
99
+ if (released) return;
100
+ released = true;
101
+ stream.off("data", onData);
102
+ watching -= 1;
103
+ if (watching === 0) { if (raw) { try { stream.setRawMode(false); } catch { /* gone */ } raw = false; } stream.pause(); input = null; }
104
+ unlisten();
105
+ };
106
+ }
107
+
108
+ /** `work` with keys watched for its whole length; released also when it fails. */
109
+ export async function watched(work) {
110
+ const release = watchKeys();
111
+ try { return await work(); } finally { release(); }
112
+ }
113
+
114
+ /** Whether this process is a command the menu started (for a script it starts: pass the channel on, or not). */
115
+ export const menuChild = () => MENU_CHILD;
116
+
117
+ /**
118
+ * THE MENU'S SIDE: watch one child. → { stopped() }: whether Esc stopped it. `kill` and `timers` are for the tests.
119
+ * Grace: SIGINT, then SIGTERM after `grace`, then SIGKILL after another `grace`; a child that said it is finishing a write
120
+ * gets `ceiling` before SIGKILL instead.
121
+ */
122
+ export function superviseChild(child, { platform = process.platform, grace = 1500, ceiling = 60_000, timers = { setTimeout, clearTimeout } } = {}) {
123
+ let asked = false, finishing = false, alive = true, timer = null;
124
+ const later = (ms, then) => { timers.clearTimeout(timer); timer = timers.setTimeout(then, ms); timer?.unref?.(); };
125
+ const kill = (signal) => { if (!alive) return; try { child.kill(signal); } catch { /* gone */ } };
126
+ const last = () => kill("SIGKILL");
127
+ const escalate = () => { if (!alive) return; if (finishing) { later(ceiling, last); return; } kill("SIGTERM"); later(grace, last); };
128
+ const stop = () => {
129
+ if (asked || !alive) return;
130
+ asked = true;
131
+ if (platform === "win32") { try { child.send({ wt: "stop" }); } catch { kill("SIGTERM"); } }
132
+ else kill("SIGINT");
133
+ later(grace, escalate);
134
+ };
135
+ child.on("message", (message) => { if (message?.wt === "finishing") finishing = true; if (message?.wt === "esc") stop(); });
136
+ child.once("exit", () => { alive = false; timers.clearTimeout(timer); });
137
+ return { stopped: () => asked, stop };
138
+ }
139
+
140
+ /**
141
+ * The menu reading the keys itself, for a command that only reads and asks nothing (WORKTRUST_MENU_KEYS=menu): Esc is
142
+ * `onEsc`, Ctrl+C is `onCtrlC` (raw mode turns the terminal's own off); → release(). Without a terminal: nothing.
143
+ */
144
+ export function menuKeys(stream, { onEsc, onCtrlC }) {
145
+ if (!stream?.isTTY) return () => {};
146
+ const onData = (chunk) => { const text = String(chunk); if (/^\x1b+$/.test(text)) onEsc(); else if (text.includes("\x03")) onCtrlC(); };
147
+ try { stream.setRawMode(true); } catch { return () => {}; }
148
+ stream.on("data", onData); stream.resume();
149
+ return () => { stream.off("data", onData); try { stream.setRawMode(false); } catch { /* gone */ } stream.pause(); };
150
+ }
151
+
152
+ /** The commands the menu starts that only read and ask nothing: the menu reads their keys, so Esc stops even a busy read. */
153
+ export function readsOnly(args) {
154
+ const [first = "", second = "", third = ""] = args.filter((arg) => !arg.startsWith("--")), flags = args.filter((arg) => arg.startsWith("--"));
155
+ if (["status", "look", "help", "version"].includes(first) && second === "") return true;
156
+ if (first === "remote" && (second === "status" || (second === "modes" && third === "status"))) return true;
157
+ return first === "preserve" && second === "" && flags.every((flag) => ["--verify", "--summary"].includes(flag)) && flags.length <= 1;
158
+ }