shapewall 0.0.0-stage → 0.2.2

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 (304) hide show
  1. package/CHANGELOG.md +139 -0
  2. package/Dockerfile.agent +45 -0
  3. package/LICENSE +202 -0
  4. package/NOTICE +12 -0
  5. package/README.md +651 -2
  6. package/THIRD_PARTY.md +165 -0
  7. package/bin/shapewall.js +29 -0
  8. package/dist/agent/package-lock.json +8384 -0
  9. package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
  10. package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
  11. package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
  12. package/dist/client/assets/History-CEv6b-av.js +1 -0
  13. package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
  14. package/dist/client/assets/Management-DCfhcEUY.js +1 -0
  15. package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
  16. package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
  17. package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
  18. package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
  19. package/dist/client/assets/index-ByQRKVit.css +2 -0
  20. package/dist/client/assets/index-DweQ8Qtu.js +29 -0
  21. package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
  22. package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
  23. package/dist/client/assets/square-A8EnIYLR.js +1 -0
  24. package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
  25. package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
  26. package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
  27. package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
  28. package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
  29. package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
  30. package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
  31. package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
  32. package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
  33. package/dist/client/assets/ui-CLbws0rx.js +41 -0
  34. package/dist/client/build-info.json +1 -0
  35. package/dist/client/favicon.svg +7 -0
  36. package/dist/client/icons/apple-touch-icon.png +0 -0
  37. package/dist/client/icons/icon-192.png +0 -0
  38. package/dist/client/icons/icon-512.png +0 -0
  39. package/dist/client/icons/maskable-512.png +0 -0
  40. package/dist/client/index.html +25 -0
  41. package/dist/client/manifest.webmanifest +15 -0
  42. package/dist/client/sw.js +53 -0
  43. package/dist/client/theme-boot.js +27 -0
  44. package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
  45. package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
  46. package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
  47. package/dist/console/assets/console-C7uJLLOn.js +51 -0
  48. package/dist/console/assets/console-R8IBY3Am.css +2 -0
  49. package/dist/console/build-info.json +1 -0
  50. package/dist/console/console.html +21 -0
  51. package/dist/console/favicon.svg +7 -0
  52. package/dist/console/icons/apple-touch-icon.png +0 -0
  53. package/dist/console/icons/icon-192.png +0 -0
  54. package/dist/console/icons/icon-512.png +0 -0
  55. package/dist/console/icons/maskable-512.png +0 -0
  56. package/dist/console/manifest.webmanifest +15 -0
  57. package/dist/console/theme-boot.js +27 -0
  58. package/docs/agent-hardening.md +342 -0
  59. package/docs/agent-recipes.md +187 -0
  60. package/docs/agent-workflow.md +320 -0
  61. package/docs/agents.md +894 -0
  62. package/docs/architecture.md +242 -0
  63. package/docs/buzz.md +140 -0
  64. package/docs/capture-warnings.md +57 -0
  65. package/docs/config.md +489 -0
  66. package/docs/deployment.md +289 -0
  67. package/docs/design-system.md +162 -0
  68. package/docs/github.md +107 -0
  69. package/docs/hosted.md +764 -0
  70. package/docs/images/board-overview.png +0 -0
  71. package/docs/images/journeys.png +0 -0
  72. package/docs/images/live-comment.png +0 -0
  73. package/docs/images/phone-comment.png +0 -0
  74. package/docs/images/phone-overview.png +0 -0
  75. package/docs/images/variant.png +0 -0
  76. package/docs/interaction-audits.md +40 -0
  77. package/docs/journeys.md +137 -0
  78. package/docs/local-accounts.md +80 -0
  79. package/docs/notifications.md +237 -0
  80. package/docs/page-checks.md +69 -0
  81. package/docs/performance.md +174 -0
  82. package/docs/starter-agent.md +325 -0
  83. package/docs/updates.md +87 -0
  84. package/examples/audits/interaction.audit.json +17 -0
  85. package/package.json +132 -4
  86. package/src/accounts/avatar.js +121 -0
  87. package/src/accounts/local.js +464 -0
  88. package/src/agent/acp/command.js +204 -0
  89. package/src/agent/acp/detect.js +75 -0
  90. package/src/agent/acp/sandbox.js +160 -0
  91. package/src/agent/agent-health.js +75 -0
  92. package/src/agent/backends/acp.js +1297 -0
  93. package/src/agent/backends/index.js +61 -0
  94. package/src/agent/backends/openai.js +308 -0
  95. package/src/agent/composer.js +221 -0
  96. package/src/agent/config.js +338 -0
  97. package/src/agent/context.js +191 -0
  98. package/src/agent/control.js +122 -0
  99. package/src/agent/errors.js +17 -0
  100. package/src/agent/feedback-loop.js +137 -0
  101. package/src/agent/manage.js +94 -0
  102. package/src/agent/next-steps.js +51 -0
  103. package/src/agent/owner-mcp.js +38 -0
  104. package/src/agent/plain-text.js +52 -0
  105. package/src/agent/ratings-core.js +213 -0
  106. package/src/agent/ratings.js +100 -0
  107. package/src/agent/reply-text.js +67 -0
  108. package/src/agent/routes.js +1065 -0
  109. package/src/agent/run.js +326 -0
  110. package/src/agent/settings-routes.js +704 -0
  111. package/src/agent/showable.js +23 -0
  112. package/src/agent/starter/approvals.js +181 -0
  113. package/src/agent/starter/build-image.js +90 -0
  114. package/src/agent/starter/cli.js +163 -0
  115. package/src/agent/starter/disk.js +53 -0
  116. package/src/agent/starter/doctor.js +180 -0
  117. package/src/agent/starter/egress-proxy.js +351 -0
  118. package/src/agent/starter/gate.js +90 -0
  119. package/src/agent/starter/loop.js +114 -0
  120. package/src/agent/starter/model-relay.js +289 -0
  121. package/src/agent/starter/pause.js +14 -0
  122. package/src/agent/starter/probe.js +272 -0
  123. package/src/agent/starter/prompt.js +41 -0
  124. package/src/agent/starter/push-guard.js +146 -0
  125. package/src/agent/starter/rpc.js +164 -0
  126. package/src/agent/starter/runtime.js +287 -0
  127. package/src/agent/starter/sandbox-main.js +121 -0
  128. package/src/agent/starter/settings.js +290 -0
  129. package/src/agent/starter/source.js +69 -0
  130. package/src/agent/starter/supervisor.js +755 -0
  131. package/src/agent/starter/sweep.js +46 -0
  132. package/src/agent/starter/tools.js +524 -0
  133. package/src/agent/starter/watch.js +84 -0
  134. package/src/agent/starter/worktree.js +409 -0
  135. package/src/agent/text-diff.js +210 -0
  136. package/src/agent/thread-history.js +223 -0
  137. package/src/agent/threads.js +399 -0
  138. package/src/agent/tools.js +200 -0
  139. package/src/agent/turn-changes.js +424 -0
  140. package/src/agent/undo-state.js +26 -0
  141. package/src/agent/user-settings.js +308 -0
  142. package/src/auth/record.js +375 -0
  143. package/src/broken-links.js +164 -0
  144. package/src/buzz/client.js +75 -0
  145. package/src/buzz/config.js +151 -0
  146. package/src/buzz/environment.js +13 -0
  147. package/src/buzz/gateway.js +192 -0
  148. package/src/buzz/routes.js +61 -0
  149. package/src/buzz/signer-child.js +205 -0
  150. package/src/buzz/store.js +89 -0
  151. package/src/buzz/transport.js +60 -0
  152. package/src/buzz/verify.js +140 -0
  153. package/src/capture/actions.js +159 -0
  154. package/src/capture/capture.js +776 -0
  155. package/src/capture/dom-names.js +189 -0
  156. package/src/capture/element-map.js +509 -0
  157. package/src/capture/live.js +827 -0
  158. package/src/capture/media-scheme.js +317 -0
  159. package/src/capture/network-summary.js +86 -0
  160. package/src/capture/pacing.js +34 -0
  161. package/src/capture/requests.js +167 -0
  162. package/src/capture/sanitize.js +752 -0
  163. package/src/checks/accessibility.js +134 -0
  164. package/src/checks/budgets.js +58 -0
  165. package/src/checks/cli.js +55 -0
  166. package/src/checks/comparison.js +113 -0
  167. package/src/checks/environments.js +32 -0
  168. package/src/checks/flow-config.js +82 -0
  169. package/src/checks/flow-origin.js +53 -0
  170. package/src/checks/flows.js +398 -0
  171. package/src/checks/lighthouse-auth.js +145 -0
  172. package/src/checks/lighthouse-findings.js +130 -0
  173. package/src/checks/lighthouse.js +395 -0
  174. package/src/checks/robots.js +85 -0
  175. package/src/checks/routes.js +52 -0
  176. package/src/checks/run-control.js +259 -0
  177. package/src/checks/runner.js +724 -0
  178. package/src/checks/schema.js +133 -0
  179. package/src/checks/seo-analysis.js +443 -0
  180. package/src/checks/seo-probe.js +190 -0
  181. package/src/checks/seo-snapshot.js +99 -0
  182. package/src/checks/store.js +214 -0
  183. package/src/checks/transport.js +47 -0
  184. package/src/cli/args.js +319 -0
  185. package/src/cli/capture.js +79 -0
  186. package/src/cli/commands.js +92 -0
  187. package/src/cli/comments.js +84 -0
  188. package/src/cli/help.js +243 -0
  189. package/src/cli/init.js +214 -0
  190. package/src/cli/misc.js +64 -0
  191. package/src/cli/notify.js +87 -0
  192. package/src/cli/open.js +22 -0
  193. package/src/cli/serve.js +274 -0
  194. package/src/cli/variant.js +82 -0
  195. package/src/cli/watch.js +70 -0
  196. package/src/cli.js +130 -0
  197. package/src/comment-fields.js +76 -0
  198. package/src/comments-cli.js +208 -0
  199. package/src/config-reload.js +100 -0
  200. package/src/config.js +1061 -0
  201. package/src/devices-cli.js +21 -0
  202. package/src/diff.js +95 -0
  203. package/src/discover.js +284 -0
  204. package/src/doctor.js +295 -0
  205. package/src/event-log.js +268 -0
  206. package/src/events-cli.js +102 -0
  207. package/src/events.js +113 -0
  208. package/src/export.js +119 -0
  209. package/src/feedback.js +246 -0
  210. package/src/github.js +551 -0
  211. package/src/hosted/LICENSE.md +105 -0
  212. package/src/hosted/access-cli.js +78 -0
  213. package/src/hosted/admin.js +682 -0
  214. package/src/hosted/agent-approvals.js +163 -0
  215. package/src/hosted/agent-policy.js +189 -0
  216. package/src/hosted/app.js +510 -0
  217. package/src/hosted/auth-routes.js +540 -0
  218. package/src/hosted/auth.js +536 -0
  219. package/src/hosted/backup.js +483 -0
  220. package/src/hosted/board-context.js +35 -0
  221. package/src/hosted/board-routes.js +486 -0
  222. package/src/hosted/board-view.js +94 -0
  223. package/src/hosted/clean-worker.js +24 -0
  224. package/src/hosted/cleaner.js +89 -0
  225. package/src/hosted/comments.js +355 -0
  226. package/src/hosted/console-routes.js +401 -0
  227. package/src/hosted/cookies.js +18 -0
  228. package/src/hosted/crypto.js +80 -0
  229. package/src/hosted/db.js +496 -0
  230. package/src/hosted/device-routes.js +175 -0
  231. package/src/hosted/device.js +233 -0
  232. package/src/hosted/events.js +63 -0
  233. package/src/hosted/guards.js +172 -0
  234. package/src/hosted/guest-view.js +65 -0
  235. package/src/hosted/http.js +39 -0
  236. package/src/hosted/import.js +300 -0
  237. package/src/hosted/mail.js +73 -0
  238. package/src/hosted/mcp-http.js +71 -0
  239. package/src/hosted/membership.js +114 -0
  240. package/src/hosted/operator.js +478 -0
  241. package/src/hosted/ops-cli.js +345 -0
  242. package/src/hosted/pages.js +146 -0
  243. package/src/hosted/permissions.js +113 -0
  244. package/src/hosted/presence.js +372 -0
  245. package/src/hosted/projects.js +124 -0
  246. package/src/hosted/public.js +109 -0
  247. package/src/hosted/push.js +622 -0
  248. package/src/hosted/quotas.js +115 -0
  249. package/src/hosted/ratelimit.js +96 -0
  250. package/src/hosted/rebind.js +316 -0
  251. package/src/hosted/retention.js +128 -0
  252. package/src/hosted/server.js +260 -0
  253. package/src/hosted/setup-link.js +64 -0
  254. package/src/hosted/setup.js +323 -0
  255. package/src/hosted/shares.js +444 -0
  256. package/src/hosted/tailscale.js +204 -0
  257. package/src/hosted/tenancy.js +301 -0
  258. package/src/hosted/token-api.js +455 -0
  259. package/src/hosted/token-events.js +60 -0
  260. package/src/hosted/tokens.js +57 -0
  261. package/src/hosted/turnstile.js +49 -0
  262. package/src/hosted/usercontent.js +154 -0
  263. package/src/hosted/zip.js +155 -0
  264. package/src/invocation.js +58 -0
  265. package/src/journey-paths.js +282 -0
  266. package/src/journeys.js +189 -0
  267. package/src/links.js +106 -0
  268. package/src/local-projects.js +182 -0
  269. package/src/lock.js +193 -0
  270. package/src/mcp.js +417 -0
  271. package/src/mentions.js +151 -0
  272. package/src/net.js +15 -0
  273. package/src/notify/config.js +275 -0
  274. package/src/notify/index.js +301 -0
  275. package/src/notify/lease.js +73 -0
  276. package/src/notify/messages.js +212 -0
  277. package/src/notify/run.js +174 -0
  278. package/src/pixeldiff.js +49 -0
  279. package/src/png.js +143 -0
  280. package/src/reactions.js +111 -0
  281. package/src/remote/cli.js +133 -0
  282. package/src/remote/credentials.js +62 -0
  283. package/src/remote/ids.js +12 -0
  284. package/src/remote/login.js +155 -0
  285. package/src/remote/remote-mcp.js +237 -0
  286. package/src/remote/remote-watch.js +291 -0
  287. package/src/remote/remote.js +313 -0
  288. package/src/remote/share-state.js +78 -0
  289. package/src/remote/share.js +369 -0
  290. package/src/remote/terminal.js +13 -0
  291. package/src/serve-state.js +64 -0
  292. package/src/server/app.js +824 -0
  293. package/src/server/devices.js +186 -0
  294. package/src/server/local-console.js +28 -0
  295. package/src/server/local-user.js +59 -0
  296. package/src/server/pairing-routes.js +159 -0
  297. package/src/server/share-routes.js +89 -0
  298. package/src/server/tailscale.js +97 -0
  299. package/src/sitemap.js +431 -0
  300. package/src/store.js +983 -0
  301. package/src/tokens.js +11 -0
  302. package/src/update/routes.js +245 -0
  303. package/src/watch.js +403 -0
  304. package/src/which.js +58 -0
