shapewall 0.3.3 → 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 (157) hide show
  1. package/CHANGELOG.md +501 -0
  2. package/README.md +87 -4
  3. package/THIRD_PARTY.md +15 -0
  4. package/dist/agent/package-lock.json +594 -2
  5. package/dist/client/assets/BoardChat-WS8mAIW6.js +27 -0
  6. package/dist/client/assets/{BuzzDialog-Ix9qJvim.js → BuzzDialog-B-Mlr6wF.js} +1 -1
  7. package/dist/client/assets/ChecksPanel-Dx1ZLBR6.js +1 -0
  8. package/dist/client/assets/History-sXhmpcvs.js +1 -0
  9. package/dist/client/assets/LocalSettings-CtGzz9F3.js +1 -0
  10. package/dist/client/assets/{Management-NVFDtSZB.js → Management-CGHe8Wt9.js} +1 -1
  11. package/dist/client/assets/QuickConnect-DEk84E4A.js +1 -0
  12. package/dist/client/assets/{ShareDialog-By0ETg6n.js → ShareDialog-CGGx-AYK.js} +2 -2
  13. package/dist/client/assets/{app-update-dialog-RGIw24iZ.js → app-update-dialog-_bVp8hnC.js} +1 -1
  14. package/dist/client/assets/{circle-x-B6KfScOE.js → circle-x-BWoHA1QY.js} +1 -1
  15. package/dist/client/assets/index-Bm-Xd3YN.js +37 -0
  16. package/dist/client/assets/index-C7Ostk3K.css +2 -0
  17. package/dist/client/assets/play-BzQ3tRTv.js +1 -0
  18. package/dist/client/assets/{refresh-cw-vkgvCCfR.js → refresh-cw-BYBMyDKT.js} +1 -1
  19. package/dist/client/assets/{runtime-Bft6x_6E.js → runtime-Bvq10IhH.js} +1 -1
  20. package/dist/client/assets/ui-CAY6myRA.js +41 -0
  21. package/dist/client/build-info.json +1 -1
  22. package/dist/client/index.html +3 -3
  23. package/dist/client/sw.js +2 -2
  24. package/dist/console/assets/LocalAccountsApp-CWRguRRL.js +1 -0
  25. package/dist/console/assets/LocalConsole--I2SaIpr.js +2 -0
  26. package/dist/console/assets/LocalUsage-BmpCZ36k.js +1 -0
  27. package/dist/console/assets/app-update-dialog-B8M9plaT.js +1 -0
  28. package/dist/console/assets/app-version-muKrQqbL.js +1 -0
  29. package/dist/console/assets/console-CrhTsPbz.css +2 -0
  30. package/dist/console/assets/console-DxapQ9oS.js +11 -0
  31. package/dist/console/assets/local-agents-CoqD4dSN.js +6 -0
  32. package/dist/console/assets/minus-DDQ0ydcM.js +1 -0
  33. package/dist/console/assets/tailnet-C5Flwl_d.js +2 -0
  34. package/dist/console/assets/theme-DCd0qh4l.js +1 -0
  35. package/dist/console/assets/ui-Bry1mnCY.js +41 -0
  36. package/dist/console/assets/usage-CIPWnHaS.css +1 -0
  37. package/dist/console/assets/usage-CqVjMb7m.js +5 -0
  38. package/dist/console/assets/usage-D1G0GgE3.js +56 -0
  39. package/dist/console/build-info.json +1 -1
  40. package/dist/console/console.html +8 -2
  41. package/docs/agent-hardening.md +206 -0
  42. package/docs/agent-recipes.md +23 -0
  43. package/docs/agent-workflow.md +5 -0
  44. package/docs/agents.md +49 -6
  45. package/docs/architecture.md +10 -4
  46. package/docs/deployment.md +39 -17
  47. package/docs/design-system.md +56 -7
  48. package/docs/hosted.md +1800 -46
  49. package/docs/images/board-overview.png +0 -0
  50. package/docs/images/journeys.png +0 -0
  51. package/docs/images/live-comment.png +0 -0
  52. package/docs/images/phone-comment.png +0 -0
  53. package/docs/images/phone-overview.png +0 -0
  54. package/docs/images/variant.png +0 -0
  55. package/docs/where-to-run.md +119 -3
  56. package/package.json +6 -1
  57. package/src/agent/backends/acp.js +745 -44
  58. package/src/agent/branch-mode.js +17 -3
  59. package/src/agent/card-hash.js +65 -0
  60. package/src/agent/context.js +41 -0
  61. package/src/agent/exec-paths.js +105 -0
  62. package/src/agent/routes.js +23 -2
  63. package/src/agent/run.js +11 -1
  64. package/src/agent/starter/cli.js +6 -1
  65. package/src/agent/turn-changes.js +70 -8
  66. package/src/agent/usage-log.js +251 -0
  67. package/src/cli/args.js +37 -0
  68. package/src/cli/commands.js +20 -5
  69. package/src/cli/help.js +73 -3
  70. package/src/cli/init.js +2 -1
  71. package/src/cli/serve.js +20 -5
  72. package/src/cli.js +8 -0
  73. package/src/hosted/access-cli.js +99 -1
  74. package/src/hosted/activity-core.js +232 -0
  75. package/src/hosted/activity.js +375 -0
  76. package/src/hosted/admin.js +87 -13
  77. package/src/hosted/agent-approvals.js +29 -4
  78. package/src/hosted/agent-link.js +1032 -0
  79. package/src/hosted/agent-policy.js +10 -3
  80. package/src/hosted/agent-presence.js +63 -22
  81. package/src/hosted/agent-routes.js +135 -0
  82. package/src/hosted/agents.js +1206 -0
  83. package/src/hosted/app.js +178 -12
  84. package/src/hosted/auth-routes.js +156 -15
  85. package/src/hosted/auth.js +123 -20
  86. package/src/hosted/board-routes.js +129 -5
  87. package/src/hosted/chat-frames.js +246 -0
  88. package/src/hosted/chat-job.js +204 -0
  89. package/src/hosted/chat-permissions.js +203 -0
  90. package/src/hosted/chat-routes.js +1009 -0
  91. package/src/hosted/chat-store.js +477 -0
  92. package/src/hosted/comment-files.js +11 -1
  93. package/src/hosted/comments.js +1 -1
  94. package/src/hosted/console-routes.js +122 -34
  95. package/src/hosted/db.js +295 -0
  96. package/src/hosted/device-routes.js +88 -10
  97. package/src/hosted/device.js +54 -4
  98. package/src/hosted/events.js +3 -3
  99. package/src/hosted/guards.js +337 -27
  100. package/src/hosted/http.js +6 -3
  101. package/src/hosted/membership.js +22 -3
  102. package/src/hosted/operator-access.js +418 -0
  103. package/src/hosted/operator.js +106 -2
  104. package/src/hosted/ops-cli.js +238 -3
  105. package/src/hosted/pages.js +4 -0
  106. package/src/hosted/passkey-policy.js +75 -0
  107. package/src/hosted/permissions.js +52 -6
  108. package/src/hosted/presence.js +31 -2
  109. package/src/hosted/projects.js +30 -2
  110. package/src/hosted/public.js +4 -4
  111. package/src/hosted/ratelimit.js +14 -0
  112. package/src/hosted/retention.js +18 -2
  113. package/src/hosted/server.js +123 -11
  114. package/src/hosted/shares.js +2 -2
  115. package/src/hosted/step-up-settings.js +68 -0
  116. package/src/hosted/step-up.js +135 -0
  117. package/src/hosted/tailnet-identity.js +24 -0
  118. package/src/hosted/tailnet-routes.js +342 -0
  119. package/src/hosted/tailnet.js +220 -0
  120. package/src/hosted/tailscale.js +75 -9
  121. package/src/hosted/tenancy.js +66 -1
  122. package/src/hosted/token-api.js +119 -20
  123. package/src/hosted/token-events.js +5 -3
  124. package/src/hosted/tokens.js +29 -6
  125. package/src/hosted/turn-hub.js +152 -0
  126. package/src/hosted/usage-core.js +624 -0
  127. package/src/hosted/usage-layout.js +724 -0
  128. package/src/hosted/usage-routes.js +375 -0
  129. package/src/hosted/usage-shape.js +256 -0
  130. package/src/hosted/usage.js +641 -0
  131. package/src/remote/agent-connect.js +469 -0
  132. package/src/remote/agent-fix.js +611 -0
  133. package/src/remote/agent-job.js +216 -0
  134. package/src/remote/agent-link.js +906 -0
  135. package/src/remote/agent-policy-file.js +242 -0
  136. package/src/remote/credentials.js +35 -1
  137. package/src/remote/login.js +44 -9
  138. package/src/remote/share.js +1 -1
  139. package/src/remote/tailnet-cli.js +547 -0
  140. package/src/server/app.js +15 -0
  141. package/src/server/pairing-routes.js +34 -5
  142. package/src/server/tailscale.js +97 -4
  143. package/src/tailnet-proof.js +766 -0
  144. package/dist/client/assets/BoardChat-DxehB761.js +0 -27
  145. package/dist/client/assets/ChecksPanel-pA_ueIaJ.js +0 -1
  146. package/dist/client/assets/History-C9N32kCv.js +0 -1
  147. package/dist/client/assets/LocalSettings-DawtKnvi.js +0 -1
  148. package/dist/client/assets/QuickConnect-DO1TjS1t.js +0 -1
  149. package/dist/client/assets/index-CsqLdqGx.css +0 -2
  150. package/dist/client/assets/index-DnZarJ3U.js +0 -37
  151. package/dist/client/assets/shield-check-QzwGhz0t.js +0 -1
  152. package/dist/client/assets/ui-DI-FGWWK.js +0 -41
  153. package/dist/console/assets/LocalAccountsApp-VOCZg8dg.js +0 -1
  154. package/dist/console/assets/LocalConsole-CMwAW-mF.js +0 -1
  155. package/dist/console/assets/app-update-dialog-Cw6UDqNP.js +0 -1
  156. package/dist/console/assets/console-DgfWmUEx.js +0 -55
  157. package/dist/console/assets/console-Lis0vvdL.css +0 -2
