ccdeck 3.82.3 → 4.0.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 (146) hide show
  1. package/LICENSING.md +42 -4
  2. package/README.md +183 -72
  3. package/THIRD_PARTY_NOTICES.md +243 -17
  4. package/bin/cli/login-item.js +5 -0
  5. package/bin/cli/tui.js +58 -4
  6. package/bin/deck.js +27 -1
  7. package/dist/web/assets/AccountBridge-OQHT5qmS.js +1 -0
  8. package/dist/web/assets/AccountSection-BpIHPhF3.js +1 -0
  9. package/dist/web/assets/BrowserWatchModal-DBdt52v7.js +1 -0
  10. package/dist/web/assets/FeedbackConversations-BJjgXI0-.js +1 -0
  11. package/dist/web/assets/IntegrationModal-DQ0vEz4X.js +7 -0
  12. package/dist/web/assets/IntegrationSkeleton-JCPbqp96.js +1 -0
  13. package/dist/web/assets/RadioPanel-Be6AkrKl.js +1 -0
  14. package/dist/web/assets/StageShell-Dq0JOQhd.js +4 -0
  15. package/dist/web/assets/TrafficRadar-7jqJbhaK.js +8 -0
  16. package/dist/web/assets/UsageHistoryModal-ckawZGoe.js +1 -0
  17. package/dist/web/assets/addon-unicode-graphemes-DW3WJwyh.js +18 -0
  18. package/dist/web/assets/addon-web-links-BWjmmSgS.js +12 -0
  19. package/dist/web/assets/addon-webgl-CLK4R-_u.js +75 -0
  20. package/dist/web/assets/app-40gNTTfq.js +361 -0
  21. package/dist/web/assets/app-BRjYF6oD.css +1 -0
  22. package/dist/web/assets/{index-B4c5MZCc.js → index-XIY3yFiN.js} +1 -1
  23. package/dist/web/assets/inspector-status-pane-BV_m7eBv.js +1 -0
  24. package/dist/web/assets/screens-9_ivqfcF.js +12 -0
  25. package/dist/web/assets/screens-DUniTTbC.css +1 -0
  26. package/dist/web/assets/stage-board-NF_wgGRA.js +2 -0
  27. package/dist/web/assets/use-account-BUmI-A8e.js +1 -0
  28. package/dist/web/assets/xterm-4jYizCpg.js +27 -0
  29. package/dist/web/assets/xterm-sheet-6GBZ9nXN.css +32 -0
  30. package/dist/web/index.html +16 -6
  31. package/package.json +13 -1
  32. package/release-notes.json +79 -0
  33. package/src/server/account-client.mjs +196 -0
  34. package/src/server/account-connect.mjs +238 -0
  35. package/src/server/account-flag.mjs +106 -0
  36. package/src/server/account-projects.mjs +1 -1
  37. package/src/server/account-service.mjs +532 -0
  38. package/src/server/account-status.mjs +293 -0
  39. package/src/server/account-store.mjs +137 -0
  40. package/src/server/account-sync.mjs +473 -0
  41. package/src/server/account-token-store.mjs +216 -0
  42. package/src/server/account-ui-fields.mjs +126 -0
  43. package/src/server/account-watch.mjs +1 -1
  44. package/src/server/browser-watch-log.mjs +1 -1
  45. package/src/server/browser-watch-store.mjs +1 -1
  46. package/src/server/ccdeck-account-routes.mjs +252 -0
  47. package/src/server/ccusage-install.mjs +2 -2
  48. package/src/server/ccusage-registry.mjs +4 -4
  49. package/src/server/ccusage-session.mjs +11 -0
  50. package/src/server/claude-accounts.mjs +1 -1
  51. package/src/server/claude-recovery.mjs +9 -4
  52. package/src/server/claude-settings-catalog.mjs +6 -6
  53. package/src/server/claude-settings.mjs +1 -1
  54. package/src/server/codex-auto.mjs +1 -1
  55. package/src/server/codex-cost-usage.mjs +7 -2
  56. package/src/server/codex-live-checkpoint.mjs +24 -9
  57. package/src/server/codex-live-engine.mjs +14 -4
  58. package/src/server/codex-live-handoff.mjs +53 -9
  59. package/src/server/codex-names.mjs +49 -0
  60. package/src/server/codex-translate.mjs +1 -1
  61. package/src/server/codex-ultrafast.d.mts +3 -0
  62. package/src/server/codex-ultrafast.mjs +5 -0
  63. package/src/server/codex-watch.mjs +25 -0
  64. package/src/server/command-panel-engine.mjs +300 -0
  65. package/src/server/command-panel-platform.mjs +99 -0
  66. package/src/server/cswap-auto-choice.mjs +1 -1
  67. package/src/server/cswap-auto-loop.mjs +1 -1
  68. package/src/server/cswap-install.mjs +21 -40
  69. package/src/server/deck-home.mjs +6 -0
  70. package/src/server/deck-prefs.mjs +53 -1
  71. package/src/server/detach.mjs +1 -1
  72. package/src/server/engine-download.mjs +277 -0
  73. package/src/server/engine-install.mjs +378 -0
  74. package/src/server/engine-package.mjs +267 -0
  75. package/src/server/event-log.mjs +7 -1
  76. package/src/server/event-pipeline.mjs +29 -1
  77. package/src/server/ghostty-handoff.mjs +81 -0
  78. package/src/server/index.mjs +143 -5
  79. package/src/server/installer.mjs +4 -1
  80. package/src/server/integrations/jira-write-guard.mjs +14 -208
  81. package/src/server/integrations/store.mjs +37 -19
  82. package/src/server/integrations/write-guard.mjs +223 -0
  83. package/src/server/intel-cpu-temperature.mjs +26 -0
  84. package/src/server/lifecycle.mjs +69 -6
  85. package/src/server/log-replay.mjs +4 -0
  86. package/src/server/login-service.mjs +116 -14
  87. package/src/server/macmon.mjs +1 -1
  88. package/src/server/npm-latest.mjs +1 -1
  89. package/src/server/org-telemetry.mjs +1 -1
  90. package/src/server/output-watch.mjs +4 -1
  91. package/src/server/panel-provenance.mjs +390 -0
  92. package/src/server/pinned-build.mjs +14 -0
  93. package/src/server/prefs-refusal.mjs +8 -1
  94. package/src/server/prefs-routes.mjs +60 -11
  95. package/src/server/pro-engine-client.mjs +339 -0
  96. package/src/server/pro-engine-install.mjs +294 -0
  97. package/src/server/pro-engine-terminal.mjs +308 -0
  98. package/src/server/project-discovery.mjs +139 -0
  99. package/src/server/provider-session-name.mjs +58 -0
  100. package/src/server/quota-closes.mjs +1 -1
  101. package/src/server/quota-history.mjs +1 -1
  102. package/src/server/reports.mjs +86 -21
  103. package/src/server/request-gates.mjs +34 -5
  104. package/src/server/restart-note.mjs +1 -1
  105. package/src/server/seed-boundary.mjs +489 -0
  106. package/src/server/session-counts.mjs +244 -0
  107. package/src/server/session-deck-names.mjs +143 -0
  108. package/src/server/session-enrichment.mjs +43 -6
  109. package/src/server/session-name-route.mjs +73 -0
  110. package/src/server/session-summary.mjs +12 -1
  111. package/src/server/session-transcript-routes.mjs +167 -0
  112. package/src/server/swap-log.mjs +1 -1
  113. package/src/server/system-metrics.mjs +57 -0
  114. package/src/server/terminal-bridge.mjs +485 -0
  115. package/src/server/terminal-folder.mjs +61 -0
  116. package/src/server/terminal-js-routes.mjs +752 -0
  117. package/src/server/terminal-routes.mjs +553 -0
  118. package/src/server/terminal-sessions.mjs +759 -0
  119. package/src/server/terminal-socket.mjs +403 -0
  120. package/src/server/terminal-target.mjs +928 -0
  121. package/src/server/thermal-metrics.mjs +13 -9
  122. package/src/server/tmux-control.mjs +1319 -0
  123. package/src/server/tmux-download.mjs +220 -0
  124. package/src/server/tmux.mjs +542 -0
  125. package/src/server/token-redact.mjs +42 -3
  126. package/src/server/tool-audit-report.mjs +44 -6
  127. package/src/server/tool-audit-routes.mjs +12 -1
  128. package/src/server/tool-audit.mjs +42 -8
  129. package/src/server/traffic-radar-monitor.mjs +1 -1
  130. package/src/server/traffic-radar-permission.mjs +1 -1
  131. package/src/server/transcript-gate.mjs +1 -1
  132. package/src/server/transcript-scan.mjs +15 -7
  133. package/src/server/transcript-turns.mjs +154 -0
  134. package/src/server/tui-network.mjs +1 -0
  135. package/src/server/tui-view.mjs +28 -0
  136. package/src/server/utf8-carry.mjs +159 -0
  137. package/src/server/uv-bootstrap.mjs +2 -2
  138. package/src/server/windows-acl.mjs +158 -0
  139. package/src/server/ws-frames.mjs +690 -0
  140. package/dist/web/assets/BrowserWatchModal-BmRTh_xT.js +0 -1
  141. package/dist/web/assets/IntegrationModal-C_f526aV.js +0 -7
  142. package/dist/web/assets/RadioPanel-D2rkf9cg.js +0 -1
  143. package/dist/web/assets/TrafficRadar-BOgVBLIN.js +0 -8
  144. package/dist/web/assets/UsageHistoryModal-BJPTFwM9.js +0 -1
  145. package/dist/web/assets/app-CbXmr9rC.css +0 -1
  146. package/dist/web/assets/app-DZdZoqJ6.js +0 -358