@@ -0,0 +1,174 @@
1
+ # Local Lighthouse navigation audits
2
+
3
+ Shapewall's Lighthouse runner audits the original application URL. It does not
4
+ measure the screenshot viewer, capture duration or PNG size. Audits run only
5
+ when explicitly invoked locally or in CI. The hosted server never launches an
6
+ audit or fetches an arbitrary submitted URL.
7
+
8
+ The runner exports `auditCommand(config, positional, flags, out, err)` for the
9
+ CLI and `runLighthouseAudits({ config, ...options })` for trusted local tooling.
10
+ The CLI integration mounts it under `shapewall audit`. The runner itself
11
+ does not change captures or application configuration.
12
+
13
+ ## Runtime and limits
14
+
15
+ Use Node 22.19 or later and an installed Chrome. The exact runtime dependencies
16
+ are Lighthouse 13.6.0, chrome-launcher 1.2.2 and puppeteer-core 25.16.0. No browser
17
+ is downloaded. `config.browser.executablePath` selects Chrome explicitly;
18
+ otherwise the installed Chrome is discovered. An unsupported browser channel
19
+ fails honestly. An optional `--browser-version` requires an exact installed
20
+ browser version for reproducible CI comparisons.
21
+
22
+ Run audits through the machine's capped browser wrapper, for example
23
+ `browser-slot node ...` in local tooling. Each navigation gets its own private
24
+ browser profile beneath the configured output directory. The runner closes the
25
+ browser and removes this profile on success or failure.
26
+
27
+ Selection flags are `--board`, `--env`, `--only page-a,page-b` and
28
+ `--viewports desktop,phone`. The defaults allow at most five pages and ten
29
+ navigations. Explicit `--max-pages` and `--max-runs` can raise those caps to 20
30
+ pages and 40 navigations. `--samples` defaults to one and cannot exceed ten.
31
+ All navigations run serially, with a two-minute hard deadline per navigation.
32
+ An oversized selection fails before starting Chrome.
33
+
34
+ Each repeat is a separate raw report with `sampleCount: 1`, a distinct report
35
+ identifier and the same run identifier. Repeats do not silently become a median
36
+ or a more confident score. `--json` prints only the bounded report result.
37
+ A partial, unsupported or failed audit returns a nonzero command status.
38
+
39
+ ## Measurement profile
40
+
41
+ The report records the actual Chrome version, a hash of the emulated user
42
+ agent, the configured viewport dimensions, device scale, mobile emulation and
43
+ the pinned Lighthouse version. Tablet and phone use Lighthouse's mobile user
44
+ agent; desktop uses its desktop agent. The emulated user agent is independent
45
+ of the installed Chrome version.
46
+
47
+ Network and CPU conditions use Lighthouse simulation, not field measurements.
48
+ Desktop uses 40 ms RTT, 10240 Kbps throughput and a CPU multiplier of one.
49
+ Mobile uses 150 ms RTT, 1638.4 Kbps throughput and a CPU multiplier of four.
50
+ The exact conditions are persisted in the profile, so unlike profiles must not
51
+ be compared as equivalent runs.
52
+
53
+ Anonymous audits default to `--cache cold`: browser cache and origin storage
54
+ are cleared before navigation. `--cache warm` performs an unmeasured initial
55
+ navigation before the measured one. Configured authentication requires
56
+ `--cache auth-preserved`, which retains authentication storage, cache and
57
+ service workers. These conditions are deliberately different profiles.
58
+
59
+ Set `--production production` or `--production development` to declare the
60
+ build mode; the default is `unknown`. Set `--source-build` to an opaque build
61
+ identifier when available, such as a Git commit SHA or build hash. Identifiers
62
+ accept one to 120 letters, digits, dots, underscores or hyphens. Both checks
63
+ runners hash the identifier with the same fingerprint function before storing it. The runner does not infer a production build from
64
+ a fast response or a familiar hostname. A capture association and target state
65
+ fingerprint identify which existing wall entry was audited, while
66
+ `sampledSeparately: true` makes clear that this was a later navigation.
67
+
68
+ Raw metrics are `largestContentfulPaintMs`, `cumulativeLayoutShift` (unitless),
69
+ `firstContentfulPaintMs`, `totalBlockingTimeMs`, `speedIndexMs`,
70
+ `transferredResourceBytes` and `observedRequests`. Unknown values remain `null`.
71
+ `lighthouseLabScore` and optional `lighthouseSeoLabScore` are secondary scores
72
+ from zero to 100. Enable the latter with `--seo`; it is an automated local
73
+ check, not a search ranking claim. Navigation audits do not establish field
74
+ INP or interaction responsiveness. Configured actions run once during the
75
+ navigation window; their presence is recorded as a limitation.
76
+
77
+ ## Authentication and intended state
78
+
79
+ A Playwright storage file is not passed blindly to Lighthouse. The adapter
80
+ reads the configured storage file, or executes the trusted configured
81
+ Playwright login script, then deliberately transfers cookies and localStorage
82
+ to the prepared Chrome target. It records a hash of the resulting state and
83
+ never persists the credentials in a report.
84
+
85
+ Only bounded cookie and localStorage state is supported. Partitioned cookies,
86
+ IndexedDB content and unsupported storage shapes fail as unsupported.
87
+ Session storage, browser extensions, custom Playwright selectors and other
88
+ browser-only session mechanisms are not translated. Use standard CSS selectors
89
+ for ready states and configured actions.
90
+
91
+ A configured signed-in audit must declare `waitFor` with a selector visible
92
+ only in the intended signed-in state. The original origin, path and query state
93
+ must match before and after readiness checks and actions. An authentication
94
+ redirect, missing ready selector or unexpected document status produces a
95
+ failed report with unknown metrics. A login page never counts as a successful
96
+ measurement of the intended application.
97
+
98
+ Login scripts are existing trusted local configuration, not code submitted by
99
+ a hosted user. They can have application side effects. Use a dedicated test
100
+ account and the same deliberate fixture discipline as capture automation.
101
+
102
+ ## Reports and privacy
103
+
104
+ Reports use the shared bounded checks schema and retain at most 200 reports per
105
+ board. They contain raw numeric metrics, a measurement profile, completeness
106
+ limitations and a capped set of static actionable performance findings.
107
+ Only audited, applicable opportunities from an allowlist become findings.
108
+ Resource URLs, private paths, query values, headers, cookies, response bodies,
109
+ DOM snippets, raw Lighthouse logs and traces are not written to reports.
110
+ Failures also use fixed safe messages rather than raw browser errors.
111
+
112
+ A complete report requires all four primary navigation metrics: LCP, CLS, FCP
113
+ and TBT. Missing metrics produce `partial`; failures and unsupported conditions
114
+ produce no trustworthy numeric measurements. Never substitute zero for missing
115
+ data or mix these reports with capture timings.
116
+
117
+ Reference: [Lighthouse authentication guidance](https://github.com/GoogleChrome/lighthouse/blob/main/docs/authenticated-pages.md),
118
+ [Lighthouse programmatic usage](https://github.com/GoogleChrome/lighthouse/blob/main/docs/readme.md).
119
+
120
+ ## Performance budgets and report history
121
+
122
+ Checks keeps up to 200 reports per board. In the Checks panel, expand **History and comparison**,
123
+ choose an after report and a baseline, then inspect raw measurements and finding changes. History
124
+ remains usable when its screenshot has expired. Reports stay separated by runner, page, environment
125
+ and device; repeat samples are individually selectable, not silently averaged.
126
+
127
+ The comparison requires the same recorded runner version, browser, authentication state, configured
128
+ page state, viewport, device emulation, cache, throttling, observation coverage and service worker
129
+ state. Older reports missing browser/device/throttling evidence explain why comparison is unavailable.
130
+ Different declared builds can be compared only by explicitly choosing **Allow declared build as the
131
+ changed variable**. Both runs must have a build fingerprint; this choice never relaxes other conditions.
132
+ Build identifiers are stored as fingerprints, not raw labels. Undeclared builds remain labelled unknown.
133
+
134
+ Missing or failed measurements show **Unknown**, never zero. Deltas use the metric's units. Movement
135
+ below either 5 percent or the display floor (50 ms, 1024 bytes, 0.01 layout shift, otherwise 1) is labelled
136
+ small; these are display rules, not statistical confidence or regression detection. An increase alone
137
+ is not proof of a regression. Finding changes require two complete comparable runs and unchanged budget
138
+ policy; absence in a later run is only “no longer observed,” not proof of a fix.
139
+
140
+ Set optional explicit maximums in the top-level configuration. No performance budgets are enabled by
141
+ default. Choose values appropriate to the app, device and lab setup; the following is an example, not
142
+ an enforced universal target:
143
+
144
+ ```json
145
+ {
146
+ "checks": {
147
+ "budgets": {
148
+ "largestContentfulPaintMs": 2500,
149
+ "totalBlockingTimeMs": 200,
150
+ "cumulativeLayoutShift": 0.1,
151
+ "transferredResourceBytes": 1500000,
152
+ "loadMs": 3000
153
+ }
154
+ }
155
+ }
156
+ ```
157
+
158
+ Each newly run report records the exact configured thresholds and policy version. A known measurement
159
+ above its maximum produces a performance warning with the observation and next action; equality is
160
+ within budget. Missing metrics, including metrics belonging to another runner, remain unknown. Failed
161
+ and unsupported runs never pass budgets. Importing or viewing an old report does not recompute it
162
+ against a newer configuration.
163
+
164
+ Supported metrics are `ttfbMs`, `loadMs`, `domContentLoadedMs`, `documentTransferBytes`,
165
+ `resourceTransferBytes`, `resourceDecodedBytes`, `requestCount`, `largestContentfulPaintMs`,
166
+ `firstContentfulPaintMs`, `totalBlockingTimeMs`, `cumulativeLayoutShift`, `transferredResourceBytes`,
167
+ `observedRequests` and `speedIndexMs`. Values are finite nonnegative maxima in the named units. These
168
+ budgets apply to explicit local `checks` and `audit` runs; they do not schedule scans or measure field vitals.
169
+
170
+ **Problems first** prioritizes failed/unsupported runners, warnings, stale results and partial runs.
171
+ **Performance findings** narrows to observed performance warnings. **Slowest LCP first** orders the
172
+ latest Lighthouse value per page/device view, placing unknown and failed values last. Use the device
173
+ selector to narrow the list. It never combines device scores, and this triage ordering does not make
174
+ runs with different conditions comparable.
@@ -0,0 +1,325 @@
1
+ # The sandboxed starter agent
2
+
3
+ `shapewall agent` takes one board comment at a time and works on it inside a container: it reads the request, edits files in a fresh
4
+ checkout of your repo (with no `.git` in it), runs your tests, replies on the comment and leaves the change on a new branch (and, if you ask, a pull request). It is
5
+ meant for **shared boards**, where the people writing comments are not all people you would hand a shell to.
6
+
7
+ The board chat ([agents.md](agents.md)) runs an agent _as you_, on your machine. The starter agent assumes the comment may be hostile and
8
+ puts walls around the agent instead: the container, an egress allow list, a fixed set of tools, a trigger gate, budgets and branch-only
9
+ output. This page says what each wall does and, as plainly, what it does not.
10
+
11
+ ## Quick start
12
+
13
+ You need podman or docker, a git repo with a `shapewall.config.json`, and an OpenAI-compatible model endpoint (the same settings as the
14
+ chat: `agent.baseUrl` and `agent.model`, or `SHAPEWALL_AGENT_BASE_URL` and `SHAPEWALL_AGENT_MODEL`, with the key in
15
+ `SHAPEWALL_AGENT_API_KEY` or the variable `agent.apiKeyEnv` names).
16
+
17
+ 1. Build the agent image once. It is built on your machine from the `Dockerfile.agent` that ships in the package, and never pulled
18
+ or published:
19
+
20
+ ```sh
21
+ npx shapewall agent build-image # --runtime podman|docker, --image NAME (default localhost/shapewall-agent:latest)
22
+ ```
23
+
24
+ It builds from a folder holding only what the image needs, with the locked dependency versions (npm never puts
25
+ `package-lock.json` in a package, so the package carries a copy in `dist/agent/`). In a clone of the repository,
26
+ `podman build -f Dockerfile.agent -t localhost/shapewall-agent:latest .` (or `docker build ...`) does the same by hand.
27
+
28
+ 2. Say who may dispatch work, and how to test, in `shapewall.config.json`:
29
+
30
+ ```json
31
+ "starterAgent": {
32
+ "trusted": ["robin", "sam"],
33
+ "setupCommand": "npm ci",
34
+ "testCommand": "npm test"
35
+ }
36
+ ```
37
+
38
+ 3. Check the machine and the sandbox:
39
+
40
+ ```sh
41
+ npx shapewall agent doctor
42
+ ```
43
+
44
+ The doctor starts a container exactly like the agent's (same network, proxy, mounts, user and limits) with a probe in place of the
45
+ agent, and reports each check: not root, no capabilities, no new privileges, read-only root, only the checkout mounted, no home
46
+ folder, SSH keys or runtime socket, no host environment, no direct egress or outside DNS, no way to this machine's own ports, and a
47
+ proxy that refuses hosts off the list and TLS names other than the allowed one.
48
+
49
+ `agent run` and `agent watch` start by removing what runs that died left behind (containers, networks and checkout folders whose
50
+ owner process is gone).
51
+
52
+ 4. Run it on a comment, or watch the board:
53
+
54
+ ```sh
55
+ npx shapewall agent run --comment 12
56
+ npx shapewall agent watch # every comment the gate lets through; --once to drain and exit
57
+ ```
58
+
59
+ The reply on the comment says what changed, the branch, the tests, anything the proxy blocked, and the budget used, for example
60
+ `Budget: 6 of 20 turns, 41,200 of 200,000 tokens, 2m 14s of 15m.` The comment's agent status ends as `done` or `needs-human`.
61
+
62
+ ## The trigger gate
63
+
64
+ Anyone who can comment can write text the agent will act on, so a comment is dispatched only when a trusted member stands behind it:
65
+
66
+ - a **share link guest's** comment (`authorGuest`) is never dispatched, whoever tags it later, and guest replies are left out of the
67
+ task;
68
+ - a comment **written by an agent** is never dispatched, so agents do not feed each other;
69
+ - a **trusted member's** own comment is dispatched;
70
+ - anyone else's comment **waits** until a trusted member replies with `@agent`. The tag vouches for the text as it was: if the comment
71
+ is edited after the tag, it waits for a new one.
72
+
73
+ `starterAgent.trusted` is the default list; `starterAgent.boards.<id>.trusted` replaces it for one board; `--trusted NAME` adds to it for
74
+ one run. An empty list dispatches nothing. `--trust-comment` runs one comment the gate holds back (never a guest's or an agent's).
75
+
76
+ Who counts as a member depends on the board:
77
+
78
+ - **Hosted boards** (`--remote`): the account handle the server attests (`authorHandle`, `reply.handle`). Display names never count.
79
+ - **Local boards**: the author name as typed. A local board has no accounts, so this is only as strong as who can reach the board. On
80
+ a board shared through a proxy, anyone who can comment can type a trusted name: put real authentication in front (see
81
+ [deployment.md](deployment.md)) or use a hosted board.
82
+
83
+ A comment is claimed with a compare-and-set on its agent status, so two runs never take the same comment. `--retry` takes one whose
84
+ status is `done` or `needs-human`.
85
+
86
+ ## What the agent can do
87
+
88
+ A fixed set of tools, nothing else:
89
+
90
+ | Tool | What it does |
91
+ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
92
+ | `list_files`, `read_file`, `search` | Read the checkout. `.git` is refused. |
93
+ | `write_file`, `edit_file` | Change files in the checkout. Paths are resolved after symlinks; anything outside the checkout, or in `.git`, is refused. |
94
+ | `run_tests` | Runs `starterAgent.testCommand` (no shell), only when one is set. Needs your approval after the agent changed what it runs. |
95
+ | `capture` | `shapewall capture --only <page>` in the checkout. Offered only when the site is reachable from the sandbox (see below). |
96
+ | `reply`, `set_status` | Up to 3 replies on the comment (2,000 characters each), and its agent status. |
97
+ | `run_shell` | Any command, but only after you approve that exact command on the board (local boards only, see below). |
98
+
99
+ `starterAgent.setupCommand` (for example `npm ci`) runs once before the agent starts, in the container, with the package registry
100
+ reachable.
101
+
102
+ Paths are relative to the repo root. Models often write the container's mount point into them, so `/work/src/app.js`, and
103
+ `work/src/app.js` when the repo has no top-level `work`, both mean `src/app.js`. A path that does not exist answers
104
+ `path not found: <path>; paths are relative to the repo root`, for reads, listings, searches and edits alike.
105
+
106
+ `capture` is offered only when the board's `baseUrl` can be reached from the sandbox: its host and port must be on the egress allow list
107
+ (`--allow-host`), and it must not be this machine (`localhost`, `127.0.0.1`: in the container that is the container itself) or a
108
+ private address you did not allow. A dev server on your machine is not reachable, by design, so with the usual
109
+ `http://127.0.0.1:...` baseUrl the agent has no `capture` tool and its prompt says it cannot see the site. If it calls `capture` anyway,
110
+ or a capture cannot connect, the answer is `capture is unavailable in the sandbox; skip it`.
111
+
112
+ ### Tests run the agent's code
113
+
114
+ Be plain about this: `run_tests` runs your test command over files the agent may have just changed, so a test is code the agent wrote,
115
+ and it runs with everything the sandbox allows. The walls around the container are what limit it, not the tool list. The approval of
116
+ `run_shell` happens inside the agent's own process (the host shows the card and waits for you; the container asks), so it limits what the
117
+ model can do through the tools, not what code already running in the sandbox can do.
118
+
119
+ One rule narrows it: once the agent changed a file that decides what the test command runs (a manifest or lockfile, `.npmrc`, a test,
120
+ build or TypeScript config, `Makefile`, `justfile`, `pyproject.toml` and the like, or a file the test command names), or ran an approved
121
+ shell command, `run_tests` asks for your approval on the board like `run_shell` does, and is not run where there are no approvals.
122
+
123
+ ### Approving shell commands
124
+
125
+ When the agent asks for `run_shell`, the comment's chat thread on the board shows a permission card with the exact command and the
126
+ agent's reason. The terminal running `agent run` prints the command and a link that opens the board on the comment with its chat
127
+ thread (the running `shapewall serve`'s own address when it recorded one, else `SHAPEWALL_BOARD_URL`, `notifications.boardUrl` or the
128
+ default). **Run** runs that command once; **Deny**, or no answer within two minutes, is a no. The card can only be answered from
129
+ the board on this machine: the request needs the settings token from the link `shapewall serve` prints, must be a direct local request,
130
+ same-origin, on a board that is not shared. Nobody at the board means no answer, which is a no. On hosted boards (`--remote`) the card
131
+ is on the hosted board instead (see [Hosted boards](#hosted-boards)).
132
+
133
+ ## Budgets
134
+
135
+ Each comment gets a budget of model turns, tokens and wall time (defaults 20 turns, 200,000 tokens, 15 minutes; at most 100, 2,000,000 and
136
+ 120). Set them in `starterAgent.budget` or per run with `--max-turns`, `--max-tokens` and `--max-minutes`.
137
+
138
+ They are enforced on the host, not by the agent: every model call goes through Shapewall on the host, one at a time, which refuses calls
139
+ past the turn or token budget, reserves each call's prompt (estimated at four characters a token) and caps its `max_tokens` at what is
140
+ left after that. Tokens are counted from the usage the endpoint reports (or estimated
141
+ at four characters a token, and the reply says "estimated"). At the wall time the host asks the agent to stop, and kills the container a
142
+ few seconds later. The reply always reports what was used.
143
+
144
+ Each model call has a time limit to start answering (its response headers): 180 seconds until the model first answers in a run (a
145
+ local model loading on a cold start can take minutes), 60 seconds after. `starterAgent.modelTimeoutSeconds` or `--model-timeout SECONDS`
146
+ (1 to 900) sets both. A call that times out or cannot connect is tried once more, as the same turn, within the wall time; if that fails
147
+ too, the run stops with one plain line, such as `Stopped: the model endpoint failed (could not reach it: timed out after 180 s).`
148
+
149
+ The checkout has a disk cap too (`starterAgent.limits.disk` or `--max-disk`, default `2g`, at most `64g`): a bind mount has no size limit
150
+ of its own on podman or docker, so the host measures the folder every few seconds (`du`, one file system, no symlink followed) and
151
+ kills the container as soon as it is over. Nothing is committed then, and the reply says how much it took. `/tmp` in the container is a
152
+ tmpfs with its own size (`limits.tmp`, default `1g`).
153
+
154
+ ## Output: a branch, never main
155
+
156
+ The change is committed on a new branch, `shapewall-agent/<board>-<comment>-<id>` (prefix from `starterAgent.branchPrefix`), authored
157
+ `Shapewall starter agent <starter-agent@shapewall.invalid>`, with `shapewall:<board>/<comment>` in the message so
158
+ [GitHub connect](github.md) links it. Branch names that are, or end in, `main`, `master`, `trunk`, `develop`, `production`, `staging`
159
+ or `release` are refused, for the branch and for the push, and the branch is only created if it does not exist.
160
+
161
+ The commit is made without trusting anything in the folder the container had. That folder has no `.git` (an agent that writes one
162
+ changes nothing), and git on the host always names your repository explicitly, with a temporary index outside the folder, no system
163
+ config, and hooks, fsmonitor and signing off. Shapewall reads the changed files itself, without following a symlink anywhere in a path
164
+ (a symlink is committed as a symlink) and refusing hard-linked files, and writes them with `git hash-object --no-filters`, so no clean
165
+ filter, attribute or config from the agent's files runs. `.gitattributes` and `.gitmodules` keep the base's version, and submodules are
166
+ left as they were. The reply calls out changes to dot files, package manifests, `Makefile`, `Dockerfile`, `justfile` and
167
+ `shapewall.config.json`, and symlinks that point outside the repository (`--pr` does not push those without `--allow-ci-push`).
168
+ Nothing is read from the folder until the agent container is confirmed gone; if it cannot be removed, nothing is committed and the
169
+ folder is left for the sweep. One commit reads in at most the disk cap's worth of changed files (a sparse file looks small to `du`).
170
+
171
+ `--pr` also pushes the branch to `--git-remote NAME` (default `origin`, explicit refspec, `--no-verify`, no tags, no submodules) and opens a pull request into
172
+ `starterAgent.prBase` (default: the remote's default branch) through GitHub connect, then links it to the comment. The token is GitHub
173
+ connect's (`SHAPEWALL_GITHUB_TOKEN` or `GITHUB_TOKEN`) and never enters the container. Nothing is ever pushed to main.
174
+
175
+ A pushed branch runs CI with the repository's secrets before anyone reviews it. So `--pr` does not push a change to CI config
176
+ (`.github/`, `.gitlab-ci.yml`, `.circleci/` and the like), dependency manifests and lockfiles, or build and task files (`Makefile`,
177
+ `Dockerfile`, ...): the branch stays local and the reply says why. `--allow-ci-push` pushes it anyway, for that run. Better still, pass
178
+ `--fork-remote NAME` with a git remote of your fork: the branch goes there and the pull request comes from
179
+ `<owner>:<branch>`, so the main repository's workflows treat it as a fork's (no secrets, unless a workflow uses `pull_request_target`; the CI-file rule above still applies). Even a change to plain source files can do
180
+ harm in a job that runs tests with secrets on push to any branch: prefer a fork, or CI that gives branch pushes no secrets.
181
+
182
+ The checkout lives under `~/.cache/shapewall/starter-agent/` (or `--work-dir`) and is removed after the run; the branch stays.
183
+
184
+ A run that only added new files and changed no existing one says so in the reply ("check it edited the right place"): a small model
185
+ that cannot find the file behind a page often makes a new one the site never uses.
186
+
187
+ The run's log is kept next to the board (`<board>/agent/starter-<comment>-<run>.log`, hosted runs: in the work folder). It starts with
188
+ a line naming the comment, model, endpoint host and budget, and ends with the outcome (status, why it stopped, the branch, the budget
189
+ used), failures and timeouts included. In between: which tools were offered, each turn's answer text (up to 4,000 characters a turn),
190
+ each tool call with its arguments (long values cut) and result, every approval asked and answered with the command's text and its
191
+ SHA-256, model endpoint retries, egress refusals and the container's stderr. The key is removed from every line, and no request header
192
+ is logged.
193
+
194
+ ## Configuration
195
+
196
+ `starterAgent` in `shapewall.config.json` (usually committed) may only choose what stays inside the sandbox:
197
+
198
+ | Key | Default | Notes |
199
+ | --------------------- | -------------------------------------------------- | -------------------------------------------------------- |
200
+ | `trusted` | `[]` | Who may dispatch work, on every board. |
201
+ | `boards.<id>.trusted` | | Replaces `trusted` for one board. |
202
+ | `testCommand` | none | One program and its arguments, no shell. |
203
+ | `setupCommand` | none | Runs once before the agent, with the registry reachable. |
204
+ | `budget` | `{ turns: 20, tokens: 200000, minutes: 15 }` | |
205
+ | `modelTimeoutSeconds` | 180 for the first call, then 60 | Time for a model call to start answering, 1 to 900. |
206
+ | `limits` | `{ memory: "4g", cpus: 2, pids: 512, disk: "2g" }` | Memory and `tmp` up to `16g`, CPUs up to 8, disk `64g`. |
207
+ | `branchPrefix` | `shapewall-agent/` | Lowercase, ending in `/`. |
208
+ | `prBase` | the remote's default branch | The base branch of `--pr`. |
209
+
210
+ What decides what leaves the sandbox comes only from you, never from the repo: a config with `image`, `runtime`, `registry`, `egress`,
211
+ `allowHosts`, `network`, `apiKey`, `env` or `mounts` under `starterAgent` is refused, and so is `remote` or `forkRemote` (where the
212
+ branch is pushed is a flag: `--git-remote`, `--fork-remote`).
213
+
214
+ | Flag | Environment | What |
215
+ | -------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
216
+ | `--runtime` | `SHAPEWALL_AGENT_RUNTIME` | `podman` or `docker` (default: whichever is installed, podman first). |
217
+ | `--image` | `SHAPEWALL_AGENT_IMAGE` | Default `localhost/shapewall-agent:latest`. |
218
+ | `--registry HOST`, `none` | `SHAPEWALL_AGENT_REGISTRY` | Default `registry.npmjs.org:443`. |
219
+ | `--allow-host HOST[:PORT]` | `SHAPEWALL_AGENT_EGRESS` (comma-separated) | Extra egress hosts (port 443 if none given). |
220
+ | `--profile` | | `openai-compatible` (the default). `claude-code` and `codex` are reserved and say "not available yet". |
221
+ | `--max-disk SIZE` | | The disk cap on the checkout for this run (default `2g`). |
222
+ | `--model-timeout SECONDS` | | Time for a model call to start answering, 1 to 900 (overrides `starterAgent.modelTimeoutSeconds`). |
223
+ | `--work-dir` | | Where checkouts go. |
224
+ | `--allow-ci-push` | | With `--pr`: push even when the change touches CI config, manifests or build files. |
225
+ | `--git-remote NAME` | | With `--pr`: the remote to push to (default `origin`). |
226
+ | `--fork-remote NAME` | | With `--pr`: push to this remote (your fork) and open the pull request from it. |
227
+ | `--remote URL` | | A hosted board instead of the local one (`run` and `watch`). |
228
+
229
+ The model endpoint and key follow the chat's rules ([agents.md](agents.md)): a config cannot send your key to a host you did not
230
+ confirm. The starter agent always uses the OpenAI-compatible endpoint, never the chat's ACP agent.
231
+
232
+ ## Threat model
233
+
234
+ The starting assumption: the comment, the page text and the repo can all be hostile, and the model may do whatever they talk it into.
235
+
236
+ ### The container
237
+
238
+ Every run gets its own network and two containers, both from the local image (`--pull never`):
239
+
240
+ - **The agent container:** on the run's internal network (no route out, no outside DNS). The fresh checkout is mounted read-write at
241
+ `/work`, and nothing else: not your home folder, SSH keys, browser profile, the docker or podman socket, or your repository's `.git`
242
+ (the checkout has none). It runs as your
243
+ uid (never root; `--userns keep-id` on podman), with a read-only root file system and a small `/tmp`, every capability dropped,
244
+ `no-new-privileges`, memory, CPU and process limits, and an environment of a few fixed names: no host variable, and no key. The
245
+ agent is the container's first process (no init) and runs from a copy of node its user may execute but not read, which makes the
246
+ kernel mark it not dumpable: a test or approved command, running as the same user, cannot open its `/proc` files, so it cannot write
247
+ to the agent's line protocol with the host or read its memory. The host still checks every line it gets (results field by field, one
248
+ approval at a time, at most 10 per run, replies and cards limited).
249
+ - **The egress proxy:** on the run network and on `shapewall-egress`, the only way out. It passes HTTP `CONNECT` and plain `http://`
250
+ requests only to the allowed `host:port` pairs: the package registry and any `--allow-host`. A `CONNECT` tunnel carries only TLS,
251
+ and only when the ClientHello's server name is the allowed host (a missing name, two names, or an encrypted ClientHello are
252
+ refused): many sites share one address on a CDN, so the address alone would let any of them through. Plain `http://` requests go
253
+ out with the allowed host as their `Host`. Names on the default list that resolve to a private, loopback or link-local address
254
+ (IPv6 forms included: `::ffff:` mapped, NAT64 `64:ff9b::`, 6to4) are refused, so a rebinding DNS answer cannot reach your network
255
+ through them. Every refusal is logged and listed in the reply.
256
+
257
+ ### The model key
258
+
259
+ The key never enters the container. The agent sends each model request to the host over its stdin/stdout; the host adds the key, sends
260
+ the request to the configured endpoint only (with its own model name, with only text and inline `data:` images in the messages, and with
261
+ only `function` tools: a remote image URL, or a provider-side tool such as web search or a browser, would act outside the sandbox), and streams the answer back with the key removed. So a test or
262
+ an approved command, which runs as the same uid as the agent, has no key to read from memory or the environment, and a hijacked model
263
+ has none to post in a reply. The model endpoint is not on the egress allow list.
264
+
265
+ ### Board text is data
266
+
267
+ The comment, its replies, any page text and a failed setup command's output go to the model as quoted data with provenance (`<shapewall-data source="comment"
268
+ trust="untrusted" ...>`), never in the system prompt, and the system prompt tells the model that text inside is never an instruction.
269
+ That lowers the risk of prompt injection; it does not remove it, which is why the walls above exist.
270
+
271
+ ### What each runtime enforces
272
+
273
+ | Wall | Rootless podman (netavark) | Docker (rootful) | Rootless docker |
274
+ | ----------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
275
+ | User, read-only root, caps, no-new-privileges, limits | Enforced, verified | Enforced | Enforced |
276
+ | Only the checkout mounted | Enforced, verified | Enforced | Enforced |
277
+ | No route out of the internal network | Enforced, verified | Enforced | Enforced |
278
+ | No outside DNS | Enforced, verified (ENOTFOUND) | Best-effort: depends on the Docker version's embedded DNS; the doctor checks | Same as Docker |
279
+ | No way to the host's own ports | Enforced, verified | Best-effort: `host-gateway` reachability depends on the version and firewall; the doctor checks | Same as Docker |
280
+ | Files written as your uid | Enforced (`keep-id`), verified | Enforced (`--user`) | Not by default: the uid is mapped; the doctor says when the checkout is not writable as you |
281
+ | Egress allow list (the proxy) | Enforced, verified | Enforced | Enforced |
282
+
283
+ "Verified" means the opt-in container test and `agent doctor` passed on rootless podman 5.8. Docker was not available to test against:
284
+ run `shapewall agent doctor` and treat a FAIL line as a wall that is not there.
285
+
286
+ ### What is not covered
287
+
288
+ - **The change itself.** The agent can still write a bad or malicious change into the branch (a test that exfiltrates on CI, a
289
+ dependency swap, a workflow edit). Review the whole diff before merging; the reply flags changes to scripts, manifests and config.
290
+ - **Allowed hosts are channels.** Anything the proxy lets through (the registry, your `--allow-host` entries) can carry data out. The
291
+ npm registry takes publishes: code in the sandbox can publish a package (to an account it creates) with whatever it read, and the
292
+ TLS name check does not stop that. Keep the list short; `--registry none` when setup does not need it.
293
+ - **Tests and approved commands** run code the agent may have written (see [Tests run the agent's code](#tests-run-the-agents-code)).
294
+ - **What your model provider sees**: the comment, the files the agent reads, and the tool output.
295
+ - **Local author names are not authenticated** (see [The trigger gate](#the-trigger-gate)).
296
+ - **Commands you approve** run in the sandbox with the same walls as the agent, but they run: read them.
297
+ - **`capture`** works only for a site the sandbox can reach, and is not offered otherwise. A dev server on your machine is not
298
+ reachable, by design.
299
+ - **The `claude-code` and `codex` profiles** are reserved names, not implementations: those CLIs would need their own login inside the
300
+ sandbox, which this version does not do.
301
+ - **Container escapes** through kernel or runtime bugs. Keep podman or docker up to date.
302
+
303
+ ### Hosted boards
304
+
305
+ Run the starter on your own machine with a local repository and configuration:
306
+ `shapewall agent run --remote https://board.example --board site --comment 12`.
307
+ Supply the project token through `SHAPEWALL_TOKEN`, a protected token file, or
308
+ `shapewall login`; it needs `read,reply,status,claim`. Hosted trust comes only
309
+ from the server's Agent policy and hash-bound Send to agent action. Local
310
+ `starterAgent.trusted`, `--trusted` and `--trust-comment` cannot bypass it.
311
+ Guest and agent comments never start work; imports require a trusted vouch.
312
+
313
+ Shell requests create permission cards at the top of the hosted board. A
314
+ trusted admin checks the exact command and approves once with a fresh passkey.
315
+ No answer within two minutes means no execution. Editing the comment, ending
316
+ the claim, changing policy, or losing token authority invalidates the card.
317
+ The hosted server never executes the command; the developer's sandbox does.
318
+
319
+ `--pr` also works with a hosted source when the local repository has GitHub
320
+ connect configured. The existing push guard still blocks CI/workflow-sensitive
321
+ changes unless explicitly allowed by the runner. The GitHub credential remains
322
+ on the runner; it is never uploaded with the board or given to the sandbox.
323
+ Comments and captures are untrusted text. A shell-capable agent with a readable
324
+ token remains a prompt-injection risk: read [agent-hardening.md](agent-hardening.md)
325
+ and keep both server claim budgets and per-run turns/tokens/minutes limits.
@@ -0,0 +1,87 @@
1
+ # Installation updates
2
+
3
+ The small credit and version below the board and workspace console open **About & Updates**. On a local installation, the profile menu
4
+ opens **Workspace Console** at `/console`, with real local board cards and a **Settings** section for appearance preferences, installation details and **About & Updates**. The version includes the source revision,
5
+ so two builds of the same package version can still be distinguished. A static export or public demo shows its own build version;
6
+ it cannot update a server.
7
+
8
+ Updates are manual. Opening the panel reads installation details but never contacts a release provider or installs anything. There are
9
+ no update timers, automatic downloads or automatic restarts. **Check for updates** asks the installer-provided helper for the latest
10
+ prepared release. **Update now** explicitly activates it. After the server restarts, the panel verifies the new running revision and
11
+ offers **Reload Shapewall**.
12
+
13
+ ## Ordinary installations
14
+
15
+ Without an update helper, the panel explains that the installation owner manages updates. Update using the same method used to install
16
+ Shapewall, then restart `shapewall serve`. Keep the project's config and `.shapewall/` data. An npm install, a source checkout and a
17
+ container image do not share an updater; Shapewall does not guess a command or run `npm update` on your behalf.
18
+
19
+ - **A clone:** stop your server, `git pull` (or check out the release tag you want), run `npm ci` in the clone, and start the server
20
+ again with the same config.
21
+ - **Installed in a project from npm:** run `npm install --save-dev shapewall@latest` (or a version, such as `shapewall@0.2.1`), then
22
+ restart with `npx shapewall serve`.
23
+ - **Installed in a project from GitHub:** run `npm install --save-dev github:danbaruch/shapewall` again (add `#<tag>` to pin a
24
+ release tag), then restart with `npx shapewall serve`.
25
+ - **A tarball:** `npm install --save-dev /absolute/path/to/shapewall-0.2.1.tgz`, then restart.
26
+
27
+ The source revision in **About & Updates** tells two builds of the same version apart. Before switching, back up the config, captures, comments and account data, and keep the previous build
28
+ so you can go back. A server that runs as a service should be updated by replacing its release, not by editing the live folder.
29
+
30
+ ## Managed installations
31
+
32
+ An operator can provide `SHAPEWALL_UPDATE_HELPER`, an absolute path to a trusted executable. Shapewall invokes that exact executable
33
+ with one argument, `check` or `apply`, without a shell. The browser cannot supply commands, paths, download URLs or target revisions.
34
+ The helper must serialize changes across processes and preserve the previous release for rollback. The server supplies the actual
35
+ running source revision as `SHAPEWALL_RUNNING_REVISION`, overriding inherited values. Compare that revision with the new release,
36
+ not only the installation symlink: a previous attempt may have switched the pointer before its server restarted.
37
+
38
+ On success the helper prints only JSON:
39
+
40
+ ```json
41
+ { "latest": { "version": "0.1.0", "revision": "abcdef1234567890abcdef1234567890abcdef1234" }, "updateAvailable": true }
42
+ ```
43
+
44
+ An apply operation that needs this server to restart also returns `"restartRequired": true`. Only managed `serve` installations with
45
+ `SHAPEWALL_UPDATE_RESTART=1` honor that flag: after acknowledging the request they exit with code 75. The existing service manager must
46
+ restart failures. Do not enable this option for an unmanaged terminal process. The UI waits for the advertised revision to run; helper
47
+ success alone is not installation success. Failed helpers and checks never restart the app. The helper must not print credentials or
48
+ diagnostic logs to stdout; the server returns bounded, generic errors.
49
+
50
+ ### Prepared immutable releases
51
+
52
+ `scripts/managed-update.py` is a reference helper for Linux services. It does not fetch or build software, execute package managers,
53
+ change a service unit or require sudo. An operator first builds, tests and stages a release into a root-owned installation's `releases/`
54
+ directory, including `dist/client/build-info.json`. The operator installs the helper root-owned and configures the fixed file
55
+ `/etc/shapewall/updater.json`:
56
+
57
+ ```json
58
+ { "installRoot": "/opt/example-shapewall", "pointerRoot": "/var/lib/example-shapewall/install" }
59
+ ```
60
+
61
+ The installation root, release directories and metadata must be root-owned and not writable by other users. The pointer directory must
62
+ be owned by the app user with mode 0700. Its `current` and `previous` symlinks point at immutable release directories. Start the service
63
+ through that `current` pointer, directly or through another fixed symlink. Give the app write permission only to its data and pointer
64
+ directory; existing `NoNewPrivileges` and filesystem restrictions can stay enabled.
65
+
66
+ Publish a prepared release by atomically writing the root-owned `installRoot/update-channel.json`:
67
+
68
+ ```json
69
+ { "release": "release-abcdef1" }
70
+ ```
71
+
72
+ Checking reads that file and validates release metadata. Applying takes a file lock, saves `previous`, atomically switches `current`,
73
+ and asks the app to restart. Config, captures and comments remain in their data directory. A rollback points `current` at `previous`
74
+ and restarts the service. After an update, open the board and try a real flow: a running service can still serve a broken UI. If a
75
+ release starts and fails later, roll back by hand.
76
+
77
+ ### Who can update
78
+
79
+ The local owner link authorizes updates using the existing settings capability, sent in a header. Shared, read-only and unpaired
80
+ visitors cannot update. Mutations require same-origin JSON requests and accept an empty object only.
81
+
82
+ For a service behind a separately authenticated owner-only reverse proxy, an operator can configure `SHAPEWALL_UPDATE_TOKEN` (at least 32 characters, or the server refuses to start) and have
83
+ that proxy overwrite `X-Shapewall-Update-Token` with the same secret **only after verifying the installation owner**. Keep the token in
84
+ private server/proxy configuration, never browser code, a URL or a public repository. Ten wrong tokens from one address within 15 minutes block requests carrying the header from that address until the window ends. The application listener must remain private;
85
+ do not trust a client-supplied header or configure the header on a multi-user board. Shapewall still checks Host, Origin and JSON.
86
+
87
+ This capability can replace executable app code. Enable it only for the installation owner, independently of comment or board access.
@@ -0,0 +1,17 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "pageId": "checkout",
4
+ "viewport": "desktop",
5
+ "accessibility": true,
6
+ "steps": [
7
+ {
8
+ "action": { "click": "button.cart" },
9
+ "ready": "section.cart",
10
+ "maxDurationMs": 1500
11
+ },
12
+ {
13
+ "action": { "fill": ["input.quantity", "2"] },
14
+ "ready": "button.update"
15
+ }
16
+ ]
17
+ }