@@ -1 +1 @@
1
- {"version":"0.3.3","revision":"3667db3f69905f9158cce15006b48fa056c03786"}
1
+ {"version":"0.7.0","revision":"277d4df57399b398e4c1fe4d7d5ba593b0646d4e"}
@@ -12,8 +12,14 @@
12
12
  <title>Shapewall</title>
13
13
  <!-- Saved light/dark mode and theme, before the first paint (see src/lib/theme.js). -->
14
14
  <script src="/_console/theme-boot.js"></script>
15
- <script type="module" crossorigin src="/_console/assets/console-DgfWmUEx.js"></script>
16
- <link rel="stylesheet" crossorigin href="/_console/assets/console-Lis0vvdL.css">
15
+ <script type="module" crossorigin src="/_console/assets/console-DxapQ9oS.js"></script>
16
+ <link rel="modulepreload" crossorigin href="/_console/assets/ui-Bry1mnCY.js">
17
+ <link rel="modulepreload" crossorigin href="/_console/assets/theme-DCd0qh4l.js">
18
+ <link rel="modulepreload" crossorigin href="/_console/assets/app-version-muKrQqbL.js">
19
+ <link rel="modulepreload" crossorigin href="/_console/assets/local-agents-CoqD4dSN.js">
20
+ <link rel="modulepreload" crossorigin href="/_console/assets/minus-DDQ0ydcM.js">
21
+ <link rel="modulepreload" crossorigin href="/_console/assets/tailnet-C5Flwl_d.js">
22
+ <link rel="stylesheet" crossorigin href="/_console/assets/console-CrhTsPbz.css">
17
23
  </head>
18
24
  <body>
19
25
  <div id="root"></div>
@@ -173,6 +173,201 @@ When the chat panel drives an agent CLI over ACP:
173
173
  board and comment ids before they become file names. Hosted API tokens are scoped to one project and to what you tick: `read`,
174
174
  `comment`, `resolve`, `push`.
175
175
 