@@ -0,0 +1,300 @@
1
+ // The one place the deck makes the Command Panel's engine: the optional local
2
+ // engine, started for the panel only once somebody has switched the panel on
3
+ // and asked it something, on the platforms it runs on (Linux, macOS and Windows).
4
+ //
5
+ // NOTHING HAPPENS UNTIL A ROUTE ASKS. Importing this does no I/O. The routes
6
+ // (terminal-routes.mjs) ask only while the panel's switch is on — with it off
7
+ // they are a 404 and never get here — so a deck with the switch off, the
8
+ // default, never looks at the install folder, never builds a client, never
9
+ // starts anything and never touches the network. On a platform without the
10
+ // panel, a route is answered `unsupported` without looking either.
11
+ //
12
+ // SUPPORTED IS NOT SERVED. On every platform a route still goes nowhere
13
+ // unless the engine's own hello advertises a terminal backend
14
+ // (routeThroughEngine in pro-engine-terminal.mjs answers `no-terminal`
15
+ // otherwise): the engine decides, behind its own opt-in, whether it serves
16
+ // the panel on this machine.
17
+ //
18
+ // ONE FOLDER, AND ONLY KEYS SHIPPED IN THIS FILE. The engine is looked for in
19
+ // `<deck data folder>/engine` (CCDECK_HOME when set; deck-home.mjs) and
20
+ // nowhere else: not on PATH, and downloaded only when somebody presses
21
+ // Install on the page (engine-install.mjs). Its manifest must
22
+ // be signed by one of ENGINE_PUBLIC_KEYS — the one release key the published
23
+ // @ccdeck/engine-* packages are signed with — so a folder whose manifest that
24
+ // key did not sign answers `not-verified` without the deck reading the
25
+ // executable, and one under a folder other accounts can change answers
26
+ // `unsafe-folder` (pro-engine-install.mjs), the folder named in the deck's
27
+ // log alone. A deck that is handed an engine by its caller instead
28
+ // (startServer's `terminal.engine`) never uses this.
29
+ //
30
+ // WHERE THE FOLDER COMES FROM. Given keys, the first question that finds the
31
+ // folder missing or older first tries to bring the engine in from the npm
32
+ // package that came with the deck for this machine (engine-package.mjs):
33
+ // verified, never downgrading, copied whole or not at all. A package that is
34
+ // not there, or an import that is refused, leaves whatever is installed as it
35
+ // was. Still only on a question, still only with the switch on. The page's
36
+ // own Install (engine-install.mjs, `installer` below) is the third source:
37
+ // the same package from the npm registry, or a package file, after a press.
38
+ // Every change to the folder, from either, runs under one lock
39
+ // (withEngineLock), and an install stops the running engine first.
40
+ //
41
+ // THE ENGINE IS TOLD IT MAY SERVE THE PANEL, and only this one. The client
42
+ // made here is the only one constructed with `terminal: true`, which is what
43
+ // sets CCDECK_ENGINE_TERMINAL=1 in the engine's environment
44
+ // (pro-engine-client.mjs); any value the deck itself inherited is removed
45
+ // first, for this engine and every other.
46
+ //
47
+ // IT STOPS WHEN THE PANEL IS SWITCHED OFF, a moment after the panels it
48
+ // served have been told (STOP_GRACE_MS, the time those panels' sockets are
49
+ // given to close), and at once when the deck shuts down. Stopping detaches
50
+ // the engine; the sessions it showed keep running. The next question after a
51
+ // stop starts a new one.
52
+ //
53
+ // NEVER UNDER A QUESTION, NEVER TWO. A question asked while on that the
54
+ // engine is still answering when the grace runs out — a launch whose tmux is
55
+ // still making its session — is answered first, and the stop follows: the
56
+ // session is made and labelled with its launch key, not left half made by an
57
+ // engine stopped under it (each question has the client's own deadline, so
58
+ // this ends). Switched back on before the stop has begun, the stop is called
59
+ // off and the engine kept. A question asked while an engine is stopping waits
60
+ // for its process to exit before the next is started (EXIT_WAIT_MS at most,
61
+ // and `restarting` after that), so two never run at once.
62
+ import { promises as fsp } from "node:fs";
63
+ import { posix as posixPath, win32 as winPath } from "node:path";
64
+ import { deckDataDir } from "./deck-home.mjs";
65
+ import { ENGINE_ON_WINDOWS, importEngine } from "./engine-package.mjs";
66
+ import { createEngineInstaller, tightenDataFolder, withEngineLock } from "./engine-install.mjs";
67
+ import { createProEngineClient } from "./pro-engine-client.mjs";
68
+ import { UNSAFE_FOLDER } from "./pro-engine-install.mjs";
69
+ import { engineRefusal, engineTerminals } from "./pro-engine-terminal.mjs";
70
+ import { RUNNING_VERSION } from "./running-version.mjs";
71
+
72
+ /** The Ed25519 public keys an engine's manifest may be signed with, as PEM or
73
+ * KeyObjects. One: the release key the published @ccdeck/engine-* packages
74
+ * are signed with (SHA-256 of its DER, ENGINE_RELEASE_KEY_SHA256, below).
75
+ * Frozen, so nothing at run time can add one. */
76
+ export const ENGINE_PUBLIC_KEYS = Object.freeze([
77
+ "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA/ynXDN1fhh2GmedOCCRxR28YClWi+d9HycrnMfFAAmA=\n-----END PUBLIC KEY-----\n",
78
+ ]);
79
+
80
+ /** SHA-256 of the release key's DER (SubjectPublicKeyInfo), so a test can tell
81
+ * the key above is the one the packages are signed with and was not changed. */
82
+ export const ENGINE_RELEASE_KEY_SHA256 = "98e8d4289655b4861bb8214cab575416086822757968935eeee639b1fcce16a9";
83
+
84
+ /** How long after the switch goes off the engine is stopped: the time a
85
+ * relayed panel's socket is given to close once it has been told
86
+ * (pro-engine-terminal.mjs' SHUTDOWN_GRACE_MS). */
87
+ export const STOP_GRACE_MS = 1_500;
88
+
89
+ /** How long a question waits for a stopped engine's process to exit before
90
+ * it is answered `restarting` (a moment the page waits out) rather than
91
+ * have a second engine started beside it. The client gives the engine a
92
+ * second to answer its shutdown and then ends it (pro-engine-client.mjs
93
+ * close); this is far above that, and is the engine's own drain, the
94
+ * longest it takes to go by itself. */
95
+ export const EXIT_WAIT_MS = 5_000;
96
+
97
+ /** Whether `platform` has the Command Panel: Linux, macOS and, while
98
+ * ENGINE_ON_WINDOWS (engine-package.mjs) is set, Windows.
99
+ * Only where the engine's hello also advertises a terminal backend does a
100
+ * route reach it (`no-terminal` otherwise). */
101
+ export function commandPanelSupported(platform = process.platform) {
102
+ return platform === "linux" || platform === "darwin" || (platform === "win32" && ENGINE_ON_WINDOWS);
103
+ }
104
+
105
+ /** The one folder the Command Panel's engine is installed in. Joined with
106
+ * `platform`'s separator, not the host's, as deckDataDir is: a bare `join`
107
+ * answers `\x\deck\engine` on a Windows runner for a question about Linux. */
108
+ export function engineInstallDir(platform = process.platform, env = process.env) {
109
+ const { join } = platform === "win32" ? winPath : posixPath;
110
+ return join(deckDataDir(platform, env), "engine");
111
+ }
112
+
113
+ /** Whether `promise` settles within `ms`. */
114
+ function settlesWithin(promise, ms) {
115
+ let timer;
116
+ const out = new Promise((resolve) => {
117
+ timer = setTimeout(() => resolve(false), ms);
118
+ timer.unref?.();
119
+ });
120
+ return Promise.race([promise.then(() => true, () => true), out]).finally(() => clearTimeout(timer));
121
+ }
122
+
123
+ /** The package that came with the deck, brought in (engine-package.mjs) once
124
+ * the data folder is the owner's alone: nothing in a folder others may write
125
+ * to verifies (tightenDataFolder). The default `importPackage` below, so a
126
+ * test that hands in its own import touches no real folder. */
127
+ async function importBesideDeck(options) {
128
+ await tightenDataFolder(deckDataDir(options.platform, options.env), options.platform);
129
+ return importEngine(options);
130
+ }
131
+
132
+ /**
133
+ * The Command Panel's engine as the routes and the upgrade take it (the shape
134
+ * engineTerminals gives, with `route` answering a refusal of its own while
135
+ * there is no client, and `forgetTmux` doing nothing), plus `switchedOff()`,
136
+ * `switchedOn()` and `stop()`.
137
+ *
138
+ * `installer` is the page's Install (engine-install.mjs), made here with the
139
+ * same platform, keys and import unless one is given; it stops this engine
140
+ * before it changes the folder (`release`).
141
+ *
142
+ * `platform`, `arch`, `env`, `keys`, `lstat`, `importPackage`,
143
+ * `createClient`, `graceMs`, `exitWaitMs` and `installer` are there for
144
+ * tests; the deck uses the defaults (`commandPanel`, below).
145
+ */
146
+ export function commandPanelEngine({
147
+ platform = process.platform,
148
+ arch = process.arch,
149
+ env = process.env,
150
+ keys = ENGINE_PUBLIC_KEYS,
151
+ lstat = (path) => fsp.lstat(path),
152
+ importPackage = importBesideDeck,
153
+ createClient = createProEngineClient,
154
+ graceMs = STOP_GRACE_MS,
155
+ exitWaitMs = EXIT_WAIT_MS,
156
+ installer,
157
+ } = {}) {
158
+ let held = null; // { client, terminals, asking: the questions it is answering }
159
+ let making = null; // the question that is making it, so two make one
160
+ // A stop asked for and not begun: its grace, then the questions it waits
161
+ // for. Called off by a question or by the switch going on again.
162
+ let stopping = null; // { timer }
163
+ // The last engine stopped, until its process has exited: the next waits.
164
+ let exiting = null;
165
+ // Counts stops: a client being made when one came is not made after it.
166
+ let stops = 0;
167
+
168
+ const cancelStop = () => {
169
+ if (stopping) clearTimeout(stopping.timer);
170
+ stopping = null;
171
+ };
172
+
173
+ /** The engine's terminals, or why there is none. */
174
+ async function ready() {
175
+ if (!commandPanelSupported(platform)) return { refusal: "unsupported" };
176
+ if (held) return held;
177
+ making ??= (async () => {
178
+ const directory = engineInstallDir(platform, env);
179
+ const at = stops;
180
+ // Never one beside another: the one stopped last is let go first.
181
+ if (exiting && !(await settlesWithin(exiting, exitWaitMs))) return { refusal: "restarting" };
182
+ // With keys to verify against, bring the engine in from its package first.
183
+ // Under the folder's lock, so never beside an install from the page.
184
+ const brought = keys.length > 0 ? await withEngineLock(() => importPackage({ platform, env, keys: [...keys] })) : null;
185
+ try {
186
+ await lstat(directory);
187
+ } catch (error) {
188
+ if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") return { refusal: "not-verified" };
189
+ if (brought?.status !== "refused") return { refusal: "not-installed" };
190
+ return { refusal: brought.reason === UNSAFE_FOLDER ? UNSAFE_FOLDER : "not-verified" };
191
+ }
192
+ // Nothing to verify a manifest against: the executable is never read.
193
+ if (keys.length === 0) return { refusal: "not-verified" };
194
+ if (at !== stops) return { refusal: "restarting" };
195
+ const client = createClient({
196
+ enabled: true,
197
+ directory,
198
+ publicKey: [...keys],
199
+ ...(brought?.minimumVersion === undefined ? {} : { minimumVersion: brought.minimumVersion }),
200
+ hostVersion: RUNNING_VERSION ?? "0.0.0",
201
+ terminal: true,
202
+ });
203
+ held = { client, terminals: engineTerminals(client), asking: new Set() };
204
+ return held;
205
+ })().finally(() => { making = null; });
206
+ return making;
207
+ }
208
+
209
+ function drop() {
210
+ const was = held;
211
+ held = null;
212
+ stops += 1;
213
+ if (!was) return;
214
+ // close() answers once the engine's process has exited (pro-engine-client.mjs).
215
+ const gone = was.client.close().catch(() => {});
216
+ exiting = gone;
217
+ gone.then(() => { if (exiting === gone) exiting = null; });
218
+ }
219
+
220
+ /** The stop the switch-off asked for, once its grace is out: after the
221
+ * questions the engine is answering, unless called off meanwhile. */
222
+ async function stopOnceAnswered(wanted) {
223
+ while (stopping === wanted && held?.asking.size) await Promise.allSettled([...held.asking]);
224
+ if (stopping !== wanted) return;
225
+ stopping = null;
226
+ drop();
227
+ }
228
+
229
+ /** Stops the engine now and waits for its process to exit (an install is
230
+ * about to replace or remove its folder). Answers whether it exited. */
231
+ async function release() {
232
+ cancelStop();
233
+ drop();
234
+ return exiting ? settlesWithin(exiting, exitWaitMs) : true;
235
+ }
236
+
237
+ const install = installer ?? createEngineInstaller({ platform, arch, env, keys: [...keys], importPackage, beforeChange: release });
238
+
239
+ return Object.freeze({
240
+ get enabled() { return true; },
241
+ /** The page's Install: status, install, a file, cancel, remove. */
242
+ installer: install,
243
+ release,
244
+ async route(method, body) {
245
+ cancelStop();
246
+ const r = await ready();
247
+ if (r.refusal) return engineRefusal(r.refusal);
248
+ // Kept while the engine answers it: a stop waits for it (stopOnceAnswered).
249
+ const asked = r.terminals.route(method, body);
250
+ r.asking.add(asked);
251
+ try {
252
+ return await asked;
253
+ } finally {
254
+ r.asking.delete(asked);
255
+ }
256
+ },
257
+ async attach(handle, socket) {
258
+ // A ticket outlives nothing: with no engine there is nothing it names.
259
+ return held ? held.terminals.attach(handle, socket) : { ok: false, status: 503 };
260
+ },
261
+ /** The deck's own tmux has landed (terminal-routes.mjs): the engine
262
+ * running now forgets the miss it remembered. One being made, or the
263
+ * next, looks afresh; nothing is started for this. Never rejects. */
264
+ forgetTmux() {
265
+ return held ? held.terminals.forgetTmux() : Promise.resolve();
266
+ },
267
+ /** The switch went off: stop the engine once its panels have closed —
268
+ * one running, or one a question asked while on is making now, which
269
+ * is stopped the same grace later (or, made after it, not made) — and
270
+ * once it has answered the questions it was asked while on. */
271
+ switchedOff() {
272
+ if ((!held && !making) || stopping) return;
273
+ const wanted = { timer: null };
274
+ wanted.timer = setTimeout(() => { void stopOnceAnswered(wanted); }, graceMs);
275
+ wanted.timer.unref?.();
276
+ stopping = wanted;
277
+ },
278
+ /** The switch went on again: a stop that has not begun is called off,
279
+ * and the engine kept. One already stopping goes; the next question
280
+ * waits for its process to exit (ready). */
281
+ switchedOn() {
282
+ cancelStop();
283
+ },
284
+ /** The deck is going: stop it now, without waiting for it. */
285
+ stop() {
286
+ cancelStop();
287
+ drop();
288
+ },
289
+ /** Whether a client is held, for tests. */
290
+ get running() { return held !== null; },
291
+ });
292
+ }
293
+
294
+ /** The deck's own: the default `engine` of terminal-routes.mjs. */
295
+ export const commandPanel = commandPanelEngine();
296
+
297
+ /** For bin/deck.js's shutdown, beside closeAllTerminals: never awaited. */
298
+ export function stopCommandPanelEngine() {
299
+ commandPanel.stop();
300
+ }
@@ -0,0 +1,99 @@
1
+ // Whether this deck's platform has the Command Panel: what /api/prefs says as
2
+ // `terminalSupported`, which decides whether Settings offers the panel's
3
+ // switch (TerminalSection.tsx). Asked once, by startServer.
4
+ //
5
+ // LINUX AND MACOS: commandPanelSupported (command-panel-engine.mjs), as it has
6
+ // always been. Nothing below is loaded, read or asked there, whatever startServer
7
+ // was given.
8
+ //
9
+ // WINDOWS: the same path as the other platforms, commandPanelSupported
10
+ // (ENGINE_ON_WINDOWS in engine-package.mjs): the deck's own engine from its npm
11
+ // package, verified by the installer with its Windows ACL reader
12
+ // (windows-acl.mjs). The engine's sessions there always live in the per-user
13
+ // session host, so `sessionHost` is true whenever the panel is supported.
14
+ //
15
+ // THE PREVIEW OPTION, WHICH IS TEST-ONLY: the Windows preview, a local
16
+ // development and test configuration for a VM, never a production feature.
17
+ // Without it a Windows deck answers as above. With it, it holds only when ALL
18
+ // of these do:
19
+ // - process.platform is "win32";
20
+ // - startServer was given `terminal.windowsPreview === true`. Only the
21
+ // private QA preload passes it (the private repo's
22
+ // scripts/qa/engine-preload.mjs, and only when its lab's own config asks
23
+ // for the preview). bin/deck.js, bin/agent-dag.js and the desktop app
24
+ // pass startServer no `terminal` at all, and nothing here reads an
25
+ // environment variable, a setting, a CLI flag, a file or a request;
26
+ // - startServer was also given an explicit `terminal.engine`: the engine
27
+ // that preload built, with a fresh test key it holds in memory and passes
28
+ // as that engine's `publicKey`. The deck's own ENGINE_PUBLIC_KEYS stay
29
+ // empty and are never added to;
30
+ // - the test-only module preview/command-panel-windows.mjs, outside
31
+ // src/server, can be loaded. It is not in the published package
32
+ // (package.json `files`) nor in the desktop app's resources
33
+ // (electron-builder.config.cjs), so on a production install the option is
34
+ // refused whatever is passed, and the deck's log says so once.
35
+ // Then the switch is offered on Windows and everything it reaches goes to that
36
+ // explicit engine; when any of them fails the option is refused and the Windows
37
+ // deck does not offer the panel at all, not even through its own path: a lab
38
+ // that asked for the preview is told it is missing, not given the deck's engine.
39
+ // (A startServer caller's `terminal.engine` always wins on every platform,
40
+ // terminal-routes.mjs.)
41
+ import { commandPanelSupported } from "./command-panel-engine.mjs";
42
+ import { PRODUCT } from "./brand.mjs";
43
+
44
+ /** The test-only module, beside the package rather than in it. Imported by
45
+ * this literal name below, so a walk of what the deck can load
46
+ * (terminal-js-offpath.test.ts) follows it rather than meeting a computed one. */
47
+ export const WINDOWS_PREVIEW_MODULE = new URL("../../preview/command-panel-windows.mjs", import.meta.url);
48
+
49
+ /** What the deck's log says when the preview was asked for and is refused. No
50
+ * path: the reason only. */
51
+ export const WINDOWS_PREVIEW_REFUSED = Object.freeze({
52
+ "no-engine": "the Windows Command Panel preview was asked for without an engine, so it is off; the Command Panel is unavailable on this platform.",
53
+ absent: "the Windows Command Panel preview was asked for, but this build does not include it; the Command Panel is unavailable on this platform.",
54
+ "not-preview": "the Windows Command Panel preview was asked for, but the module found is not the preview; the Command Panel is unavailable on this platform.",
55
+ });
56
+
57
+ const answer = (supported, windowsPreview, sessionHost = false) => Object.freeze({ supported, windowsPreview, sessionHost });
58
+
59
+ /** Whether this answer puts the panel's sessions in the Windows session host
60
+ * rather than tmux: on Windows always (through the engine, or the preview),
61
+ * nowhere else. A caller with no answer asks the platform. */
62
+ export const panelInSessionHost = (panel, platform = process.platform) =>
63
+ panel ? panel.sessionHost === true || panel.windowsPreview === true : platform === "win32" && commandPanelSupported(platform);
64
+
65
+ /**
66
+ * This deck's Command Panel platform, for startServer's `terminal` option:
67
+ * `{ supported, windowsPreview, sessionHost }`: `windowsPreview` is the
68
+ * test-only preview, `sessionHost` that sessions live in the per-user session
69
+ * host. `platform`, `load` and `log` are there for
70
+ * tests; the deck uses the defaults.
71
+ */
72
+ export async function commandPanelPlatform(terminal, {
73
+ platform = process.platform,
74
+ load = () => import("../../preview/command-panel-windows.mjs"),
75
+ log = (line) => console.error(`${PRODUCT}: ${line}`),
76
+ } = {}) {
77
+ if (platform !== "win32") return answer(commandPanelSupported(platform), false);
78
+ if (terminal?.windowsPreview !== true) {
79
+ const supported = commandPanelSupported(platform);
80
+ return answer(supported, false, supported);
81
+ }
82
+ const engine = terminal.engine;
83
+ if (!engine || typeof engine !== "object" || typeof engine.route !== "function" || typeof engine.attach !== "function") {
84
+ log(WINDOWS_PREVIEW_REFUSED["no-engine"]);
85
+ return answer(false, false);
86
+ }
87
+ let preview;
88
+ try {
89
+ preview = await load(WINDOWS_PREVIEW_MODULE);
90
+ } catch {
91
+ log(WINDOWS_PREVIEW_REFUSED.absent);
92
+ return answer(false, false);
93
+ }
94
+ if (preview?.WINDOWS_PREVIEW !== true) {
95
+ log(WINDOWS_PREVIEW_REFUSED["not-preview"]);
96
+ return answer(false, false);
97
+ }
98
+ return answer(true, true, true);
99
+ }
@@ -75,7 +75,7 @@ function updateChoice(change) {
75
75
  const next = normaliseChoice(change(before));
76
76
  if (JSON.stringify(next) === JSON.stringify(before)) return before;
77
77
  const path = choicePath();
78
- await mkdir(dirname(path), { recursive: true });
78
+ await mkdir(dirname(path), { recursive: true, mode: 0o700 });
79
79
  await writeFileAtomic(path, `${JSON.stringify(next)}\n`);
80
80
  _held = next;
81
81
  return next;
@@ -201,7 +201,7 @@ async function loadState() {
201
201
  }
202
202
  async function saveState(state) {
203
203
  try {
204
- await mkdir(STATE_DIR, { recursive: true });
204
+ await mkdir(STATE_DIR, { recursive: true, mode: 0o700 });
205
205
  await writeFile(STATE_PATH, JSON.stringify(state, null, 2));
206
206
  } catch { /* best-effort */ }
207
207
  }
@@ -51,26 +51,12 @@ const MARKER = join(homedir(), ".agents-deck", ".cswap-update-check");
51
51
  // did not ask, and can be told so. Raise it deliberately, with claude-swap's
52
52
  // release notes open.
53
53
  //
54
- // CEILING: the next major. claude-swap is 0.x and ships a minor every couple of
55
- // weeks, so a ceiling tight enough to stop a hostile 0.27 would stop every real
56
- // release too and rot within the month. What this ceiling does stop is the
57
- // shape a takeover actually takes — a version number picked to win every
58
- // resolution, `9.9.9` — and a 1.0 arriving unattended while the deck's caller
59
- // list still speaks 0.x.
60
- //
61
- // Spelled `~=0.26` and not `>=0.26,<1`, which is the same set. PEP 440's
62
- // compatible-release operator expands to `>= 0.26, == 0.*`, and the spelling
63
- // with no `<` or `>` in it cannot be read as redirection by anything that ever
64
- // sees this argument as text: `run` spawns with shell:false, but the Windows
65
- // leg routes a `.cmd`/`.bat` shim through cmd.exe (exec.mjs viaCmd), where `<`
66
- // and `>` are syntax while outside quotes. That quoting is correct and tested;
67
- // not needing it is better.
68
- // Dated for the reason uv-bootstrap.mjs dates its FALLBACK_VERSION: a floor
69
- // rots silently. Nothing fails when it falls behind — it simply stops being the
70
- // version anyone is developing against — so no test and no user will report it.
71
- const MIN_VERSION = "0.26"; // latest on PyPI as of 2026-09-15
72
- const MAX_VERSION = "1"; // the first one this deck will not run
73
- const RANGE_SPEC = `${PKG}~=${MIN_VERSION}`; // >= 0.26, == 0.*
54
+ // The CLI and JSON contracts used by the deck are compatible with 1.x.
55
+ // Keep the previous install range when the registry cannot be inspected.
56
+ // A registry-backed install always requests the exact accepted release.
57
+ const MIN_VERSION = "0.26";
58
+ const MAX_VERSION = "2";
59
+ const FALLBACK_SPEC = `${PKG}~=${MIN_VERSION}`;
74
60
 
75
61
  /**
76
62
  * True when `v` is a version this deck is willing to put in front of the user's
@@ -151,7 +137,7 @@ function refuse(entry) {
151
137
  _bin = null;
152
138
  _probe = null;
153
139
  try {
154
- mkdirSync(join(homedir(), ".agents-deck"), { recursive: true });
140
+ mkdirSync(join(homedir(), ".agents-deck"), { recursive: true, mode: 0o700 });
155
141
  writeFileSync(REFUSED_RECORD, JSON.stringify({ ...entry, at: new Date().toISOString() }, null, 2) + "\n");
156
142
  } catch { /* the in-process refusal still holds; a note on disk is the next launch's */ }