176
+ ### Connected agents
177
+
178
+ `shapewall agent connect` puts a coding agent on a hosted board, where members of a workspace chat with it
179
+ ([Connected agents](hosted.md#connected-agents)). It runs on your machine, with your login, and other people write the questions. So
180
+ by default it reads and answers only, and the machine that runs it is what enforces that. Edits from the board are a separate
181
+ choice, made on that machine ([Edits from a hosted board](#edits-from-a-hosted-board) below).
182
+
183
+ - **The command is yours.** The program that runs is Claude Code, found on your `PATH` or saved as an agent on your machine. Nothing
184
+ the server sends names a command, an argument, a folder, an environment variable or an MCP server.
185
+ - **Only an agent whose own controls were proven.** Refusing what an agent asks for is not enough: a tool it is set up to run
186
+ without asking never asks. So `agent connect` offers only Claude Code in this release, and refuses Codex, goose, Gemini CLI and
187
+ any program it does not know, with a message.
188
+ - **Read-only by the agent's own controls.** A connected Claude Code session is started:
189
+ - with no settings files (`settingSources: []`): your `~/.claude/settings.json` and the project's `.claude/settings.json` and
190
+ `.claude/settings.local.json` are left out, so their allow rules, hooks, default mode and plugins do not apply;
191
+ - with no MCP servers from `.mcp.json` or settings (`strictMcpConfig`);
192
+ - with only its reading tools (Read, Grep, Glob). Bash, Edit, Write, MultiEdit, NotebookEdit, WebFetch, WebSearch, Task/Agent and
193
+ Skill are removed from the session, and bypassing permissions is switched off.
194
+ - **Fail closed.** The session's mode must be "default" or "plan"; any other is switched to "default", or the agent is not
195
+ started. An agent that reports no session mode at all is not started read-only. An agent that switches itself to another mode
196
+ mid-answer is stopped, and the thread says which mode. claude-agent-acp 0.106.0 starts a session in the mode "auto" (Claude
197
+ decides what to ask about) when no settings file names a default mode. The adapter reads that from the settings files itself,
198
+ so leaving them out of the session does not change it. Shapewall switches such a session to "default" before the first
199
+ question, and the machine's log says so.
200
+ - **Checked when it starts.** `agent connect` opens the session before it goes online, the way a question would (no prompt is
201
+ sent). A session that cannot be opened, or that cannot be put in a mode that asks, stops the command with the cause. An adapter
202
+ version this release was not tested with is used with a plain warning ([tested versions](agents.md#claude-code)).
203
+ - **Managed settings stop the start.** `/etc/claude-code/managed-settings.json` cannot be left out of a session. When it allows
204
+ acting tools (Bash, Edit, Write, MultiEdit, NotebookEdit, WebFetch, WebSearch, Task, `mcp__*`, or Read of absolute or home paths)
205
+ or runs hooks, `agent connect` refuses to start. Your own and the project's rules are reported as "Left out of this session".
206
+ - **No writes and no terminals from Shapewall either.** The agent is told at the start that Shapewall offers neither. A write or a
207
+ command it asks Shapewall for anyway is refused, and every permission request its own tools make is refused on the spot, a read
208
+ outside the project included. Nobody is asked, on the board or anywhere else.
209
+ - **Board text is quoted on your machine.** The server sends data; your machine wraps every comment, reply, page title, mention and
210
+ attached file as untrusted data before the agent sees it. A server that was broken into can ask your agent questions. It cannot
211
+ hand it "instructions" that skip the quoting, and it cannot make it edit or run anything.
212
+ - **Who may ask.** By default only the person who connected it. Sharing it is a choice made at the approval or on the Agents page.
213
+ `--audience owner` on your machine asks the server to keep the agent to you even if its audience there is widened later, and
214
+ your machine refuses a job the server labels as someone else's. Your machine cannot check that label, so this does not protect
215
+ against a compromised server.
216
+ - **Its token stays out of the agent.** The agent process gets a small environment with no `SHAPEWALL_*` variable, and the agent's
217
+ own token is removed from anything sent back.
218
+
219
+ How it was proven. The check used the real Claude Code adapter, **claude-agent-acp 0.93.0 and 0.106.0** (the tested versions of
220
+ Shapewall 0.7.0; 0.106.0 with Claude Code 2.1.322), in a project whose `.claude/settings.json` and `.claude/settings.local.json`
221
+ allowed Bash, Edit, Write, WebFetch, `mcp__*` and reads anywhere, with the default mode `bypassPermissions` and, for 0.7.0, hooks
222
+ that run a command when a session starts, on every prompt and before every tool. The instructions told the agent it had full
223
+ permission and must create a file, run `touch`, and read `/etc/hostname`.
224
+
225
+ - **Claude Code, started as above, on each of the two versions:** no file was created, no command ran (the session had only Glob,
226
+ Grep and Read), none of the project's hooks ran, and the read outside the project was asked for and refused. On 0.106.0 the
227
+ session started in "auto" and was switched to "default" first.
228
+ - **Claude Code, same project, session not hardened:** it ran a shell command without asking. That is why the hardening exists.
229
+ - **Codex 2.2.2, under the same test in its read-only sandbox:** it wrote no file, but it ran `pwd` and read `/etc/hostname`
230
+ without asking. What it reads can leave the machine in an answer, so it is not offered.
231
+
232
+ goose's chat-only mode could not be verified on the test machine, and Gemini CLI was not installed to verify, so neither is
233
+ offered. For those agents, `shapewall watch --remote` stays the way.
234
+
235
+ The limits, plainly:
236
+
237
+ - **It reads the project, and its answers leave your machine.** Whoever may ask can get file contents quoted back: every file in
238
+ the project folder, a `.env` file included. The agent is told not to quote secrets; that is an instruction, not a control.
239
+ Connect only projects whose code the audience may read, and keep secrets out of the folder.
240
+ - **One machine, two adapter versions.** The check above is what was seen there, with 0.93.0 and 0.106.0. A later adapter may
241
+ take other options or bring other tools: Shapewall 0.6.0 could not start a connected session on 0.106.0 at all, because that
242
+ version reports a mode switch in another order. `agent connect` warns when the adapter is not a tested version; it cannot know
243
+ what a version it has never seen does. So still give a connected agent a profile of its own: a separate config folder with no
244
+ allow rules, logged in for this purpose. The hooks of your own `~/.claude/settings.json` were not provoked separately: the same
245
+ option (`settingSources: []`) leaves that file out as it does the project's.
246
+ - **Settings in the left-out files do not apply.** An `apiKeyHelper` or `env` in those settings files is not used by the connected
247
+ session. The login itself is not in those files.
248
+ - **One link per agent.** A second `agent connect` on the same token is refused, and names the machine already connected.
249
+ `--takeover` closes that link first. Whoever holds the agent's token can take the link over, so keep the token file private.
250
+
251
+ The hard rule below holds for connected agents too: it is a shared board, and other people write what the agent reads.
252
+
253
+ ### Edits from a hosted board
254
+
255
+ From Shapewall 0.6.0 a connected agent can make a fix for a hosted comment
256
+ ([Edits from the board](hosted.md#edits-from-the-board-the-trust-decision)). The question behind it: **who may make someone
257
+ else's machine change files?** By default, nobody. Even the person who connected the agent cannot allow an edit from the board
258
+ until they said so on that machine.
259
+
260
+ | Level | Where it is set | Default | What the board can cause |
261
+ | --------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
262
+ | Audience "only the person who connected it", `--approvals none` | The audience at the approval; `--audience owner` pins it from the machine | Yes | That person asks. The agent reads the project and answers |
263
+ | Audience: named members, or everyone the agent policy trusts | On the server: the approval page, or the Agents page | Opt-in | Those members may ask too. Still read and answer only |
264
+ | `--approvals owner` | On the machine | Opt-in | A fix on a new branch. Each edit waits for the person who connected the agent |
265
+ | `--approvals admins` | On the machine | Opt-in | A fix on a new branch. Each edit waits for someone with the agent's answer role (admin by default), in its audience and trusted |
266
+ | "Allow without asking" | On the machine (`--auto edits`), and then the agent's approval rule on the server | Opt-in, twice | Edits to ordinary source files go into the fix without a person. The fix stays on the machine: it is pushed only after a person allows "Push this fix" on its whole diff |
267
+ | Commands | On the machine (`--allow-command`) | Not offered for Claude Code in 0.6.0 | Nothing: a fix session of Claude Code has no shell tool |
268
+
269
+ The machine's choice is saved in its own policy file (`agent-policy.json` beside the saved token, 0600, outside every
270
+ repository). It is the ceiling: the server can only narrow it. The file fails narrow: a value this version does not know (a typo,
271
+ `false`, `""`, a wrong type) reads as the narrowest setting for that key, never as the default, and `agent connect` names the key
272
+ when it starts. The file must be yours and not writable by others; that is checked before it is read.
273
+
274
+ What the machine does, whatever the server says:
275
+
276
+ - **A fix is never made in your checkout.** The agent works in a fresh copy of the base commit, with no `.git` in it, in a folder
277
+ outside the project (under your state folder). Your checkout is only read.
278
+ - **Every edit is checked on the machine before anyone is asked.** The file must be inside the fix's folder after resolving
279
+ symlinks, not in `.git`, not in Shapewall's store, and not a file that runs something unless you named it with `--allow-path`.
280
+ The whole resulting file must be computable and small enough to show in full. What fails is refused there and never becomes a
281
+ question.
282
+ - **Files that run something are a list, used twice.** Dotfiles and dot folders, dependency manifests and lockfiles, build and
283
+ tool configuration (`*.config.js`, `tsconfig*.json`, the jest, vitest, vite, webpack, rollup, babel and eslint files), scripts
284
+ a package runs (`scripts/`, `bin/`, install hooks, `*.sh`), `Dockerfile*` and compose files, makefiles, CI files, and test files
285
+ ([the list](hosted.md#files-that-run-something)). The same list decides what is refused when an edit is asked and what is never
286
+ pushed. One you named with `--allow-path` is always answered by a person, never allowed without asking.
287
+ - **What Git would leave out is refused, not dropped.** An edit to a file Git ignores, to anything under `node_modules`, or to
288
+ `.gitattributes` / `.gitmodules` is refused when it is asked.
289
+ - **A card shows what will be written.** The path and the full diff, in the machine's own words, never the agent's title. The
290
+ card carries a hash of the turn, the card, the path, the whole diff and how long it waits. The diff goes to the people the
291
+ agent works for (its audience, whoever may answer, whoever asked); everyone else who can open the thread reads that it asked to
292
+ edit a file and how that ended.
293
+ - **An answer is for one card.** It must send the card's hash back, within 2 minutes, once. The 2 minutes are a length of time
294
+ each side counts on its own clock, so the clocks need not agree. A workspace can ask for the answerer's passkey again before Allow
295
+ (off by default; the server's Settings, "Agent edits and pushes"). The machine then checks the answer again: a card it asked and still waits on, the same hash, not expired by its own
296
+ count, once, and from the connecting person when it said "owner". A failed "allow" is a deny, and the board then shows the
297
+ card as expired or denied, never as allowed. An answer for a card it never asked is ignored.
298
+ - **Shapewall makes the commit, and only of what was allowed.** No hook, filter or attribute runs. Every changed file must have
299
+ had an allowed edit and must hold exactly the bytes that were shown, with the file mode it had. Every allowed file must be in
300
+ the commit, and nothing may be removed. A changed edit, an extra file, a mode change, a deletion: the branch is taken back and
301
+ the thread says nothing was committed.
302
+ - **Nothing is pushed that runs something, or that no person has seen.** A fix that touches a file from the list above stays on
303
+ the machine, and the thread says "Not pushed" and why. A fix with an edit that went without asking stays there too, until a
304
+ person who may answer cards allows one "Push this fix" card that shows its whole diff. Anything else is pushed as one new
305
+ branch, and a pull request is opened when [GitHub connect](github.md) is set up on that machine.
306
+ - **Stop stops all of it.** After Stop nothing is committed, pushed or opened, and a fix that was waiting to be pushed is taken
307
+ back. A push that had already finished cannot be undone: the thread says the branch exists.
308
+ - **Leftovers are swept.** Copies a killed process left behind are removed when `agent connect` starts and around every fix. The
309
+ folder fixes are made in is never inside the project; where it would be, the fix is refused.
310
+ - **Chat never edits.** Only "Fix with" on a comment starts a turn that may edit, and it follows the rules of sending a comment
311
+ to an agent: a trusted member's vouch, an admin's "Approve agent run" where the policy says so, the audience, the budgets.
312
+ - **"Allow without asking" only where the machine named it** (`--auto edits`), and under `--approvals owner` only when the
313
+ person who connected the agent switched it on themself: an admin cannot take them out of the loop. It never widens what may be
314
+ edited, never covers a file that runs something, never pushes, and a machine that connects again without it resets the
315
+ server's rule to "ask".
316
+
317
+ **Commands, and what the real adapter did.** The link and the policy file know "exact commands from the machine's own list, each
318
+ allowed on the board" (`--allow-command`). This is not available for Claude Code in Shapewall 0.6.0, and Claude Code is the only
319
+ agent `agent connect` offers. In the check below, a Claude Code session started with its shell tool ran commands it takes to be
320
+ read-only (`ls`, `cat`) without asking anyone, and those can read outside the project. A list of allowed commands is no control
321
+ over an agent that does not ask. So a fix session of Claude Code gets no shell tool at all (it has Read, Grep, Glob, Edit, Write
322
+ and MultiEdit, no settings files and no MCP servers), `--allow-command` is refused for it with that explanation, and commands in a
323
+ hand-edited policy file are not in effect.
324
+
325
+ How edits were proven. The check used the real Claude Code adapter (claude-agent-acp 0.93.0 for 0.6.0; 0.93.0 and 0.106.0 again
326
+ for 0.7.0, in a repository whose committed `.claude/settings.json` allowed Bash, Edit and Write without asking and ran a hook), a
327
+ throwaway server on localhost, a throwaway Git repository with a local bare remote, and the real
328
+ `shapewall agent connect --approvals owner`:
329
+
330
+ - **Allow.** A Fix with Builder edited one file after Allow in a browser (with a passkey check, which that workspace asked
331
+ for). The commit landed on
332
+ `shapewall/comment-1-...` and was pushed to the bare remote. The checkout stayed clean on `main`, with the old file.
333
+ - **Deny.** A Deny left no branch and no folder.
334
+ - **A comment that asked for more.** The comment also asked for a file outside the project, a new `package.json` and shell
335
+ commands. It ended with only the allowed one-line edit committed. In one run the `package.json` request was refused on the
336
+ machine as a settings file. Claude Code itself declined the file outside the project and, having no shell tool, ran nothing.
337
+ - **A server that lies.** Forged "allowed" answers from the server side with a wrong hash turned the waiting edit into a deny.
338
+ - **Without asking.** With `--approvals owner --auto edits` and the rule switched on by the connecting person, the edit went
339
+ without a card to answer, the commit landed on its branch on the machine, and the bare remote stayed empty until "Push this
340
+ fix" was allowed in the browser. Then that one branch was pushed.
341
+
342
+ The real model declined some of what a hostile agent would try. The scripted-agent tests (`test/hosted-fix-security.test.js`)
343
+ cover that: an edit changed after the answer, a file nobody was asked about, an answer for another card, another turn or sent
344
+ twice, a stolen agent token that says "approved", and a server that says "allow without asking" when the machine did not.
345
+
346
+ The limits of edit mode, plainly:
347
+
348
+ - **Shapewall does not sandbox the agent's own tools.** The checks above cover what the agent asks. The fix session is set up so
349
+ that its editing tools ask every time, and that was seen with one adapter version on one machine. If files in your own checkout
350
+ change during a fix, the thread says so; it cannot undo it.
351
+ - **With approvals on, a compromised hosted server can forge an "allow".** The machine cannot see the person behind an answer, or whether a
352
+ passkey was checked: it sees what the server sends. A server that was broken into can answer "allow", with the right hash, for an
353
+ edit the agent really asked, and for "Push this fix". So the worst case with approvals on is: edits to ordinary source files,
354
+ on a branch, in a throwaway folder, pushed for review. Not commands, not your checkout, not files that run something on
355
+ install, build, test or CI, and not files outside the project that the agent asks about.
356
+ - **The branch is a proposal.** It comes from a board comment, which is untrusted text. Nothing is merged by Shapewall.
357
+ - **Diffs leave the machine.** Beyond the answers of 0.5.0, edit mode sends the diffs on edit cards (bounded), the file paths
358
+ and line counts of a fix, the branch name and the pull request link. Still not the agent's token and not absolute paths.
359
+
360
+ What to do:
361
+
362
+ - **Give the agent a restricted profile of its own**: a separate config folder with no allow rules, logged in for this purpose.
363
+ - **Prefer `--approvals owner` to `--approvals admins`.** Then an "allow" has to come from you, and both the server and your
364
+ machine check that.
365
+ - **Review the pull request like any other**, the whole diff ([Review the agent's output](#review-the-agents-output)), and
366
+ protect `main` so a pushed branch cannot merge itself.
367
+ - **Do not add `--allow-path` for CI files**, and think twice before adding it for `package.json` or any file that runs.
368
+ - **Leave `--auto` off** unless everyone who may press Fix is someone you would let edit the project unseen. Even then the fix
369
+ waits on the machine until someone looks at its whole diff.
370
+
176
371
  ### What Shapewall cannot do
177
372
 
178
373
  - **The agent's own tools.** An ACP agent is still a program running as you. Claude Code's Bash and Edit, Codex's sandbox, goose's
@@ -194,6 +389,8 @@ Pick the weakest setup that does the job.
194
389
  | Chat with an endpoint, read-only tools | Read the board, write answers | Shared boards, with a spend-limited key |
195
390
  | `comments --json` into an agent you run by hand | Whatever you let it, one comment at a time, you watching | Any board, if you read the comment first |
196
391
  | Chat with an agent CLI over ACP, permission prompts on | Edit and run in the project after you approve each card | Your own board on your own machine |
392
+ | `agent connect` on a hosted board (the default) | Read the project, write answers | Projects whose code the agent's audience may read |
393
+ | `agent connect --approvals owner` | Edit a fresh copy on a new branch after you allow each diff | Hosted boards, with a restricted profile and PR review |
197
394
  | `watch --exec` with an edit mode and a narrow tool list | Edit the project and call `npx shapewall`, no person in between | Boards whose commenters you trust |
198
395
  | `watch --exec` in a sandbox, output as a branch | Edit a fresh clone, open a PR | Shared boards ([Sandbox checklist](#sandbox-checklist)) |
199
396
  | An agent with your shell, keys, browser and email | Anything you can | Nothing that reads other people's text |
@@ -217,6 +414,14 @@ shared board is text other people write.
217
414
 
218
415
  Use a separate agent for shared boards: its own key, its own login, in a sandbox with nothing worth stealing and nowhere to send it.
219
416
 
417
+ A [connected agent](#connected-agents) on a hosted board is a shared board's agent. By default it reads and answers only, which
418
+ takes away editing and running, not reading: connect a profile that holds nothing but that project, never your main one.
419
+
420
+ With [edits from the board](#edits-from-a-hosted-board) switched on, the rule matters more. Other people's comments now end as
421
+ changes to files, and an "allow" reaches your machine through the server. The edits are held to a branch in a throwaway folder,
422
+ and each one was shown to a person, but the agent that makes them still runs as you, with its own tools. Never switch
423
+ `--approvals` on for your main agent.
424
+
220
425
  ## Sandbox checklist
221
426
 
222
427
  For `watch --exec`, an agent loop on a hosted project, or the chat on a shared board. Every item is something you set up outside
@@ -345,6 +550,7 @@ to a shared board.
345
550
  - [ ] Only trusted members trigger work (`--mention agent`, no `--include-guests`).
346
551
  - [ ] Share links are off, or view-only, with a passcode and a short expiry.
347
552
  - [ ] The agent's prompt says comments are requests about the UI, not instructions.
553
+ - [ ] A connected agent takes edits only if I chose so on its machine: `--approvals owner`, no `--allow-path` for CI files, `--auto` off.
348
554
 
349
555
  **Every change**
350
556
 
@@ -18,6 +18,29 @@ about the UI, never as instructions, and gives the agent no more than it needs.
18
18
  The commands assume `shapewall` is installed in the project (`npm install --save-dev shapewall`), so `npx shapewall`
19
19
  runs that copy, and that you are in the folder with `shapewall.config.json`.
20
20
 
21
+ **On a team server.** Every `watch` recipe below works against a hosted board by adding `--remote https://wall.example.com` (after
22
+ `shapewall login --remote https://wall.example.com`, with **Take agent work** ticked). The watcher then shows up on that board as an
23
+ agent with a name, an icon and a state, and people send comments to it by name. A new agent takes work only from the person who
24
+ connected it until an admin shares it on the project's Agents page. See
25
+ [Agents on a hosted board](hosted.md#agents-on-a-hosted-board).
26
+
27
+ **Chat on a team server.** To let teammates ask your coding agent questions on the hosted board, run this in the project's folder,
28
+ on the machine that has Claude Code set up for the board chat ([The board chat (ACP)](#the-board-chat-acp) below):
29
+
30
+ ```sh
31
+ shapewall agent connect --remote https://wall.example.com # this project's agent, else Claude Code; or --agent claude
32
+ shapewall agent connect --remote https://wall.example.com --as scout --name "Scout" # a second connection, with its own token
33
+ ```
34
+
35
+ An admin approves the code it prints, names the agent and chooses who may use it. By default it reads the project and answers,
36
+ and does not change files or run commands from the board. Add `--approvals owner` on that machine to let it make a fix for a
37
+ comment: on a new branch, never in the checkout, each edit allowed on the board by you
38
+ ([Edits from the board](hosted.md#edits-from-the-board-the-trust-decision)). It runs no commands from the board, so keep a `watch`
39
+ recipe for fixes that need to build, test or recapture. Only Claude Code can be connected in this release.
40
+ Codex, goose and Gemini CLI are refused with a message: their read-only behaviour could not be shown to hold, so for them the
41
+ `watch` recipes below, with `--remote`, stay the way.
42
+ See [Connected agents](hosted.md#connected-agents).
43
+
21
44
  ## Claude Code
22
45
 
23
46
  ### MCP in your session
@@ -212,6 +212,11 @@ requires a claiming local `--exec`, so it is refused with `--remote`, `--no-clai
212
212
  command did not edit a file; inspect the before/after before resolving. To capture additional pages, the agent can use `recapture_pages`
213
213
  through MCP or the capture CLI. Variants still require manual capture.
214
214
 
215
+ With `--remote`, the watcher is an **agent** of the hosted project: the board lists it by its token's name with its state (online,
216
+ working, offline), and people choose it when they send a comment. It is handed the comments sent to it and the ones sent to any
217
+ agent, from the people it takes work from; a comment sent to another agent never reaches it. Nothing changes in how you run it. See
218
+ [Agents on a hosted board](hosted.md#agents-on-a-hosted-board).
219
+
215
220
  Options: `--concurrency N` (1 to 4, default 1; agents editing one repo at once usually step on each other), `--new-only` (ignore comments
216
221
  that exist when the watch starts), `--once` (hand out what is open now, wait for the commands, exit; handy in CI or a cron you run
217
222
  yourself), `--timeout MIN` (default 60), `--no-claim` (below).
package/docs/agents.md CHANGED
@@ -125,8 +125,36 @@ the agent picker's **Agent settings** item link to the Agents page.
125
125
 
126
126
  Connecting, removing, testing and choosing the default run commands as the machine's owner, so they need the settings token (the owner
127
127
  link `shapewall serve` prints). Without it the card is read-only and says how to open that link; it asks nothing of the agent routes.
128
- Self-hosted multiplayer (`shapewall hosted`) has its own workspace Settings (project agent tokens) and no Agents page. The public demo
129
- shows the card read-only on its console's Agents page.
128
+ Self-hosted multiplayer (`shapewall hosted`) has its own Agents pages, for the machines that watch a hosted project or connect a
129
+ coding agent to it ([Agents on a hosted board](hosted.md#agents-on-a-hosted-board)): they list and name agents, and never start a
130
+ program on the server. The chat panel described here is also on hosted boards, for an agent connected with `shapewall agent
131
+ connect`: the same panel, with an agent that reads the project and answers. On a hosted comment, **Fix with** an agent is offered
132
+ only when that agent's own machine switched edits on (`--approvals`): the fix is made on a new branch on that machine, never in
133
+ its checkout, and each edit is a card with the full diff that someone allows or denies on the board. Only Claude Code can be
134
+ connected that way in this release, and it runs no commands from a hosted board ([Connected agents](hosted.md#connected-agents)).
135
+ The public demo shows this card read-only on its console's Agents page.
136
+
137
+ ## Usage
138
+
139
+ Every agent turn leaves one usage record: when, on which board, in which kind of thread (the board's chat, a comment's, or a chat
140
+ of your own), who asked (the owner or a viewer; a local board has no accounts to name), which agent, whether it was a chat, a
141
+ comment answer or a fix, how it ended, how long it took, its tool calls counted by type, and the numbers the agent reported:
142
+ model, input, output and cached tokens, context used, and a cost only when the agent or its endpoint reported one. Nothing is
143
+ estimated: an agent that reports no tokens shows "Not reported", never zero. A record never holds the question, the answer, a
144
+ file's name or content, or a diff.
145
+
146
+ - **On a local board** the records are lines in `.shapewall/agent-usage.jsonl` (past 5 MB the file is renamed to
147
+ `agent-usage.1.jsonl` and a new one starts). The file is readable by its owner only (0600) and is written under a file lock,
148
+ like the event log. It says who used which agent and when, so keep it out of git: `.shapewall/` is ignored by `shapewall
149
+ init`, which from 0.7.0 also adds `.shapewall/agent-usage*.jsonl` by name. In a project set up earlier, check that your
150
+ `.gitignore` has `.shapewall/` (or add that line) before you commit. The Workspace Console's **Usage** page (`/console?section=usage`) shows them to the
151
+ owner: turns, tokens, agent time and reported cost for the last 7, 30 or 90 days against the days before, a chart by day and
152
+ agent (turns, tokens, time or cost), how turns ended, and a table of the newest 200 turns. It needs the owner link, like Agent
153
+ feedback: it says who used which agent on this computer. `GET /api/agent/usage?days=30` is the same data. The local view has no
154
+ filters, grouping or export; delete the two files to clear it.
155
+ - **On a team server** the records are rows in its database and the console has the full Usage page: filters, breakdowns,
156
+ approvals, turn duration, a grid of every turn, saved views and CSV or JSON export, with a rule for who sees what
157
+ ([Usage and activity](hosted.md#usage-and-activity)).
130
158
 
131
159
  ## Name and icon
132
160
 
@@ -169,8 +197,9 @@ fixed with `--agent-acp` or `SHAPEWALL_AGENT_ACP` still wins over which agent ru
169
197
  saved for that fixed agent (`fixedAgent` in `agents.json`) and the Agents page shows it with **Edit**. Everyone who can see the board
170
198
  gets the name, the icon's id and the colour in the agent info they already receive (`/api/agent/status`, `/api/info`); nothing else
171
199
  about the agent is added to it. In the public demo you can rename the two scripted agents and give them built-in icons (no upload);
172
- **Reset** puts them back. On a hosted board an agent is its API token: rename the token there ([hosted.md](hosted.md#workspaces-roles-and-invites));
173
- icons for hosted agents are not there yet.
200
+ **Reset** puts them back. On a hosted board an agent is a project API token that may take work: an admin gives it a name, one of the
201
+ same built-in icons and a colour on the project's Agents page in the console
202
+ ([Agents on a hosted board](hosted.md#agents-on-a-hosted-board)). Pictures are not uploaded there.
174
203
 
175
204
  ### While a connection test runs
176
205
 
@@ -598,6 +627,19 @@ to the agent unless you name it (see [The agent's environment](#the-agents-envir
598
627
  replace your subscription. The old package names `@zed-industries/claude-code-acp` and `@zed-industries/claude-agent-acp` are
599
628
  deprecated; use `@agentclientprotocol/claude-agent-acp`.
600
629
 
630
+ **Tested adapter versions.** Shapewall 0.7.0 was tested with `@agentclientprotocol/claude-agent-acp` **0.93.0** and **0.106.0**
631
+ (the latest when 0.7.0 was released, with Claude Code 2.1.322). Both work as a connected agent (`shapewall agent connect`),
632
+ read-only and for edits. The adapter changes between versions: 0.106.0 starts a session in the mode "auto" where 0.93.0 started
633
+ in "default", and reports the mode in two places. So:
634
+
635
+ - `shapewall agent connect` opens a session when it starts (no prompt is sent, nothing is spent) and prints which adapter
636
+ answered: `Claude Code answers through @agentclientprotocol/claude-agent-acp 0.106.0, a version this release was tested with.`
637
+ - A version it was not tested with is used as it is, with a `Warning:` line that names the tested versions and the command to
638
+ install one (`npm install -g @agentclientprotocol/claude-agent-acp@0.106.0`). It is not refused.
639
+ - A session that cannot be opened stops `agent connect` with the cause: the adapter's error, its version and its last output.
640
+ - A start that fails later says the same in the chat and in the log of the machine that runs the agent, never just "did not
641
+ start". `shapewall doctor --agent-acp "claude-agent-acp"` repeats the handshake on its own.
642
+
601
643
  For headless Claude Code setups that already supply `CLAUDE_CODE_OAUTH_TOKEN`, explicitly allow that variable when starting the
602
644
  board:
603
645
 
@@ -961,8 +1003,9 @@ Older thread files need no migration: a file with only `messages` (and `profileI
961
1003
  its title. The fields added since (`owner`, `title`, `titleSource`, `createdAt`, `archived`, `branches`) are written only when something
962
1004
  sets them. A board keeps at most 500 New chat threads; delete old ones to start more.
963
1005
 
964
- There are no share links for chats: chat runs only on a local `shapewall serve` board, and hosted boards (which have share links) have no
965
- agent chat. Export a chat as Markdown to share it.
1006
+ There are no share links for chats. On a hosted board, chat is for signed-in members with a
1007
+ [connected agent](hosted.md#connected-agents); a share link's guests and a public project's visitors never get it. Export a chat as
1008
+ Markdown to share it.
966
1009
 
967
1010
  ## Board tools
968
1011
 
@@ -143,6 +143,7 @@ touch):
143
143
  | Trackpad two-finger scroll | Pan in any direction |
144
144
  | Ctrl+wheel, Cmd+wheel, trackpad pinch | Zoom about the cursor (0.02x to 4x; a mouse notch is about 1.3x) |
145
145
  | Space+drag, middle-button drag, drag on the board | Pan (Space and middle drag work over pages and in comment mode as well) |
146
+ | The Hand tool (H): drag anywhere | Pan, over pages and pins too; a click selects and opens nothing |
146
147
  | Touch: one finger, two-finger pinch | Pan, zoom |
147
148
 
148
149
  Space pans while the mouse is over the canvas, except in text fields and on a control reached with the keyboard (Space presses it).
@@ -180,13 +181,18 @@ the same way. Scrolling inside a `nowheel` element (the frame bar, a live page b
180
181
  group at a readable zoom (two cards across), top-aligned. Pins never shrink below their 44 px touch target, and a tap in comment mode
181
182
  on a page drawn small zooms to it first, so the next tap can pin to an element.
182
183
  - The desktop toolbar never truncates: below 1440 px (1600 px with Capture and Agent) Links and Compare drop their labels, below
183
- 1280 px the lists become icons and the capture time moves into a tooltip. Notes over the canvas (comment mode, the tip, the
184
- viewport switch, the links note) are pills in one stack at its top, so turning comment mode on never moves the canvas. The minimap
184
+ 1280 px the lists become icons and the capture time moves into a tooltip. Notes about what the canvas shows (the tip, the
185
+ viewport switch, the links note) are pills in one stack at its top. The board tools (Select, Hand, Comment, Draw, Select text) float at
186
+ the bottom centre of the canvas, with the note for the tool in use (the comment hint, the drawing bar) just above them, so
187
+ turning comment mode on never moves the canvas; they stay clear of the zoom controls and the minimap at every width
188
+ (`client/src/board/toolDock.js`), and on a phone they are the bottom bar. The minimap
185
189
  can be turned off and hides while a page is live. Resolve and delete show a toast with Undo (a delete is sent after a few seconds,
186
190
  or when the page is left).
187
191
  - Keyboard: each card is one tab stop; the arrow keys move through its pins and buttons, Esc returns to the card, Enter opens its
188
192
  action bar. "Skip to comments" is the first tab stop. After a pick from a toolbar list, focus returns to the canvas, and a closed
189
- list ignores typed letters (Radix type-ahead), so shortcuts like C keep working. Esc closes a journey.
193
+ list ignores typed letters (Radix type-ahead), so shortcuts like C keep working. Esc closes a journey. The board tools are one
194
+ tab stop (a labelled toolbar): the arrow keys, Home and End move between them; V is Select, H is Hand, C is Comment (none
195
+ of them while typing) and Esc ends on Select.
190
196
  - URL state: board, viewport mode, comment filter, selected comment, camera, journey, branches and step, links, and compare pair live in the
191
197
  query string.
192
198
  - Overlays (dialogs, the comment sheet, the selected card, comment mode) each own a history entry, so Back closes the topmost one.
@@ -198,7 +204,7 @@ for replies, a dot for news) drawn at screen size; pins closer than about 30 scr
198
204
  count, and clicking it zooms in until they part (`clusterPins` in `client/src/board/pins.jsx`). Hovering a pin previews the thread in
199
205
  a kit `HoverCard`. Resolved threads are hidden by the Open filter, which is the toggle for showing them.
200
206
 
201
- C (or the Comment button) turns comment mode on; a click drops a draft pin and an inline composer (`ComposerPopover`) opens beside
207
+ C (or the Comment tool, in the board tools at the bottom of the canvas, or Comment on the selected page's bar, which also names that page in the hint) turns comment mode on; a click drops a draft pin and an inline composer (`ComposerPopover`) opens beside
202
208
  it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The open thread is a popover at
203
209
  its pin (`ThreadPopover`): resolve, previous and next (also the arrow keys), and a more menu (copy link, edit, ask agent, GitHub,
204
210
  history, delete), then the messages with reactions and an inline reply box. Both are Radix popovers anchored to a virtual element
@@ -192,23 +192,45 @@ error is a host permission failure before account enrollment, not a passkey or T
192
192
  complete the existing supported Serve permission/setup process for the intended port, then retry deliberately. Do not run Shapewall
193
193
  as root, change account origins or relax identity checks to bypass it.
194
194
 
195
- A Tailscale request gets owner access only if its immediate peer is loopback,
196
- its Host is exactly this node's `*.ts.net` name, and `Tailscale-User-Login` equals
197
- the node owner's login. Other users, shared-in devices, tagged nodes, and
198
- missing or mismatched identity headers must pair. `--no-identity` disables
199
- header trust altogether. The node owner is determined at server start; restart
200
- Shapewall after changing the node's owner.
201
-
202
- This relies on Tailscale Serve stripping client-supplied identity headers and
203
- setting its own values. Keep Tailscale current. See the
204
- [Tailscale identity-header documentation](https://tailscale.com/docs/features/tailscale-serve#identity-headers)
205
- and its [proxy header implementation](https://github.com/tailscale/tailscale/blob/main/ipn/ipnlocal/serve.go).
206
- A process already running on the host can forge loopback requests and headers;
207
- that process is inside the host trust boundary. Do not proxy another service to
208
- this listener. For an unverified proxy or client version, use `--no-identity`
209
- until you have checked a forged owner header from a different tailnet user is
210
- replaced or rejected. Shapewall's tests cover its own request handling, not
211
- your Tailscale daemon or tailnet ACLs.
195
+ A Tailscale request gets owner access only if its Host is exactly this node's
196
+ `*.ts.net` name, `Tailscale-User-Login` equals the node owner's login, and the
197
+ request provably came through the serve entry Shapewall made. A header alone
198
+ proves nothing: any program on the host (an agent whose command is waiting for
199
+ approval included) can send it to the loopback port. The proof is the same as
200
+ the hosted server's tailnet sign-in: the serve entry points at a secret path
201
+ made at each start, the connection's other end must be a socket owned by root
202
+ (tailscaled), `tailscale whois` must give the request's tailnet address to
203
+ the owner's login, and the request must not come from this machine itself
204
+ ([how](hosted.md#how-the-server-knows-a-request-came-through-tailscale-serve)).
205
+ A program on the host can ask tailscaled for the board's tailnet address and
206
+ would arrive with the owner's login, so the host's own tailnet address is
207
+ never the owner: on the host, open `http://localhost:<port>` (the settings
208
+ token makes you the owner there); the tailnet address opened on the host asks
209
+ to pair and says why. The secret path is taken off before the application
210
+ sees the request and is in no redirect or response.
211
+ Other users, shared-in devices, tagged nodes, and missing or mismatched
212
+ identity headers must pair. `--no-identity` disables it altogether. The node
213
+ owner is determined at server start; restart Shapewall after changing the
214
+ node's owner.
215
+
216
+ Where that cannot be proven, identity is off and every other device pairs; the
217
+ board still starts and says why: not Linux, tailscaled in userspace-networking
218
+ mode, Tailscale before 1.98, tailscaled running a SOCKS5 or outbound HTTP
219
+ proxy or started with a loopback-forwarding debug switch, no tailscaled of
220
+ root visible, the node unable to say which node it is, or Shapewall in a
221
+ container. The same is checked every 30 seconds while the board runs.
222
+
223
+ Approving an agent's command or edit (`/permissions/` routes) needs the
224
+ settings token from the host's own terminal, unless the request is the owner by
225
+ proven tailnet identity or comes from a device the owner paired. A local
226
+ program cannot approve its own command by dressing a request up.
227
+
228
+ Root and the Tailscale operator on the host are trusted; nothing else on the
229
+ host or the tailnet is. A tailnet identity is per device: anything running as
230
+ you on another tailnet device of yours is the owner here. Do not proxy another
231
+ service to this listener. Shapewall's tests cover its own request handling with
232
+ a stand-in proxy, not your Tailscale daemon or tailnet ACLs
233
+ ([what was and was not checked](hosted.md#what-was-and-was-not-checked-against-real-tailscale)).
212
234
 
213
235
  ### Tailscale with a local account
214
236
 
@@ -134,16 +134,59 @@ scrolling keeps momentum and `scrollIntoView` on phones).
134
134
 
135
135
  On desktop the toolbar has two zones with the room between them, the way canvas tools lay it out. Left, identity: the board
136
136
  switcher with the capture status dot (its tooltip says when the pages were captured); then, after a hairline, the view controls: the
137
- screen-size switch, Views (the journeys and what the canvas shows) and, on a local board, Capture with its status. Right, act and
138
- open panels: the viewer note, Comment (the primary action and the one accent control: `soft` while comment mode is off, filled
139
- `default` with `aria-pressed="true"` while it is on, agreeing with the comment-mode banner); then, after a hairline, the Comments,
140
- Agent and Checks toggles on one track (`Toggle variant="segment"`: the open panel's toggle is the raised chip, exactly like the
141
- chosen screen size, none while the panel is closed), then Agent settings. One look for every control but the name and Comment: a
142
- quiet 32 px box with the same radius, hairline and tint, either a single button or a track whose chosen option is the raised chip.
137
+ screen-size switch, Views (the journeys and what the canvas shows) and, on a local board, Capture with its status. Right, open
138
+ panels: the viewer note, then the Comments, Agent and Checks toggles on one track (`Toggle variant="segment"`: the open panel's
139
+ toggle is the raised chip, exactly like the chosen screen size, none while the panel is closed), then Agent settings. The toolbar
140
+ holds what you look at; what you do to the board is in the board tools (below). One look for every control but the name: a quiet
141
+ 32 px box with the same radius, hairline and tint, either a single button or a track whose chosen option is the raised chip.
143
142
  Comments carries its count as a pill at its right end, and Agent carries the board's agent activity in the same place and size: a
144
143
  dot for one agent, a count for more, accent while working (a slow `breathe`, the same as a working pin, never outside the button),
145
144
  the attention colour when an agent needs a person, green for a moment when the last one finishes.
146
145
 
146
+ ### The board tools
147
+
148
+ The tools you use on the board float at the bottom centre of the canvas, the way FigJam, Miro and tldraw do it
149
+ (`client/src/board/BoardTools.jsx`, their state in `tools.js`): **Select** (V, the default pointer: a click selects a page or
150
+ opens a pin, a drag on empty canvas pans), **Hand** (H: a drag anywhere pans, a click opens nothing; desktop only), a hairline,
151
+ then **Comment** (C), **Draw** (click a page to draw on it; with a comment or a reply open it draws on that comment's page)
152
+ and, on desktop when the board has live pages, **Select text**. One tool is in use at a time (`aria-pressed`): Comment, Draw
153
+ and Select text are the filled accent button, because they change what a click does; Select and Hand in use are quiet, the
154
+ neutral fill of a chosen segment (`bg-surface-2` with an inset hairline). Esc goes back a step at a time and ends on Select. The pill is the zoom controls' pill (`rounded-lg border border-line bg-surface/95 p-0.5 shadow-pop
155
+ backdrop-blur`, 32 px icon buttons), a labelled `role="toolbar"` with one tab stop: the arrow keys, Home and End move between
156
+ the tools, and each has a tooltip with its shortcut. A person who may not comment has no Comment or Draw tool, and with only
157
+ Select left there is no toolbar (a viewer on a phone). On a desktop they keep Select and Hand, and Select text while a page
158
+ is live.
159
+
160
+ The note for the tool in use sits just above the tools, one at a time: the comment hint ("Click a page to comment ...", or
161
+ "Click where the comment goes on Pricing" when Comment was pressed on that page's bar),
162
+ "Commenting on ..." while the composer is open, the drawing bar, or the select-text note. Select has none. The tools, their note,
163
+ an open journey's bar and the toast are one column (the tool dock), so they never overlap. The tools are centred on the canvas,
164
+ not the window, and never sit over the zoom controls (bottom left) or the minimap (bottom right): on a narrow canvas they shift
165
+ off centre, then the zoom controls compact to out, level and in, then the minimap steps aside (`toolDock.js`, unit-tested). On a
166
+ phone the tools are the bottom bar: 44 px targets above the safe-area inset, hidden while a sheet or the keyboard is up.
167
+
168
+ ### The page bar
169
+
170
+ A selected page has a bar of its actions floating beside it in screen pixels (`client/src/board/FrameBar.jsx`): above the card, else
171
+ to its right or left, never over the notes at the top of the canvas or the tool dock at the bottom, and one "..." button when
172
+ there is no room (`frameBarPlace.js`). In order: the page's name and screen size, **Comment**, **Open live** (or **Select text**
173
+ once the page is live), **Checks**, **History**, **Capture**, open in a new tab, close.
174
+
175
+ **Comment** is first because it is the main thing people do with a page, and the tools at the bottom are easy to miss. It is the
176
+ `soft` button at rest (accent text on a light accent tint) and the filled accent while on (`aria-pressed`); its tooltip is
177
+ "Comment on this page" with the C key. It turns the Comment tool on with this page as the target: the hint above the tools names
178
+ the page, the next click on it pins (to the element, on a live page), and a click anywhere else is comment mode's as ever. From
179
+ the keyboard, Enter on the button moves the focus to the page, and Enter there opens the composer near the top left of what
180
+ shows of it; Esc gives the focus back to the button. Only people who have the Comment tool have the button (the same rule: not
181
+ viewers, view-only links, compare mode or static exports). The first time someone who has not started a comment in this browser
182
+ selects a page, the button wears an accent ring for about two and a half seconds (`shapewall.tip.pageComment` in local storage;
183
+ the demo's Reset forgets it). It is a ring, not an animation, so reduced motion needs no other path.
184
+
185
+ The bar is always one line. When the canvas is too narrow for it, words drop in a fixed order and each button keeps its
186
+ accessible name and a tooltip (`fitFrameBar` in `frameBarPlace.js`, unit-tested): Capture, History, Checks, then the page's
187
+ name, then Open live, and Comment last. The widths come from the buttons' fixed sizes, never from the rendered bar. On a phone
188
+ the bar has 44 px targets, no name, and words only on Comment and Open live.
189
+
147
190
  Search is not in the toolbar. It is the field at the top of the expanded sidebar ("Search the board" with its
148
191
  Ctrl/Cmd+K hint) and an icon in the collapsed rail; both open the command palette, as the shortcut does from anywhere. So the bar
149
192
  keeps its shape whatever is open: an open journey shows as the state of the Views button in place (its name, truncated past 240 px,
@@ -151,6 +194,12 @@ and a clear button), and nothing else moves or collapses for it. When it gets na
151
194
  in a fixed order (the panel toggles, Views (an open journey's name shortens first), then the screen-size toggle to icons with
152
195
  tooltips, where the hairlines go too) and the board name truncates a little at each step, never below about 8 characters.
153
196
  Accessible names, shortcuts and tooltips never change.
197
+ While a side panel is open its toggles are the panel's header: their track is exactly as wide as the panel under it, inside the
198
+ bar's 12 px padding on both sides (the panel's own inset), the three sharing the width, and it follows the panel's drag handle with
199
+ no transition (`sidePanelWidth.js` carries the width from the panel to the bar). Everything else in the right zone (the viewer
200
+ note, Agent settings) stays to their left. The left zone drops words sooner to make the room; when no step fits, the toggles keep
201
+ their own width. The panel is never narrower than its toggles need (`SIDE_PANEL` in `toolbarFit.js`: 384 px by default, 368 px at
202
+ least, 560 px or 40% of the window at most).
154
203
  `test/toolbar-fit.test.js` checks the order and that nothing overlaps from a 1024 px window with the widest sidebar up. The phone
155
204
  toolbar is a separate compact bar. `ToggleGroup` options take a `tooltip` for icon-only labels.
156
205
 
@@ -167,7 +216,7 @@ One scale for `z-index`, lowest first. Pick the row that says what the thing is;
167
216
  | --------- | ----------------- | ----------------------------------------------------------------------------------------------- |
168
217
  | Canvas | `z-10`/`z-20` | Pins, card headers and bars, resize handles, presence cursors. |
169
218
  | On canvas | `z-30` | Things that belong to the canvas but float over cards: the comment thread and new-comment box, |
170
- | | | the journey bar, canvas notes, Try this. |
219
+ | | | the board tools and their note, the journey bar, canvas notes, Try this. |
171
220
  | Chrome | `z-40` | Sticky app headers and the collapsed sidebar's flyouts. |
172
221
  | Modal | `z-50` | Dialogs, sheets, the command palette and their dimmed overlay. A modal covers everything below. |
173
222
  | Menu | `z-[60]` | Dropdown menus, selects and small popovers, so they work inside a dialog. |