157
143
  }
@@ -181,7 +167,7 @@ export async function cswapRefusal() {
181
167
  /** ensureCswap's answer for a refused copy: the install-time row's shape, so
182
168
  * the boot says the same thing on every launch the refusal holds. */
183
169
  function refusedState(r) {
184
- return { state: "unavailable", reason: "unexpected_version", version: r.version, want: r.want ?? RANGE_SPEC, via: r.via ?? null };
170
+ return { state: "unavailable", reason: "unexpected_version", version: r.version, want: r.want ?? FALLBACK_SPEC, via: r.via ?? null };
185
171
  }
186
172
 
187
173
  /**
@@ -401,7 +387,7 @@ async function safePythons() {
401
387
  * half is why that step is uv's alone (and why the bound is re-checked on
402
388
  * arrival, not trusted to the installer).
403
389
  */
404
- async function installers(spec = RANGE_SPEC) {
390
+ async function installers(spec = FALLBACK_SPEC) {
405
391
  const out = [
406
392
  { cmd: "uv", probe: ["--version"], args: ["tool", "install", spec], upgrade: ["tool", "upgrade", PKG], via: "uv", owner: "uv" },
407
393
  { cmd: "pipx", probe: ["--version"], args: ["install", spec], upgrade: ["upgrade", PKG], via: "pipx", owner: "pipx" },
@@ -449,7 +435,7 @@ async function installCswap() {
449
435
  // daily check already makes, bounded at six seconds in front of an install
450
436
  // that takes minutes.
451
437
  const want = await newestAcceptableOnPypi();
452
- const spec = want ? `${PKG}==${want}` : RANGE_SPEC;
438
+ const spec = want ? `${PKG}==${want}` : FALLBACK_SPEC;
453
439
 
454
440
  for (const { cmd, probe, args, via } of await installers(spec)) {
455
441
  if (!(await run(cmd, probe, { timeout: 8_000 })).ok) continue;
@@ -505,10 +491,10 @@ export async function installHint() {
505
491
  if ((await run(py, ["-c", "import sys"], { timeout: 5_000 })).ok) {
506
492
  // Quoted: a resolved Windows path routinely contains spaces.
507
493
  const q = /\s/.test(py) ? `"${py}"` : py;
508
- return `${q} -m pip install --user pipx && ${q} -m pipx install "${RANGE_SPEC}"`;
494
+ return `${q} -m pip install --user pipx && ${q} -m pipx install "${FALLBACK_SPEC}"`;
509
495
  }
510
496
  }
511
- return `${getUv} (then: uv tool install "${RANGE_SPEC}")`;
497
+ return `${getUv} (then: uv tool install "${FALLBACK_SPEC}")`;
512
498
  }
513
499
 
514
500
  function updateCheckDue() {
@@ -517,7 +503,7 @@ function updateCheckDue() {
517
503
  }
518
504
  function touchMarker() {
519
505
  try {
520
- mkdirSync(join(homedir(), ".agents-deck"), { recursive: true });
506
+ mkdirSync(join(homedir(), ".agents-deck"), { recursive: true, mode: 0o700 });
521
507
  writeFileSync(MARKER, String(Date.now()));
522
508
  } catch { /* ignore */ }
523
509
  }
@@ -526,15 +512,8 @@ function touchMarker() {
526
512
  * The newest claude-swap on PyPI that this deck would actually install, or null
527
513
  * when the registry cannot be asked.
528
514
  *
529
- * "Newest acceptable" and not `info.version`, which is PyPI's own idea of
530
- * latest and is bounded by nothing here. Reading that one and then installing
531
- * inside a bound is two different questions answered by two different parties,
532
- * and the disagreement between them is a daily lie of the kind this file has
533
- * already been bitten by twice (#579): the day claude-swap ships 1.0.0, every
534
- * deck would see a newer version, fire an upgrade its own specifier forbids,
535
- * and print "upgrading to v1.0.0 in background" at every launch, forever, about
536
- * a version that can never arrive. So the bound decides what "newest" means,
537
- * once, and the upgrade decision and the install target are the same answer.
515
+ * Use the same version bound for registry installs and upgrades so an
516
+ * out-of-range latest release does not trigger an upgrade on every launch.
538
517
  *
539
518
  * Pre-releases are skipped — claude-swap publishes `0.21.0b1` and friends, and
540
519
  * an unattended upgrade is not the place to chase them — as are releases whose
@@ -578,7 +557,7 @@ const UPGRADE_RECORD = join(homedir(), ".agents-deck", "cswap-upgrade.json");
578
557
 
579
558
  function recordUpgrade(entry) {
580
559
  try {
581
- mkdirSync(join(homedir(), ".agents-deck"), { recursive: true });
560
+ mkdirSync(join(homedir(), ".agents-deck"), { recursive: true, mode: 0o700 });
582
561
  writeFileSync(UPGRADE_RECORD, JSON.stringify(entry, null, 2) + "\n");
583
562
  } catch { /* a note about an upgrade is not worth failing the upgrade over */ }
584
563
  }
@@ -828,11 +807,13 @@ async function installAndConfirm() {
828
807
  // supply-chain risk for a certain outage the day `cswap --version` changes
829
808
  // how it prints.
830
809
  if (version !== "installed") {
831
- const wrong = result.want ? !sameVersion(version, result.want) : !isAcceptableVersion(version);
810
+ const wrong = result.want
811
+ ? !sameVersion(version, result.want)
812
+ : !isAcceptableVersion(version) || !isOlder(version, "1");
832
813
  if (wrong) {
833
814
  // Kept, not only reported (#1799): see REFUSED_RECORD.
834
- refuse({ path: _bin, version, want: result.want ?? RANGE_SPEC, via: result.via });
835
- return { state: "unavailable", reason: "unexpected_version", version, want: result.want ?? RANGE_SPEC, via: result.via };
815
+ refuse({ path: _bin, version, want: result.want ?? FALLBACK_SPEC, via: result.via });
816
+ return { state: "unavailable", reason: "unexpected_version", version, want: result.want ?? FALLBACK_SPEC, via: result.via };
836
817
  }
837
818
  }
838
819
  return { state: "installed", via: result.via, version };
@@ -74,6 +74,12 @@ export function legacyDeckDir(env = process.env, home = homedir(), platform = pr
74
74
  * machine-wide deck would collapse two profiles into one on upgrade, which is
75
75
  * exactly the kind of silent change this file exists to stop. They keep what
76
76
  * they have; everybody else moves.
77
+ *
78
+ * A WRITER THAT MAKES THIS FOLDER, or the log folder (deckLogDir), makes it and any
79
+ * missing folder above it 0700 (`mode: 0o700` beside `recursive`): the
80
+ * optional engine is used only where no folder above it is writable by
81
+ * another account. A folder already there keeps its mode. Windows ignores the
82
+ * mode. deck-folders-private.test.ts holds every writer to it.
77
83
  */
78
84
  export function deckDataDir(platform = process.platform, env = process.env, home = homedir()) {
79
85
  // THE TARGET PLATFORM'S SEPARATOR, NOT THE HOST'S — the same reason
@@ -98,12 +98,42 @@ export const DEFAULTS = Object.freeze({
98
98
  // Its tour marker must outlive that origin; browser tabs still use their
99
99
  // own localStorage marker and never read this preference.
100
100
  tourSeen: false,
101
+ // Which tour that was, as a number (release-notes.ts TOUR_EDITION): 0 is
102
+ // none recorded. `tourSeen: true` alone is the 3.x tour, and 4.0 shows its
103
+ // own once, so this is what the page reads now. tourSeen stays, written
104
+ // beside it, because it is all a 3.x deck understands of this file — and a
105
+ // 3.x deck that rewrites the file drops this key (normalise), which costs
106
+ // the V4 tour one more showing after a downgrade, never a crash.
107
+ tourEdition: 0,
101
108
  // Whether the deck may update itself: restart into code already on disk once
102
109
  // it is idle, and — while nobody is looking — install a newer release and
103
110
  // restart into that (auto-update.mjs). ON, because this is the banner's
104
111
  // `auto when idle`, which defaulted on as a localStorage key; it moved here so
105
112
  // the server can read it with no page open.
106
113
  autoUpdate: true,
114
+ // THE COMMAND PANEL, ON unless somebody turns it off: the engine that runs
115
+ // it ships on Linux, macOS and Windows, so the panel is part of the deck the
116
+ // way the board is. A terminal you can type into is still the first thing in
117
+ // the deck that reaches into an agent rather than watching one, so it stays
118
+ // behind the switch in Settings › General › Experimental, in PAGE_FIELDS,
119
+ // behind the gates every other switch is behind. Those turn away every other
120
+ // site, a rebound name and the network; they cannot turn away a process on
121
+ // this machine that writes a loopback Origin itself (request-gates.mjs says
122
+ // so), and such a process can switch on a way to type into the user's
123
+ // sessions — where it would otherwise have to write prefs.json. Accepted for
124
+ // the experiment, knowingly: that process can already read the ring and the
125
+ // accounts through the same gates. The switch is the only way off; no launch
126
+ // variable turns it on or off. See terminal-routes.mjs.
127
+ //
128
+ // No release stored this key before it defaulted to on, so a stored false is
129
+ // somebody's switch, or a pre-release build's.
130
+ terminal: true,
131
+ // THE CCDECK ACCOUNT, OFF and hidden (account-flag.mjs): Settings › Account,
132
+ // the status frames and the settings sync. Deck-owned and hand-edited — not
133
+ // in PAGE_FIELDS while the feature is hidden, so no page can switch on a
134
+ // connection to the API. CCDECK_ACCOUNT=1 turns it on for one run, and
135
+ // AGENTS_DECK_NO_ACCOUNT / AGENTS_DECK_NO_INSTALL veto both.
136
+ account: false,
107
137
  // USAGE REPORTS (#1853), ON unless somebody turns them off — the owner's
108
138
  // decision, 2026-09-30: nobody is asked and the README says what is sent; the
109
139
  // page has no switch since 2026-10-01. See reports.mjs for what is sent, and
@@ -357,7 +387,12 @@ export function normalise(raw) {
357
387
  notifyStopped: flagOr(src.notifyStopped, DEFAULTS.notifyStopped),
358
388
  continueStopped: flagOr(src.continueStopped, DEFAULTS.continueStopped),
359
389
  tourSeen: flagOr(src.tourSeen, DEFAULTS.tourSeen),
390
+ // A whole number, or none: a string, a fraction or a negative from a
391
+ // hand-edited file is not an edition anybody was shown.
392
+ tourEdition: Number.isInteger(src.tourEdition) && src.tourEdition > 0 && src.tourEdition < 10_000 ? src.tourEdition : DEFAULTS.tourEdition,
360
393
  autoUpdate: flagOr(src.autoUpdate, DEFAULTS.autoUpdate),
394
+ terminal: flagOr(src.terminal, DEFAULTS.terminal),
395
+ account: flagOr(src.account, DEFAULTS.account),
361
396
  reports: flagOr(src.reports, DEFAULTS.reports),
362
397
  report: normaliseReport(src.report),
363
398
  accounts: normaliseOrigins(src.accounts),
@@ -743,7 +778,7 @@ export function publicPrefs(prefs) {
743
778
  export const PAGE_FIELDS = Object.freeze({
744
779
  top: Object.freeze([
745
780
  "notifications", "notifySwap", "notifyQuota", "notifyReset", "notifyStopped", "continueStopped",
746
- "tourSeen", "autoUpdate", "recoverCodexSessions", "recoverClaudeSessions",
781
+ "tourSeen", "tourEdition", "autoUpdate", "recoverCodexSessions", "recoverClaudeSessions", "terminal",
747
782
  ]),
748
783
  lan: Object.freeze([
749
784
  "enabled", "name", "shared", "manual", "shareActive", "sendInUse", "pairingMode",
@@ -808,6 +843,23 @@ export function lanEnabled(prefs, env = process.env) {
808
843
  return normalise(prefs).lan.enabled;
809
844
  }
810
845
 
846
+ /**
847
+ * Is the Command Panel switched on? The `terminal` switch as normalise()
848
+ * reads it: on unless a real false was stored, and nothing else: no
849
+ * environment variable or launch flag turns it on or off.
850
+ *
851
+ * Not lanEnabled's veto, on purpose: the panel is the feature the person
852
+ * switches, in Settings or in the settings file, and no launch can overrule
853
+ * that either way.
854
+ *
855
+ * Asked on every request and every upgrade rather than once at boot, so the
856
+ * routes and the socket answer from the same settings at every moment and can
857
+ * never disagree about whether the panel exists.
858
+ */
859
+ export function terminalOn(prefs) {
860
+ return flagOr(prefs?.terminal, DEFAULTS.terminal);
861
+ }
862
+
811
863
  /**
812
864
  * Did the MACHINE veto this, as opposed to the person?
813
865
  *